Sun GlassFish Message Queue 4.4 Developer's Guide for C Clients

Parameters

sessionHandle

The handle to the session to which this consumer belongs. This handle is passed back by the MQCreateSession() function. For this asynchronous durable consumer, the session must have been created with the MQ_SESSION_ASYNC_RECEIVE receive mode.

destinationHandle

A handle to a topic destination on which the consumer receives messages. This handle remains valid after the call.

durableName

An MQString specifying a name for the durable subscriber. The library makes a copy of the durableName string.

messageSelector

An expression (based on SQL92 conditional syntax) that specifies the criteria upon which incoming messages should be selected for this consumer.

Specify a NULL or empty string to indicate that there is no message selector for this consumer. In this case, all messages are delivered.

The library makes a copy of the messageSelector string.

For more information about SQL, see X/Open CAE Specification Data Management: Structured Query Language (SQL), Version 2, ISBN 1-85912-151-9, March 1966.

noLocal

Specify MQ_TRUE to inhibit delivery of messages published by this consumer’s own connection.

messageListener

The name of an MQMessageListenerFunc type callback function that is to be called when this consumer receives a message on the specified destination.

listenerCallbackData

A pointer to data that you want passed to your message listener function when it is called by the library.

consumerHandle

Output parameter for the handle that references the consumer for the specified destination.

In the case of an asynchronous consumer, you should not start a connection before calling the MQCreateAsyncDurableMessageConsumer function. (You should create a connection, create a session, set up your asynchronous consumer, create the consumer, and then start the connection.) Attempting to create a consumer when the connection is not stopped, will result in an MQ_CONCURRENT_ACCESS error.

The MQCreateAsyncDurableMessageConsumer function creates an asynchronous durable message consumer for the specified destination. You can define parameters to filter messages and to inhibit the delivery of messages you published to your own connection. Note that the session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create a synchronous durable message consumer for a destination, call the function MQCreateDurableMessageConsumer.()

Durable consumers can only be used for topic destinations. If you are creating an asynchronous consumer for a queue destination or if you are not interested in messages that arrive to a topic while you are inactive, you might prefer to use the function MQCreateAsyncMessageConsumer().

The broker retains a record of this durable subscription and makes sure that all messages from the publishers to this topic are retained until they are either acknowledged by this durable subscriber or until they have expired. Sessions with durable subscribers must always provide the same client identifier. (See MQCreateConnection, clientID parameter.) In addition, each durable consumer must specify a durable name using the durableName parameter, which uniquely identifies (for each client identifier) the durable subscription when it is created.

A session’s consumers are automatically closed when you close the session or connection to which they belong. However, messages will be routed to the durable subscriber while it is inactive and delivered when the durable consumer is recreated. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer() function. If you want to close a durable consumer permanently, you should call the MQUnsubscribeDurableMessageConsumer() after closing it to delete state information maintained by the Broker on behalf of the durable consumer.