proton-c/include/proton/connection.h

#ifndef PROTON_CONNECTION_H
#define PROTON_CONNECTION_H 1

/*
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 */

#include <proton/import_export.h>
#include <proton/codec.h>
#include <proton/condition.h>
#include <proton/error.h>
#include <proton/type_compat.h>
#include <proton/types.h>

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file
 *
 * Connection API for the proton Engine.
 *
 * @defgroup connection Connection
 * @ingroup engine
 * @{
 */

/**
 * The local @link pn_state_t endpoint state @endlink is uninitialized.
 */
#define PN_LOCAL_UNINIT (1)
/**
 * The local @link pn_state_t endpoint state @endlink is active.
 */
#define PN_LOCAL_ACTIVE (2)
/**
 * The local @link pn_state_t endpoint state @endlink is closed.
 */
#define PN_LOCAL_CLOSED (4)
/**
 * The remote @link pn_state_t endpoint state @endlink is uninitialized.
 */
#define PN_REMOTE_UNINIT (8)
/**
 * The remote @link pn_state_t endpoint state @endlink is active.
 */
#define PN_REMOTE_ACTIVE (16)
/**
 * The remote @link pn_state_t endpoint state @endlink is closed.
 */
#define PN_REMOTE_CLOSED (32)

/**
 * A mask for values of ::pn_state_t that preserves only the local
 * bits of an endpoint's state.
 */
#define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)

/**
 * A mask for values of ::pn_state_t that preserves only the remote
 * bits of an endpoint's state.
 */
#define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)

/**
 * Factory to construct a new Connection.
 *
 * @return pointer to a new connection object.
 */
PN_EXTERN pn_connection_t *pn_connection(void);

/**
 * Free a connection object.
 *
 * When a connection object is freed, all ::pn_session_t, ::pn_link_t,
 * and ::pn_delivery_t objects associated with the connection are also
 * freed.
 *
 * @param[in] connection the connection object to free (or NULL)
 */
PN_EXTERN void pn_connection_free(pn_connection_t *connection);

/**
 * Release a connection object.
 *
 * When a connection object is released, all ::pn_session_t and
 * ::pn_link_t, objects associated with the connection are also
 * released and all ::pn_delivery_t objects are settled.
 *
 * @param[in] connection the connection object to be released
 */
PN_EXTERN void pn_connection_release(pn_connection_t *connection);

/**
 * Get additional error information associated with the connection.
 *
 * Whenever a connection operation fails (i.e. returns an error code),
 * additional error details can be obtained using this function. The
 * error object that is returned may also be used to clear the error
 * condition.
 *
 * The pointer returned by this operation is valid until the
 * connection object is freed.
 *
 * @param[in] connection the connection object
 * @return the connection's error object
 */
PN_EXTERN pn_error_t *pn_connection_error(pn_connection_t *connection);

/**
 * Associate a connection object with an event collector.
 *
 * By associating a connection object with an event collector, key
 * changes in endpoint state are reported to the collector via
 * ::pn_event_t objects that can be inspected and processed. See
 * ::pn_event_t for more details on the kinds of events.
 *
 * Note that by registering a collector, the user is requesting that
 * an indefinite number of events be queued up on his behalf. This
 * means that unless the application eventually processes these
 * events, the storage requirements for keeping them will grow without
 * bound. In other words, don't register a collector with a connection
 * if you never intend to process any of the events.
 *
 * @param[in] connection the connection object
 * @param[in] collector the event collector
 */
PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector);

/**
 * @deprecated
 * Get the application context that is associated with a connection
 * object.
 *
 * The application context for a connection may be set using
 * ::pn_connection_set_context.
 *
 * @param[in] connection the connection whose context is to be returned.
 * @return the application context for the connection object
 */
PN_EXTERN void *pn_connection_get_context(pn_connection_t *connection);

/**
 * @deprecated
 * Set a new application context for a connection object.
 *
 * The application context for a connection object may be retrieved
 * using ::pn_connection_get_context.
 *
 * @param[in] connection the connection object
 * @param[in] context the application context
 */
PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);

/**
 * Get the attachments that are associated with a connection object.
 *
 * @param[in] connection the connection whose attachments are to be returned.
 * @return the attachments for the connection object
 */
PN_EXTERN pn_record_t *pn_connection_attachments(pn_connection_t *connection);

/**
 * Get the endpoint state flags for a connection.
 *
 * @param[in] connection the connection
 * @return the connection's state flags
 */
PN_EXTERN pn_state_t pn_connection_state(pn_connection_t *connection);

/**
 * Open a connection.
 *
 * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
 * will be set.
 *
 * @param[in] connection a connection object
 */
PN_EXTERN void pn_connection_open(pn_connection_t *connection);

/**
 * Close a connection.
 *
 * Once this operation has completed, the PN_LOCAL_CLOSED state flag
 * will be set. This may be called without calling
 * ::pn_connection_open, in this case it is equivalent to calling
 * ::pn_connection_open followed by ::pn_connection_close.
 *
 * @param[in] connection a connection object
 */
PN_EXTERN void pn_connection_close(pn_connection_t *connection);

/**
 * Reset a connection object back to the uninitialized state.
 *
 * Note that this does *not* remove any contained ::pn_session_t,
 * ::pn_link_t, and ::pn_delivery_t objects.
 *
 * @param[in] connection a connection object
 */
PN_EXTERN void pn_connection_reset(pn_connection_t *connection);

/**
 * Get the local condition associated with the connection endpoint.
 *
 * The ::pn_condition_t object retrieved may be modified prior to
 * closing the connection in order to indicate a particular condition
 * exists when the connection closes. This is normally used to
 * communicate error conditions to the remote peer, however it may
 * also be used in non error cases such as redirects. See
 * ::pn_condition_t for more details.
 *
 * The pointer returned by this operation is valid until the
 * connection object is freed.
 *
 * @param[in] connection the connection object
 * @return the connection's local condition object
 */
PN_EXTERN pn_condition_t *pn_connection_condition(pn_connection_t *connection);

/**
 * Get the remote condition associated with the connection endpoint.
 *
 * The ::pn_condition_t object retrieved may be examined in order to
 * determine whether the remote peer was indicating some sort of
 * exceptional condition when the remote connection endpoint was
 * closed. The ::pn_condition_t object returned may not be modified.
 *
 * The pointer returned by this operation is valid until the
 * connection object is freed.
 *
 * @param[in] connection the connection object
 * @return the connection's remote condition object
 */
PN_EXTERN pn_condition_t *pn_connection_remote_condition(pn_connection_t *connection);

/**
 * Get the AMQP Container name advertised by a connection object.
 *
 * The pointer returned by this operation is valid until
 * ::pn_connection_set_container is called, or until the connection
 * object is freed, whichever happens sooner.
 *
 * @param[in] connection the connection object
 * @return a pointer to the container name
 */
PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection);

/**
 * Set the AMQP Container name advertised by a connection object.
 *
 * @param[in] connection the connection object
 * @param[in] container the container name
 */
PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container);

/**
 * Set the authentication username for a client connection
 *
 * It is necessary to set the username and password before binding the connection
 * to a trasnport and it isn't allowed to change them after the binding.
 *
 * If not set then no authentication will be negotiated unless the client
 * sasl layer is explicitly created (this would be for sometting like Kerberos
 * where the credentials are implicit in the environment, or to explicitly use
 * the ANONYMOUS SASL mechanism)
 *
 * @param[in] connection the connection
 * @param[in] user the username
 */
PN_EXTERN void pn_connection_set_user(pn_connection_t *connection, const char *user);

/**
 * Set the authentication password for a client connection
 *
 * It is necessary to set the username and password before binding the connection
 * to a trasnport and it isn't allowed to change them after the binding.
 *
 * Note that the password is write only and has no accessor as the underlying
 * implementation should be zeroing the password after use to avoid the password
 * being present in memory longer than necessary
 *
 * @param[in] connection the connection
 * @param[in] password the password corresponding to the username - this will be copied and zeroed out after use
 */
PN_EXTERN void pn_connection_set_password(pn_connection_t *connection, const char *password);

/**
 * Get the authentication username for a client connection
 *
 * @param[in] connection the connection
 * @return the username passed into the connection
 */
PN_EXTERN const char *pn_connection_get_user(pn_connection_t *connection);

/**
 * Get the value of the AMQP Hostname used by a connection object.
 *
 * The pointer returned by this operation is valid until
 * ::pn_connection_set_hostname is called, or until the connection
 * object is freed, whichever happens sooner.
 *
 * @param[in] connection the connection object
 * @return a pointer to the hostname
 */
PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection);

/**
 * Set the name of the virtual host (either fully qualified or relative) to
 * which this connection is connecting to.  This information may be used by the
 * remote peer to determine the correct back-end service to connect the client
 * to. This value will be sent in the Open performative, and will be used by
 * SSL and SASL layers to identify the peer.
 *
 * @note Note: the virtual host string is passed verbatim, it is not parsed as
 * a URL or modified in any way. It should not contain numeric IP addresses or
 * port numbers unless that is what you intend to send as the virtual host name
 * @param[in] connection the connection object
 * @param[in] hostname the virtual host name
 */
PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);

/**
 * Get the AMQP Container name advertised by the remote connection
 * endpoint.
 *
 * This will return NULL until the ::PN_REMOTE_ACTIVE state is
 * reached. See ::pn_state_t for more details on endpoint state.
 *
 * Any non null pointer returned by this operation will be valid until
 * the connection object is unbound from a transport or freed,
 * whichever happens sooner.
 *
 * @param[in] connection the connection object
 * @return a pointer to the remote container name
 */
PN_EXTERN const char *pn_connection_remote_container(pn_connection_t *connection);

/**
 * Get the AMQP Hostname set by the remote connection endpoint.
 *
 * This will return NULL until the ::PN_REMOTE_ACTIVE state is
 * reached. See ::pn_state_t for more details on endpoint state.
 *
 * Any non null pointer returned by this operation will be valid until
 * the connection object is unbound from a transport or freed,
 * whichever happens sooner.
 *
 * @param[in] connection the connection object
 * @return a pointer to the remote hostname
 */
PN_EXTERN const char *pn_connection_remote_hostname(pn_connection_t *connection);

/**
 * Access/modify the AMQP offered capabilities data for a connection
 * object.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the connection object is freed. Any data contained
 * by the ::pn_data_t object will be sent as the offered capabilites
 * for the parent connection object. Note that this MUST take the form
 * of an array of symbols to be valid.
 *
 * The ::pn_data_t pointer returned is valid until the connection
 * object is freed.
 *
 * @param[in] connection the connection object
 * @return a pointer to a pn_data_t representing the offered capabilities
 */
PN_EXTERN pn_data_t *pn_connection_offered_capabilities(pn_connection_t *connection);

/**
 * Access/modify the AMQP desired capabilities data for a connection
 * object.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the connection object is freed. Any data contained
 * by the ::pn_data_t object will be sent as the desired capabilites
 * for the parent connection object. Note that this MUST take the form
 * of an array of symbols to be valid.
 *
 * The ::pn_data_t pointer returned is valid until the connection
 * object is freed.
 *
 * @param[in] connection the connection object
 * @return a pointer to a pn_data_t representing the desired capabilities
 */
PN_EXTERN pn_data_t *pn_connection_desired_capabilities(pn_connection_t *connection);

/**
 * Access/modify the AMQP properties data for a connection object.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the connection object is freed. Any data contained
 * by the ::pn_data_t object will be sent as the AMQP properties for
 * the parent connection object. Note that this MUST take the form of
 * a symbol keyed map to be valid.
 *
 * The ::pn_data_t pointer returned is valid until the connection
 * object is freed.
 *
 * @param[in] connection the connection object
 * @return a pointer to a pn_data_t representing the connection properties
 */
PN_EXTERN pn_data_t *pn_connection_properties(pn_connection_t *connection);

/**
 * Access the AMQP offered capabilites supplied by the remote
 * connection endpoint.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the connection object is freed. This data object
 * will be empty until the remote connection is opened as indicated by
 * the ::PN_REMOTE_ACTIVE flag.
 *
 * @param[in] connection the connection object
 * @return the remote offered capabilities
 */
PN_EXTERN pn_data_t *pn_connection_remote_offered_capabilities(pn_connection_t *connection);

/**
 * Access the AMQP desired capabilites supplied by the remote
 * connection endpoint.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the connection object is freed. This data object
 * will be empty until the remote connection is opened as indicated by
 * the ::PN_REMOTE_ACTIVE flag.
 *
 * @param[in] connection the connection object
 * @return the remote desired capabilities
 */
PN_EXTERN pn_data_t *pn_connection_remote_desired_capabilities(pn_connection_t *connection);

/**
 * Access the AMQP connection properties supplied by the remote
 * connection endpoint.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the connection object is freed. This data object
 * will be empty until the remote connection is opened as indicated by
 * the ::PN_REMOTE_ACTIVE flag.
 *
 * @param[in] connection the connection object
 * @return the remote connection properties
 */
PN_EXTERN pn_data_t *pn_connection_remote_properties(pn_connection_t *connection);

/**
 * Get the transport bound to a connection object.
 *
 * If the connection is unbound, then this operation will return NULL.
 *
 * @param[in] connection the connection object
 * @return the transport bound to a connection, or NULL if the
 * connection is unbound
 */
PN_EXTERN pn_transport_t *pn_connection_transport(pn_connection_t *connection);

/** @}
 */

#ifdef __cplusplus
}
#endif

#endif /* connection.h */