TipcConnMsgInsert

Name

TipcConnMsgInsert — insert a message into queue of a connection

Synopsis

T_BOOL TipcConnMsgInsert(conn, msg, pos) 
T_IPC_CONN conn; 
T_IPC_MSG msg; 
T_INT4 pos;

Arguments

conn — connection to insert message into

msg — message to insert

pos — position to insert message

Return Values

TRUE if the message was successfully inserted into the queue of the connection, FALSE otherwise.

Diagnostics

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

T_ERR_NULL_PTR — conn was null or msg was null

T_ERR_MSG_INVALID — msg was not a valid message

T_ERR_VAL_INVALID — pos was negative or larger than the number of messages in the queue

Description

TipcConnMsgInsert inserts a message into the message queue of a connection. A connection has a priority queue of incoming messages. Use 0 for pos to insert the message as the first message in the queue, 1 for pos to insert the message as the second message, and so on. Use T_IPC_POS_PRIORITY for pos to insert the message in priority order, after all other message with equal or higher priority. TipcConnMsgInsert also calls the connection’s queue callbacks.

Caution

The message passed to TipcConnMsgInsert should not be destroyed by calling TipcMsgDestroy, as TipcConnMsgInsert takes responsibility for destroying the message.

TipcConnMsgInsert does not make a copy of msg.

Examples

This example constructs a message and inserts it onto the front of a connection’s message queue:

T_IPC_MT mt; 
T_IPC_MSG msg; 
 
mt = TipcMtLookupByNum(T_MT_NUMERIC_DATA); 
if (mt == NULL) { 
  return;  /* error */ 
}  
 
msg = TipcMsgCreate(mt); 
if (msg == NULL) { 
  return;  /* error */ 
}  
 
if (!TipcMsgAppendStrReal8(msg, "temperature", 98.6)) { 
  return;  /* error */ 
}  
 
if (!TipcConnMsgInsert(conn, msg, 0)) { 
  return;  /* error */ 
} 
  
/* At this point, msg "belongs" to the connection, and should */ 
/* not be destroyed by the caller */