TipcSrvConnMsgSendRpc

TipcSrvConnMsgSendRpc — make a remote procedure call (RPC) with messages on the connection

Synopsis

T_IPC_MSG TipcSrvConnMsgSendRpc(srv, call_msg, timeout) 
T_IPC_SRV srv; 
T_IPC_MSG call_msg; 
T_REAL8 timeout;

Arguments

Return Values

Diagnostics

If TipcSrvConnMsgSendRpc fails, it returns NULL and sets the global SmartSockets error number to one of:

T_ERR_NULL_PTR — srv or call_msg was null, or the destination of call_msg was null

T_ERR_MSG_INVALID — call_msg was not a valid message

T_ERR_VAL_INVALID — destination of call_msg is not a valid subject

T_ERR_VAL_TOO_SMALL — timeout was negative

T_ERR_SRV_NOT_CONNECTED — a connection to RTserver could not be created

any error number from TipcConnMsgSendRpc

Description

TipcSrvConnMsgSendRpc makes a remote procedure call (RPC) with messages on the connection to RTserver by calling TipcConnMsgSendRpc. One message is sent as the RPC call from the caller, and another message is sent back as the RPC result to the caller. See TipcConnMsgSendRpc for more information on RPCs that use message passing.

TipcSrvConnMsgSendRpc may attempt to automatically create a connection to RTserver. If RTclient has a warm connection to RTserver, TipcSrvConnMsgSendRpc returns null immediately. See TipcSrvConnOpen for more information on automatic creation of connections and warm connections to RTserver.

Caution

When the message returned by TipcSrvConnMsgSendRpc is no longer needed, destroy it by calling TipcMsgDestroy, unless the message is passed to another function which takes responsibility for destroying the message, such as TipcSrvConnMsgInsert.

The message type number of the result message must be one greater than the message type number of the call message.

TipcSrvConnMsgSendRpc does not work well if multiple RTclients receive the call message, and thus all send a result message back to the caller. TipcSrvConnMsgSendRpc returns the first result message in this case.

See Also

Examples

This example queries the current time of another RTclient with a message-based connection RPC. It sends a call message and waits for up to 10 seconds for a result message to be sent back from the other end of the connection. Shown first is a utility fragment that must be used by both the caller and the callee:

#define USER_MT_TIME_QUERY_CALL 100 
#define USER_MT_TIME_QUERY_RESULT 101 /* call num plus one */ 
 
/* utility function to create message types */ 
static void T_ENTRY create_time_query_mt() 
{ 
  T_IPC_MT mt; 
 
  mt = TipcMtCreate("time_query_call",  
                    USER_MT_TIME_QUERY_CALL, 
                    ""); 
  if (mt == NULL) { 
    return;  /* error */ 
  } 
 
  mt = TipcMtCreate("time_query_result", 
                    USER_MT_TIME_QUERY_RESULT, 
                    "real8"); 
  if (mt == NULL) { 
    return;  /* error */ 
  } 
} /* create_time_query_mt */

/* query current time via RPC */ 
T_REAL8 T_ENTRY time_query_rpc(unique_subject) 
T_STR unique_subject; /* unique subject of remote process */ 
{ 
  T_IPC_MT mt; 
  T_IPC_MSG call_msg; 
  T_IPC_MSG result_msg; 
  T_REAL8 result; 
 
  mt = TipcMtLookupByNum(USER_MT_TIME_QUERY_CALL); 
  if (mt == NULL) { 
    return;  /* error */ 
  } 
 
  call_msg = TipcMsgCreate(mt); 
  if (call_msg == NULL) { 
    return;  /* error */ 
  } 
  if (!TipcMsgSetDest(call_msg, unique_subject)) { 
    return;  /* error */ 
  } 
  
 /* send/recv RPC messages */ 
  result_msg = TipcSrvConnMsgSendRpc(srv, call_msg, 10.0); 
  if (result_msg == NULL) { 
    return;  /* error */ 
  } 
  
 /* process result without using TipcSrvConnMsgProcess */ 
 
  if (!TipcMsgNextReal8(result_msg, &result)) { 
    return;  /* error */ 
  } 
  if (!TipcMsgDestroy(result_msg)) { 
    return;  /* error */ 
  } 
  if (!TipcMsgDestroy(call_msg)) { 
    return;  /* error */ 
  } 
  return result; 
} /* time_query_rpc */

/* callback to process RPC "call" message */ 
 
static void T_ENTRY process_call(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR caller; /* unique subject of caller process */ 
 
  mt = TipcMtLookupByNum(USER_MT_TIME_QUERY_RESULT); 
  if (mt == NULL) { 
    return;  /* error */ 
  } 
 
  /* get the sender property of the message, which is the */ 
  /* unique subject of the caller process */ 
  if (!TipcMsgGetSender(data->msg, &caller)) { 
    return;  /* error */ 
  } 
 
  /* send a result message back to the caller */ 
  if (!TipcSrvConnMsgWrite(srv, caller, mt, FALSE, 
                       T_IPC_FT_REAL8, TutGetCurrentTime(), 
                       NULL)) { 
    return;  /* error */ 
  } 
  if (!TipcSrvConnFlush(srv)) { 
    return;  /* error */ 
  } 
} /* process_call */ 
 
/*...fragment that uses process_call */ 
T_IPC_MT mt; 
 
mt = TipcMtLookupByNum(USER_MT_TIME_QUERY_CALL); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvConnProcessCbCreate(srv, mt, process_call, NULL) == 
NULL) { 
  return;  /* error */ 
} 
TipcSrvConnMainLoop(srv, T_TIMEOUT_FOREVER); /* process call messages */