WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

Message and exception listener functions in C

A C application uses a message listener function to receive messages asynchronously, and an exception listener function to be notified asynchronously of a problem with a connection.

Message listener functions in C

To receive messages asynchronously, a C application must register a message listener function and context data with one or more message consumers. The application does this by calling the xmsMsgConsumerSetMessageListener() function for each message consumer, passing pointers to the message listener function and context data as parameters.

A message listener function is a callback function written by the user. When a message arrives for a message consumer, XMS calls the message listener function to deliver the message, passing a pointer to the context data as one parameter and the handle for the message as the other parameter.

The format and content of the context data is defined by the application, and the data itself occupies memory owned by the application. For example, the context data might be a structure allocated on the heap. The context data contains all the information that the message listener function needs to refer to when processing a message. XMS does not make a copy of the context data, and so the application must ensure that the context data is still available when XMS calls the message listener function.

Note: The application must release the resources used by a message that is received asynchronously. XMS does not release these resources.

To stop the asynchronous delivery of messages to a message consumer, the application can call the xmsMsgConsumerSetMessageListener() function again, by passing a null pointer as a parameter instead of a pointer to a message listener function.

A new message listener function and context data can be registered with a message consumer without cancelling the registration of an existing message listener function. If an existing message listener function is running when a new message listener function is registered, the active message listener function completes as usual, and any subsequent messages are processed by calls to the new message listener function. If a transaction is in progress when a message listener function is changed, the transaction is completed by calls to the new message listener function.

For more information about the message listener function, including its signature, see MessageListener.

Exception listener functions in C

Using an exception listener function is similar in principle to using a message listener function.

A C application must register an exception listener function with a connection by calling the xmsConnSetExceptionListener() function, passing pointers to the exception listener function and context data as parameters. An exception listener function is a callback function written by the user. If XMS detects a problem with the connection, XMS calls the exception listener function, passing a pointer to the context data as one parameter and the handle for an error block as the other parameter.

The context data contains all the information that the exception listener function requires when processing an error block. In all other respects, the context data is used with an exception listener function in the same way as it is used with a message listener function.

For more information about the exception listener function, including its signature, see MessageListener.

Note: The application is required to release the resources used by an error block received in this way. XMS does not release these resources.

To stop the asynchronous reporting of problems with a connection, the application can call the xmsConnSetExceptionListener() function again, by passing a null pointer as a parameter instead of a pointer to an exception listener function.


Concept topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.