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

MessageConsumer

An application uses a message consumer to receive messages sent to a destination.

For a list of the XMS defined properties of a MessageConsumer object, see Properties of MessageConsumer.

Functions

Summary of functions:
Function Description
xmsMsgConsumerClose Close the message consumer.
xmsMsgConsumerGetMessageListener Get pointers to the message listener function and context data that are registered with the message consumer.
xmsMsgConsumerGetMessageSelector Get the message selector for the message consumer.
xmsMsgConsumerReceive Receive the next message for the message consumer. The call waits indefinitely for a message, or until the message consumer is closed.
xmsMsgConsumerReceiveNoWait Receive the next message for the message consumer if one is available immediately.
xmsMsgConsumerReceiveWithWait Receive the next message for the message consumer. The call waits only a specified period of time for a message, or until the message consumer is closed.
xmsMsgConsumerSetMessageListener Register a message listener function and context data with the message consumer.

xmsMsgConsumerClose – Close Message Consumer

Interface:
xmsRC xmsMsgConsumerClose(xmsHMsgConsumer *consumer,
                          xmsHErrorBlock errorBlock);

Close the message consumer.

If an application tries to close a message consumer that is already closed, the call is ignored.

Parameters:
consumer (input/output)
On input, the handle for the message consumer. On output, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerGetMessageListener – Get Message Listener

Interface:
xmsRC xmsMsgConsumerGetMessageListener(xmsHMsgConsumer consumer,
                                       fpXMS_MESSAGE_CALLBACK *lsr,
                                       xmsCONTEXT *context,
                                       xmsHErrorBlock errorBlock);

Get pointers to the message listener function and context data that are registered with the message consumer.

For more information about using message listener functions, see Message listener functions in C.

Parameters:
consumer (input)
The handle for the message consumer.
lsr (output)
A pointer to the message listener function. If no message listener function is registered with the message consumer, the call returns a null pointer.
context (output)
A pointer to the context data. If no message listener function is registered with the connection, the call returns a null pointer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerGetMessageSelector – Get Message Selector

Interface:
xmsRC xmsMsgConsumerGetMessageSelector(xmsHMsgConsumer consumer,
                                       xmsCHAR *messageSelector,
                                       xmsINT length,
                                       xmsINT *actualLength,
                                       xmsHErrorBlock errorBlock);

Get the message selector for the message consumer.

For more information about how to use this function, see C functions that return a string by value.

Parameters:
consumer (input)
The handle for the message consumer.
messageSelector (output)
The buffer to contain the message selector expression. If data conversion is required, this is the message selector expression after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the message selector expression is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the message selector expression in bytes. If data conversion is required, this is the length of the message selector expression after conversion. If you specify a null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerReceive – Receive

Interface:
xmsRC xmsMsgConsumerReceive(xmsHMsgConsumer consumer,
                            xmsHMsg *message,
                            xmsHErrorBlock errorBlock);

Receive the next message for the message consumer. The call waits indefinitely for a message, or until the message consumer is closed.

Parameters:
consumer (input)
The handle for the message consumer.
message (output)
The handle for the message. If the message consumer is closed while the call is waiting for a message, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerReceiveNoWait – Receive with No Wait

Interface:
xmsRC xmsMsgConsumerReceiveNoWait(xmsHMsgConsumer consumer,
                                  xmsHMsg *message,
                                  xmsHErrorBlock errorBlock);

Receive the next message for the message consumer if one is available immediately.

Parameters:
consumer (input)
The handle for the message consumer.
message (output)
The handle for the message. If no message is available immediately, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerReceiveWithWait – Receive (with a wait interval)

Interface:
xmsRC xmsMsgConsumerReceiveWithWait(xmsHMsgConsumer consumer,
                                    xmsLONG waitInterval,
                                    xmsHMsg *message,
                                    xmsHErrorBlock errorBlock);

Receive the next message for the message consumer. The call waits only a specified period of time for a message, or until the message consumer is closed.

Parameters:
consumer (input)
The handle for the message consumer.
waitInterval (input)
The time, in milliseconds, that the call waits for a message. If you specify a wait interval of 0, the call waits indefinitely for a message.
message (output)
The handle for the message. If no message arrives during the wait interval, or if the message consumer is closed while the call is waiting for a message, the function returns a null handle but no error.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerSetMessageListener – Set Message Listener

Interface:
xmsRC xmsMsgConsumerSetMessageListener(xmsHMsgConsumer consumer,
                                       fpXMS_MESSAGE_CALLBACK lsr,
                                       xmsCONTEXT context,
                                       xmsHErrorBlock errorBlock);

Register a message listener function and context data with the message consumer.

For more information about using message listener functions, see Message listener functions in C.

Parameters:
consumer (input)
The handle for the message consumer.
lsr (input)
A pointer to the message listener function. If a message listener function is already registered with the message consumer, you can cancel the registration by specifying a null pointer instead.
context (input)
A pointer to the context data.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

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