http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/37136940/c/include/proton/codec.h ---------------------------------------------------------------------- diff --git a/c/include/proton/codec.h b/c/include/proton/codec.h new file mode 100644 index 0000000..1755f53 --- /dev/null +++ b/c/include/proton/codec.h @@ -0,0 +1,1294 @@ +#ifndef PROTON_CODEC_H +#define PROTON_CODEC_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/object.h> +#include <proton/types.h> +#include <proton/error.h> +#include <proton/type_compat.h> +#include <stdarg.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @file + * + * @copybrief codec + */ + +/** + * Identifies an AMQP type. + * + * @ingroup amqp_types + */ +typedef enum { + /** + * The NULL AMQP type. + */ + PN_NULL = 1, + + /** + * The boolean AMQP type. + */ + PN_BOOL = 2, + + /** + * The unsigned byte AMQP type. An 8 bit unsigned integer. + */ + PN_UBYTE = 3, + + /** + * The byte AMQP type. An 8 bit signed integer. + */ + PN_BYTE = 4, + + /** + * The unsigned short AMQP type. A 16 bit unsigned integer. + */ + PN_USHORT = 5, + + /** + * The short AMQP type. A 16 bit signed integer. + */ + PN_SHORT = 6, + + /** + * The unsigned int AMQP type. A 32 bit unsigned integer. + */ + PN_UINT = 7, + + /** + * The signed int AMQP type. A 32 bit signed integer. + */ + PN_INT = 8, + + /** + * The char AMQP type. A 32 bit unicode character. + */ + PN_CHAR = 9, + + /** + * The ulong AMQP type. An unsigned 32 bit integer. + */ + PN_ULONG = 10, + + /** + * The long AMQP type. A signed 32 bit integer. + */ + PN_LONG = 11, + + /** + * The timestamp AMQP type. A signed 64 bit value measuring + * milliseconds since the epoch. + */ + PN_TIMESTAMP = 12, + + /** + * The float AMQP type. A 32 bit floating point value. + */ + PN_FLOAT = 13, + + /** + * The double AMQP type. A 64 bit floating point value. + */ + PN_DOUBLE = 14, + + /** + * The decimal32 AMQP type. A 32 bit decimal floating point value. + */ + PN_DECIMAL32 = 15, + + /** + * The decimal64 AMQP type. A 64 bit decimal floating point value. + */ + PN_DECIMAL64 = 16, + + /** + * The decimal128 AMQP type. A 128 bit decimal floating point value. + */ + PN_DECIMAL128 = 17, + + /** + * The UUID AMQP type. A 16 byte UUID. + */ + PN_UUID = 18, + + /** + * The binary AMQP type. A variable length sequence of bytes. + */ + PN_BINARY = 19, + + /** + * The string AMQP type. A variable length sequence of unicode + * characters. + */ + PN_STRING = 20, + + /** + * The symbol AMQP type. A variable length sequence of unicode + * characters. + */ + PN_SYMBOL = 21, + + /** + * A described AMQP type. + */ + PN_DESCRIBED = 22, + + /** + * An AMQP array. A monomorphic sequence of other AMQP values. + */ + PN_ARRAY = 23, + + /** + * An AMQP list. A polymorphic sequence of other AMQP values. + */ + PN_LIST = 24, + + /** + * An AMQP map. A polymorphic container of other AMQP values formed + * into key/value pairs. + */ + PN_MAP = 25, + + /** + * A special invalid type value that is returned when no valid type + * is available. + */ + PN_INVALID = -1 +} pn_type_t; + +/** + * Return a string name for an AMQP type. + * + * @ingroup amqp_types + * @param type an AMQP type + * @return the string name of the given type + */ +PN_EXTERN const char *pn_type_name(pn_type_t type); + +/** + * A discriminated union that holds any scalar AMQP value. The type + * field indicates the AMQP type of the value, and the union may be + * used to access the value for a given type. + * + * @ingroup api_types + */ +typedef struct { + /** + * Indicates the type of value the atom is currently pointing to. + * See ::pn_type_t for details on AMQP types. + */ + pn_type_t type; + union { + /** + * Valid when type is ::PN_BOOL. + */ + bool as_bool; + + /** + * Valid when type is ::PN_UBYTE. + */ + uint8_t as_ubyte; + + /** + * Valid when type is ::PN_BYTE. + */ + int8_t as_byte; + + /** + * Valid when type is ::PN_USHORT. + */ + uint16_t as_ushort; + + /** + * Valid when type is ::PN_SHORT. + */ + int16_t as_short; + + /** + * Valid when type is ::PN_UINT. + */ + uint32_t as_uint; + + /** + * Valid when type is ::PN_INT. + */ + int32_t as_int; + + /** + * Valid when type is ::PN_CHAR. + */ + pn_char_t as_char; + + /** + * Valid when type is ::PN_ULONG. + */ + uint64_t as_ulong; + + /** + * Valid when type is ::PN_LONG. + */ + int64_t as_long; + + /** + * Valid when type is ::PN_TIMESTAMP. + */ + pn_timestamp_t as_timestamp; + + /** + * Valid when type is ::PN_FLOAT. + */ + float as_float; + + /** + * Valid when type is ::PN_DOUBLE. + */ + double as_double; + + /** + * Valid when type is ::PN_DECIMAL32. + */ + pn_decimal32_t as_decimal32; + + /** + * Valid when type is ::PN_DECIMAL64. + */ + pn_decimal64_t as_decimal64; + + /** + * Valid when type is ::PN_DECIMAL128. + */ + pn_decimal128_t as_decimal128; + + /** + * Valid when type is ::PN_UUID. + */ + pn_uuid_t as_uuid; + + /** + * Valid when type is ::PN_BINARY or ::PN_STRING or ::PN_SYMBOL. + * When the type is ::PN_STRING the field will point to utf8 + * encoded unicode. When the type is ::PN_SYMBOL, the field will + * point to 7-bit ASCII. In the latter two cases, the bytes + * pointed to are *not* necessarily null terminated. + */ + pn_bytes_t as_bytes; + } u; +} pn_atom_t; + +/** + * @addtogroup data + * @{ + */ + +/** + * An AMQP Data object. + * + * A pn_data_t object provides an interface for decoding, extracting, + * creating, and encoding arbitrary AMQP data. A pn_data_t object + * contains a tree of AMQP values. Leaf nodes in this tree correspond + * to scalars in the AMQP type system such as @link ::PN_INT ints + * @endlink or @link ::PN_STRING strings @endlink. Non-leaf nodes in + * this tree correspond to compound values in the AMQP type system + * such as @link ::PN_LIST lists @endlink, @link ::PN_MAP maps + * @endlink, @link ::PN_ARRAY arrays @endlink, or @link ::PN_DESCRIBED + * described @endlink values. The root node of the tree is the + * pn_data_t object itself and can have an arbitrary number of + * children. + * + * A pn_data_t object maintains the notion of the current node and the + * current parent node. Siblings are ordered within their parent. + * Values are accessed and/or added by using the ::pn_data_next(), + * ::pn_data_prev(), ::pn_data_enter(), and ::pn_data_exit() + * operations to navigate to the desired location in the tree and + * using the supplied variety of pn_data_put_* / pn_data_get_* + * operations to access or add a value of the desired type. + * + * The pn_data_put_* operations will always add a value _after_ the + * current node in the tree. If the current node has a next sibling + * the pn_data_put_* operations will overwrite the value on this node. + * If there is no current node or the current node has no next sibling + * then one will be added. The pn_data_put_* operations always set the + * added/modified node to the current node. The pn_data_get_* + * operations read the value of the current node and do not change + * which node is current. + * + * The following types of scalar values are supported: + * + * - ::PN_NULL + * - ::PN_BOOL + * - ::PN_UBYTE + * - ::PN_USHORT + * - ::PN_SHORT + * - ::PN_UINT + * - ::PN_INT + * - ::PN_ULONG + * - ::PN_LONG + * - ::PN_FLOAT + * - ::PN_DOUBLE + * - ::PN_BINARY + * - ::PN_STRING + * - ::PN_SYMBOL + * + * The following types of compound values are supported: + * + * - ::PN_DESCRIBED + * - ::PN_ARRAY + * - ::PN_LIST + * - ::PN_MAP + */ +typedef struct pn_data_t pn_data_t; + +/** + * Construct a pn_data_t object with the supplied initial capacity. A + * pn_data_t will grow automatically as needed, so an initial capacity + * of 0 is permitted. + * + * @param capacity the initial capacity + * @return the newly constructed pn_data_t + */ +PN_EXTERN pn_data_t *pn_data(size_t capacity); + +/** + * Free a pn_data_t object. + * + * @param data a pn_data_t object or NULL + */ +PN_EXTERN void pn_data_free(pn_data_t *data); + +/** + * Access the current error code for a given pn_data_t. + * + * @param data a pn_data_t object + * @return the current error code + */ +PN_EXTERN int pn_data_errno(pn_data_t *data); + +/** + * Access the current error for a given pn_data_t. + * + * Every pn_data_t has an error descriptor that is created with the + * pn_data_t and dies with the pn_data_t. The error descriptor is + * updated whenever an operation fails. The ::pn_data_error() function + * may be used to access a pn_data_t's error descriptor. + * + * @param data a pn_data_t object + * @return a pointer to the pn_data_t's error descriptor + */ +PN_EXTERN pn_error_t *pn_data_error(pn_data_t *data); + +/** + * @cond INTERNAL + */ +PN_EXTERN int pn_data_vfill(pn_data_t *data, const char *fmt, va_list ap); +PN_EXTERN int pn_data_fill(pn_data_t *data, const char *fmt, ...); +PN_EXTERN int pn_data_vscan(pn_data_t *data, const char *fmt, va_list ap); +PN_EXTERN int pn_data_scan(pn_data_t *data, const char *fmt, ...); +/** + * @endcond + */ + +/** + * Clears a pn_data_t object. + * + * A cleared pn_data_t object is equivalent to a newly constructed + * one. + * + * @param data the pn_data_t object to clear + */ +PN_EXTERN void pn_data_clear(pn_data_t *data); + +/** + * Returns the total number of nodes contained in a pn_data_t object. + * This includes all parents, children, siblings, grandchildren, etc. + * In other words the count of all ancestors and descendants of the + * current node, along with the current node if there is one. + * + * @param data a pn_data_t object + * @return the total number of nodes in the pn_data_t object + */ +PN_EXTERN size_t pn_data_size(pn_data_t *data); + +/** + * Clears current node pointer and sets the parent to the root node. + * Clearing the current node sets it _before_ the first node, calling + * ::pn_data_next() will advance to the first node. + */ +PN_EXTERN void pn_data_rewind(pn_data_t *data); + +/** + * Advances the current node to its next sibling and returns true. If + * there is no next sibling the current node remains unchanged and + * false is returned. + * + * @param data a pn_data_t object + * @return true iff the current node was changed + */ +PN_EXTERN bool pn_data_next(pn_data_t *data); + +/** + * Moves the current node to its previous sibling and returns true. If + * there is no previous sibling the current node remains unchanged and + * false is returned. + * + * @param data a pn_data_t object + * @return true iff the current node was changed + */ +PN_EXTERN bool pn_data_prev(pn_data_t *data); + +/** + * Sets the parent node to the current node and clears the current + * node. Clearing the current node sets it _before_ the first child, + * calling ::pn_data_next() advances to the first child. This + * operation will return false if there is no current node or if the + * current node is not a compound type. + * + * @param data a pn_data_object + * @return true iff the pointers to the current/parent nodes are changed + */ +PN_EXTERN bool pn_data_enter(pn_data_t *data); + +/** + * Sets the current node to the parent node and the parent node to its + * own parent. This operation will return false if there is no current + * node or parent node. + * + * @param data a pn_data object + * @return true iff the pointers to the current/parent nodes are + * changed + */ +PN_EXTERN bool pn_data_exit(pn_data_t *data); + +/** + * @cond INTERNAL + */ +PN_EXTERN bool pn_data_lookup(pn_data_t *data, const char *name); +/** + * @endcond + */ + +/** + * Access the type of the current node. Returns PN_INVALID if there is no + * current node. + * + * @param data a data object + * @return the type of the current node + */ +PN_EXTERN pn_type_t pn_data_type(pn_data_t *data); + +/** + * Prints the contents of a pn_data_t object using ::pn_data_format() + * to stdout. + * + * @param data a pn_data_t object + * @return zero on success or an error on failure + */ +PN_EXTERN int pn_data_print(pn_data_t *data); + +/** + * Formats the contents of a pn_data_t object in a human readable way + * and writes them to the indicated location. The size pointer must + * hold the amount of free space following the bytes pointer, and upon + * success will be updated to indicate how much space has been used. + * + * @param data a pn_data_t object + * @param bytes a buffer to write the output to + * @param size a pointer to the size of the buffer + * @return zero on success, or an error on failure + */ +PN_EXTERN int pn_data_format(pn_data_t *data, char *bytes, size_t *size); + +/** + * Writes the contents of a data object to the given buffer as an AMQP + * data stream. + * + * @param data the data object to encode + * @param bytes the buffer for encoded data + * @param size the size of the buffer + * + * @return the size of the encoded data on success or an error code on failure + */ +PN_EXTERN ssize_t pn_data_encode(pn_data_t *data, char *bytes, size_t size); + +/** + * Returns the number of bytes needed to encode a data object. + * + * @param data the data object + * + * @return the size of the encoded data or an error code if data is invalid. + */ +PN_EXTERN ssize_t pn_data_encoded_size(pn_data_t *data); + +/** + * Decodes a single value from the contents of the AMQP data stream + * into the current data object. Note that if the pn_data_t object is + * pointing to a current node, the decoded value will overwrite the + * current one. If the pn_data_t object has no current node then a + * node will be appended to the current parent. If there is no current + * parent then a node will be appended to the pn_data_t itself. + * + * Upon success, this operation returns the number of bytes consumed + * from the AMQP data stream. Upon failure, this operation returns an + * error code. + * + * @param data a pn_data_t object + * @param bytes a pointer to an encoded AMQP data stream + * @param size the size of the encoded AMQP data stream + * @return the number of bytes consumed from the AMQP data stream or an error code + */ +PN_EXTERN ssize_t pn_data_decode(pn_data_t *data, const char *bytes, size_t size); + +/** + * Puts an empty list value into a pn_data_t. Elements may be filled + * by entering the list node using ::pn_data_enter() and using + * pn_data_put_* to add the desired contents. Once done, + * ::pn_data_exit() may be used to return to the current level in the + * tree and put more values. + * + * @code + * pn_data_t *data = pn_data(0); + * ... + * pn_data_put_list(data); + * pn_data_enter(data); + * pn_data_put_int(data, 1); + * pn_data_put_int(data, 2); + * pn_data_put_int(data, 3); + * pn_data_exit(data); + * ... + * @endcode + * + * @param data a pn_data_t object + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_list(pn_data_t *data); + +/** + * Puts an empty map value into a pn_data_t. Elements may be filled by + * entering the map node and putting alternating key value pairs. + * + * @code + * pn_data_t *data = pn_data(0); + * ... + * pn_data_put_map(data); + * pn_data_enter(data); + * pn_data_put_string(data, pn_bytes(3, "key")); + * pn_data_put_string(data, pn_bytes(5, "value")); + * pn_data_exit(data); + * ... + * @endcode + * + * @param data a pn_data_t object + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_map(pn_data_t *data); + +/** + * Puts an empty array value into a pn_data_t. Elements may be filled + * by entering the array node and putting the element values. The + * values must all be of the specified array element type. If an array + * is described then the first child value of the array is the + * descriptor and may be of any type. + * + * @code + * pn_data_t *data = pn_data(0); + * ... + * pn_data_put_array(data, false, PN_INT); + * pn_data_enter(data); + * pn_data_put_int(data, 1); + * pn_data_put_int(data, 2); + * pn_data_put_int(data, 3); + * pn_data_exit(data); + * ... + * pn_data_put_array(data, True, Data.DOUBLE); + * pn_data_enter(data); + * pn_data_put_symbol(data, "array-descriptor"); + * pn_data_put_double(data, 1.1); + * pn_data_put_double(data, 1.2); + * pn_data_put_double(data, 1.3); + * pn_data_exit(data); + * ... + * @endcode + * + * @param data a pn_data_t object + * @param described specifies whether the array is described + * @param type the type of the array + * + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_array(pn_data_t *data, bool described, pn_type_t type); + +/** + * Puts a described value into a pn_data_t object. A described node + * has two children, the descriptor and the value. These are specified + * by entering the node and putting the desired values. + * + * @code + * pn_data_t *data = pn_data(0); + * ... + * pn_data_put_described(data); + * pn_data_enter(data); + * pn_data_put_symbol(data, pn_bytes(16, "value-descriptor")); + * pn_data_put_string(data, pn_bytes(9, "the value")); + * pn_data_exit(data); + * ... + * @endcode + * + * @param data a pn_data_t object + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_described(pn_data_t *data); + +/** + * Puts a ::PN_NULL value. + * + * @param data a pn_data_t object + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_null(pn_data_t *data); + +/** + * Puts a ::PN_BOOL value. + * + * @param data a pn_data_t object + * @param b the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_bool(pn_data_t *data, bool b); + +/** + * Puts a ::PN_UBYTE value. + * + * @param data a pn_data_t object + * @param ub the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_ubyte(pn_data_t *data, uint8_t ub); + +/** + * Puts a ::PN_BYTE value. + * + * @param data a pn_data_t object + * @param b the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_byte(pn_data_t *data, int8_t b); + +/** + * Puts a ::PN_USHORT value. + * + * @param data a pn_data_t object + * @param us the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_ushort(pn_data_t *data, uint16_t us); + +/** + * Puts a ::PN_SHORT value. + * + * @param data a pn_data_t object + * @param s the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_short(pn_data_t *data, int16_t s); + +/** + * Puts a ::PN_UINT value. + * + * @param data a pn_data_t object + * @param ui the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_uint(pn_data_t *data, uint32_t ui); + +/** + * Puts a ::PN_INT value. + * + * @param data a pn_data_t object + * @param i the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_int(pn_data_t *data, int32_t i); + +/** + * Puts a ::PN_CHAR value. + * + * @param data a pn_data_t object + * @param c the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_char(pn_data_t *data, pn_char_t c); + +/** + * Puts a ::PN_ULONG value. + * + * @param data a pn_data_t object + * @param ul the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_ulong(pn_data_t *data, uint64_t ul); + +/** + * Puts a ::PN_LONG value. + * + * @param data a pn_data_t object + * @param l the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_long(pn_data_t *data, int64_t l); + +/** + * Puts a ::PN_TIMESTAMP value. + * + * @param data a pn_data_t object + * @param t the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_timestamp(pn_data_t *data, pn_timestamp_t t); + +/** + * Puts a ::PN_FLOAT value. + * + * @param data a pn_data_t object + * @param f the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_float(pn_data_t *data, float f); + +/** + * Puts a ::PN_DOUBLE value. + * + * @param data a pn_data_t object + * @param d the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_double(pn_data_t *data, double d); + +/** + * Puts a ::PN_DECIMAL32 value. + * + * @param data a pn_data_t object + * @param d the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_decimal32(pn_data_t *data, pn_decimal32_t d); + +/** + * Puts a ::PN_DECIMAL64 value. + * + * @param data a pn_data_t object + * @param d the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_decimal64(pn_data_t *data, pn_decimal64_t d); + +/** + * Puts a ::PN_DECIMAL128 value. + * + * @param data a pn_data_t object + * @param d the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_decimal128(pn_data_t *data, pn_decimal128_t d); + +/** + * Puts a ::PN_UUID value. + * + * @param data a pn_data_t object + * @param u the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_uuid(pn_data_t *data, pn_uuid_t u); + +/** + * Puts a ::PN_BINARY value. The bytes referenced by the pn_bytes_t + * argument are copied and stored inside the pn_data_t object. + * + * @param data a pn_data_t object + * @param bytes the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_binary(pn_data_t *data, pn_bytes_t bytes); + +/** + * Puts a ::PN_STRING value. The bytes referenced by the pn_bytes_t + * argument are copied and stored inside the pn_data_t object. + * + * @param data a pn_data_t object + * @param string utf8 encoded unicode + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_string(pn_data_t *data, pn_bytes_t string); + +/** + * Puts a ::PN_SYMBOL value. The bytes referenced by the pn_bytes_t + * argument are copied and stored inside the pn_data_t object. + * + * @param data a pn_data_t object + * @param symbol ascii encoded symbol + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_symbol(pn_data_t *data, pn_bytes_t symbol); + +/** + * Puts any scalar value value. + * + * @param data a pn_data_t object + * @param atom the value + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_put_atom(pn_data_t *data, pn_atom_t atom); + +/** + * If the current node is a list, return the number of elements, + * otherwise return zero. List elements can be accessed by entering + * the list. + * + * @code + * ... + * size_t count = pn_data_get_list(data); + * pn_data_enter(data); + * for (size_t i = 0; i < count; i++) { + * if (pn_data_next(data)) { + * switch (pn_data_type(data)) { + * case PN_STRING: + * ... + * break; + * case PN_INT: + * ... + * break; + * } + * } + * pn_data_exit(data); + * ... + * @endcode +.* + * @param data a pn_data_t object + * @return the size of a list node + */ +PN_EXTERN size_t pn_data_get_list(pn_data_t *data); + +/** + * If the current node is a map, return the number of child elements, + * otherwise return zero. Key value pairs can be accessed by entering + * the map. + * + * @code + * ... + * size_t count = pn_data_get_map(data); + * pn_data_enter(data); + * for (size_t i = 0; i < count/2; i++) { + * // read key + * if (pn_data_next(data)) { + * switch (pn_data_type(data)) { + * case PN_STRING: + * ... + * break; + * ... + * } + * } + * ... + * // read value + * if (pn_data_next(data)) { + * switch (pn_data_type(data)) { + * case PN_INT: + * ... + * break; + * ... + * } + * } + * ... + * } + * pn_data_exit(data); + * ... + * @endcode + * + * @param data a pn_data_t object + * @return the number of child elements of a map node + */ +PN_EXTERN size_t pn_data_get_map(pn_data_t *data); + +/** + * If the current node is an array, return the number of elements in + * the array, otherwise return 0. Array data can be accessed by + * entering the array. If the array is described, the first child node + * will be the descriptor, and the remaining count child nodes + * will be the elements of the array. + * + * @code + * ... + * size_t count = pn_data_get_array(data); + * bool described = pn_data_is_array_described(data); + * pn_type_t type = pn_data_get_array_type(data); + * + * pn_data_enter(data); + * + * if (described && pn_data_next(data)) { + * // the descriptor could be another type, but let's assume it's a symbol + * pn_bytes_t descriptor = pn_data_get_symbol(data); + * } + * + * for (size_t i = 0; i < count; i++) { + * if (pn_data_next(data)) { + * // all elements will be values of the array type retrieved above + * ... + * } + * } + * pn_data_exit(data); + * ... + * @endcode + * + * @param data a pn_data_t object + * @return the number of elements of an array node + */ +PN_EXTERN size_t pn_data_get_array(pn_data_t *data); + +/** + * Returns true if the current node points to a described array. + * + * @param data a pn_data_t object + * @return true if the current node points to a described array + */ +PN_EXTERN bool pn_data_is_array_described(pn_data_t *data); + +/** + * Return the array type if the current node points to an array, + * PN_INVALID otherwise. + * + * @param data a pn_data_t object + * @return the element type of an array node + */ +PN_EXTERN pn_type_t pn_data_get_array_type(pn_data_t *data); + +/** + * Checks if the current node is a described value. The descriptor and + * value may be accessed by entering the described value node. + * + * @code + * ... + * // read a symbolically described string + * if (pn_data_is_described(data)) { + * pn_data_enter(data); + * pn_data_next(data); + * assert(pn_data_type(data) == PN_SYMBOL); + * pn_bytes_t symbol = pn_data_get_symbol(data); + * pn_data_next(data); + * assert(pn_data_type(data) == PN_STRING); + * pn_bytes_t utf8 = pn_data_get_string(data); + * pn_data_exit(data); + * } + * ... + * @endcode + * + * @param data a pn_data_t object + * @return true if the current node is a described type + */ +PN_EXTERN bool pn_data_is_described(pn_data_t *data); + +/** + * Checks if the current node is a ::PN_NULL. + * + * @param data a pn_data_t object + * @return true iff the current node is ::PN_NULL + */ +PN_EXTERN bool pn_data_is_null(pn_data_t *data); + +/** + * If the current node is a ::PN_BOOL, returns its value. + * + * @param data a pn_data_t object + */ +PN_EXTERN bool pn_data_get_bool(pn_data_t *data); + +/** + * If the current node is a ::PN_UBYTE, return its value, otherwise + * return 0. + * + * @param data a pn_data_t object + */ +PN_EXTERN uint8_t pn_data_get_ubyte(pn_data_t *data); + +/** + * If the current node is a signed byte, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN int8_t pn_data_get_byte(pn_data_t *data); + +/** + * If the current node is an unsigned short, returns its value, + * returns 0 otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN uint16_t pn_data_get_ushort(pn_data_t *data); + +/** + * If the current node is a signed short, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN int16_t pn_data_get_short(pn_data_t *data); + +/** + * If the current node is an unsigned int, returns its value, returns + * 0 otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN uint32_t pn_data_get_uint(pn_data_t *data); + +/** + * If the current node is a signed int, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN int32_t pn_data_get_int(pn_data_t *data); + +/** + * If the current node is a char, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN pn_char_t pn_data_get_char(pn_data_t *data); + +/** + * If the current node is an unsigned long, returns its value, returns + * 0 otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN uint64_t pn_data_get_ulong(pn_data_t *data); + +/** + * If the current node is an signed long, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN int64_t pn_data_get_long(pn_data_t *data); + +/** + * If the current node is a timestamp, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN pn_timestamp_t pn_data_get_timestamp(pn_data_t *data); + +/** + * If the current node is a float, returns its value, raises 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN float pn_data_get_float(pn_data_t *data); + +/** + * If the current node is a double, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN double pn_data_get_double(pn_data_t *data); + +/** + * If the current node is a decimal32, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN pn_decimal32_t pn_data_get_decimal32(pn_data_t *data); + +/** + * If the current node is a decimal64, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN pn_decimal64_t pn_data_get_decimal64(pn_data_t *data); + +/** + * If the current node is a decimal128, returns its value, returns 0 + * otherwise. + * + * @param data a pn_data_t object + */ +PN_EXTERN pn_decimal128_t pn_data_get_decimal128(pn_data_t *data); + +/** + * If the current node is a UUID, returns its value, returns None + * otherwise. + * + * @param data a pn_data_t object + * @return a uuid value + */ +PN_EXTERN pn_uuid_t pn_data_get_uuid(pn_data_t *data); + +/** + * If the current node is binary, returns its value, returns "" + * otherwise. The pn_bytes_t returned will point to memory held inside + * the pn_data_t. When the pn_data_t is cleared or freed, this memory + * will be reclaimed. + * + * @param data a pn_data_t object + */ +PN_EXTERN pn_bytes_t pn_data_get_binary(pn_data_t *data); + +/** + * If the current node is a string, returns its value, returns "" + * otherwise. The pn_bytes_t returned will point to memory held inside + * the pn_data_t. When the pn_data_t is cleared or freed, this memory + * will be reclaimed. + * + * @param data a pn_data_t object + * @return a pn_bytes_t pointing to utf8 + */ +PN_EXTERN pn_bytes_t pn_data_get_string(pn_data_t *data); + +/** + * If the current node is a symbol, returns its value, returns "" + * otherwise. The pn_bytes_t returned will point to memory held inside + * the pn_data_t. When the pn_data_t is cleared or freed, this memory + * will be reclaimed. + * + * @param data a pn_data_t object + * @return a pn_bytes_t pointing to ascii + */ +PN_EXTERN pn_bytes_t pn_data_get_symbol(pn_data_t *data); + +/** + * If the current node is a symbol, string, or binary, return the + * bytes representing its value. The pn_bytes_t returned will point to + * memory held inside the pn_data_t. When the pn_data_t is cleared or + * freed, this memory will be reclaimed. + * + * @param data a pn_data_t object + * @return a pn_bytes_t pointing to the node's value + */ +PN_EXTERN pn_bytes_t pn_data_get_bytes(pn_data_t *data); + +/** + * If the current node is a scalar value, return it as a pn_atom_t. + * + * @param data a pn_data_t object + * @return the value of the current node as pn_atom_t + */ +PN_EXTERN pn_atom_t pn_data_get_atom(pn_data_t *data); + +/** + * Copy the contents of another pn_data_t object. Any values in the + * data object will be lost. + * + * @param data a pn_data_t object + * @param src the source pn_data_t to copy from + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_copy(pn_data_t *data, pn_data_t *src); + +/** + * Append the contents of another pn_data_t object. + * + * @param data a pn_data_t object + * @param src the source pn_data_t to append from + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_append(pn_data_t *data, pn_data_t *src); + +/** + * Append up to _n_ values from the contents of another pn_data_t + * object. + * + * @param data a pn_data_t object + * @param src the source pn_data_t to append from + * @param limit the maximum number of values to append + * @return zero on success or an error code on failure + */ +PN_EXTERN int pn_data_appendn(pn_data_t *data, pn_data_t *src, int limit); + +/** + * Modify a pn_data_t object to behave as if the current node is the + * root node of the tree. This impacts the behaviour of + * ::pn_data_rewind(), ::pn_data_next(), ::pn_data_prev(), and + * anything else that depends on the navigational state of the + * pn_data_t object. Use ::pn_data_widen() to reverse the effect of + * this operation. + * + * @param data a pn_data_t object + */ +PN_EXTERN void pn_data_narrow(pn_data_t *data); + +/** + * Reverse the effect of ::pn_data_narrow(). + * + * @param data a pn_data_t object + */ +PN_EXTERN void pn_data_widen(pn_data_t *data); + +/** + * Returns a handle for the current navigational state of a pn_data_t + * so that it can be later restored using ::pn_data_restore(). + * + * @param data a pn_data_t object + * @return a handle for the current navigational state + */ +PN_EXTERN pn_handle_t pn_data_point(pn_data_t *data); + +/** + * Restores a prior navigational state that was saved using + * ::pn_data_point(). If the data object has been modified in such a + * way that the prior navigational state cannot be restored, then this + * will return false and the navigational state will remain unchanged, + * otherwise it will return true. + * + * @param data a pn_data_t object + * @param point a handle referencing the saved navigational state + * @return true iff the prior navigational state was restored + */ +PN_EXTERN bool pn_data_restore(pn_data_t *data, pn_handle_t point); + +/** + * Dumps a debug representation of the internal state of the pn_data_t + * object that includes its navigational state to stdout for debugging + * purposes. + * + * @param data a pn_data_t object that is behaving in a confusing way + */ +PN_EXTERN void pn_data_dump(pn_data_t *data); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* codec.h */
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/37136940/c/include/proton/condition.h ---------------------------------------------------------------------- diff --git a/c/include/proton/condition.h b/c/include/proton/condition.h new file mode 100644 index 0000000..8c5cfe3 --- /dev/null +++ b/c/include/proton/condition.h @@ -0,0 +1,195 @@ +#ifndef PROTON_CONDITION_H +#define PROTON_CONDITION_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/type_compat.h> +#include <stddef.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @file + * + * @copybrief condition + * + * @addtogroup condition + * @{ + */ + +/** + * An AMQP Condition object. Conditions hold exception information + * pertaining to the closing of an AMQP endpoint such as a Connection, + * Session, or Link. Conditions also hold similar information + * pertaining to deliveries that have reached terminal states. + * Connections, Sessions, Links, and Deliveries may all have local and + * remote conditions associated with them. + * + * The local condition may be modified by the local endpoint to signal + * a particular condition to the remote peer. The remote condition may + * be examined by the local endpoint to detect whatever condition the + * remote peer may be signaling. Although often conditions are used to + * indicate errors, not all conditions are errors per/se, e.g. + * conditions may be used to redirect a connection from one host to + * another. + * + * Every condition has a short symbolic name, a longer description, + * and an additional info map associated with it. The name identifies + * the formally defined condition, and the map contains additional + * information relevant to the identified condition. + */ +typedef struct pn_condition_t pn_condition_t; + +/** + * Returns true if the condition object is holding some information, + * i.e. if the name is set to some non NULL value. Returns false + * otherwise. + * + * @param[in] condition the condition object to test + * @return true iff some condition information is set + */ +PN_EXTERN bool pn_condition_is_set(pn_condition_t *condition); + +/** + * Clears the condition object of any exceptional information. After + * calling ::pn_condition_clear(), ::pn_condition_is_set() is + * guaranteed to return false and ::pn_condition_get_name() as well as + * ::pn_condition_get_description() will return NULL. The ::pn_data_t + * returned by ::pn_condition_info() will still be valid, but will + * have been cleared as well (See ::pn_data_clear()). + * + * @param[in] condition the condition object to clear + */ +PN_EXTERN void pn_condition_clear(pn_condition_t *condition); + +/** + * Returns the name associated with the exceptional condition, or NULL + * if there is no conditional information set. + * + * @param[in] condition the condition object + * @return a pointer to the name, or NULL + */ +PN_EXTERN const char *pn_condition_get_name(pn_condition_t *condition); + +/** + * Sets the name associated with the exceptional condition. + * + * @param[in] condition the condition object + * @param[in] name the desired name + * @return an error code or 0 on success + */ +PN_EXTERN int pn_condition_set_name(pn_condition_t *condition, const char *name); + +/** + * Gets the description associated with the exceptional condition. + * + * @param[in] condition the condition object + * @return a pointer to the description, or NULL + */ +PN_EXTERN const char *pn_condition_get_description(pn_condition_t *condition); + +/** + * Sets the description associated with the exceptional condition. + * + * @param[in] condition the condition object + * @param[in] description the desired description + * @return an error code or 0 on success + */ +PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char *description); + +/** + * Returns a data object that holds the additional information + * associated with the condition. The data object may be used both to + * access and to modify the additional information associated with the + * condition. + * + * @param[in] condition the condition object + * @return a data object holding the additional information for the condition + */ +PN_EXTERN pn_data_t *pn_condition_info(pn_condition_t *condition); + +/** + * Set the name and printf-style formatted description. + */ +PN_EXTERN int pn_condition_vformat(pn_condition_t *, const char *name, const char *fmt, va_list ap); + +/** + * Set the name and printf-style formatted description. + */ +PN_EXTERN int pn_condition_format(pn_condition_t *, const char *name, const char *fmt, ...); + +/** + * Returns true if the condition is a redirect. + * + * @param[in] condition the condition object + * @return true if the condition is a redirect, false otherwise + */ +PN_EXTERN bool pn_condition_is_redirect(pn_condition_t *condition); + +/** + * Retrieves the redirect host from the additional information + * associated with the condition. If the condition is not a redirect, + * this will return NULL. + * + * @param[in] condition the condition object + * @return the redirect host or NULL + */ +PN_EXTERN const char *pn_condition_redirect_host(pn_condition_t *condition); + +/** + * Retrieves the redirect port from the additional information + * associated with the condition. If the condition is not a redirect, + * this will return an error code. + * + * @param[in] condition the condition object + * @return the redirect port or an error code + */ +PN_EXTERN int pn_condition_redirect_port(pn_condition_t *condition); + +/** + * Copy the src condition to the dst condition. + */ +PN_EXTERN int pn_condition_copy(pn_condition_t *dest, pn_condition_t *src); + +/** + * Create a condition object. + */ +PN_EXTERN pn_condition_t *pn_condition(void); + +/** + * Free a condition object. + */ +PN_EXTERN void pn_condition_free(pn_condition_t *); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* condition.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/37136940/c/include/proton/connection.h ---------------------------------------------------------------------- diff --git a/c/include/proton/connection.h b/c/include/proton/connection.h new file mode 100644 index 0000000..ff6c68c --- /dev/null +++ b/c/include/proton/connection.h @@ -0,0 +1,504 @@ +#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 + * + * @copybrief connection + * + * @addtogroup connection + * @{ + */ + +/** + * 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) + +PN_EXTERN pn_connection_t *pn_connection(void); + +/** + * 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); + +/** + * **Deprecated** + * + * 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); + +/** + * Get the collector set with pn_connection_collect() + * @return NULL if pn_connection_collect() has not been called. + */ +PN_EXTERN pn_collector_t* pn_connection_collector(pn_connection_t *connection); + +/** + * **Deprecated** - Use ::pn_connection_attachments(). + * + * 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** - Use ::pn_connection_attachments(). + * + * 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 the 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 the 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 the 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 transport 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 something 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 transport 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 capabilities + * 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 capabilities + * 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 capabilities 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 capabilities 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 */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/37136940/c/include/proton/connection_driver.h ---------------------------------------------------------------------- diff --git a/c/include/proton/connection_driver.h b/c/include/proton/connection_driver.h new file mode 100644 index 0000000..e83e2e9 --- /dev/null +++ b/c/include/proton/connection_driver.h @@ -0,0 +1,290 @@ +#ifndef PROTON_CONNECTION_DRIVER_H +#define PROTON_CONNECTION_DRIVER_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. + */ + +/** + * @file + * + * @copybrief connection_driver + * + * @addtogroup connection_driver + * @{ + * + * Associate a @ref connection and @ref transport with AMQP byte + * streams from any source. + * + * - process AMQP-encoded bytes from some input byte stream + * - generate ::pn_event_t events for your application to handle + * - encode resulting AMQP output bytes for some output byte stream + * + * The `pn_connection_driver_*` functions provide a simplified API and + * extra logic to use ::pn_connection_t and ::pn_transport_t as a + * unit. You can also access them directly for features that do not + * have `pn_connection_driver_*` functions. + * + * The driver buffers events and data. You should run it until + * pn_connection_driver_finished() is true, to ensure all reading, + * writing, and event handling (including `ERROR` and `FINAL` events) + * is finished. + * + * ## Error handling + * + * The `pn_connection_driver_*` functions do not return an error + * code. IO errors are set on the transport condition and are returned + * as a `PN_TRANSPORT_ERROR`. The integration code can set errors + * using pn_connection_driver_errorf(). + * + * ## IO patterns + * + * This API supports asynchronous, proactive, non-blocking and + * reactive IO. An integration does not have to follow the + * dispatch-read-write sequence above, but note that you should handle + * all available events before calling + * pn_connection_driver_read_buffer() and check that `size` is + * non-zero before starting a blocking or asynchronous read call. A + * `read` started while there are unprocessed `CLOSE` events in the + * buffer may never complete. + * + * AMQP is a full-duplex, asynchronous protocol. The "read" and + * "write" sides of an AMQP connection can close separately. + * + * ## Thread safety + * + * The @ref connection_driver types are not thread safe, but each + * connection and its associated types form an independent + * unit. Different connections can be processed concurrently by + * different threads. + */ + +#include <proton/import_export.h> +#include <proton/event.h> +#include <proton/types.h> + +#include <stdarg.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The elements needed to drive AMQP IO and events. + */ +typedef struct pn_connection_driver_t { + pn_connection_t *connection; + pn_transport_t *transport; + pn_collector_t *collector; + pn_event_batch_t batch; +} pn_connection_driver_t; + +/** + * Set connection and transport to the provided values, or create a new + * @ref pn_connection_t or @ref pn_transport_t if either is NULL. + * The provided values belong to the connection driver and will be freed by + * pn_connection_driver_destroy(). + * + * The transport is bound automatically after the PN_CONNECTION_INIT has been is + * handled by the application. It can be bound earlier with + * pn_connection_driver_bind(). + * + * The following functions must be called before the transport is + * bound to have effect: pn_connection_set_username(), pn_connection_set_password(), + * pn_transport_set_server(). + * + * @return PN_OUT_OF_MEMORY if any allocation fails. + */ +PN_EXTERN int pn_connection_driver_init(pn_connection_driver_t*, pn_connection_t*, pn_transport_t*); + +/** + * Force binding of the transport. This happens automatically after + * the PN_CONNECTION_INIT is processed. + * + * @return PN_STATE_ERR if the transport is already bound. + */ +PN_EXTERN int pn_connection_driver_bind(pn_connection_driver_t *d); + +/** + * Unbind, release and free the connection and transport. Set all pointers to + * NULL. Does not free the @ref pn_connection_driver_t struct itself. + */ +PN_EXTERN void pn_connection_driver_destroy(pn_connection_driver_t *); + +/** + * Disassociate the driver's connection from its transport and collector and + * sets d->connection = NULL. Returns the previous value, which must be freed + * by the caller. + * + * The transport and collector are still owned by the driver and will be freed by + * pn_connection_driver_destroy(). + * + * @note This has nothing to do with pn_connection_release() + */ +PN_EXTERN pn_connection_t *pn_connection_driver_release_connection(pn_connection_driver_t *d); + +/** + * Get the read buffer. + * + * Copy data from your input byte source to buf.start, up to buf.size. + * Call pn_connection_driver_read_done() when reading is complete. + * + * buf.size==0 means reading is not possible: no buffer space or the read side is closed. + */ +PN_EXTERN pn_rwbytes_t pn_connection_driver_read_buffer(pn_connection_driver_t *); + +/** + * Process the first n bytes of data in pn_connection_driver_read_buffer() and + * reclaim the buffer space. + */ +PN_EXTERN void pn_connection_driver_read_done(pn_connection_driver_t *, size_t n); + +/** + * Close the read side. Call when the IO can no longer be read. + */ +PN_EXTERN void pn_connection_driver_read_close(pn_connection_driver_t *); + +/** + * True if read side is closed. + */ +PN_EXTERN bool pn_connection_driver_read_closed(pn_connection_driver_t *); + +/** + * Get the write buffer. + * + * Write data from buf.start to your IO destination, up to a max of buf.size. + * Call pn_connection_driver_write_done() when writing is complete. + * + * buf.size==0 means there is nothing to write. + */ + PN_EXTERN pn_bytes_t pn_connection_driver_write_buffer(pn_connection_driver_t *); + +/** + * Call when the first n bytes of pn_connection_driver_write_buffer() have been + * written to IO. Reclaims the buffer space and reset the write buffer. + */ +PN_EXTERN void pn_connection_driver_write_done(pn_connection_driver_t *, size_t n); + +/** + * Close the write side. Call when IO can no longer be written to. + */ +PN_EXTERN void pn_connection_driver_write_close(pn_connection_driver_t *); + +/** + * True if write side is closed. + */ +PN_EXTERN bool pn_connection_driver_write_closed(pn_connection_driver_t *); + +/** + * Close both sides. + */ +PN_EXTERN void pn_connection_driver_close(pn_connection_driver_t * c); + +/** + * Get the next event to handle. + * + * @return pointer is valid till the next call of + * pn_connection_driver_next(). NULL if there are no more events available now, + * reading/writing may produce more. + */ +PN_EXTERN pn_event_t* pn_connection_driver_next_event(pn_connection_driver_t *); + +/** + * True if pn_connection_driver_next_event() will return a non-NULL event. + */ +PN_EXTERN bool pn_connection_driver_has_event(pn_connection_driver_t *); + +/** + * Return true if the the driver is closed for reading and writing and there are + * no more events. + * + * Call pn_connection_driver_free() to free all related memory. + */ +PN_EXTERN bool pn_connection_driver_finished(pn_connection_driver_t *); + +/** + * Set transport error. + * + * The name and formatted description are set on the transport condition, and + * returned as a PN_TRANSPORT_ERROR event from pn_connection_driver_next_event(). + * + * You must call this *before* pn_connection_driver_read_close() or + * pn_connection_driver_write_close() to ensure the error is processed. + */ +PN_EXTERN void pn_connection_driver_errorf(pn_connection_driver_t *d, const char *name, const char *fmt, ...); + +/** + * Set transport error via a va_list, see pn_connection_driver_errorf() + */ +PN_EXTERN void pn_connection_driver_verrorf(pn_connection_driver_t *d, const char *name, const char *fmt, va_list); + +/** + * If batch is part of a connection_driver, return the connection_driver address, + * else return NULL + */ +PN_EXTERN pn_connection_driver_t* pn_event_batch_connection_driver(pn_event_batch_t *batch); + +/** + * The write side of the transport is closed, it will no longer produce bytes to write to + * external IO. Synonym for PN_TRANSPORT_HEAD_CLOSED + */ +#define PN_TRANSPORT_WRITE_CLOSED PN_TRANSPORT_HEAD_CLOSED + +/** + * The read side of the transport is closed, it will no longer read bytes from external + * IO. Alias for PN_TRANSPORT_TAIL_CLOSED + */ +#define PN_TRANSPORT_READ_CLOSED PN_TRANSPORT_TAIL_CLOSED + +/** + * **Deprecated** - Use pn_transport_log(). + */ +PN_EXTERN void pn_connection_driver_log(pn_connection_driver_t *d, const char *msg); + +/** + * **Deprecated** - Use pn_transport_logf(). + */ +PN_EXTERN void pn_connection_driver_logf(pn_connection_driver_t *d, const char *fmt, ...); + +/** + * **Deprecated** - Use pn_transport_vlogf(). + */ +PN_EXTERN void pn_connection_driver_vlogf(pn_connection_driver_t *d, const char *fmt, va_list ap); + +/** + * Associate a pn_connection_t with its pn_connection_driver_t. + * + * **NOTE**: this is only for use by IO integration writers. If you are using the standard + * pn_proactor_t you *must not* use this function. + * + * @return pointer to the pn_connection_driver_t* field in a pn_connection_t. + * + * Return type is pointer to a pointer so that the caller can (if desired) use + * atomic operations when loading and storing the value. + */ +PN_EXTERN pn_connection_driver_t **pn_connection_driver_ptr(pn_connection_t *connection); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* connection_driver.h */ --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
