TipcMsgSetSender

Name

TipcMsgSetSender — set the sender of a message

Synopsis

T_BOOL TipcMsgSetSender(msg, sender) 
T_IPC_MSG msg; 
T_STR sender;

Arguments

msg — message to set sender for

sender — message sender

Return Values

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

Diagnostics

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

T_ERR_NULL_PTR — msg was null or sender 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 — sender was an empty string ("")

Description

TipcMsgSetSender sets the sender property of a message. The sender 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. TipcMsgSetSender makes a copy of the message sender.

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

Caution

RTclients do not have to explicitly set the sender property of a message sent to RTserver; the functions TipcSrvMsgSend, TipcSrvMsgWrite, and TipcSrvMsgWriteVa all set the sender property of their messages to the unique subject of the process (which is stored in the option Unique_Subject).

Examples

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

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