proton-c/include/proton/terminus.h

#ifndef PROTON_TERMINUS_H
#define PROTON_TERMINUS_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/type_compat.h>
#include <proton/codec.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/** @file
 *
 * Terminus API for the proton Engine.
 *
 * @defgroup terminus Terminus
 * @ingroup link
 * @{
 */

/**
 * Encapsulates the endpoint state associated with an AMQP Terminus.
 *
 * An AMQP Terminus acts as either a source or target for messages,
 * but never both. Every AMQP link is associated with both a source
 * terminus and a target terminus that is negotiated during link
 * establishment. A terminus consists of an AMQP address, along with a
 * number of other properties defining the quality of service and
 * behaviour of the link.
 */
typedef struct pn_terminus_t pn_terminus_t;

/**
 * Type of an AMQP terminus.
 */
typedef enum {
  PN_UNSPECIFIED = 0, /**< indicates a nonexistent terminus, may used
                         as a source or target */
  PN_SOURCE = 1, /**< indicates a source of messages */
  PN_TARGET = 2, /**< indicates a target for messages */
  PN_COORDINATOR = 3 /**< a special target identifying a transaction
                        coordinator */
} pn_terminus_type_t;

/**
 * Durability mode of an AMQP terminus.
 *
 * An AMQP terminus may provide durable storage for its state, thereby
 * permitting link recovery in the event of endpoint failures. This
 * durability may be applied to the configuration of the terminus
 * only, or to all delivery state as well.
 */
typedef enum {
  PN_NONDURABLE = 0, /**< indicates a non durable terminus */
  PN_CONFIGURATION = 1, /**< indicates a terminus with durably held
                           configuration, but not delivery state */
  PN_DELIVERIES = 2 /**< indicates a terminus with both durably held
                       configuration and durably held delivery
                       state. */
} pn_durability_t;

/**
 * Expiry policy of an AMQP terminus.
 *
 * An orphaned terminus can only exist for the timeout configured by
 * ::pn_terminus_set_timeout. The expiry policy determins when a
 * terminus is considered orphaned, i.e. when the expiry timer starts
 * counting down.
 */
typedef enum {
  PN_EXPIRE_WITH_LINK, /**< the terminus is orphaned when the parent link is closed */
  PN_EXPIRE_WITH_SESSION, /**< the terminus is orphaned when the parent session is closed */
  PN_EXPIRE_WITH_CONNECTION, /**< the terminus is orphaned when the parent connection is closed */
  PN_EXPIRE_NEVER /**< the terminus is never considered orphaned */
} pn_expiry_policy_t;

/**
 * Distribution mode of an AMQP terminus.
 *
 * The distribution mode of a source terminus defines the behaviour
 * when multiple receiving links provide addresses that resolve to the
 * same node.
 */
typedef enum {
  PN_DIST_MODE_UNSPECIFIED = 0, /**< the behaviour is defined by the node */
  PN_DIST_MODE_COPY = 1, /**< the receiver gets all messages */
  PN_DIST_MODE_MOVE = 2 /**< the receiver competes for messages */
} pn_distribution_mode_t;

/**
 * Get the type of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @return the terminus type
 */
PN_EXTERN pn_terminus_type_t pn_terminus_get_type(pn_terminus_t *terminus);

/**
 * Set the type of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @param[in] type the terminus type
 * @return 0 on success or an error code on failure
 */
PN_EXTERN int pn_terminus_set_type(pn_terminus_t *terminus, pn_terminus_type_t type);

/**
 * Get the address of a terminus object.
 *
 * The pointer returned by this operation is valid until
 * ::pn_terminus_set_address is called or until the terminus is freed
 * due to its parent link being freed.
 *
 * @param[in] terminus a terminus object
 * @return a pointer to the address
 */
PN_EXTERN const char *pn_terminus_get_address(pn_terminus_t *terminus);

/**
 * Set the address of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @param[in] address an AMQP address string
 * @return 0 on success or an error code on failure
 */
PN_EXTERN int pn_terminus_set_address(pn_terminus_t *terminus, const char *address);

/**
 * Get the distribution mode of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @return the distribution mode of the terminus
 */
PN_EXTERN pn_distribution_mode_t pn_terminus_get_distribution_mode(const pn_terminus_t *terminus);

/**
 * Set the distribution mode of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @param[in] mode the distribution mode for the terminus
 * @return 0 on success or an error code on failure
 */
PN_EXTERN int pn_terminus_set_distribution_mode(pn_terminus_t *terminus, pn_distribution_mode_t mode);

/**
 * Get the durability mode of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @return the terminus durability mode
 */
PN_EXTERN pn_durability_t pn_terminus_get_durability(pn_terminus_t *terminus);

/**
 * Set the durability mode of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @param[in] durability the terminus durability mode
 * @return 0 on success or an error code on failure
 */
PN_EXTERN int pn_terminus_set_durability(pn_terminus_t *terminus,
                                         pn_durability_t durability);

/**
 * Get the expiry policy of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @return the expiry policy of the terminus
 */
PN_EXTERN pn_expiry_policy_t pn_terminus_get_expiry_policy(pn_terminus_t *terminus);

/**
 * Set the expiry policy of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @param[in] policy the expiry policy for the terminus
 * @return 0 on success or an error code on failure
 */
PN_EXTERN int pn_terminus_set_expiry_policy(pn_terminus_t *terminus, pn_expiry_policy_t policy);

/**
 * Get the timeout of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @return the timeout of the terminus
 */
PN_EXTERN pn_seconds_t pn_terminus_get_timeout(pn_terminus_t *terminus);

/**
 * Set the timeout of a terminus object.
 *
 * @param[in] terminus a terminus object
 * @param[in] timeout the timeout for the terminus
 * @return 0 on success or an error code on failure
 */
PN_EXTERN int pn_terminus_set_timeout(pn_terminus_t *terminus, pn_seconds_t timeout);

/**
 * Get the dynamic flag for a terminus object.
 *
 * @param[in] terminus a terminus object
 * @return true if the dynamic flag is set for the terminus, false otherwise
 */
PN_EXTERN bool pn_terminus_is_dynamic(pn_terminus_t *terminus);

/**
 * Set the dynamic flag for a terminus object.
 *
 * @param[in] terminus a terminus object
 * @param[in] dynamic the dynamic flag for the terminus
 * @return 0 on success or an error code on failure
 */
PN_EXTERN int pn_terminus_set_dynamic(pn_terminus_t *terminus, bool dynamic);

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

/**
 * Access/modify the AMQP capabilities data for a terminus object.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the terminus object is freed due to its parent link
 * being freed. Any data contained by the ::pn_data_t object will be
 * sent as the AMQP capabilities for the parent terminus object. Note
 * that this MUST take the form of an array of symbols to be valid.
 *
 * @param[in] terminus a terminus object
 * @return a pointer to a pn_data_t representing the terminus capabilities
 */
PN_EXTERN pn_data_t *pn_terminus_capabilities(pn_terminus_t *terminus);

/**
 * Access/modify the AMQP outcomes for a terminus object.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the terminus object is freed due to its parent link
 * being freed. Any data contained by the ::pn_data_t object will be
 * sent as the AMQP outcomes for the parent terminus object. Note
 * that this MUST take the form of an array of symbols to be valid.
 *
 * @param[in] terminus a terminus object
 * @return a pointer to a pn_data_t representing the terminus outcomes
 */
PN_EXTERN pn_data_t *pn_terminus_outcomes(pn_terminus_t *terminus);

/**
 * Access/modify the AMQP filter set for a terminus object.
 *
 * This operation will return a pointer to a ::pn_data_t object that
 * is valid until the terminus object is freed due to its parent link
 * being freed. Any data contained by the ::pn_data_t object will be
 * sent as the AMQP filter set for the parent terminus object. Note
 * that this MUST take the form of a symbol keyed map to be valid.
 *
 * @param[in] terminus a source terminus object
 * @return a pointer to a pn_data_t representing the terminus filter set
 */
PN_EXTERN pn_data_t *pn_terminus_filter(pn_terminus_t *terminus);

/**
 * Copy a terminus object.
 *
 * @param[in] terminus the terminus object to be copied into
 * @param[in] src the terminus to be copied from
 * @return 0 on success or an error code on failure
 */
PN_EXTERN int pn_terminus_copy(pn_terminus_t *terminus, pn_terminus_t *src);

/** @}
 */

#ifdef __cplusplus
}
#endif

#endif /* terminus.h */