eCAL 5.10 changes

Service API - C

The service info struct has been renamed and extended

Old 5.9.x version:

struct SServiceInfoC
{
  const char*      host_name;      //!< service host
  const char*      service_name;   //!< service name
  const char*      method_name;    //!< method name
  const char*      error_msg;      //!< error message in case of failure
  int              ret_state;      //!< return state from method callback
  enum eCallState  call_state;     //!< service call state
};

New 5.10.x version (now containing 2 new elements for the service response):

struct SServiceResponseC
{
  const char*      host_name;     //!< service host name
  const char*      service_name;  //!< name of the service
  const char*      service_id;    //!< id of the service
  const char*      method_name;   //!< name of the service method
  const char*      error_msg;     //!< human readable error message
  int              ret_state;     //!< return state of the called service method
  enum eCallState  call_state;    //!< call state (see eCallState)
  const char*      response;      //!< service response
  int              response_len;  //!< service response length (response string could include zeros)
};

The 2 new elements response and response_len are used in the new C client response callback type

Old 5.9.x version:

/**
 * @brief eCAL service response callback function (client side)
 *
 * @param service_info_       Service info struct.
 * @param reponse_            Method response payload.
 * @param reponse_len_        Method response payload length.
 * @param par_                Forwarded user defined parameter.
**/
typedef void (*ResponseCallbackCT)(const struct SServiceInfoC* service_info_, const char* response_, int response_len_, void* par_);

New 5.10.x version:

/**
 * @brief eCAL service response callback function (client side)
 *
 * @param service_response_   Service response struct containing the (responding) server informations and the response itself.
 * @param par_                Forwarded user defined parameter.
**/
typedef void(*ResponseCallbackCT)(const struct SServiceResponseC* service_response_, void* par_);

The signature of the blocking client service call function has been changed.

Old 5.9.x version:

/**
 * @brief Call method of this service (blocking variant with timeout).
 *
 * @param       handle_        Client handle.
 * @param       host_name_     Host name.
 * @param       method_name_   Method name.
 * @param       request_       Request message buffer.
 * @param       request_len_   Request message length.
 * @param [out] service_info_  Service info struct with additional infos like call state and
 *                             error message.
 * @param [out] response_      Pointer to the allocated buffer for the response message.
 * @param       response_len_  Response message buffer length or ECAL_ALLOCATE_4ME if
 *                             eCAL should allocate the buffer for you (see eCAL_FreeMem).
 *
 * @return  Size of response buffer if succeeded, otherwise zero.
**/
ECALC_API int eCAL_Client_Call_Wait(ECAL_HANDLE handle_, const char* host_name_, const char* method_name_, const char* request_, int request_len_, struct SServiceInfoC* service_info_, void* response_, int response_len_);

New 5.10.x version:

/**
 * @brief Call a method of this service (blocking variant).
 *
 * @param       handle_            Client handle.
 * @param       method_name_       Method name.
 * @param       request_           Request message buffer.
 * @param       request_len_       Request message length.
 * @param       timeout_           Maximum time before operation returns (in milliseconds, -1 means infinite).
 * @param [out] service_response_  Service response struct with additional infos like call state and
 *                                 error message.
 * @param [out] response_          Pointer to the allocated buffer for the response message.
 *                                 In case of more then one connected server, only the reponse of the first
 *                                 answering server is returned (use callback variant to get all responses).
 * @param       response_len_      Response message buffer length or ECAL_ALLOCATE_4ME if
 *                                 eCAL should allocate the buffer for you (see eCAL_FreeMem).
 *
 * @return  Size of response buffer if succeeded, otherwise zero.
**/
ECALC_API int eCAL_Client_Call_Wait(ECAL_HANDLE handle_, const char* method_name_, const char* request_, int request_len_, int timeout_, struct SServiceResponseC* service_response_, void* response_, int response_len_);

The new signature is using the new SServiceResponseC struct and an additional timeout_ parameter. The 5.9 version was blocking infinitely by default.

Service API - C++

The service info struct has been renamed and extended.

Old 5.9.x version:

struct SServiceInfo
{
  std::string  host_name;      //!< service host name
  std::string  service_name;   //!< name of the service
  std::string  method_name;    //!< name of the service method
  std::string  error_msg;      //!< human readable error message
  int          ret_state;      //!< return state of the called service method
  eCallState   call_state;     //!< call state (see eCallState)
};

New 5.10.x version (now containing the service response):

struct SServiceResponse
{
  std::string  host_name;      //!< service host name
  std::string  service_name;   //!< name of the service
  std::string  service_id;     //!< id of the service
  std::string  method_name;    //!< name of the service method
  std::string  error_msg;      //!< human readable error message
  int          ret_state;      //!< return state of the called service method
  eCallState   call_state;     //!< call state (see eCallState)
  std::string  response;       //!< service response
};

Additional to the new SServiceResponse struct there is a new ServiceResponseVecT type that is used to return multiple services response as a standard vector in all kinds of service calls.

typedef std::vector<SServiceResponse> ServiceResponseVecT; //!< vector of multiple service responses

So the service response callback type been changed too.

Old 5.9.x version:

typedef std::function<void(const struct SServiceInfo& service_info_, const std::string& response_)> ResponseCallbackT ->

New 5.10.x version:

typedef std::function<void(const struct SServiceResponse& service_response_)> ResponseCallbackT

Calling a client in C++ is fully downward compatible excepting that blocking call variant

Old 5.9.x version:

/**
 * @brief Call method of this service, for specific host.
 *
 * @param       host_name_     Host name.
 * @param       method_name_   Method name.
 * @param       request_       Request string.
 * @param [out] service_info_  Service info struct for detailed informations.
 * @param [out] response_      Response string.
 *
 * @return  True if successful.
**/
bool Call(const std::string& host_name_, const std::string& method_name_, const std::string& request_, struct SServiceInfo& service_info_, std::string& response_);

New 5.10.x version (this is deprecated, see samples section how to use the new recommended interface):

/**
 * @brief Call method of this service, for specific host (deprecated).
 *
 * @param       host_name_         Host name.
 * @param       method_name_       Method name.
 * @param       request_           Request string.
 * @param [out] service_info_      Service response struct for detailed informations.
 * @param [out] response_          Response string.
 *
 * @return  True if successful.
**/
[[deprecated]]
bool Call(const std::string& host_name_, const std::string& method_name_, const std::string& request_, struct SServiceResponse& service_info_, std::string& response_);

Service API - C++ (Protobuf)

Old 5.9.x version:

/**
  * @brief Call method of this service, for specific host.
  *
  * @param       host_name_     Host name.
  * @param       method_name_   Method name.
  * @param       request_       Request message.
  * @param [out] service_info_  Service info struct for detailed informations.
  * @param [out] response_      Response string.
  *
 * @return  True if successful.
 **/
 bool Call(const std::string& host_name_, const std::string& method_name_, const google::protobuf::Message& request_, struct SServiceInfo& service_info_, google::protobuf::Message& response_)

New 5.10.x version (this is deprecated, see samples section how to use the new recommended interface):

/**
  * @brief Call method of this service, for specific host (deprecated).
  *
  * @param       host_name_         Host name.
  * @param       method_name_       Method name.
  * @param       request_           Request message.
  * @param [out] service_response_  Service response struct for detailed informations.
  * @param [out] response_          Response message.
  *
  * @return  True if successful.
 **/
 [[deprecated]]
 bool Call(const std::string& host_name_, const std::string& method_name_, const google::protobuf::Message& request_, struct SServiceResponse& service_response_, google::protobuf::Message& response_)

Service Sample - C

A minimal service client implementation can been seen here.

Old 5.9.x version:

struct SServiceInfoC service_info;
char                 request[]                 = "HELLO";
char                 response[sizeof(request)] = { 0 };
// call method "echo"
eCAL_Client_Call_Wait(client_handle, "", "echo", request, sizeof(request), &service_info, &response, sizeof(response));

New 5.10.x version:

struct SServiceResponseC service_response;
char                     request[]                 = "HELLO";
char                     response[sizeof(request)] = { 0 };
// call method "echo"
eCAL_Client_Call_Wait(client_handle, "echo", request, sizeof(request), -1, &service_response, &response, sizeof(response));

Service Sample - C++

Old 5.9.x version:

eCAL::SServiceInfo service_info;
std::string method_name("echo");
std::string request("Hello");
std::string response;
minimal_client.Call("", method_name, request, service_info, response);

New 5.10.x version (deprecated):

eCAL::SServiceResponse service_info;
std::string method_name("echo");
std::string request("Hello");
std::string response;
minimal_client.Call("", method_name, request, service_info, response);

New 5.10.x version (new recommended API):

eCAL::SServiceResponse service_info;
std::string method_name("echo");
std::string request("Hello");
eCAL::ServiceResponseVecT service_response_vec;
minimal_client.Call(method_name, request, /*timeout_*/ -1, &service_response_vec);
for (auto service_response : service_response_vec)
{
  std::cout << "Received response : " << service_response.response << std::endl;
}

Service Sample - C++ (Protobuf)

Old 5.9.x version:

eCAL::SServiceInfo service_info;
PingRequest        ping_request;
PingResponse       ping_response;
ping_request.set_message("PING");
ping_service.Call("", "Ping", ping_request, service_info, ping_response);

New 5.10.x version:

PingRequest               ping_request;
eCAL::ServiceResponseVecT service_response_vec;
ping_request.set_message("PING");
ping_service.Call("Ping", ping_request, /*timeout_*/ -1, &service_response_vec);
for (auto service_response : service_response_vec)
{
  PingResponse ping_response;
  ping_response.ParseFromString(service_response.response);
}