TipcMtGetUserProp

Name

TipcMtGetUserProp — get the user-defined property of a message type

Synopsis

T_BOOL TipcMtGetUserProp(mt, user_prop_return) 
T_IPC_MT mt; 
T_INT4 *user_prop_return; 

Arguments

mt — message type to get user-defined property from

user_prop_return — storage for message type user-defined property

Return Values

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

Diagnostics

If TipcMtGetUserProp fails, it returns FALSE and sets the global SmartSockets error number to:

Description

TipcMtGetUserProp gets the user-defined property of a message type. The user-defined property of a message type is used as the default user-defined property for messages of this type. When a message is created, its user-defined property is initialized to the message type user-defined property.

You can use the user-defined property for any purpose, such as attaching a version number to message types. 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 type. This is useful for attaching extra temporary data to the message type. 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.

The user-defined property of an outgoing message can always be set on a per-message basis, but using message type user-defined properties makes it easier to change the default user-defined property for all outgoing messages of a specific type. The standard SmartSockets message types by default all have a user-defined property of 0, but these can be changed. User-defined message types can also use whatever user-defined property is appropriate.

Caution

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

See Also

TipcMsgGetUserProp, TipcMtSetUserProp

Examples

This example prints the user-defined property of the NUMERIC_DATA message type:

T_IPC_MT mt; 
T_INT4 user_prop; 
 
mt = TipcMtLookup("numeric_data"); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (!TipcMtGetUserProp(mt, &user_prop)) { 
  return;  /* error */ 
} 
 
TutOut("NUMERIC_DATA msg type has user prop %d\n", user_prop);