TipcMsgGetDeliveryMode

Name

TipcMsgGetDeliveryMode — get the delivery mode of a message

Synopsis

T_BOOL TipcMsgGetDeliveryMode(msg, delivery_mode_return) 
T_IPC_MSG msg; 
T_IPC_DELIVERY_MODE *delivery_mode_return; 

Arguments

msg — message to get delivery mode from

delivery_mode_return — storage for message delivery mode

Return Values

TRUE if the delivery mode was successfully retrieved from the message, FALSE otherwise.

Diagnostics

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

Description

TipcMsgGetDeliveryMode gets the delivery mode of a message. The delivery mode of a message controls what level of guarantee is used when the message is sent through a connection with TipcConnMsgSend. When a message is created, its delivery mode is initialized to the message type delivery mode. This allows a default value to easily be set for all messages of a certain type. See TipcMtGetDeliveryMode for more information on message type delivery modes.

The default message delivery mode is T_IPC_DELIVERY_BEST_EFFORT. In this mode, no special actions are taken to ensure delivery of sent messages. The message is delivered unless network failures or process failures occur. If the message is not delivered, there is no way for the sender to know that delivery failed. When there is a failure, it is possible for some messages to be lost or be delivered in a different order than the order in which they were published.

In the case of a network or process failure, a more useful delivery mode is T_IPC_DELIVERY_ORDERED. Messages can still be lost in the event of a failure, but all delivered messages are received in the order in which they were published. Because Java Message Service (JMS) cannot handle messages that come out of order, you must use the T_IPC_DELIVERY_ORDERED delivery mode or one of the GMD delivery modes if you are sending messages to a JMS client.

The difference between the other delivery modes and the GMD delivery modes is that in GMD, a copy of the message is kept when the message is sent and acknowledgements are sent when the message is received. No acknowledgements (ACKs) are used in the ordered or best effort delivery modes, and no copy of the message is kept.

One of the GMD delivery modes is T_IPC_DELIVERY_SOME. In this mode, the sending process saves a copy of the message in the connection GMD area until the message is successfully delivered, and the sender can also resend the message if necessary. Delivery is considered successful if the sent message is acknowledged by at least one receiving process.

The other and most robust GMD delivery mode is T_IPC_DELIVERY_ALL. In this mode, the sending process saves a copy of the message in the connection GMD area until the message is successfully delivered, and the sender can also resend the message if necessary. Delivery is not considered successful until all receiving processes acknowledge the sent message. For two processes communicating through a non-RTclient and non-RTserver T_IPC_CONN connection, T_IPC_DELIVERY_SOME and T_IPC_DELIVERY_ALL are identical because there is only one process receiving the message. For RTclients, the two modes do differ if more than one RTclient is subscribing to the subject in the destination of the message.

Caution

If TipcMsgGetDeliveryMode returns FALSE, it does not store a value in delivery_mode_return.

See Also

TipcMsgSetDeliveryMode, TipcMtGetDeliveryMode, TipcDeliveryModeToStr

Examples

This example prints the delivery mode of a message:

T_IPC_MSG msg; 
T_IPC_DELIVERY_MODE delivery_mode; 
T_STR delivery_mode_str; 
 
if (!TipcMsgGetDeliveryMode(msg, &delivery_mode)) { 
  return;  /* error */ 
} 
 
/* convert the delivery mode to a string to make it easier to read */ 
if (!TipcDeliveryModeToStr(delivery_mode, &delivery_mode_str)) { 
  return;  /* error */ 
} 
 
TutOut("The message has delivery mode %s\n", delivery_mode_str);