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.

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

Functions

Summary of functions:
Function Description
xmsConnClose Close the connection.
xmsConnCreateSession Create a session.
xmsConnGetClientID Get the client identifier for the connection.
xmsConnGetExceptionListener Get pointers to the exception listener function and context data that are registered with the connection.
xmsConnGetMetaData Get the metadata for the connection.
xmsConnSetClientID Set a client identifier for the connection.
xmsConnSetExceptionListener Register an exception listener function and context data with the connection.
xmsConnStart Start, or restart, the delivery of incoming messages for the connection.
xmsConnStop Stop the delivery of incoming messages for the connection.

xmsConnClose – Close Connection

Interface:
xmsRC xmsConnClose(xmsHConn *connection,
                   xmsHErrorBlock errorBlock);

Close the connection.

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

Parameters:
connection (input/output)
On input, the handle for the connection. 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

xmsConnCreateSession – Create Session

Interface:
xmsRC xmsConnCreateSession(xmsHConn connection,
                           xmsBOOL transacted,
                           xmsINT acknowledgeMode,
                           xmsHSess *session,
                           xmsHErrorBlock errorBlock);

Create a session.

Parameters:
connection (input)
The handle for the connection.
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.

session (output)
The handle for the session.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsConnGetClientID – Get Client ID

Interface:
xmsRC xmsConnGetClientID(xmsHConn connection,
                         xmsCHAR *clientID,
                         xmsINT length,
                         xmsINT *actualLength,
                         xmsHErrorBlock errorBlock);

Get the client identifier for the connection.

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

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

Parameters:
connection (input)
The handle for the connection.
clientID (output)
The buffer to contain the client identifier.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the client identifier is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the client identifier in bytes. If data conversion is required, this is the length of the client identifier 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

xmsConnGetExceptionListener – Get Exception Listener

Interface:
xmsRC xmsConnGetExceptionListener(xmsHConn connection,
                                  fpXMS_EXCEPTION_CALLBACK *lsr,
                                  xmsCONTEXT *context,
                                  xmsHErrorBlock errorBlock);

Get pointers to the exception listener function and context data that are registered with the connection.

For more information about using exception listener functions, see Using exception listener functions in C.

Parameters:
connection (input)
The handle for the connection.
lsr (output)
A pointer to the exception listener function. If no exception listener function is registered with the connection, the call returns a null pointer.
context (output)
A pointer to the context data. If no exception 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

xmsConnGetMetaData – Get Metadata

Interface:
xmsRC xmsConnGetMetaData(xmsHConn connection,
                         xmsHConnMetaData *connectionMetaData,
                         xmsHErrorBlock errorBlock);

Get the metadata for the connection.

Parameters:
connection (input)
The handle for the connection.
connectionMetaData (output)
The handle for the connection metadata.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsConnSetClientID – Set Client ID

Interface:
xmsRC xmsConnSetClientID(xmsHConn connection,
                         xmsCHAR *clientID,
                         xmsINT length,
                         xmsHErrorBlock errorBlock)

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 function 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 function after this point, the function returns exception XMS_X_ILLEGAL_STATE_EXCEPTION.

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

Parameters:
connection (input)
The handle for the connection.
clientID (input)
The client identifier as a character array.
length (input)
The length of the client identifier in bytes. If the client identifier is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION
  • XMS_X_INVALID_CLIENTID_EXCEPTION

xmsConnSetExceptionListener – Set Exception Listener

Interface:
xmsRC xmsConnSetExceptionListener(xmsHConn connection,
                                  fpXMS_EXCEPTION_CALLBACK lsr,
                                  xmsCONTEXT context,
                                  xmsHErrorBlock errorBlock);

Register an exception listener function and context data with the connection.

For more information about using exception listener functions, see Using exception listener functions in C.

Parameters:
connection (input)
The handle for the connection.
lsr (input)
A pointer to the exception listener function. If an exception listener function is already registered with the connection, 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

xmsConnStart – Start Connection

Interface:
xmsRC xmsConnStart(xmsHConn connection,
                   xmsHErrorBlock errorBlock);

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

Parameters:
connection (input)
The handle for the connection.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsConnStop – Stop Connection

Interface:
xmsRC xmsConnStop(xmsHConn connection,
                  xmsHErrorBlock errorBlock);

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

Parameters:
connection (input)
The handle for the connection.
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: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.