TipcMsgSetDest

Name

TipcMsgSetDest — set the destination of a message

Synopsis

T_BOOL TipcMsgSetDest(msg, dest) 
T_IPC_MSG msg; 
T_STR dest;

Arguments

msg — message to set destination for

dest — message destination

Return Values

TRUE if the destination was successfully set for the message, FALSE otherwise.

Diagnostics

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

T_ERR_NULL_PTR — msg was null or dest was null

T_ERR_MSG_INVALID — msg was not a valid message

T_ERR_READ_ONLY — the message was marked read-only. This happens if the message is a field in another message.

T_ERR_VAL_INVALID — dest was not a valid subject

Description

TipcMsgSetDest sets the destination property of a message. The destination property is a string whose meaning depends on how the message is being used. Other applications of messages are free to use the sender and destination for another purpose. Message sender and destination properties can be null if they are not needed. TipcMsgSetDest makes a copy of the message destination.

Messages sent with publish-subscribe between RTclients by RTserver, for example, use a subject name for the message sender and destination.

Caution

TipcMsgSetDest does not detect errors in dest (such as misspelled subject names).

Examples

This example sets the destination property of a message to _all:

if (!TipcMsgSetDest(msg, "_all")) { 
  return;  /* error */ 
}