Skip navigation.
Downloads | Product Documentation | Support

# JmsConnection.h File Reference

Describes a JmsConnection handle. More...

`#include <JmsCommon.h>`
`#include <JmsContext.h>`
`#include <JmsMetaData.h>`
`#include <JmsConnectionFactory.h>`
`#include <JmsSession.h>`
`#include <JmsTypes.h>`

Go to the source code of this file.

## Typedefs
typedef JmsConnection | JmsConnection
## Functions
int JMSENTRY | JmsConnectionFactoryCreateConnection (JmsConnectionFactory *connectionFactory, JmsConnection **connection, JMS64I flags)
int JMSENTRY | JmsConnectionCreateSession (JmsConnection *connection, int transacted, int acknowledeMode, JmsSession **session, JMS64I flags)
int JMSENTRY | JmsConnectionGetClientId (JmsConnection *connection, JmsString *clientId, JMS64I flags)
int JMSENTRY | JmsConnectionSetClientId (JmsConnection *connection, JmsString *clientId, JMS64I flags)
int JMSENTRY | JmsConnectionGetMetaData (JmsConnection *connection, JmsMetaData **metaData, JMS64I flags)
int JMSENTRY | JmsConnectionGetExceptionListener (JmsConnection *connection, void(**listener)(JmsException *, void *, JMS64I), void **argument, JMS64I flags)
int JMSENTRY | JmsConnectionSetExceptionListener (JmsConnection *connection, void(*listener)(JmsException *, void *, JMS64I), void *argument, JMS64I flags)
int JMSENTRY | JmsConnectionStart (JmsConnection *connection, JMS64I flags)
int JMSENTRY | JmsConnectionStop (JmsConnection *connection, JMS64I flags)
int JMSENTRY | JmsConnectionClose (JmsConnection *connection, JMS64I flags)

## Detailed Description

Describes a JmsConnection handle.

Author:
  Copyright (c) 2002, BEA Systems, Inc. This file describes the functions that can be performed on a JmsConnection handle A JmsConnection handle corresponds to javax.jms.Connection

## Typedef Documentation

typedef struct JmsConnection JmsConnection

| A connection handle that represents the class javax.jms.Connection

## Function Documentation

int JMSENTRY JmsConnectionClose | ( | JmsConnection * | connection,
|  | JMS64I | flags
| ) |

  | Closes the connection. Since a provider typically allocates significant resources outside the JVM on behalf of a connection, clients should close these resources when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough. Unlike the java close, all sessions, producers, and consumers of a closed connection must be closed explicitly in order to free up their handles. Closing a connection causes all temporary destinations to be deleted. However, all temporary destinations must be explicitly closed in order to free up their handles. When this method is invoked, it should not return until message processing has been shut down in an orderly fashion. This means that all message listeners that may have been running have returned, and that all pending receives have returned. A close terminates all pending message receives on the connection's sessions' consumers. The receives may return with a message or with NULL, depending on whether there was a message available at the time of the close. If one or more of the connection's sessions' message listeners is processing a message at the time when connection close is invoked, all the facilities of the connection and its sessions must remain available to those listeners until they return control to the JMS provider. Closing a connection causes any of its sessions' transactions in progress to be rolled back. In the case where a session's work is coordinated by an external transaction manager, a session's commit and rollback methods are not used and the result of a closed session's work is determined later by the transaction manager. Closing a connection does NOT force an acknowledgment of client-acknowledged sessions. Invoking the acknowledge method of a received message from a closed connection's session must throw an IllegalStateException. Closing a closed connection must NOT throw an exception. Parameters:
  connection | Must be a valid connection handle. May not be NULL
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionCreateSession | ( | JmsConnection * | connection,
|  | int | transacted,
|  | int | acknowledeMode,
|  | JmsSession ** | session,
|  | JMS64I | flags
| ) |

  | Gets a session handle from a connection handle Parameters:
  connection | Must be a valid connection handle. May not be NULL
  transacted | If not zero, this session will be transacted. If zero, this session will not be transacted
  acknowledgeMode | One of the following values AUTO_ACKNOWLEDGE Messages will be automatically acknoweldged CLIENT_ACKNOWLEDGE The user must explicitly acknowledge messages DUPS_OK_ACKNOWLEDGE Messages will be automatically acknowledged, and duplicate messages are allowable
  session | May not be NULL. On success *session will contain a valid JmsSession handle
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionFactoryCreateConnection | ( | JmsConnectionFactory * | connectionFactory,
|  | JmsConnection ** | connection,
|  | JMS64I | flags
| ) |

  | Gets a connection handle from a connection factory handle Parameters:
  connectionFactory | Must be a valid connection factory handle. May not be NULL
  connection | May not be NULL. On success *connection will contain a valid JmsConnection handle
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionGetClientId | ( | JmsConnection * | connection,
|  | JmsString * | clientId,
|  | JMS64I | flags
| ) |

  | Gets the client identifier associated with this connection handle Parameters:
  connection | Must be a valid connection handle. May not be NULL
  clientId | Must not be NULL. On success will contain the client identifier
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionGetExceptionListener | ( | JmsConnection * | connection,
|  | void(** | listener)(JmsException *, void *, JMS64I),
|  | void ** | argument,
|  | JMS64I | flags
| ) |

  | Gets a the exception listener function associated with this connection Parameters:
  connection | Must be a valid connection handle. May not be NULL
  listener | May not be NULL. On success *listener will contain the exception listener function
  argument | May not be NULL. On success *argument will contain the application supplied argument used for this connection
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionGetMetaData | ( | JmsConnection * | connection,
|  | JmsMetaData ** | metaData,
|  | JMS64I | flags
| ) |

  | Gets a meta data handle associated with this connection Parameters:
  connection | Must be a valid connection handle. May not be NULL
  metaData | May not be NULL. On success *metaData will contain a valid meta data handle
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionSetClientId | ( | JmsConnection * | connection,
|  | JmsString * | clientId,
|  | JMS64I | flags
| ) |

  | Sets the client identifier associated with this connection handle Parameters:
  connection | Must be a valid connection handle. May not be NULL
  clientId | Must not be NULL. The client identifier to set on this handle
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionSetExceptionListener | ( | JmsConnection * | connection,
|  | void(* | listener)(JmsException *, void *, JMS64I),
|  | void * | argument,
|  | JMS64I | flags
| ) |

  | Sets an exception listener function associated with this connection The exception passed into the listener function is destroyed by the system. Hence the exception should not be freed by the listener function and should not be referenced after the listener function returns Parameters:
  connection | Must be a valid connection handle. May not be NULL
  listener | The function that should be called in the event an exception happens on this connection. The exception passed into the function will normally be freed by the system when the function returns (see flags). The second argument to the function is an application defined argument.
  argument | The argument to be passed as the second parameter to the exception listener. The application can use this for any reason.
  flags | JMS_APPLICATION_MUST_FREE_HANDLE should be set if the exception handle given to the listener function should not be freed by the system when the function returns. The flags value (plus the JMS_CALLED_FROM_JMS flag) will be passed to the listener function as its flags input parameter on every invokation.
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionStart | ( | JmsConnection * | connection,
|  | JMS64I | flags
| ) |

  | Starts (or restarts) a connection's delivery of incoming messages. A call to start on a connection that has already been started is ignored Parameters:
  connection | Must be a valid connection handle. May not be NULL
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR

int JMSENTRY JmsConnectionStop | ( | JmsConnection * | connection,
|  | JMS64I | flags
| ) |

  | Temporarily stops a connection's delivery of incoming messages. Delivery can be restarted using the connection's start method. When the connection is stopped, delivery to all the connection's message consumers is inhibited: synchronous receives block, and messages are not delivered to message listeners. This call blocks until receives and/or message listeners in progress have completed. Stopping a connection has no effect on its ability to send messages. A call to stop on a connection that has already been stopped is ignored. A call to stop must not return until delivery of messages has paused. This means that a client can rely on the fact that none of its message listeners will be called and that all threads of control waiting for receive calls to return will not return with a message until the connection is restarted. The receive timers for a stopped connection continue to advance, so receives may time out while the connection is stopped. If message listeners are running when stop is invoked, the stop call must wait until all of them have returned before it may return. While these message listeners are completing, they must have the full services of the connection available to them. Parameters:
  connection | Must be a valid connection handle. May not be NULL
  flags | Reserved for future use. Must be zero
Returns: JMS_NO_ERROR JMS_GOT_EXCEPTION JMS_INPUT_PARAM_ERROR JMS_MALLOC_ERROR JMS_JVM_ERROR