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.

Inheritance hierarchy:
xms::PropertyContext
   |
   +----xms::MessageConsumer

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

Methods

Summary of methods:
Method Description
close Close the message consumer.
getHandle Get the handle that a C application would use to access the message consumer.
getMessageListener Get a pointer to the message listener that is registered with the message consumer.
getMessageSelector Get the message selector for the message consumer.
isNull Determine whether the MessageConsumer object is a null object.
receive Receive the next message for the message consumer. The call waits indefinitely for a message, or until the message consumer is closed.
receive 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.
receiveNoWait Receive the next message for the message consumer if one is available immediately.
setMessageListener Register a message listener with the message consumer.

close – Close Message Consumer

Interface:
xmsVOID close();

Close the message consumer.

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

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHMsgConsumer getHandle() const;

Get the handle that a C application would use to access the message consumer.

Parameters:
None
Returns:
The handle for the message consumer.
Thread context:
Any
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getMessageListener – Get Message Listener

Interface:
MessageListener * getMessageListener() const;

Get a pointer to the message listener that is registered with the message consumer.

For more information about using message listeners, see Message listeners in C++.

Parameters:
None
Returns:
A pointer to the message listener. If no message listener is registered with the message consumer, the method returns a null pointer.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getMessageSelector – Get Message Selector

Interface:
String getMessageSelector() const;

Get the message selector for the message consumer.

Parameters:
None
Returns:
A String object encapsulating the message selector expression. If data conversion is required, this is the message selector expression after conversion. If the message consumer does not have a message selector, the method returns a null String object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the MessageConsumer object is a null object.

Parameters:
None
Returns:
  • xmsTRUE, if the MessageConsumer object is a null object.
  • xmsFALSE, if the MessageConsumer object is not a null object.
Thread context:
Any
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

receive – Receive

Interface:
Message * receive() const;

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

Parameters:
None
Returns:
A pointer to the Message object. If the message consumer is closed while the call is waiting for a message, the method returns a pointer to a null Message object.
Note: Because the method returns a pointer to an object the application must release the object using the C++ delete operator.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

receive – Receive (with a wait interval)

Interface:
Message * receive(const xmsLONG waitInterval) const;

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:
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.
Returns:
A pointer to the Message object. If no message arrives during the wait interval, or if the message consumer is closed while the call is waiting for a message, the method returns a pointer to a null Message object but throws no exception.
Note: Because the method returns a pointer to an object the application must release the object using the C++ delete operator.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

receiveNoWait – Receive with No Wait

Interface:
Message * receiveNoWait() const;

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

Parameters:
None
Returns:
A pointer to a Message object. If no message is available immediately, the method returns a pointer to a null Message object.
Note: Because the method returns a pointer to an object the application must release the object using the C++ delete operator.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setMessageListener – Set Message Listener

Interface:
xmsVOID setMessageListener(const MessageListener *lsr);

Register a message listener with the message consumer.

For more information about using message listeners, see Message listeners in C++.

Parameters:
lsr (input)
A pointer to the message listener. If a message listener is already registered with the message consumer, you can cancel the registration by specifying a null pointer instead.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Inherited methods


Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

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