You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2018/07/03 22:13:35 UTC
[46/89] [abbrv] [partial] qpid-proton git commit: PROTON-1728:
Reorganize the source tree
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/37136940/c/include/proton/link.h
----------------------------------------------------------------------
diff --git a/c/include/proton/link.h b/c/include/proton/link.h
new file mode 100644
index 0000000..8099a32
--- /dev/null
+++ b/c/include/proton/link.h
@@ -0,0 +1,692 @@
+#ifndef PROTON_LINK_H
+#define PROTON_LINK_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/condition.h>
+#include <proton/terminus.h>
+#include <proton/types.h>
+#include <proton/object.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @file
+ *
+ * @copybrief link
+ *
+ * @addtogroup link
+ * @{
+ */
+
+/**
+ * Construct a new sender on a session.
+ *
+ * Each sending link between two AMQP containers must be uniquely
+ * named. Note that this uniqueness cannot be enforced at the API
+ * level, so some consideration should be taken in choosing link
+ * names.
+ *
+ * @param[in] session the session object
+ * @param[in] name the name of the link
+ * @return a newly constructed sender link or NULL on error
+ */
+PN_EXTERN pn_link_t *pn_sender(pn_session_t *session, const char *name);
+
+/**
+ * Construct a new receiver on a session.
+ *
+ * Each receiving link between two AMQP containers must be uniquely
+ * named. Note that this uniqueness cannot be enforced at the API
+ * level, so some consideration should be taken in choosing link
+ * names.
+ *
+ * @param[in] session the session object
+ * @param[in] name the name of the link
+ * @return a newly constructed receiver link or NULL on error
+ */
+PN_EXTERN pn_link_t *pn_receiver(pn_session_t *session, const char *name);
+
+/**
+ * Free a link object.
+ *
+ * When a link object is freed, all ::pn_delivery_t objects associated
+ * with the session are also freed. Freeing a link will settle any
+ * unsettled deliveries on the link.
+ *
+ * @param[in] link a link object to free (or NULL)
+ */
+PN_EXTERN void pn_link_free(pn_link_t *link);
+
+/**
+ * **Deprecated** - Use ::pn_link_attachments().
+ *
+ * Get the application context that is associated with a link object.
+ *
+ * The application context for a link may be set using
+ * ::pn_link_set_context.
+ *
+ * @param[in] link the link whose context is to be returned.
+ * @return the application context for the link object
+ */
+PN_EXTERN void *pn_link_get_context(pn_link_t *link);
+
+/**
+ * **Deprecated** - Use ::pn_link_attachments().
+ *
+ * Set a new application context for a link object.
+ *
+ * The application context for a link object may be retrieved using
+ * ::pn_link_get_context.
+ *
+ * @param[in] link the link object
+ * @param[in] context the application context
+ */
+PN_EXTERN void pn_link_set_context(pn_link_t *link, void *context);
+
+/**
+ * Get the attachments that are associated with a link object.
+ *
+ * @param[in] link the link whose attachments are to be returned.
+ * @return the attachments for the link object
+ */
+PN_EXTERN pn_record_t *pn_link_attachments(pn_link_t *link);
+
+/**
+ * Get the name of a link.
+ *
+ * @param[in] link a link object
+ * @return the name of the link
+ */
+PN_EXTERN const char *pn_link_name(pn_link_t *link);
+
+/**
+ * Test if a link is a sender.
+ *
+ * @param[in] link a link object
+ * @return true if and only if the link is a sender
+ */
+PN_EXTERN bool pn_link_is_sender(pn_link_t *link);
+
+/**
+ * Test if a link is a receiver.
+ *
+ * @param[in] link a link object
+ * @return true if and only if the link is a receiver
+ */
+PN_EXTERN bool pn_link_is_receiver(pn_link_t *link);
+
+/**
+ * Get the endpoint state flags for a link.
+ *
+ * @param[in] link the link
+ * @return the link's state flags
+ */
+PN_EXTERN pn_state_t pn_link_state(pn_link_t *link);
+
+/**
+ * **Deprecated**
+ *
+ * Get additional error information associated with the link.
+ *
+ * Whenever a link 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
+ * link object is freed.
+ *
+ * @param[in] link the link object
+ * @return the link's error object
+ */
+PN_EXTERN pn_error_t *pn_link_error(pn_link_t *link);
+
+/**
+ * Get the local condition associated with a link endpoint.
+ *
+ * The ::pn_condition_t object retrieved may be modified prior to
+ * closing a link in order to indicate a particular condition
+ * exists when the link closes. This is normally used to
+ * communicate error conditions to the remote peer, however it may
+ * also be used in non error cases. See ::pn_condition_t for more
+ * details.
+ *
+ * The pointer returned by this operation is valid until the link
+ * object is freed.
+ *
+ * @param[in] link the link object
+ * @return the link's local condition object
+ */
+PN_EXTERN pn_condition_t *pn_link_condition(pn_link_t *link);
+
+/**
+ * Get the remote condition associated with a link 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 link endpoint was
+ * closed. The ::pn_condition_t object returned may not be modified.
+ *
+ * The pointer returned by this operation is valid until the
+ * link object is freed.
+ *
+ * @param[in] link the link object
+ * @return the link's remote condition object
+ */
+PN_EXTERN pn_condition_t *pn_link_remote_condition(pn_link_t *link);
+
+/**
+ * Get the parent session for a link object.
+ *
+ * This operation retrieves the parent ::pn_session_t object that
+ * contains the given ::pn_link_t object.
+ *
+ * @param[in] link the link object
+ * @return the parent session object
+ */
+PN_EXTERN pn_session_t *pn_link_session(pn_link_t *link);
+
+/**
+ * Retrieve the first link that matches the given state mask.
+ *
+ * Examines the state of each link owned by the connection and returns
+ * the first link that matches the given state mask. If state contains
+ * both local and remote flags, then an exact match against those
+ * flags is performed. If state contains only local or only remote
+ * flags, then a match occurs if any of the local or remote flags are
+ * set respectively. state==0 matches all links.
+ *
+ * @param[in] connection to be searched for matching Links
+ * @param[in] state mask to match
+ * @return the first link owned by the connection that matches the
+ * mask, else NULL if no links match
+ */
+PN_EXTERN pn_link_t *pn_link_head(pn_connection_t *connection, pn_state_t state);
+
+/**
+ * Retrieve the next link that matches the given state mask.
+ *
+ * When used with pn_link_head, the application can access all links
+ * on the connection that match the given state. See pn_link_head for
+ * description of match behavior.
+ *
+ * @param[in] link the previous link obtained from pn_link_head or
+ * pn_link_next
+ * @param[in] state mask to match
+ * @return the next session owned by the connection that matches the
+ * mask, else NULL if no sessions match
+ */
+PN_EXTERN pn_link_t *pn_link_next(pn_link_t *link, pn_state_t state);
+
+/**
+ * Open a link.
+ *
+ * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
+ * will be set.
+ *
+ * @param[in] link a link object
+ */
+PN_EXTERN void pn_link_open(pn_link_t *link);
+
+/**
+ * Close a link.
+ *
+ * Once this operation has completed, the PN_LOCAL_CLOSED state flag
+ * will be set. This may be called without calling
+ * ::pn_link_open, in this case it is equivalent to calling
+ * ::pn_link_open followed by ::pn_link_close.
+ *
+ * @param[in] link a link object
+ */
+PN_EXTERN void pn_link_close(pn_link_t *link);
+
+/**
+ * Detach a link.
+ *
+ * @param[in] link a link object
+ */
+PN_EXTERN void pn_link_detach(pn_link_t *link);
+
+/**
+ * Access the locally defined source definition for a link.
+ *
+ * The pointer returned by this operation is valid until the link
+ * object is freed.
+ *
+ * @param[in] link a link object
+ * @return a pointer to a source terminus
+ */
+PN_EXTERN pn_terminus_t *pn_link_source(pn_link_t *link);
+
+/**
+ * Access the locally defined target definition for a link.
+ *
+ * The pointer returned by this operation is valid until the link
+ * object is freed.
+ *
+ * @param[in] link a link object
+ * @return a pointer to a target terminus
+ */
+PN_EXTERN pn_terminus_t *pn_link_target(pn_link_t *link);
+
+/**
+ * Access the remotely defined source definition for a link.
+ *
+ * The pointer returned by this operation is valid until the link
+ * object is freed. The remotely defined terminus will be empty until
+ * the link is remotely opened as indicated by the PN_REMOTE_ACTIVE
+ * flag.
+ *
+ * @param[in] link a link object
+ * @return a pointer to the remotely defined source terminus
+ */
+PN_EXTERN pn_terminus_t *pn_link_remote_source(pn_link_t *link);
+
+/**
+ * Access the remotely defined target definition for a link.
+ *
+ * The pointer returned by this operation is valid until the link
+ * object is freed. The remotely defined terminus will be empty until
+ * the link is remotely opened as indicated by the PN_REMOTE_ACTIVE
+ * flag.
+ *
+ * @param[in] link a link object
+ * @return a pointer to the remotely defined target terminus
+ */
+PN_EXTERN pn_terminus_t *pn_link_remote_target(pn_link_t *link);
+
+/**
+ * Get the current delivery for a link.
+ *
+ * Each link maintains a sequence of deliveries in the order they were
+ * created, along with a pointer to the *current* delivery. All
+ * send/recv operations on a link take place on the *current*
+ * delivery. If a link has no current delivery, the current delivery
+ * is automatically initialized to the next delivery created on the
+ * link. Once initialized, the current delivery remains the same until
+ * it is changed through use of ::pn_link_advance or until it is
+ * settled via ::pn_delivery_settle.
+ *
+ * @param[in] link a link object
+ * @return the current delivery for the link, or NULL if there is none
+ */
+PN_EXTERN pn_delivery_t *pn_link_current(pn_link_t *link);
+
+/**
+ * Advance the current delivery of a link to the next delivery on the
+ * link.
+ *
+ * For sending links this operation is used to finish sending message
+ * data for the current outgoing delivery and move on to the next
+ * outgoing delivery (if any).
+ *
+ * For receiving links, this operation is used to finish accessing
+ * message data from the current incoming delivery and move on to the
+ * next incoming delivery (if any).
+ *
+ * Each link maintains a sequence of deliveries in the order they were
+ * created, along with a pointer to the *current* delivery. The
+ * pn_link_advance operation will modify the *current* delivery on the
+ * link to point to the next delivery in the sequence. If there is no
+ * next delivery in the sequence, the current delivery will be set to
+ * NULL. This operation will return true if invoking it caused the
+ * value of the current delivery to change, even if it was set to
+ * NULL.
+ *
+ * @param[in] link a link object
+ * @return true if the current delivery was changed
+ */
+PN_EXTERN bool pn_link_advance(pn_link_t *link);
+
+/**
+ * Get the credit balance for a link.
+ *
+ * Links use a credit based flow control scheme. Every receiver
+ * maintains a credit balance that corresponds to the number of
+ * deliveries that the receiver can accept at any given moment. As
+ * more capacity becomes available at the receiver (see
+ * ::pn_link_flow), it adds credit to this balance and communicates
+ * the new balance to the sender. Whenever a delivery is
+ * sent/received, the credit balance maintained by the link is
+ * decremented by one. Once the credit balance at the sender reaches
+ * zero, the sender must pause sending until more credit is obtained
+ * from the receiver.
+ *
+ * Note that a sending link may still be used to send deliveries even
+ * if pn_link_credit reaches zero, however those deliveries will end
+ * up being buffered by the link until enough credit is obtained from
+ * the receiver to send them over the wire. In this case the balance
+ * reported by ::pn_link_credit will go negative.
+ *
+ * @param[in] link a link object
+ * @return the credit balance for the link
+ */
+PN_EXTERN int pn_link_credit(pn_link_t *link);
+
+/**
+ * Get the number of queued deliveries for a link.
+ *
+ * Links may queue deliveries for a number of reasons, for example
+ * there may be insufficient credit to send them to the receiver (see
+ * ::pn_link_credit), or they simply may not have yet had a chance to
+ * be written to the wire. This operation will return the number of
+ * queued deliveries on a link.
+ *
+ * @param[in] link a link object
+ * @return the number of queued deliveries for the link
+ */
+PN_EXTERN int pn_link_queued(pn_link_t *link);
+
+/**
+ * Get the remote view of the credit for a link.
+ *
+ * The remote view of the credit for a link differs from local view of
+ * credit for a link by the number of queued deliveries. In other
+ * words ::pn_link_remote_credit is defined to be ::pn_link_credit -
+ * ::pn_link_queued.
+ *
+ * @param[in] link a link object
+ * @return the remote view of the credit for a link
+ */
+PN_EXTERN int pn_link_remote_credit(pn_link_t *link);
+
+/**
+ * Get the drain flag for a link.
+ *
+ * If a link is in drain mode, then the sending endpoint of a link
+ * must immediately use up all available credit on the link. If this
+ * is not possible, the excess credit must be returned by invoking
+ * ::pn_link_drained. Only the receiving endpoint can set the drain
+ * mode. See ::pn_link_set_drain for details.
+ *
+ * @param[in] link a link object
+ * @return true if and only if the link is in drain mode
+ */
+PN_EXTERN bool pn_link_get_drain(pn_link_t *link);
+
+/**
+ * Drain excess credit for a link.
+ *
+ * When a link is in drain mode, the sender must use all excess credit
+ * immediately, and release any excess credit back to the receiver if
+ * there are no deliveries available to send.
+ *
+ * When invoked on a sending link that is in drain mode, this
+ * operation will release all excess credit back to the receiver and
+ * return the number of credits released back to the sender. If the
+ * link is not in drain mode, this operation is a noop.
+ *
+ * When invoked on a receiving link, this operation will return and
+ * reset the number of credits the sender has released back to the
+ * receiver.
+ *
+ * @param[in] link a link object
+ * @return the number of credits drained
+ */
+PN_EXTERN int pn_link_drained(pn_link_t *link);
+
+/**
+ * Get the available deliveries hint for a link.
+ *
+ * The available count for a link provides a hint as to the number of
+ * deliveries that might be able to be sent if sufficient credit were
+ * issued by the receiving link endpoint. See ::pn_link_offered for
+ * more details.
+ *
+ * @param[in] link a link object
+ * @return the available deliveries hint
+ */
+PN_EXTERN int pn_link_available(pn_link_t *link);
+
+/**
+ * Describes the permitted/expected settlement behaviours of a sending
+ * link.
+ *
+ * The sender settle mode describes the permitted and expected
+ * behaviour of a sending link with respect to settling of deliveries.
+ * See ::pn_delivery_settle for more details.
+ */
+typedef enum {
+ PN_SND_UNSETTLED = 0, /**< The sender will send all deliveries
+ initially unsettled. */
+ PN_SND_SETTLED = 1, /**< The sender will send all deliveries settled
+ to the receiver. */
+ PN_SND_MIXED = 2 /**< The sender may send a mixture of settled and
+ unsettled deliveries. */
+} pn_snd_settle_mode_t;
+
+/**
+ * Describes the permitted/expected settlement behaviours of a
+ * receiving link.
+ *
+ * The receiver settle mode describes the permitted and expected
+ * behaviour of a receiving link with respect to settling of
+ * deliveries. See ::pn_delivery_settle for more details.
+ */
+typedef enum {
+ PN_RCV_FIRST = 0, /**< The receiver will settle deliveries
+ regardless of what the sender does. */
+ PN_RCV_SECOND = 1 /**< The receiver will only settle deliveries
+ after the sender settles. */
+} pn_rcv_settle_mode_t;
+
+/**
+ * Get the local sender settle mode for a link.
+ *
+ * @param[in] link a link object
+ * @return the local sender settle mode
+ */
+PN_EXTERN pn_snd_settle_mode_t pn_link_snd_settle_mode(pn_link_t *link);
+
+/**
+ * Get the local receiver settle mode for a link.
+ *
+ * @param[in] link a link object
+ * @return the local receiver settle mode
+ */
+PN_EXTERN pn_rcv_settle_mode_t pn_link_rcv_settle_mode(pn_link_t *link);
+
+/**
+ * Set the local sender settle mode for a link.
+ *
+ * @param[in] link a link object
+ * @param[in] mode the sender settle mode
+ */
+PN_EXTERN void pn_link_set_snd_settle_mode(pn_link_t *link, pn_snd_settle_mode_t mode);
+
+/**
+ * Set the local receiver settle mode for a link.
+ *
+ * @param[in] link a link object
+ * @param[in] mode the receiver settle mode
+ */
+PN_EXTERN void pn_link_set_rcv_settle_mode(pn_link_t *link, pn_rcv_settle_mode_t mode);
+
+/**
+ * Get the remote sender settle mode for a link.
+ *
+ * @param[in] link a link object
+ * @return the remote sender settle mode
+ */
+PN_EXTERN pn_snd_settle_mode_t pn_link_remote_snd_settle_mode(pn_link_t *link);
+
+/**
+ * Get the remote receiver settle mode for a link.
+ *
+ * @param[in] link a link object
+ * @return the remote receiver settle mode
+ */
+PN_EXTERN pn_rcv_settle_mode_t pn_link_remote_rcv_settle_mode(pn_link_t *link);
+
+/**
+ * Get the number of unsettled deliveries for a link.
+ *
+ * @param[in] link a link object
+ * @return the number of unsettled deliveries
+ */
+PN_EXTERN int pn_link_unsettled(pn_link_t *link);
+
+/**
+ * Get the first unsettled delivery for a link.
+ *
+ " @param[in] link a link object
+ * @return a pointer to the first unsettled delivery on the link
+ */
+PN_EXTERN pn_delivery_t *pn_unsettled_head(pn_link_t *link);
+
+/**
+ * Get the next unsettled delivery on a link.
+ *
+ * @param[in] delivery a delivery object
+ * @return the next unsettled delivery on the link
+ */
+PN_EXTERN pn_delivery_t *pn_unsettled_next(pn_delivery_t *delivery);
+
+/**
+ * Signal the availability of deliveries for a link.
+ *
+ * @param[in] sender a sender link object
+ * @param[in] credit the number of deliveries potentially available
+ * for transfer
+ */
+PN_EXTERN void pn_link_offered(pn_link_t *sender, int credit);
+
+/**
+ * Send message data for the current delivery on a link.
+ *
+ * @param[in] sender a sender link object
+ * @param[in] bytes the start of the message data
+ * @param[in] n the number of bytes of message data
+ * @return the number of bytes sent, or an error code
+ */
+PN_EXTERN ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n);
+
+/**
+ * Grant credit for incoming deliveries on a receiver.
+ *
+ * @param[in] receiver a receiving link object
+ * @param[in] credit the amount to increment the link credit
+ */
+PN_EXTERN void pn_link_flow(pn_link_t *receiver, int credit);
+
+/**
+ * Grant credit for incoming deliveries on a receiver, and set drain
+ * mode to true.
+ *
+ * Use ::pn_link_set_drain to set the drain mode explicitly.
+ *
+ * @param[in] receiver a receiving link object
+ * @param[in] credit the amount to increment the link credit
+ */
+PN_EXTERN void pn_link_drain(pn_link_t *receiver, int credit);
+
+/**
+ * Set the drain mode on a link.
+ *
+ * @param[in] receiver a receiving link object
+ * @param[in] drain the drain mode
+ */
+PN_EXTERN void pn_link_set_drain(pn_link_t *receiver, bool drain);
+
+/**
+ * Receive message data for the current delivery on a link.
+ *
+ * Use ::pn_delivery_pending on the current delivery to figure out how
+ * much buffer space is needed.
+ *
+ * Note that the link API can be used to stream large messages across
+ * the network, so just because there is no data to read does not
+ * imply the message is complete. To ensure the entirety of the
+ * message data has been read, either invoke ::pn_link_recv until
+ * PN_EOS is returned, or verify that
+ *
+ * (!pn_delivery_partial(d) && !pn_delivery_aborted(d) && pn_delivery_pending(d)==0)
+ *
+ * @param[in] receiver a receiving link object
+ * @param[in] bytes a pointer to an empty buffer
+ * @param[in] n the buffer capacity
+ * @return The number of bytes received, or an error code:
+ * - ::PN_EOS: The message has been completely received
+ * - 0: No data available now.
+ * If pn_delivery_partial() there will be further ::PN_DELIVERY events with more data.
+ * - ::PN_STATE_ERR: The link has no current delivery
+ * - ::PN_ABORTED: See pn_delivery_aborted()
+ */
+PN_EXTERN ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n);
+
+/**
+ * Check if a link is currently draining.
+ *
+ * A link is defined to be draining when drain mode is set to true,
+ * and the sender still has excess credit.
+ *
+ * @param[in] receiver a receiving link object
+ * @return true if the link is currently draining, false otherwise
+ */
+PN_EXTERN bool pn_link_draining(pn_link_t *receiver);
+
+/**
+ * **Unsettled API** - Get the maximum message size for a link.
+ *
+ * A zero maximum message size means the size is unlimited.
+ *
+ * @param[in] link a link object
+ * @return the maximum message size for a link.
+ */
+PN_EXTERN uint64_t pn_link_max_message_size(pn_link_t *link);
+
+/**
+ * **Unsettled API** - Set the maximum message size for a link.
+ *
+ * A zero maximum message size means the size is unlimited.
+ *
+ * @param[in] link a link object
+ * @param[in] size the maximum message size for the link
+ */
+PN_EXTERN void pn_link_set_max_message_size(pn_link_t *link, uint64_t size);
+
+/**
+ * **Unsettled API** - Get the remote view of the maximum message size for a link.
+ *
+ * A zero maximum message size means the size is unlimited.
+ *
+ * @param[in] link a link object
+ * @return the remote view of the maximum message size for a link
+ */
+PN_EXTERN uint64_t pn_link_remote_max_message_size(pn_link_t *link);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* link.h */
+
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/37136940/c/include/proton/listener.h
----------------------------------------------------------------------
diff --git a/c/include/proton/listener.h b/c/include/proton/listener.h
new file mode 100644
index 0000000..9ad9ecb
--- /dev/null
+++ b/c/include/proton/listener.h
@@ -0,0 +1,130 @@
+#ifndef PROTON_LISTENER_H
+#define PROTON_LISTENER_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/types.h>
+#include <proton/event.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @file
+ *
+ * @copybrief listener
+ *
+ * @addtogroup listener
+ * @{
+ *
+ * @note Thread safety: Listener has the same thread-safety rules as a
+ * @ref core object. Calls to a single listener must be serialized
+ * with the exception of pn_listener_close().
+ */
+
+/**
+ * Create a listener to pass to pn_proactor_listen()
+ *
+ * You can use pn_listener_attachments() to set application data that can be
+ * accessed when accepting connections.
+ */
+PNP_EXTERN pn_listener_t *pn_listener(void);
+
+/**
+ * Free a listener. You don't need to call this unless you create a listener
+ * with pn_listen() but never pass it to pn_proactor_listen()
+ */
+PNP_EXTERN void pn_listener_free(pn_listener_t *l);
+
+/**
+ * Accept an incoming connection request using @p transport and @p connection,
+ * which can be configured before the call.
+ *
+ * Call after a @ref PN_LISTENER_ACCEPT event.
+ *
+ * Errors are returned as @ref PN_TRANSPORT_CLOSED events by pn_proactor_wait().
+ *
+ * @param[in] listener the listener
+ * @param[in] connection If NULL a new connection is created.
+ * Memory management is the same as for pn_proactor_connect2()
+ * @param[in] transport If NULL a new transport is created.
+ * Memory management is the same as for pn_proactor_connect2()
+ */
+PNP_EXTERN void pn_listener_accept2(pn_listener_t *listener, pn_connection_t *connection, pn_transport_t *transport);
+
+/**
+ * @deprecated Equivalent to pn_listener_accept2(listener, connection, NULL)
+ */
+PNP_EXTERN void pn_listener_accept(pn_listener_t* listener, pn_connection_t *connection);
+
+/**
+ * Get the error condition for a listener.
+ */
+PNP_EXTERN pn_condition_t *pn_listener_condition(pn_listener_t *l);
+
+/**
+ * @cond INTERNAL
+ */
+
+PNP_EXTERN void *pn_listener_get_context(pn_listener_t *listener);
+
+PNP_EXTERN void pn_listener_set_context(pn_listener_t *listener, void *context);
+
+/**
+ * @endcond
+ */
+
+/**
+ * Get the attachments that are associated with a listener object.
+ */
+PNP_EXTERN pn_record_t *pn_listener_attachments(pn_listener_t *listener);
+
+/**
+ * Close the listener.
+ * The PN_LISTENER_CLOSE event is generated when the listener has stopped listening.
+ *
+ * @note Thread safe. Must not be called after the PN_LISTENER_CLOSE event has
+ * been handled as the listener may be freed .
+ */
+PNP_EXTERN void pn_listener_close(pn_listener_t *l);
+
+/**
+ * The proactor associated with a listener.
+ */
+PNP_EXTERN pn_proactor_t *pn_listener_proactor(pn_listener_t *c);
+
+/**
+ * Return the listener associated with an event.
+ *
+ * @return NULL if the event is not associated with a listener.
+ */
+PNP_EXTERN pn_listener_t *pn_event_listener(pn_event_t *event);
+
+/**
+ *@}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* listener.h */
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/37136940/c/include/proton/log.h
----------------------------------------------------------------------
diff --git a/c/include/proton/log.h b/c/include/proton/log.h
new file mode 100644
index 0000000..2f2046b
--- /dev/null
+++ b/c/include/proton/log.h
@@ -0,0 +1,71 @@
+#ifndef LOG_H
+#define LOG_H
+/*
+ * 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>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @cond INTERNAL
+ */
+
+/**
+ * @file
+ *
+ * Control log messages that are not associated with a transport.
+ * See pn_transport_trace for transport-related logging.
+ */
+
+/**
+ * Callback for customized logging.
+ */
+typedef void (*pn_logger_t)(const char *message);
+
+/**
+ * Enable/disable global logging.
+ *
+ * By default, logging is enabled by environment variable PN_TRACE_LOG.
+ * Calling this function overrides the environment setting.
+ */
+PN_EXTERN void pn_log_enable(bool enabled);
+
+/**
+ * Set the logger.
+ *
+ * By default a logger that prints to stderr is installed.
+ *
+ * @param logger is called with each log message if logging is enabled.
+ * Passing 0 disables logging regardless of pn_log_enable() or environment settings.
+ */
+PN_EXTERN void pn_log_logger(pn_logger_t logger);
+
+/**
+ * @endcond
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/37136940/c/include/proton/message.h
----------------------------------------------------------------------
diff --git a/c/include/proton/message.h b/c/include/proton/message.h
new file mode 100644
index 0000000..f9d62b0
--- /dev/null
+++ b/c/include/proton/message.h
@@ -0,0 +1,752 @@
+#ifndef PROTON_MESSAGE_H
+#define PROTON_MESSAGE_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/types.h>
+#include <proton/codec.h>
+#include <proton/error.h>
+#include <proton/type_compat.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @file
+ *
+ * @copybrief message
+ *
+ * @addtogroup message
+ * @{
+ */
+
+/**
+ * An AMQP Message object.
+ *
+ * An AMQP Message object is a mutable holder of message content that
+ * may be used to generate and encode or decode and access AMQP
+ * formatted message data.
+ */
+typedef struct pn_message_t pn_message_t;
+
+/**
+ * Default priority for messages.
+ */
+#define PN_DEFAULT_PRIORITY (4)
+
+/**
+ * Construct a new ::pn_message_t.
+ *
+ * Every message that is constructed must be freed using
+ * ::pn_message_free().
+ *
+ * @return pointer to a new ::pn_message_t
+ */
+PN_EXTERN pn_message_t * pn_message(void);
+
+/**
+ * Free a previously constructed ::pn_message_t.
+ *
+ * @param[in] msg pointer to a ::pn_message_t or NULL
+ */
+PN_EXTERN void pn_message_free(pn_message_t *msg);
+
+/**
+ * Clears the content of a ::pn_message_t.
+ *
+ * When pn_message_clear returns, the supplied ::pn_message_t will be
+ * emptied of all content and effectively returned to the same state
+ * as if it was just created.
+ *
+ * @param[in] msg pointer to the ::pn_message_t to be cleared
+ */
+PN_EXTERN void pn_message_clear(pn_message_t *msg);
+
+/**
+ * Access the error code of a message.
+ *
+ * Every operation on a message that can result in an error will set
+ * the message's error code in case of error. The pn_message_errno()
+ * call will access the error code of the most recent failed
+ * operation.
+ *
+ * @param[in] msg a message
+ * @return the message's error code
+ */
+PN_EXTERN int pn_message_errno(pn_message_t *msg);
+
+/**
+ * Access the error information for a message.
+ *
+ * Every operation on a message that can result in an error will
+ * update the error information held by its error descriptor should
+ * that operation fail. The pn_message_error() call will access the
+ * error information of the most recent failed operation. The pointer
+ * returned by this call is valid until the message is freed.
+ *
+ * @param[in] msg a message
+ * @return the message's error descriptor
+ */
+PN_EXTERN pn_error_t *pn_message_error(pn_message_t *msg);
+
+/**
+ * Get the inferred flag for a message.
+ *
+ * The inferred flag for a message indicates how the message content
+ * is encoded into AMQP sections. If inferred is true then binary and
+ * list values in the body of the message will be encoded as AMQP DATA
+ * and AMQP SEQUENCE sections, respectively. If inferred is false,
+ * then all values in the body of the message will be encoded as AMQP
+ * VALUE sections regardless of their type. Use
+ * ::pn_message_set_inferred to set the value.
+ *
+ * @param[in] msg a message object
+ * @return the value of the inferred flag for the message
+ */
+PN_EXTERN bool pn_message_is_inferred(pn_message_t *msg);
+
+/**
+ * Set the inferred flag for a message.
+ *
+ * See ::pn_message_is_inferred() for a description of what the
+ * inferred flag is.
+ *
+ * @param[in] msg a message object
+ * @param[in] inferred the new value of the inferred flag
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_inferred(pn_message_t *msg, bool inferred);
+
+/**
+ * Get the durable flag for a message.
+ *
+ * The durable flag indicates that any parties taking responsibility
+ * for the message must durably store the content.
+ *
+ * @param[in] msg a message object
+ * @return the value of the durable flag
+ */
+PN_EXTERN bool pn_message_is_durable (pn_message_t *msg);
+
+/**
+ * Set the durable flag for a message.
+ *
+ * See ::pn_message_is_durable() for a description of the durable
+ * flag.
+ *
+ * @param[in] msg a message object
+ * @param[in] durable the new value of the durable flag
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_durable (pn_message_t *msg, bool durable);
+
+/**
+ * Get the priority for a message.
+ *
+ * The priority of a message impacts ordering guarantees. Within a
+ * given ordered context, higher priority messages may jump ahead of
+ * lower priority messages.
+ *
+ * @param[in] msg a message object
+ * @return the message priority
+ */
+PN_EXTERN uint8_t pn_message_get_priority (pn_message_t *msg);
+
+/**
+ * Set the priority for a message.
+ *
+ * See ::pn_message_get_priority() for details on message priority.
+ *
+ * @param[in] msg a message object
+ * @param[in] priority the new priority for the message
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_priority (pn_message_t *msg, uint8_t priority);
+
+/**
+ * Get the ttl for a message.
+ *
+ * The ttl for a message determines how long a message is considered
+ * live. When a message is held for retransmit, the ttl is
+ * decremented. Once the ttl reaches zero, the message is considered
+ * dead. Once a message is considered dead it may be dropped. Use
+ * ::pn_message_set_ttl() to set the ttl for a message.
+ *
+ * @param[in] msg a message object
+ * @return the ttl in milliseconds
+ */
+PN_EXTERN pn_millis_t pn_message_get_ttl (pn_message_t *msg);
+
+/**
+ * Set the ttl for a message.
+ *
+ * See ::pn_message_get_ttl() for a detailed description of message ttl.
+ *
+ * @param[in] msg a message object
+ * @param[in] ttl the new value for the message ttl
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_ttl (pn_message_t *msg, pn_millis_t ttl);
+
+/**
+ * Get the first acquirer flag for a message.
+ *
+ * When set to true, the first acquirer flag for a message indicates
+ * that the recipient of the message is the first recipient to acquire
+ * the message, i.e. there have been no failed delivery attempts to
+ * other acquirers. Note that this does not mean the message has not
+ * been delivered to, but not acquired, by other recipients.
+ *
+ * @param[in] msg a message object
+ * @return the first acquirer flag for the message
+ */
+PN_EXTERN bool pn_message_is_first_acquirer (pn_message_t *msg);
+
+/**
+ * Set the first acquirer flag for a message.
+ *
+ * See ::pn_message_is_first_acquirer() for details on the first
+ * acquirer flag.
+ *
+ * @param[in] msg a message object
+ * @param[in] first the new value for the first acquirer flag
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_first_acquirer (pn_message_t *msg, bool first);
+
+/**
+ * Get the delivery count for a message.
+ *
+ * The delivery count field tracks how many attempts have been made to
+ * delivery a message. Use ::pn_message_set_delivery_count() to set
+ * the delivery count for a message.
+ *
+ * @param[in] msg a message object
+ * @return the delivery count for the message
+ */
+PN_EXTERN uint32_t pn_message_get_delivery_count (pn_message_t *msg);
+
+/**
+ * Set the delivery count for a message.
+ *
+ * See ::pn_message_get_delivery_count() for details on what the
+ * delivery count means.
+ *
+ * @param[in] msg a message object
+ * @param[in] count the new delivery count
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_delivery_count (pn_message_t *msg, uint32_t count);
+
+/**
+ * Get/set the id for a message.
+ *
+ * The message id provides a globally unique identifier for a message.
+ * A message id can be an a string, an unsigned long, a uuid or a
+ * binary value. This operation returns a pointer to a ::pn_data_t
+ * that can be used to access and/or modify the value of the message
+ * id. The pointer is valid until the message is freed. See
+ * ::pn_data_t for details on how to get/set the value.
+ *
+ * @param[in] msg a message object
+ * @return pointer to a ::pn_data_t holding the id
+ */
+PN_EXTERN pn_data_t * pn_message_id (pn_message_t *msg);
+
+/**
+ * Get the id for a message.
+ *
+ * The message id provides a globally unique identifier for a message.
+ * A message id can be an a string, an unsigned long, a uuid or a
+ * binary value. This operation returns the value of the id using the
+ * ::pn_atom_t discriminated union. See ::pn_atom_t for details on how
+ * to access the value.
+ *
+ * @param[in] msg a message object
+ * @return the message id
+ */
+PN_EXTERN pn_atom_t pn_message_get_id (pn_message_t *msg);
+
+/**
+ * Set the id for a message.
+ *
+ * See ::pn_message_get_id() for more details on the meaning of the
+ * message id. Note that only string, unsigned long, uuid, or binary
+ * values are permitted.
+ *
+ * @param[in] msg a message object
+ * @param[in] id the new value of the message id
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_id (pn_message_t *msg, pn_atom_t id);
+
+/**
+ * Get the user id for a message.
+ *
+ * The pointer referenced by the ::pn_bytes_t struct will be valid
+ * until any one of the following operations occur:
+ *
+ * - ::pn_message_free()
+ * - ::pn_message_clear()
+ * - ::pn_message_set_user_id()
+ *
+ * @param[in] msg a message object
+ * @return a pn_bytes_t referencing the message's user_id
+ */
+PN_EXTERN pn_bytes_t pn_message_get_user_id (pn_message_t *msg);
+
+/**
+ * Set the user id for a message.
+ *
+ * This operation copies the bytes referenced by the provided
+ * ::pn_bytes_t struct.
+ *
+ * @param[in] msg a message object
+ * @param[in] user_id the new user_id for the message
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_user_id (pn_message_t *msg, pn_bytes_t user_id);
+
+/**
+ * Get the address for a message.
+ *
+ * This operation will return NULL if no address has been set or if
+ * the address has been set to NULL. The pointer returned by this
+ * operation is valid until any one of the following operations occur:
+ *
+ * - ::pn_message_free()
+ * - ::pn_message_clear()
+ * - ::pn_message_set_address()
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the address of the message (or NULL)
+ */
+PN_EXTERN const char * pn_message_get_address (pn_message_t *msg);
+
+/**
+ * Set the address for a message.
+ *
+ * The supplied address pointer must either be NULL or reference a NUL
+ * terminated string. When the pointer is NULL, the address of the
+ * message is set to NULL. When the pointer is non NULL, the contents
+ * are copied into the message.
+ *
+ * @param[in] msg a message object
+ * @param[in] address a pointer to the new address (or NULL)
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_address (pn_message_t *msg, const char *address);
+
+/**
+ * Get the subject for a message.
+ *
+ * This operation will return NULL if no subject has been set or if
+ * the subject has been set to NULL. The pointer returned by this
+ * operation is valid until any one of the following operations occur:
+ *
+ * - ::pn_message_free()
+ * - ::pn_message_clear()
+ * - ::pn_message_set_subject()
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the subject of the message (or NULL)
+ */
+PN_EXTERN const char * pn_message_get_subject (pn_message_t *msg);
+
+/**
+ * Set the subject for a message.
+ *
+ * The supplied subject pointer must either be NULL or reference a NUL
+ * terminated string. When the pointer is NULL, the subject is set to
+ * NULL. When the pointer is non NULL, the contents are copied into
+ * the message.
+ *
+ * @param[in] msg a message object
+ * @param[in] subject a pointer to the new subject (or NULL)
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_subject (pn_message_t *msg, const char *subject);
+
+/**
+ * Get the reply_to for a message.
+ *
+ * This operation will return NULL if no reply_to has been set or if
+ * the reply_to has been set to NULL. The pointer returned by this
+ * operation is valid until any one of the following operations occur:
+ *
+ * - ::pn_message_free()
+ * - ::pn_message_clear()
+ * - ::pn_message_set_reply_to()
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the reply_to of the message (or NULL)
+ */
+PN_EXTERN const char * pn_message_get_reply_to (pn_message_t *msg);
+
+/**
+ * Set the reply_to for a message.
+ *
+ * The supplied reply_to pointer must either be NULL or reference a NUL
+ * terminated string. When the pointer is NULL, the reply_to is set to
+ * NULL. When the pointer is non NULL, the contents are copied into
+ * the message.
+ *
+ * @param[in] msg a message object
+ * @param[in] reply_to a pointer to the new reply_to (or NULL)
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_reply_to (pn_message_t *msg, const char *reply_to);
+
+/**
+ * Get/set the correlation id for a message.
+ *
+ * A correlation id can be an a string, an unsigned long, a uuid or a
+ * binary value. This operation returns a pointer to a ::pn_data_t
+ * that can be used to access and/or modify the value of the
+ * correlation id. The pointer is valid until the message is freed.
+ * See ::pn_data_t for details on how to get/set the value.
+ *
+ * @param[in] msg a message object
+ * @return pointer to a ::pn_data_t holding the correlation id
+ */
+PN_EXTERN pn_data_t * pn_message_correlation_id (pn_message_t *msg);
+
+/**
+ * Get the correlation id for a message.
+ *
+ * A correlation id can be an a string, an unsigned long, a uuid or a
+ * binary value. This operation returns the value of the id using the
+ * ::pn_atom_t discriminated union. See ::pn_atom_t for details on how
+ * to access the value.
+ *
+ * @param[in] msg a message object
+ * @return the message id
+ */
+PN_EXTERN pn_atom_t pn_message_get_correlation_id (pn_message_t *msg);
+
+/**
+ * Set the correlation id for a message.
+ *
+ * See ::pn_message_get_correlation_id() for more details on the
+ * meaning of the correlation id. Note that only string, unsigned
+ * long, uuid, or binary values are permitted.
+ *
+ * @param[in] msg a message object
+ * @param[in] id the new value of the message id
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_correlation_id (pn_message_t *msg, pn_atom_t id);
+
+/**
+ * Get the content_type for a message.
+ *
+ * This operation will return NULL if no content_type has been set or if
+ * the content_type has been set to NULL. The pointer returned by this
+ * operation is valid until any one of the following operations occur:
+ *
+ * - ::pn_message_free()
+ * - ::pn_message_clear()
+ * - ::pn_message_set_content_type()
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the content_type of the message (or NULL)
+ */
+PN_EXTERN const char * pn_message_get_content_type (pn_message_t *msg);
+
+/**
+ * Set the content_type for a message.
+ *
+ * The supplied content_type pointer must either be NULL or reference a NUL
+ * terminated string. When the pointer is NULL, the content_type is set to
+ * NULL. When the pointer is non NULL, the contents are copied into
+ * the message.
+ *
+ * @param[in] msg a message object
+ * @param[in] type a pointer to the new content_type (or NULL)
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_content_type (pn_message_t *msg, const char *type);
+
+/**
+ * Get the content_encoding for a message.
+ *
+ * This operation will return NULL if no content_encoding has been set or if
+ * the content_encoding has been set to NULL. The pointer returned by this
+ * operation is valid until any one of the following operations occur:
+ *
+ * - ::pn_message_free()
+ * - ::pn_message_clear()
+ * - ::pn_message_set_content_encoding()
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the content_encoding of the message (or NULL)
+ */
+PN_EXTERN const char * pn_message_get_content_encoding (pn_message_t *msg);
+
+/**
+ * Set the content_encoding for a message.
+ *
+ * The supplied content_encoding pointer must either be NULL or reference a NUL
+ * terminated string. When the pointer is NULL, the content_encoding is set to
+ * NULL. When the pointer is non NULL, the contents are copied into
+ * the message.
+ *
+ * @param[in] msg a message object
+ * @param[in] encoding a pointer to the new content_encoding (or NULL)
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_content_encoding (pn_message_t *msg, const char *encoding);
+
+/**
+ * Get the expiry time for a message.
+ *
+ * A zero value for the expiry time indicates that the message will
+ * never expire. This is the default value.
+ *
+ * @param[in] msg a message object
+ * @return the expiry time for the message
+ */
+PN_EXTERN pn_timestamp_t pn_message_get_expiry_time (pn_message_t *msg);
+
+/**
+ * Set the expiry time for a message.
+ *
+ * See ::pn_message_get_expiry_time() for more details.
+ *
+ * @param[in] msg a message object
+ * @param[in] time the new expiry time for the message
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_expiry_time (pn_message_t *msg, pn_timestamp_t time);
+
+/**
+ * Get the creation time for a message.
+ *
+ * A zero value for the creation time indicates that the creation time
+ * has not been set. This is the default value.
+ *
+ * @param[in] msg a message object
+ * @return the creation time for the message
+ */
+PN_EXTERN pn_timestamp_t pn_message_get_creation_time (pn_message_t *msg);
+
+/**
+ * Set the creation time for a message.
+ *
+ * See ::pn_message_get_creation_time() for more details.
+ *
+ * @param[in] msg a message object
+ * @param[in] time the new creation time for the message
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_creation_time (pn_message_t *msg, pn_timestamp_t time);
+
+/**
+ * Get the group_id for a message.
+ *
+ * This operation will return NULL if no group_id has been set or if
+ * the group_id has been set to NULL. The pointer returned by this
+ * operation is valid until any one of the following operations occur:
+ *
+ * - ::pn_message_free()
+ * - ::pn_message_clear()
+ * - ::pn_message_set_group_id()
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the group_id of the message (or NULL)
+ */
+PN_EXTERN const char * pn_message_get_group_id (pn_message_t *msg);
+
+/**
+ * Set the group_id for a message.
+ *
+ * The supplied group_id pointer must either be NULL or reference a NUL
+ * terminated string. When the pointer is NULL, the group_id is set to
+ * NULL. When the pointer is non NULL, the contents are copied into
+ * the message.
+ *
+ * @param[in] msg a message object
+ * @param[in] group_id a pointer to the new group_id (or NULL)
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_group_id (pn_message_t *msg, const char *group_id);
+
+/**
+ * Get the group sequence for a message.
+ *
+ * The group sequence of a message identifies the relative ordering of
+ * messages within a group. The default value for the group sequence
+ * of a message is zero.
+ *
+ * @param[in] msg a message object
+ * @return the group sequence for the message
+ */
+PN_EXTERN pn_sequence_t pn_message_get_group_sequence (pn_message_t *msg);
+
+/**
+ * Set the group sequence for a message.
+ *
+ * See ::pn_message_get_group_sequence() for details on what the group
+ * sequence means.
+ *
+ * @param[in] msg a message object
+ * @param[in] n the new group sequence for the message
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_group_sequence (pn_message_t *msg, pn_sequence_t n);
+
+/**
+ * Get the reply_to_group_id for a message.
+ *
+ * This operation will return NULL if no reply_to_group_id has been set or if
+ * the reply_to_group_id has been set to NULL. The pointer returned by this
+ * operation is valid until any one of the following operations occur:
+ *
+ * - ::pn_message_free()
+ * - ::pn_message_clear()
+ * - ::pn_message_set_reply_to_group_id()
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the reply_to_group_id of the message (or NULL)
+ */
+PN_EXTERN const char * pn_message_get_reply_to_group_id (pn_message_t *msg);
+
+/**
+ * Set the reply_to_group_id for a message.
+ *
+ * The supplied reply_to_group_id pointer must either be NULL or reference a NUL
+ * terminated string. When the pointer is NULL, the reply_to_group_id is set to
+ * NULL. When the pointer is non NULL, the contents are copied into
+ * the message.
+ *
+ * @param[in] msg a message object
+ * @param[in] reply_to_group_id a pointer to the new reply_to_group_id (or NULL)
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_set_reply_to_group_id (pn_message_t *msg, const char *reply_to_group_id);
+
+/**
+ * Get/set the delivery instructions for a message.
+ *
+ * This operation returns a pointer to a ::pn_data_t representing the
+ * content of the delivery instructions section of a message. The
+ * pointer is valid until the message is freed and may be used to both
+ * access and modify the content of the delivery instructions section
+ * of a message.
+ *
+ * The ::pn_data_t must either be empty or consist of a symbol keyed
+ * map in order to be considered valid delivery instructions.
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the delivery instructions
+ */
+PN_EXTERN pn_data_t *pn_message_instructions(pn_message_t *msg);
+
+/**
+ * Get/set the annotations for a message.
+ *
+ * This operation returns a pointer to a ::pn_data_t representing the
+ * content of the annotations section of a message. The pointer is
+ * valid until the message is freed and may be used to both access and
+ * modify the content of the annotations section of a message.
+ *
+ * The ::pn_data_t must either be empty or consist of a symbol keyed
+ * map in order to be considered valid message annotations.
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the message annotations
+ */
+PN_EXTERN pn_data_t *pn_message_annotations(pn_message_t *msg);
+
+/**
+ * Get and set the properties for a message.
+ *
+ * This operation returns a pointer to a ::pn_data_t representing the
+ * content of the properties section of a message. The pointer is
+ * valid until the message is freed and may be used to both access and
+ * modify the content of the properties section of a message.
+ *
+ * The ::pn_data_t must either be empty or consist of a string keyed
+ * map in order to be considered valid message properties.
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the message properties
+ */
+PN_EXTERN pn_data_t *pn_message_properties(pn_message_t *msg);
+
+/**
+ * Get and set the body of a message.
+ *
+ * This operation returns a pointer to a ::pn_data_t representing the
+ * body of a message. The pointer is valid until the message is freed
+ * and may be used to both access and modify the content of the
+ * message body.
+ *
+ * @param[in] msg a message object
+ * @return a pointer to the message body
+ */
+PN_EXTERN pn_data_t *pn_message_body(pn_message_t *msg);
+
+/**
+ * Decode/load message content from AMQP formatted binary data.
+ *
+ * Upon invoking this operation, any existing message content will be
+ * cleared and replaced with the content from the provided binary
+ * data.
+ *
+ * @param[in] msg a message object
+ * @param[in] bytes the start of the encoded AMQP data
+ * @param[in] size the size of the encoded AMQP data
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_decode(pn_message_t *msg, const char *bytes, size_t size);
+
+/**
+ * Encode/save message content as AMQP formatted binary data.
+ *
+ * If the buffer space provided is insufficient to store the content
+ * held in the message, the operation will fail and return a
+ * PN_OVERFLOW error code.
+ *
+ * @param[in] msg a message object
+ * @param[in] bytes the start of empty buffer space
+ * @param[in] size the amount of empty buffer space
+ * @param[out] size the amount of data written
+ * @return zero on success or an error code on failure
+ */
+PN_EXTERN int pn_message_encode(pn_message_t *msg, char *bytes, size_t *size);
+
+/**
+ * Save message content into a pn_data_t object data. The data object will first be cleared.
+ */
+PN_EXTERN int pn_message_data(pn_message_t *msg, pn_data_t *data);
+
+/** @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* message.h */
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org