TipcMsgAck

Name

TipcMsgAck — acknowledge delivery of a message

Synopsis

T_BOOL TipcMsgAck(msg) 
T_IPC_MSG msg; 

Arguments

msg — message to acknowledge

Return Values

TRUE if the message was successfully acknowledged, FALSE otherwise.

Diagnostics

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

Description

TipcMsgAck acknowledges successful delivery of a message by a receiving process. When a message with a delivery mode of T_IPC_DELIVERY_SOME or T_IPC_DELIVERY_ALL is sent through a connection with TipcConnMsgSend, the sender saves a copy of the message until some (in the case of T_IPC_DELIVERY_SOME) or all (in the case of T_IPC_DELIVERY_ALL) receiving processes acknowledge that they have received the message.

TipcMsgDestroy automatically calls TipcMsgAck to ensure a received message is acknowledged before it is destroyed. TipcMsgDestroy assumes that when a receiving process destroys a message, it is finished processing the message and that the message can be considered to have been successfully delivered to this receiving process.

TipcMsgAck first updates the highest sequence number (based on the sequence number and sender of msg) in the GMD area of the connection the message was received on.The highest sequence number is used to detect duplicate messages. TipcMsgAck then creates a GMD_ACK message, appends an INT4 integer field containing the sequence number of the message being acknowledged, and sends the GMD_ACK message with TipcConnMsgSend through the same connection the message was received on.

If the message’s delivery mode is either T_IPC_DELIVERY_SOME or T_IPC_DELIVERY_ALL and the message has not already been acknowledged manually with TipcMsgAck, then TipcMsgDestroy first calls TipcMsgAck to acknowledge successful delivery of the message to this receiving process.

Caution

TipcMsgAck is a low-level function that is normally not used directly by developers, but called by TipcMsgDestroy. Normally, TipcMsgAck is used only when a process receives a message, processes it, and then needs to keep the message around for any period of time. When the receiver uses TipcMsgAck in this case it allows the sending process to destroy its own saved copy of the message.

TipcMsgAck sends a GMD_ACK message, but does not explicitly flush the message. See TipcConnGetAutoFlushSize for more information on message buffering.

See Also

TipcMsgCreate, TipcMsgDestroy, TipcConnMsgSend

Examples

This example reads a message from a connection, processes it, and manually acknowledges it with TipcMsgAck:

T_IPC_MSG msg; 
 
msg = TipcConnMsgNext(conn, T_TIMEOUT_FOREVER); 
if (msg == NULL) { 
  return;  /* error */ 
}  
 
/* Process the message however appropriate: either by using TipcConnMsgProcess to call 
process/default callbacks, or by using TipcMsgNext* to directly access the fields of the message. */ 
 
/* Acknowledge delivery of the message. You should only do this if you plan to keep the message 
around for a while. */ 
if (!TipcMsgAck(msg)) { 
  /* T_ERR_TYPE_INVALID in this case just means no ack needed. */ 
  if (TutErrNumGet() != T_ERR_TYPE_INVALID) { 
    return;  /* error */ 
  } 
}