http://git-wip-us.apache.org/repos/asf/qpid-proton-j/blob/2f85988e/proton-c/include/proton/link.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/link.h b/proton-c/include/proton/link.h deleted file mode 100644 index d52e6e7..0000000 --- a/proton-c/include/proton/link.h +++ /dev/null @@ -1,688 +0,0 @@ -#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 - * - * 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 - * - * 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 mixure 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); - -//PN_EXTERN void pn_link_abort(pn_sender_t *sender); - -/** - * 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 is false, - * and ::pn_delivery_pending is 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, PN_EOS, or an error code - */ -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); - -/** - * **Experimental** - 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); - -/** - * **Experimental** - 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); - -/** - * **Experimental** - 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-j/blob/2f85988e/proton-c/include/proton/listener.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/listener.h b/proton-c/include/proton/listener.h deleted file mode 100644 index 8b70c9a..0000000 --- a/proton-c/include/proton/listener.h +++ /dev/null @@ -1,122 +0,0 @@ -#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/types.h> - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * @file - * - * **Experimental** - A listener for incoming connections for the @ref - * proactor. - * - * @addtogroup proactor - * @{ - */ - -/** - * @cond INTERNAL - */ -typedef struct pn_proactor_t pn_proactor_t; -typedef struct pn_condition_t pn_condition_t; -/** - * @endcond - */ - -/** - * A listener accepts connections. - */ -typedef struct pn_listener_t pn_listener_t; - -/** - * Create a listener. - * - * You can use pn_listener_set_context() or pn_listener_attachments() to set - * application data that can be accessed when accepting connections. - * - * You must pass the returned listener to pn_proactor_listen(), the proactor - * will free the listener when it is no longer active. - */ -PN_EXTERN pn_listener_t *pn_listener(void); - -/** - * Asynchronously accept a connection using the listener. - * - * @param[in] connection the listener takes ownership, do not free. - */ -PN_EXTERN int pn_listener_accept(pn_listener_t*, pn_connection_t *connection); - -/** - * Get the error condition for a listener. - */ -PN_EXTERN pn_condition_t *pn_listener_condition(pn_listener_t *l); - -/** - * @cond INTERNAL - */ - -/** - * @deprecated - * - * Get the application context that is associated with a listener. - */ -PN_EXTERN void *pn_listener_get_context(pn_listener_t *listener); - -/** - * @deprecated - * - * Set a new application context for a listener. - */ -PN_EXTERN void pn_listener_set_context(pn_listener_t *listener, void *context); - -/** - * @endcond - */ - -/** - * Get the attachments that are associated with a listener object. - */ -PN_EXTERN pn_record_t *pn_listener_attachments(pn_listener_t *listener); - -/** - * Close the listener (thread safe). - */ -PN_EXTERN void pn_listener_close(pn_listener_t *l); - -/** - * The proactor associated with a listener. - */ -PN_EXTERN pn_proactor_t *pn_listener_proactor(pn_listener_t *c); - - -/** - *@} - */ - -#ifdef __cplusplus -} -#endif - -#endif /* listener.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton-j/blob/2f85988e/proton-c/include/proton/log.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/log.h b/proton-c/include/proton/log.h deleted file mode 100644 index 35538f7..0000000 --- a/proton-c/include/proton/log.h +++ /dev/null @@ -1,71 +0,0 @@ -#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 envionment 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 messsage 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-j/blob/2f85988e/proton-c/include/proton/message.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/message.h b/proton-c/include/proton/message.h deleted file mode 100644 index 5c310b0..0000000 --- a/proton-c/include/proton/message.h +++ /dev/null @@ -1,754 +0,0 @@ -#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); - -// standard message headers and properties - -/** - * 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 descriminated 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 descriminated 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/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/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]
