Callback Type for Asynchronous Message Consumption

When you call the MQCreateAsyncMessageConsumer() function or the MQCreateAsyncDurableMessageConsumer() function, you must pass the name of an MQMessageListenerFunc type callback function that is to be called when the consumer receives a message to the specified destination.

The MQMessageListenerFunc type has the following definition:

MQError (* MQMessageListenerFunc)(
                const MQSessionHandle  sessionHandle,
                const MQConsumerHandle  consumerHandle,
                MQMessageHandle  messageHandle
                void * callbackData);

Parameters

sessionHandle

The handle to the session to which this consumer belongs. The client runtime specifies this handle when it calls your message listener.

consumerHandle

A handle to the consumer receiving the message. The client runtime specifies this handle when it calls your message listener.

messageHandle

A handle to the incoming message. The client runtime specifies this handle when it calls your message listener.

callbackData

The void pointer that you passed to the function MQCreateAsyncMessageConsumer or the function MQCreateAsyncDurableMessageConsumer.

The body of a message listener function is written by the receiving client. Mainly, the function needs to process the incoming message by examining its header, body, and properties. The client is also responsible for freeing the message handle (either from within the handler or from outside the handler) by calling MQFreeMessage.

In addition, you should observe the following guidelines when writing the message listener function:

• If you specify MQ_CLIENT_ACKNOWLEDGE as the acknowledge mode for the session, you must explicitly call the MQAcknowledgeMessages function to acknowledge messages that you have received. For more information, see the description of the function MQAcknowledgeMessages.

• Do not try to close the session (or the connection to which it belongs) and consumer handle in the message listener.

• It is possible for a message listener to return an error; however, this is considered a client programming error. If the listener discovers that the message is badly formatted or if it cannot process it for some other reason, it should handle the problem itself by re-directing it to an application-specific bad-message destination and process it later.

  If the message listener does return an error, the client runtime will try to redeliver the message once if the session’s acknowledge mode is either MQ_AUTO_ACKNOWLEDGE or MQ_DUPS_OK_ACKNOWLEDGE .