TipcMsgGetUserProp

Name

TipcMsgGetUserProp — get the user-defined property of a message

Synopsis

T_BOOL TipcMsgGetUserProp(msg, user_prop_return) 
T_IPC_MSG msg; 
T_INT4 *user_prop_return; 

Arguments

msg — message to get user-defined property from

user_prop_return — storage for message user-defined property

Return Values

TRUE if the user-defined property was successfully retrieved from the message, FALSE otherwise.

Diagnostics

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

Description

TipcMsgGetUserProp gets the user-defined property of a message. You can use the user-defined property for any purpose, such as attaching a version number to messages. This property is not used internally by SmartSockets. When a message is sent through a connection with TipcConnMsgSend, the user-defined property is byte-swapped along with all the other integer message properties.

On architectures where a pointer is four bytes, a pointer can be stored in the user-defined property of a message. This is useful for attaching extra temporary data to the message. Use pointers with caution; when a message is sent through a connection, the data the pointer refers to does not exist in the receiving process. In this situation, add extra fields to the message instead of using a pointer in the user-defined property.

When a message is created, its user-defined property is initialized to the message type user-defined property. This allows a default value to easily be set for all messages of a certain type.

Caution

If TipcMsgGetUserProp returns FALSE, it does not store a value in user_prop_return.

See Also

TipcMsgSetUserProp, TipcMtGetUserProp

Examples

This example prints the user-defined property of a message:

T_IPC_MSG msg; 
T_INT4 user_prop; 
 
if (!TipcMsgGetUserProp(msg, &user_prop)) { 
  return;  /* error */ 
}  
 
TutOut("msg has user prop %d\n", user_prop);