TipcMsgDestroy

Name

TipcMsgDestroy — destroy a message

Synopsis

T_BOOL TipcMsgDestroy(msg) 
T_IPC_MSG msg; 

Arguments

msg — message to destroy

Return Values

TRUE if the message was successfully destroyed, FALSE otherwise.

Diagnostics

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

Description

TipcMsgDestroy decrements the reference count of a message and destroys the message if the reference count is zero. When a message is destroyed, all of its memory is deallocated and the message cannot be reused.

If the message’s delivery mode is either T_IPC_DELIVERY_SOME or T_IPC_DELIVERY_ALL and the message has not already been acknowledged manually with TipcMsgAck, then TipcMsgDestroy first calls TipcMsgAck to acknowledge successful delivery of the message to this receiving process. TipcMsgDestroy next decrements the reference count of the message, and if the reference count is still greater than zero, TipcMsgDestroy immediately returns. All memory for the message is then freed.

Caution

TipcMsgAck sends a GMD_ACK message, but does not explicitly flush the message. See TipcConnGetAutoFlushSize for more information on message buffering.

See Also

TipcMsgCreate, TipcMsgAck

Examples

This example creates a message, appends two fields, and destroys the message:

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 */ 
}  
 
/* An RTclient would typically set the destination of */ 
/* a message at this point by calling TipcMsgSetDest. */ 
 
if (!TipcMsgAppendStrReal8(msg, "speed_limit", 55.0)) { 
  return;  /* error */ 
}  
 
/* A process would typically send a message at this point by */ 
/* calling TipcConnMsgSend or TipcSrvMsgSend. */ 
 
if (!TipcMsgDestroy(msg)) { 
  return;  /* error */ 
}