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: [email protected] For additional commands, e-mail: [email protected]
