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

MQCreateConnection

The MQCreateConnection function creates a connection to the broker.

If you want to connect to the broker over SSL, you must call the MQInitializeSSL() function to initialize the SSL library before you create the connection.


MQCreateConnection
             (MQPropertiesHandle propertiesHandle
             ConstMQString username,
             ConstMQString password,
             ConstMQString clientID,
             MQConnectionExceptionListenerFunc exceptionListener,
             void * listenerCallBackData,
             MQConnectionHandle * connectionHandle);

Return Value

MQStatus. See the MQStatusIsError() function for more information.

Parameters

propertiesHandle

A handle that specifies the properties that determine the behavior of this connection. You must create this handle using the MQCreateProperties function before you try to create a connection. This handle will be invalid after the function returns successfully.

See Table 4–2 for information about connection properties.

username

An MQString specifying the user name to use when connecting to the broker.

The library makes a copy of the username string.

password

An MQString specifying the password to use when connecting to the broker.

The library makes a copy of the password string.

clientID

An MQString used to identify the connection. If you use the connection for a durable consumer, you must specify a non-NULL client identifier.

The library makes a copy of the clientID string.

exceptionListener

A connection-exception callback function used to notify the user that a connection exception has occurred.

listenerCallBackData

A data pointer that can be passed to the connection exceptionListener callback function whenever it is called. The user can set this pointer to any data that may be useful to pass along to the connection exception listener for this connection. Set this to NULL if you do not need to pass data back to the connection exception listener.

connectionHandle

Output parameter for the handle to the connection that is created by this function.

The MQCreateConnection function creates a connection to the broker. The behavior of the connection is specified by key values defined in the properties referenced by the propertiesHandle parameter. You must use the MQCreateProperties function to define these properties.

You cannot change the properties of a connection you have already created. If you need different connection properties, you must close and free the old connection and then create a new connection with the desired properties.

Setting a Client Identifier

To keep track of durable subscriptions, Message Queue uses a unique client identifier that associates a client’s connection with state information maintained by the message service on behalf of the client. By definition, a client identifier is unique, and applies to only one connection at a time.

The messaging service uses a client identifier in combination with a durable subscription name to uniquely identify each durable subscription. If a durable subscriber is inactive at the time that messages are delivered to a topic destination, the broker retains messages for that subscriber and delivers them when the subscriber once again becomes active.

Handling Connection Exceptions

Use the exceptionListener parameter to pass the name of a user-defined callback function that can be called synchronously when a connection exception occurs for this connection. Use the exceptionCallBackData parameter to specify any user data that you want to pass to the callback function.

Common Errors

MQ_INCOMPATIBLE_LIBRARY
MQ_CONNECTION_UNSUPPORTED_TRANSPORT
MQ_COULD_NOT_CREATE_THREAD
MQ_INVALID_CLIENT_ID
MQ_CLIENT_ID_IN_USE
MQ_COULD_NOT_CONNECT_TO_BROKER
MQ_SSL_NOT_INITIALIZED

This error can be returned if MQ_CONNECTION_TYPE_PROPERTY is SSL and you have not called the MQInitializeSSL function before creating this connection.