WebSphere Message Service Clients for C/C++ and .NET, Version 1.2 Operating Systems: Linux, Windows

Connection

A Connection object represents an application's active connection to a broker.

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

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

Methods

Summary of methods:
Method Description
close Close the connection.
createSession Create a session.
getClientID Get the client identifier for the connection.
getExceptionListener Get a pointer to the exception listener that is registered with the connection.
getHandle Get the handle that a C application would use to access the connection.
getMetaData Get the metadata for the connection.
isNull Determine whether the Connection object is a null object.
setClientID Set a client identifier for the connection.
setExceptionListener Register an exception listener with the connection.
start Start, or restart, the delivery of incoming messages for the connection.
stop Stop the delivery of incoming messages for the connection.

close – Close Connection

Interface:
xmsVOID close();

Close the connection.

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

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createSession – Create Session

Interface:
Session createSession(const xmsBOOL transacted,
                      const xmsINT acknowledgeMode);

Create a session.

Parameters:
transacted (input)
The value xmsTRUE means that the session is transacted. The value xmsFALSE means that the session is not transacted.

For a real-time connection to a broker, the value must be xmsFALSE.

acknowledgeMode (input)
Indicates how messages received by an application are acknowledged. The value must be one of the following acknowledgement modes:
  • XMSC_AUTO_ACKNOWLEDGE
  • XMSC_CLIENT_ACKNOWLEDGE
  • XMSC_DUPS_OK_ACKNOWLEDGE
For a real-time connection to a broker, the value must be XMSC_AUTO_ACKNOWLEDGE or XMSC_DUPS_OK_ACKNOWLEDGE

This parameter is ignored if the session is transacted. For more information about acknowledgement modes, see Acknowledging the receipt of messages in a session.

Returns:
The Session object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getClientID – Get Client ID

Interface:
String getClientID() const;

Get the client identifier for the connection.

This method is not valid for a real-time connection to a broker.

Parameters:
None
Returns:
A String object encapsulating the client identifier.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getExceptionListener – Get Exception Listener

Interface:
ExceptionListener * getExceptionListener() const;

Get a pointer to the exception listener that is registered with the connection.

For more information about using exception listeners, see Using exception listeners in C++.

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

getHandle – Get Handle

Interface:
xmsHConn getHandle() const;

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

Parameters:
None
Returns:
The handle for the connection.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getMetaData – Get Metadata

Interface:
ConnectionMetaData getMetaData() const;

Get the metadata for the connection.

Parameters:
None
Returns:
The ConnectionMetaData object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the Connection object is a null object.

Parameters:
None
Returns:
  • xmsTRUE, if the Connection object is a null object.
  • xmsFALSE, if the Connection object is not a null object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setClientID – Set Client ID

Interface:
xmsVOID setClientID(const String & clientID);

Set a client identifier for the connection. A client identifier is used only to support durable subscriptions in the publish/subscribe domain, and is ignored in the point-to-point domain.

If an application calls this method to set a client identifier for a connection, the application must do so immediately after creating the connection, and before performing any other operation on the connection. If the application tries to call the method after this point, the call throws exception XMS_X_ILLEGAL_STATE_EXCEPTION.

This method is not valid for a real-time connection to a broker.

Parameters:
clientID (input)
A String object encapsulating the client identifier.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION
  • XMS_X_INVALID_CLIENTID_EXCEPTION

setExceptionListener – Set Exception Listener

Interface:
xmsVOID setExceptionListener(const ExceptionListener *lsr);

Register an exception listener with the connection.

For more information about using exception listeners, see Using exception listeners in C++.

Parameters:
lsr (input)
A pointer to the exception listener.

If an exception listener is already registered with the connection, you can cancel the registration by specifying a null pointer instead.

Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

start – Start Connection

Interface:
xmsVOID start() const;

Start, or restart, the delivery of incoming messages for the connection. The call is ignored if the connection is already started.

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

stop – Stop Connection

Interface:
xmsVOID stop() const;

Stop the delivery of incoming messages for the connection. The call is ignored if the connection is already stopped.

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Inherited methods


Reference topic

Terms of Use | Rate this page

Last updated: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.