http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/connection_driver.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/connection_driver.h b/proton-c/include/proton/connection_driver.h index af08160..9db8233 100644 --- a/proton-c/include/proton/connection_driver.h +++ b/proton-c/include/proton/connection_driver.h @@ -1,5 +1,5 @@ #ifndef PROTON_CONNECTION_DRIVER_H -#define PROTON_CONNECTION_DRIVER_H +#define PROTON_CONNECTION_DRIVER_H 1 /* * Licensed to the Apache Software Foundation (ASF) under one @@ -22,51 +22,55 @@ /** * @file - * **Experimental**: Low-level IO integration * - * @defgroup connection_driver Connection Driver + * **Experimental** - Low-level IO integration * - * **Experimental**: Low-level IO integration - * - * Associate an @ref engine with AMQP byte-streams from any source. + * Associate a @ref connection and @ref transport with AMQP byte + * streams from any source. * * - process AMQP-encoded bytes from some input byte stream * - generate ::pn_event_t events for your application to handle * - encode resulting AMQP output bytes for some output byte stream * - * The pn_connection_driver_() functions provide a simplified API and extra - * logic to use ::pn_connection_t and ::pn_transport_t as a unit. You can also - * access them directly for features that do not have pn_connection_driver_() - * functions + * The pn_connection_driver_() functions provide a simplified API and + * extra logic to use ::pn_connection_t and ::pn_transport_t as a + * unit. You can also access them directly for features that do not + * have pn_connection_driver_() functions. * * The driver buffers events and data, you should run it until - * pn_connection_driver_finished() is true, to ensure all reading, writing and - * event handling (including ERROR and FINAL events) is finished. + * pn_connection_driver_finished() is true, to ensure all reading, + * writing and event handling (including ERROR and FINAL events) is + * finished. * * ## Error handling * - * The pn_connection_driver_*() functions do not return an error code. IO errors set - * the transport condition and are returned as a PN_TRANSPORT_ERROR. The integration - * code can set errors using pn_connection_driver_errorf() + * The pn_connection_driver_*() functions do not return an error + * code. IO errors set the transport condition and are returned as a + * PN_TRANSPORT_ERROR. The integration code can set errors using + * pn_connection_driver_errorf(). * * ## IO patterns * - * This API supports asynchronous, proactive, non-blocking and reactive IO. An - * integration does not have to follow the dispatch-read-write sequence above, - * but note that you should handle all available events before calling - * pn_connection_driver_read_buffer() and check that `size` is non-zero before - * starting a blocking or asynchronous read call. A `read` started while there - * are unprocessed CLOSE events in the buffer may never complete. + * This API supports asynchronous, proactive, non-blocking and + * reactive IO. An integration does not have to follow the + * dispatch-read-write sequence above, but note that you should handle + * all available events before calling + * pn_connection_driver_read_buffer() and check that `size` is + * non-zero before starting a blocking or asynchronous read call. A + * `read` started while there are unprocessed CLOSE events in the + * buffer may never complete. * - * AMQP is a full-duplex, asynchronous protocol. The "read" and "write" sides of - * an AMQP connection can close separately + * AMQP is a full-duplex, asynchronous protocol. The "read" and + * "write" sides of an AMQP connection can close separately. * * ## Thread safety * - * The @ref connection_driver types are not thread safe, but each connection and its - * associated types forms an independent unit. Different connections can be - * processed concurrently by different threads. + * The @ref connection_driver types are not thread safe, but each + * connection and its associated types forms an independent + * unit. Different connections can be processed concurrently by + * different threads. * + * @addtogroup connection_driver * @{ */ @@ -81,7 +85,7 @@ extern "C" { #endif /** - * Struct containing the 3 elements needed to driver AMQP IO and events, aggregated as a unit. + * The elements needed to drive AMQP IO and events. */ typedef struct pn_connection_driver_t { pn_connection_t *connection; @@ -235,10 +239,13 @@ PN_EXTERN void pn_connection_driver_vlogf(pn_connection_driver_t *d, const char * else return NULL */ PN_EXTERN pn_connection_driver_t* pn_event_batch_connection_driver(pn_event_batch_t *batch); -///@} + +/** + * @} + */ #ifdef __cplusplus } #endif -#endif // PROTON_CONNECTION_DRIVER_H +#endif /* connection_driver.h */
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/delivery.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/delivery.h b/proton-c/include/proton/delivery.h index 4225352..dbb73bf 100644 --- a/proton-c/include/proton/delivery.h +++ b/proton-c/include/proton/delivery.h @@ -33,11 +33,8 @@ extern "C" { /** * @file - * Track message delivery * - * @defgroup delivery Delivery - * Track message delivery - * @ingroup engine + * @addtogroup delivery * @{ */ @@ -70,6 +67,7 @@ PN_EXTERN pn_delivery_t *pn_delivery(pn_link_t *link, pn_delivery_tag_t tag); /** * @deprecated + * * Get the application context that is associated with a delivery object. * * The application context for a delivery may be set using @@ -82,6 +80,7 @@ PN_EXTERN void *pn_delivery_get_context(pn_delivery_t *delivery); /** * @deprecated + * * Set a new application context for a delivery object. * * The application context for a delivery object may be retrieved using @@ -245,7 +244,7 @@ PN_EXTERN bool pn_delivery_current(pn_delivery_t *delivery); * * A settled delivery can never be used again. * - * NOTE: if pn_delivery_current(delivery) is true before the call then + * @note If pn_delivery_current(delivery) is true before the call then * pn_link_advance(pn_delivery_link(deliver)) is called automatically. * * @param[in] delivery a delivery object @@ -302,7 +301,8 @@ PN_EXTERN pn_delivery_t *pn_work_head(pn_connection_t *connection); */ PN_EXTERN pn_delivery_t *pn_work_next(pn_delivery_t *delivery); -/** @} +/** + * @} */ #ifdef __cplusplus http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/disposition.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/disposition.h b/proton-c/include/proton/disposition.h index 530b738..95bfe51 100644 --- a/proton-c/include/proton/disposition.h +++ b/proton-c/include/proton/disposition.h @@ -33,11 +33,8 @@ extern "C" { /** * @file - * Outcome of message delivery * - * @defgroup disposition Disposition - * Outcome of message delivery - * @ingroup delivery + * @addtogroup delivery * @{ */ @@ -221,7 +218,8 @@ PN_EXTERN void pn_disposition_set_undeliverable(pn_disposition_t *disposition, b */ PN_EXTERN pn_data_t *pn_disposition_annotations(pn_disposition_t *disposition); -/** @} +/** + * @} */ #ifdef __cplusplus http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/engine.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/engine.h b/proton-c/include/proton/engine.h index b24265e..9763e07 100644 --- a/proton-c/include/proton/engine.h +++ b/proton-c/include/proton/engine.h @@ -23,13 +23,7 @@ */ /** - * @file - * - * The AMQP protocol engine - * - * @defgroup engine Engine - * - * Types and functions that implement the AMQP protocol + * @cond INTERNAL */ #include <proton/condition.h> @@ -41,4 +35,8 @@ #include <proton/event.h> #include <proton/transport.h> +/** + * @endcond + */ + #endif /* engine.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/error.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/error.h b/proton-c/include/proton/error.h index 122e4b6..2986850 100644 --- a/proton-c/include/proton/error.h +++ b/proton-c/include/proton/error.h @@ -29,52 +29,99 @@ extern "C" { #endif -/** A pn_error_t has an int error `code` and some string `text` to describe the error */ +/** + * @file + * + * @addtogroup error + * @{ + */ + +/** + * An int error `code` and some string `text` to describe the error. + */ typedef struct pn_error_t pn_error_t; -#define PN_OK (0) -#define PN_EOS (-1) -#define PN_ERR (-2) -#define PN_OVERFLOW (-3) -#define PN_UNDERFLOW (-4) -#define PN_STATE_ERR (-5) -#define PN_ARG_ERR (-6) -#define PN_TIMEOUT (-7) -#define PN_INTR (-8) -#define PN_INPROGRESS (-9) -#define PN_OUT_OF_MEMORY (-10) - -/** @return name of the error code. Returned pointer is to a static constant, do not delete.*/ +#define PN_OK (0) /**< No error */ +#define PN_EOS (-1) /**< End of stream */ +#define PN_ERR (-2) /**< General error */ +#define PN_OVERFLOW (-3) /**< Overflow error */ +#define PN_UNDERFLOW (-4) /**< Underflow error */ +#define PN_STATE_ERR (-5) /**< State error */ +#define PN_ARG_ERR (-6) /**< Argument error */ +#define PN_TIMEOUT (-7) /**< Timeout */ +#define PN_INTR (-8) /**< Interrupt */ +#define PN_INPROGRESS (-9) /**< In-progress */ +#define PN_OUT_OF_MEMORY (-10) /**< Out-of-momory error */ + +/** + * Get the name of the error code. Returned pointer is to a static + * constant, do not delete. + */ PN_EXTERN const char *pn_code(int code); +/** + * Create an error object. + */ PN_EXTERN pn_error_t *pn_error(void); + +/** + * Free an error object. + */ PN_EXTERN void pn_error_free(pn_error_t *error); -/** Reset the error to a "no error" state with code == 0. */ +/** + * Reset the error to a "no error" state with code == 0. + */ PN_EXTERN void pn_error_clear(pn_error_t *error); -/** Set the error code and text. Makes a copy of text. */ +/** + * Set the error code and text. Makes a copy of text. + */ PN_EXTERN int pn_error_set(pn_error_t *error, int code, const char *text); -/** Set the code and set the text using a printf-style formatted string. */ +/** + * Set the code and set the text using a printf-style formatted + * string. + */ PN_EXTERN int pn_error_vformat(pn_error_t *error, int code, const char *fmt, va_list ap); -/** Set the code and set the text using a printf-style formatted string. */ +/** + * Set the code and set the text using a printf-style formatted + * string. + */ PN_EXTERN int pn_error_format(pn_error_t *error, int code, const char *fmt, ...); -/** @return the error code. */ +/** + * Get the the error code. + */ PN_EXTERN int pn_error_code(pn_error_t *error); -/** @return the error text. Returned pointer is owned by the pn_error_t. */ +/** + * Get the error text. The returned pointer is owned by the + * pn_error_t. + */ PN_EXTERN const char *pn_error_text(pn_error_t *error); +/** + * Copy the src error. + */ PN_EXTERN int pn_error_copy(pn_error_t *error, pn_error_t *src); +/** + * @cond INTERNAL + */ #define PN_RETURN_IF_ERROR(x) \ do {\ int r = (x);\ if (r < 0) return r; \ } while (0) +/** + * @endcond + */ + +/** + * @} + */ #ifdef __cplusplus } http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/event.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/event.h b/proton-c/include/proton/event.h index 2280dc8..fad221b 100644 --- a/proton-c/include/proton/event.h +++ b/proton-c/include/proton/event.h @@ -33,17 +33,13 @@ extern "C" { /** * @file - * AMQP and transport events * - * @defgroup event Event - * AMQP and transport events - * @ingroup engine + * @addtogroup event * @{ */ /** - * An event provides notification of a state change within the - * protocol engine's object model. + * Notification of a state change in the protocol engine. * * The AMQP endpoint state modeled by the protocol engine is captured * by the following object types: @link pn_delivery_t Deliveries @@ -539,8 +535,9 @@ PN_EXTERN pn_transport_t *pn_event_transport(pn_event_t *event); PN_EXTERN pn_record_t *pn_event_attachments(pn_event_t *event); /** - * **Experimental**: A batch of events to handle. Call pn_event_batch_next() in - * a loop until it returns NULL to handle them. + * **Experimental** - A batch of events to handle. Call + * pn_event_batch_next() in a loop until it returns NULL to handle + * them. */ typedef struct pn_event_batch_t pn_event_batch_t; @@ -550,29 +547,31 @@ typedef struct pn_event_batch_t pn_event_batch_t; */ /** - * **Experimental**: Remove the next event from the batch and return it. NULL - * means the batch is empty. The returned event pointer is valid until - * pn_event_batch_next() is called again on the same batch. + * **Experimental** - Remove the next event from the batch and return + * it. NULL means the batch is empty. The returned event pointer is + * valid until pn_event_batch_next() is called again on the same + * batch. */ PN_EXTERN pn_event_t *pn_event_batch_next(pn_event_batch_t *batch); /** - *@cond INTERNAL + * @cond INTERNAL + * * pn_event_batch_next() can be re-implemented for different behaviors in different contextxs. */ struct pn_event_batch_t { pn_event_t *(*next_event)(pn_event_batch_t *batch); }; - /** - *@endcond + * @endcond */ #ifdef __cplusplus } #endif -/** @} +/** + * @} */ #endif /* event.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/handlers.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/handlers.h b/proton-c/include/proton/handlers.h index bfa68fc..6518e87 100644 --- a/proton-c/include/proton/handlers.h +++ b/proton-c/include/proton/handlers.h @@ -33,11 +33,7 @@ extern "C" { /** * @file * - * Reactor API for proton. - * - * @defgroup handlers Handlers - * Reactor API for proton. - * @{ + * @cond INTERNAL */ typedef pn_handler_t pn_handshaker_t; @@ -48,7 +44,8 @@ PNX_EXTERN pn_handshaker_t *pn_handshaker(void); PNX_EXTERN pn_iohandler_t *pn_iohandler(void); PNX_EXTERN pn_flowcontroller_t *pn_flowcontroller(int window); -/** @} +/** + * @endcond */ #ifdef __cplusplus http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/import_export.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/import_export.h b/proton-c/include/proton/import_export.h index 0010126..6547a07 100644 --- a/proton-c/include/proton/import_export.h +++ b/proton-c/include/proton/import_export.h @@ -22,6 +22,10 @@ * */ +/** + * @cond INTERNAL + */ + // // Compiler specific mechanisms for managing the import and export of // symbols between shared objects. @@ -59,5 +63,8 @@ # define PNX_EXTERN PN_IMPORT #endif +/** + * @endcond + */ #endif /* import_export.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/link.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/link.h b/proton-c/include/proton/link.h index 3ab811c..aeb3b36 100644 --- a/proton-c/include/proton/link.h +++ b/proton-c/include/proton/link.h @@ -36,11 +36,8 @@ extern "C" { /** * @file - * One-way message link * - * @defgroup link Link - * One-way message link - * @ingroup engine + * @addtogroup link * @{ */ @@ -85,6 +82,7 @@ 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 @@ -97,6 +95,7 @@ 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 @@ -565,12 +564,6 @@ PN_EXTERN pn_delivery_t *pn_unsettled_head(pn_link_t *link); PN_EXTERN pn_delivery_t *pn_unsettled_next(pn_delivery_t *delivery); /** - * @defgroup sender Sender - * Sending link - * @{ - */ - -/** * Signal the availability of deliveries for a link. * * @param[in] sender a sender link object @@ -591,14 +584,6 @@ 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); -/** @} */ - -/** - * @defgroup receiver Receiver - * Receiving link - * @{ - */ - /** * Grant credit for incoming deliveries on a receiver. * @@ -657,9 +642,8 @@ PN_EXTERN ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n); */ PN_EXTERN bool pn_link_draining(pn_link_t *receiver); -/** @} */ - -/** @} +/** + * @} */ #ifdef __cplusplus http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/listener.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/listener.h b/proton-c/include/proton/listener.h index dda1638..8b70c9a 100644 --- a/proton-c/include/proton/listener.h +++ b/proton-c/include/proton/listener.h @@ -1,5 +1,5 @@ #ifndef PROTON_LISTENER_H -#define PROTON_LISTENER_H +#define PROTON_LISTENER_H 1 /* * Licensed to the Apache Software Foundation (ASF) under one @@ -29,17 +29,21 @@ extern "C" { /** * @file * - * Listener for the @ref proactor + * **Experimental** - A listener for incoming connections for the @ref + * proactor. * - * @defgroup listener Listener - * Listen for incoming connections with a @ref proactor - * - * @ingroup 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. @@ -70,16 +74,28 @@ PN_EXTERN int pn_listener_accept(pn_listener_t*, pn_connection_t *connection); 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); @@ -103,4 +119,4 @@ PN_EXTERN pn_proactor_t *pn_listener_proactor(pn_listener_t *c); } #endif -#endif // PROTON_LISTENER_H +#endif /* listener.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/log.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/log.h b/proton-c/include/proton/log.h index 1387df5..35538f7 100644 --- a/proton-c/include/proton/log.h +++ b/proton-c/include/proton/log.h @@ -26,23 +26,32 @@ extern "C" { #endif -/**@file +/** + * @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. */ +/** + * Callback for customized logging. + */ typedef void (*pn_logger_t)(const char *message); -/** Enable/disable global logging. +/** + * 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. +/** + * Set the logger. * * By default a logger that prints to stderr is installed. * @@ -51,6 +60,10 @@ PN_EXTERN void pn_log_enable(bool enabled); */ PN_EXTERN void pn_log_logger(pn_logger_t logger); +/** + * @endcond + */ + #ifdef __cplusplus } #endif http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/message.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/message.h b/proton-c/include/proton/message.h index 8741996..b047a43 100644 --- a/proton-c/include/proton/message.h +++ b/proton-c/include/proton/message.h @@ -34,10 +34,8 @@ extern "C" { /** * @file - * Encode/decode AMQP Messages * - * @defgroup message Message - * Encode/decode AMQP Messages + * @addtogroup message * @{ */ @@ -729,7 +727,7 @@ PN_EXTERN int pn_message_decode(pn_message_t *msg, const char *bytes, size_t siz * * 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. + * PN_OVERFLOW error code. * * @param[in] msg a message object * @param[in] bytes the start of empty buffer space http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/messenger.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/messenger.h b/proton-c/include/proton/messenger.h index 198b6c6..c11e7a5 100644 --- a/proton-c/include/proton/messenger.h +++ b/proton-c/include/proton/messenger.h @@ -35,12 +35,12 @@ extern "C" { /** * @file + * @deprecated * * The messenger API provides a high level interface for sending and * receiving AMQP messages. * - * @defgroup messenger Messenger - * **Deprecated** + * @addtogroup messenger * @{ */ @@ -934,8 +934,7 @@ PNX_EXTERN int pn_messenger_rewrite(pn_messenger_t *messenger, const char *patte const char *address); /** - * Extract @link pn_selectable_t selectables @endlink from a passive - * messenger. + * Extract selectables from a passive messenger. * * A messenger that is in passive mode (see * ::pn_messenger_is_passive()) will never attempt to perform any I/O @@ -945,17 +944,16 @@ PNX_EXTERN int pn_messenger_rewrite(pn_messenger_t *messenger, const char *patte * * An application wishing to perform I/O on behalf of a passive * messenger must extract all available selectables by calling this - * operation until it returns NULL. The ::pn_selectable_t interface - * may then be used by the application to perform I/O outside the - * messenger. + * operation until it returns NULL. The selectable interface may then + * be used by the application to perform I/O outside the messenger. * * All selectables returned by this operation must be serviced until * they reach a terminal state and then freed. See - * ::pn_selectable_is_terminal() for more details. + * `pn_selectable_is_terminal()` for more details. * * By default any given selectable will only ever be returned once by * this operation, however if the selectable's registered flag is set - * to true (see ::pn_selectable_set_registered()), then the selectable + * to true (see `pn_selectable_set_registered()`), then the selectable * will be returned whenever its interest set may have changed. * * @param[in] messenger a messenger object @@ -971,21 +969,18 @@ PNX_EXTERN pn_selectable_t *pn_messenger_selectable(pn_messenger_t *messenger); */ PNX_EXTERN pn_timestamp_t pn_messenger_deadline(pn_messenger_t *messenger); -/** - * @} - */ - -#define PN_FLAGS_CHECK_ROUTES \ - (0x1) /** Messenger flag to indicate that a call \ - to pn_messenger_start should check that \ - any defined routes are valid */ +#define PN_FLAGS_CHECK_ROUTES \ + (0x1) /**< Messenger flag to indicate that a call \ + to pn_messenger_start should check that \ + any defined routes are valid */ -#define PN_FLAGS_ALLOW_INSECURE_MECHS \ - (0x2) /** Messenger flag to indicate that the PLAIN \ - mechanism is allowed on an unencrypted \ - connection */ +#define PN_FLAGS_ALLOW_INSECURE_MECHS \ + (0x2) /**< Messenger flag to indicate that the PLAIN \ + mechanism is allowed on an unencrypted \ + connection */ -/** Sets control flags to enable additional function for the Messenger. +/** + * Sets control flags to enable additional function for the Messenger. * * @param[in] messenger the messenger * @param[in] flags 0 or PN_FLAGS_CHECK_ROUTES @@ -995,7 +990,8 @@ PNX_EXTERN pn_timestamp_t pn_messenger_deadline(pn_messenger_t *messenger); PNX_EXTERN int pn_messenger_set_flags(pn_messenger_t *messenger, const int flags); -/** Gets the flags for a Messenger. +/** + * Gets the flags for a Messenger. * * @param[in] messenger the messenger * @return The flags set for the messenger @@ -1053,6 +1049,10 @@ PNX_EXTERN int pn_messenger_set_ssl_peer_authentication_mode(pn_messenger_t *messenger, const pn_ssl_verify_mode_t mode); +/** + * @} + */ + #ifdef __cplusplus } #endif http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/object.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/object.h b/proton-c/include/proton/object.h index 0433b58..e7efd94 100644 --- a/proton-c/include/proton/object.h +++ b/proton-c/include/proton/object.h @@ -33,6 +33,10 @@ extern "C" { #endif +/** + * @cond INTERNAL + */ + typedef void* pn_handle_t; typedef intptr_t pn_shandle_t; @@ -330,6 +334,10 @@ PN_EXTERN void *pn_record_get(pn_record_t *record, pn_handle_t key); PN_EXTERN void pn_record_set(pn_record_t *record, pn_handle_t key, void *value); PN_EXTERN void pn_record_clear(pn_record_t *record); +/** + * @endcond + */ + #ifdef __cplusplus } #endif http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/parser.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/parser.h b/proton-c/include/proton/parser.h index 369ba8f..a95ca86 100644 --- a/proton-c/include/proton/parser.h +++ b/proton-c/include/proton/parser.h @@ -29,6 +29,10 @@ extern "C" { #endif +/** + * @cond INTERNAL + */ + typedef struct pn_parser_t pn_parser_t; PN_EXTERN pn_parser_t *pn_parser(void); @@ -37,6 +41,10 @@ PN_EXTERN int pn_parser_errno(pn_parser_t *parser); PN_EXTERN const char *pn_parser_error(pn_parser_t *parser); PN_EXTERN void pn_parser_free(pn_parser_t *parser); +/** + * @endcond + */ + #ifdef __cplusplus } #endif http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/proactor.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/proactor.h b/proton-c/include/proton/proactor.h index fdb723b..b8fb16a 100644 --- a/proton-c/include/proton/proactor.h +++ b/proton-c/include/proton/proactor.h @@ -1,5 +1,5 @@ #ifndef PROTON_PROACTOR_H -#define PROTON_PROACTOR_H +#define PROTON_PROACTOR_H 1 /* * Licensed to the Apache Software Foundation (ASF) under one @@ -28,26 +28,32 @@ extern "C" { #endif +/** + * @cond INTERNAL + */ typedef struct pn_condition_t pn_condition_t; +/** + * @endcond + */ /** * @file * - * **Experimental**: Multi-threaded IO - * @defgroup proactor Proactor + * **Experimental** - Multithreaded IO * - * **Experimental**: Multi-threaded IO + * The proactor associates a @ref connection with a @ref transport, + * either by making an outgoing connection or accepting an incoming + * one. It delivers @ref event "events" to application threads for + * handling. * - * The proactor associates a @ref connection with a @ref transport, either - * by making an outgoing connection or accepting an incoming one. - * It delivers @ref event "events" to application threads for handling. + * ## Multi-threading * - * **Multi-threading**: - * The @ref proactor is thread-safe, but the @ref engine is not. The proactor - * ensures that each @ref connection and its associated values (@ref session, - * @ref link etc.) is handle sequentially, even if there are multiple - * application threads. See pn_proactor_wait() + * The @ref proactor is thread-safe, but the protocol engine is not. + * The proactor ensures that each @ref connection and its associated + * values (@ref session, @ref link etc.) is handle sequentially, even + * if there are multiple application threads. See pn_proactor_wait(). * + * @addtogroup proactor * @{ */ @@ -65,112 +71,123 @@ pn_proactor_t *pn_proactor(void); * Free the proactor. Abort any open network connections and clean up all * associated resources. */ -void pn_proactor_free(pn_proactor_t*); +void pn_proactor_free(pn_proactor_t *proactor); /** * Connect connection to host/port. Connection and transport events will be * returned by pn_proactor_wait() * + * @param[in] proactor the proactor object * @param[in] connection the proactor takes ownership, do not free * @param[in] host address to connect on * @param[in] port port to connect to * * @return error on immediate error, e.g. an allocation failure. - * Other errors are indicated by connection or transport events via pn_proactor_wait() + * Other errors are indicated by connection or transport events via + * pn_proactor_wait() */ -int pn_proactor_connect(pn_proactor_t*, pn_connection_t *connection, const char *host, const char *port); +int pn_proactor_connect(pn_proactor_t *proactor, pn_connection_t *connection, + const char *host, const char *port); /** - * Start listening with listener. - * pn_proactor_wait() will return a PN_LISTENER_ACCEPT event when a connection can be accepted. + * Start listening with listener. pn_proactor_wait() will return a + * PN_LISTENER_ACCEPT event when a connection can be accepted. * + * @param[in] proactor the proactor object * @param[in] listener proactor takes ownership of listener, do not free * @param[in] host address to listen on * @param[in] port port to listen on * @param[in] backlog number of connection requests to queue * * @return error on immediate error, e.g. an allocation failure. - * Other errors are indicated by pn_listener_condition() on the PN_LISTENER_CLOSE event. + * Other errors are indicated by pn_listener_condition() on the + * PN_LISTENER_CLOSE event. */ -int pn_proactor_listen(pn_proactor_t *, pn_listener_t *listener, const char *host, const char *port, int backlog); +int pn_proactor_listen(pn_proactor_t *proactor, pn_listener_t *listener, + const char *host, const char *port, int backlog); /** * Wait for events to handle. * - * Handle events in the returned batch by calling pn_event_batch_next() until it - * returns NULL. You must call pn_proactor_done() when you are finished with the batch. + * Handle events in the returned batch by calling + * pn_event_batch_next() until it returns NULL. You must call + * pn_proactor_done() when you are finished with the batch. * - * If you call pn_proactor_done() before finishing the batch, the remaining - * events will be returned again by another call pn_proactor_wait(). This is - * less efficient, but allows you to handle part of a batch and then hand off - * the rest to another thread. + * If you call pn_proactor_done() before finishing the batch, the + * remaining events will be returned again by another call + * pn_proactor_wait(). This is less efficient, but allows you to + * handle part of a batch and then hand off the rest to another + * thread. * - * Thread safe: can be called concurrently. Events in a single batch must be - * handled in sequence, but batches returned by separate calls to - * pn_proactor_wait() can be handled concurrently. + * @note Thread-safe: can be called concurrently. Events in a single + * batch must be handled in sequence, but batches returned by separate + * calls to pn_proactor_wait() can be handled concurrently. */ -pn_event_batch_t *pn_proactor_wait(pn_proactor_t *d); +pn_event_batch_t *pn_proactor_wait(pn_proactor_t *proactor); /** * Call when done handling a batch of events. * - * Must be called exactly once to match each call to pn_proactor_wait(). + * Must be called exactly once to match each call to + * pn_proactor_wait(). * - * Thread safe: may be called from any thread provided the exactly once rule is - * respected. + * @note Thread-safe: may be called from any thread provided the + * exactly once rule is respected. */ -void pn_proactor_done(pn_proactor_t *d, pn_event_batch_t *events); +void pn_proactor_done(pn_proactor_t *proactor, pn_event_batch_t *events); /** * Cause PN_PROACTOR_INTERRUPT to be returned to exactly one call of * pn_proactor_wait(). * * If threads are blocked in pn_proactor_wait(), one of them will be - * interrupted, otherwise the interrupt will be returned by a future call to - * pn_proactor_wait(). Calling pn_proactor_interrupt() N times will return - * PN_PROACTOR_INTERRUPT to N current or future calls of pn_proactor_wait() + * interrupted, otherwise the interrupt will be returned by a future + * call to pn_proactor_wait(). Calling pn_proactor_interrupt() N times + * will return PN_PROACTOR_INTERRUPT to N current or future calls of + * pn_proactor_wait() * - * Thread safe. + * @note Thread-safe. */ -void pn_proactor_interrupt(pn_proactor_t* d); +void pn_proactor_interrupt(pn_proactor_t *proactor); /** - * Cause PN_PROACTOR_TIMEOUT to be returned to a thread calling wait() after - * timeout milliseconds. Thread safe. + * Cause PN_PROACTOR_TIMEOUT to be returned to a thread calling wait() + * after timeout milliseconds. Thread-safe. * - * Note calling pn_proactor_set_timeout() again before the PN_PROACTOR_TIMEOUT is - *delivered will cancel the previous timeout and deliver an event only after - * the new timeout. ::pn_proactor_set_timeout(0) will cancel the timeout + * Note that calling pn_proactor_set_timeout() again before the + * PN_PROACTOR_TIMEOUT is delivered will cancel the previous timeout + * and deliver an event only after the new + * timeout. `pn_proactor_set_timeout(0)` will cancel the timeout * without setting a new one. */ -void pn_proactor_set_timeout(pn_proactor_t* d, pn_millis_t timeout); +void pn_proactor_set_timeout(pn_proactor_t *proactor, pn_millis_t timeout); /** * Cause a PN_CONNECTION_WAKE event to be returned by the proactor, even if * there are no IO events pending for the connection. * - * **Thread safe**: this is the only pn_connection_ function that can be - * called concurrently. + * @note Thread-safe: this is the only pn_connection_ function that + * can be called concurrently. * * Wakes can be "coalesced" - if several pn_connection_wake() calls happen * concurrently, there may be only one PN_CONNECTION_WAKE event. */ -void pn_connection_wake(pn_connection_t *c); +void pn_connection_wake(pn_connection_t *connection); /** - * Return the proactor associated with a connection or null + * Return the proactor associated with a connection or NULL. */ -pn_proactor_t *pn_connection_proactor(pn_connection_t *c); +pn_proactor_t *pn_connection_proactor(pn_connection_t *connection); /** * Return the proactor associated with an event or NULL. */ -pn_proactor_t *pn_event_proactor(pn_event_t *); +pn_proactor_t *pn_event_proactor(pn_event_t *event); /** * Return the listener associated with an event or NULL. */ -pn_listener_t *pn_event_listener(pn_event_t *); +pn_listener_t *pn_event_listener(pn_event_t *event); /** * @} @@ -180,4 +197,4 @@ pn_listener_t *pn_event_listener(pn_event_t *); } #endif -#endif // PROTON_PROACTOR_H +#endif /* proactor.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/reactor.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/reactor.h b/proton-c/include/proton/reactor.h index b61ea7a..77d78e6 100644 --- a/proton-c/include/proton/reactor.h +++ b/proton-c/include/proton/reactor.h @@ -1,4 +1,3 @@ - #ifndef PROTON_REACTOR_H #define PROTON_REACTOR_H 1 @@ -37,11 +36,7 @@ extern "C" { /** * @file * - * Reactor API for proton. - * - * @defgroup reactor Reactor - * Reactor API for proton. - * @{ + * @cond INTERNAL */ typedef struct pn_reactor_t pn_reactor_t; @@ -184,7 +179,8 @@ PNX_EXTERN void pn_record_set_handler(pn_record_t *record, pn_handler_t *handler */ PNX_EXTERN pn_handler_t *pn_event_root(pn_event_t *event); -/** @} +/** + * @endcond */ #ifdef __cplusplus http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/sasl.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/sasl.h b/proton-c/include/proton/sasl.h index e8e0d96..f5d6f2a 100644 --- a/proton-c/include/proton/sasl.h +++ b/proton-c/include/proton/sasl.h @@ -32,33 +32,34 @@ extern "C" { /** * @file - * SASL Secure Transport Layer. * - * @defgroup sasl SASL - * SASL Secure Transport Layer. + * @addtogroup sasl + * @{ + */ + +/** * The SASL layer is responsible for establishing an authenticated * and/or encrypted tunnel over which AMQP frames are passed between * peers. The peer acting as the SASL Client must provide * authentication credentials. The peer acting as the SASL Server must * provide authentication against the received credentials. - * - * @ingroup transport - * @{ */ - typedef struct pn_sasl_t pn_sasl_t; -/** The result of the SASL negotiation */ +/** + * The result of the SASL negotiation. + */ typedef enum { - PN_SASL_NONE=-1, /** negotiation not completed */ - PN_SASL_OK=0, /** authentication succeeded */ - PN_SASL_AUTH=1, /** failed due to bad credentials */ - PN_SASL_SYS=2, /** failed due to a system error */ - PN_SASL_PERM=3, /** failed due to unrecoverable error */ - PN_SASL_TEMP=4 /** failed due to transient error */ + PN_SASL_NONE = -1, /** negotiation not completed */ + PN_SASL_OK = 0, /** authentication succeeded */ + PN_SASL_AUTH = 1, /** failed due to bad credentials */ + PN_SASL_SYS = 2, /** failed due to a system error */ + PN_SASL_PERM = 3, /** failed due to unrecoverable error */ + PN_SASL_TEMP = 4 /** failed due to transient error */ } pn_sasl_outcome_t; -/** Construct an Authentication and Security Layer object +/** + * Construct an Authentication and Security Layer object. * * This will return the SASL layer object for the supplied transport * object. If there is currently no SASL layer one will be created. @@ -70,7 +71,8 @@ typedef enum { */ PN_EXTERN pn_sasl_t *pn_sasl(pn_transport_t *transport); -/** Do we support extended SASL negotiation +/** + * Do we support extended SASL negotiation * * Do we support extended SASL negotiation? * All implementations of Proton support ANONYMOUS and EXTERNAL on both @@ -83,7 +85,8 @@ PN_EXTERN pn_sasl_t *pn_sasl(pn_transport_t *transport); */ PN_EXTERN bool pn_sasl_extended(void); -/** Set the outcome of SASL negotiation +/** + * Set the outcome of SASL negotiation * * Used by the server to set the result of the negotiation process. * @@ -91,13 +94,15 @@ PN_EXTERN bool pn_sasl_extended(void); */ PN_EXTERN void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome); -/** Retrieve the outcome of SASL negotiation. +/** + * Retrieve the outcome of SASL negotiation. * * @todo */ PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl); -/** Retrieve the authenticated user +/** + * Retrieve the authenticated user * * This is usually used at the the server end to find the name of the authenticated user. * On the client it will merely return whatever user was passed in to the @@ -115,7 +120,8 @@ PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl); */ PN_EXTERN const char *pn_sasl_get_user(pn_sasl_t *sasl); -/** Return the selected SASL mechanism +/** + * Return the selected SASL mechanism * * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received. * @@ -125,7 +131,8 @@ PN_EXTERN const char *pn_sasl_get_user(pn_sasl_t *sasl); */ PN_EXTERN const char *pn_sasl_get_mech(pn_sasl_t *sasl); -/** SASL mechanisms that are to be considered for authentication +/** + * SASL mechanisms that are to be considered for authentication * * This can be used on either the client or the server to restrict the SASL * mechanisms that may be used to the mechanisms on the list. @@ -135,7 +142,8 @@ PN_EXTERN const char *pn_sasl_get_mech(pn_sasl_t *sasl); */ PN_EXTERN void pn_sasl_allowed_mechs(pn_sasl_t *sasl, const char *mechs); -/** Boolean to allow use of clear text authentication mechanisms +/** + * Boolean to allow use of clear text authentication mechanisms * * By default the SASL layer is configured not to allow mechanisms that disclose * the clear text of the password over an unencrypted AMQP connection. This specifically @@ -153,7 +161,8 @@ PN_EXTERN void pn_sasl_allowed_mechs(pn_sasl_t *sasl, const char *mechs); */ PN_EXTERN void pn_sasl_set_allow_insecure_mechs(pn_sasl_t *sasl, bool insecure); -/** Return the current value for allow_insecure_mechs +/** + * Return the current value for allow_insecure_mechs * * @param[in] sasl the SASL layer */ @@ -190,7 +199,9 @@ PN_EXTERN void pn_sasl_config_name(pn_sasl_t *sasl, const char *name); */ PN_EXTERN void pn_sasl_config_path(pn_sasl_t *sasl, const char *path); -/** @} */ +/** + * @} + */ #ifdef __cplusplus } http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/selectable.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/selectable.h b/proton-c/include/proton/selectable.h index c6e7489..56cccde 100644 --- a/proton-c/include/proton/selectable.h +++ b/proton-c/include/proton/selectable.h @@ -34,12 +34,7 @@ extern "C" { /** * @file * - * The selectable API provides an interface for integration with third - * party event loops. - * - * @defgroup selectable Selectable - * **Deprecated** - * @{ + * @cond INTERNAL */ /** @@ -268,7 +263,7 @@ PNX_EXTERN void pn_selectable_free(pn_selectable_t *selectable); PNX_EXTERN void pn_selectable_collect(pn_selectable_t *selectable, pn_collector_t *collector); /** - * @} + * @endcond */ #ifdef __cplusplus http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/session.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/session.h b/proton-c/include/proton/session.h index 34f0cfd..8cca7f6 100644 --- a/proton-c/include/proton/session.h +++ b/proton-c/include/proton/session.h @@ -35,12 +35,9 @@ extern "C" { #endif /** - * @file - * Serialized session + * @file * - * @defgroup session Session - * Serialized session - * @ingroup engine + * @addtogroup session * @{ */ @@ -63,12 +60,13 @@ PN_EXTERN pn_session_t *pn_session(pn_connection_t *connection); * longer needed. Freeing a session will free all links on that * session and settle any deliveries on those links. * - * @param[in] session a session object to free (or NULL) + * @param[in] session the session object to free (or NULL) */ PN_EXTERN void pn_session_free(pn_session_t *session); /** * @deprecated + * * Get the application context that is associated with a session * object. * @@ -82,6 +80,7 @@ PN_EXTERN void *pn_session_get_context(pn_session_t *session); /** * @deprecated + * * Set a new application context for a session object. * * The application context for a session object may be retrieved @@ -103,7 +102,7 @@ PN_EXTERN pn_record_t *pn_session_attachments(pn_session_t *session); /** * Get the endpoint state flags for a session. * - * @param[in] session the session + * @param[in] session the session object * @return the session's state flags */ PN_EXTERN pn_state_t pn_session_state(pn_session_t *session); @@ -119,7 +118,7 @@ PN_EXTERN pn_state_t pn_session_state(pn_session_t *session); * The pointer returned by this operation is valid until the * session object is freed. * - * @param[in] session the sesion object + * @param[in] session the session object * @return the session's error object */ PN_EXTERN pn_error_t *pn_session_error(pn_session_t *session); @@ -175,7 +174,7 @@ PN_EXTERN pn_connection_t *pn_session_connection(pn_session_t *session); * Once this operation has completed, the PN_LOCAL_ACTIVE state flag * will be set. * - * @param[in] session a session object + * @param[in] session the session object */ PN_EXTERN void pn_session_open(pn_session_t *session); @@ -187,7 +186,7 @@ PN_EXTERN void pn_session_open(pn_session_t *session); * ::pn_session_open, in this case it is equivalent to calling * ::pn_session_open followed by ::pn_session_close. * - * @param[in] session a session object + * @param[in] session the session object */ PN_EXTERN void pn_session_close(pn_session_t *session); @@ -236,7 +235,7 @@ PN_EXTERN void pn_session_set_outgoing_window(pn_session_t *session, size_t wind /** * Get the number of outgoing bytes currently buffered by a session. * - * @param[in] session a session object + * @param[in] session the session object * @return the number of outgoing bytes currently buffered */ PN_EXTERN size_t pn_session_outgoing_bytes(pn_session_t *session); @@ -244,7 +243,7 @@ PN_EXTERN size_t pn_session_outgoing_bytes(pn_session_t *session); /** * Get the number of incoming bytes currently buffered by a session. * - * @param[in] session a session object + * @param[in] session the session object * @return the number of incoming bytes currently buffered */ PN_EXTERN size_t pn_session_incoming_bytes(pn_session_t *session); @@ -283,7 +282,8 @@ PN_EXTERN pn_session_t *pn_session_head(pn_connection_t *connection, pn_state_t */ PN_EXTERN pn_session_t *pn_session_next(pn_session_t *session, pn_state_t state); -/** @} +/** + * @} */ #ifdef __cplusplus http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/ssl.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/ssl.h b/proton-c/include/proton/ssl.h index 420459a..ee2997f 100644 --- a/proton-c/include/proton/ssl.h +++ b/proton-c/include/proton/ssl.h @@ -32,11 +32,12 @@ extern "C" { /** * @file - * API for using SSL with the Transport Layer. - * - * @defgroup ssl SSL - * @ingroup transport * + * @addtogroup ssl + * @{ + */ + +/** * API for using SSL with the Transport Layer. * * A Transport may be configured to use SSL for encryption and/or authentication. A @@ -73,33 +74,40 @@ extern "C" { * * Support for SSL Client Session resume is provided (see ::pn_ssl_init, * ::pn_ssl_resume_status). - * - * @{ */ - typedef struct pn_ssl_domain_t pn_ssl_domain_t; + +/** + * @see pn_ssl + */ typedef struct pn_ssl_t pn_ssl_t; -/** Determines the type of SSL endpoint. */ +/** + * Determines the type of SSL endpoint. + */ typedef enum { - PN_SSL_MODE_CLIENT=1, /**< Local connection endpoint is an SSL client */ - PN_SSL_MODE_SERVER /**< Local connection endpoint is an SSL server */ + PN_SSL_MODE_CLIENT = 1, /**< Local connection endpoint is an SSL client */ + PN_SSL_MODE_SERVER /**< Local connection endpoint is an SSL server */ } pn_ssl_mode_t; -/** Indicates whether an SSL session has been resumed. */ +/** + * Indicates whether an SSL session has been resumed. + */ typedef enum { PN_SSL_RESUME_UNKNOWN, /**< Session resume state unknown/not supported */ PN_SSL_RESUME_NEW, /**< Session renegotiated - not resumed */ PN_SSL_RESUME_REUSED /**< Session resumed from previous session. */ } pn_ssl_resume_status_t; -/** Tests for SSL implementation present +/** + * Tests for SSL implementation present * * @return true if we support SSL, false if not */ PN_EXTERN bool pn_ssl_present( void ); -/** Create an SSL configuration domain +/** + * Create an SSL configuration domain * * This method allocates an SSL domain object. This object is used to hold the SSL * configuration for one or more SSL sessions. The SSL session object (pn_ssl_t) is @@ -109,16 +117,18 @@ PN_EXTERN bool pn_ssl_present( void ); * with this domain. * @return a pointer to the SSL domain, if SSL support is present. */ -PN_EXTERN pn_ssl_domain_t *pn_ssl_domain( pn_ssl_mode_t mode); +PN_EXTERN pn_ssl_domain_t *pn_ssl_domain(pn_ssl_mode_t mode); -/** Release an SSL configuration domain +/** + * Release an SSL configuration domain * * This method frees an SSL domain object allocated by ::pn_ssl_domain. * @param[in] domain the domain to destroy. */ -PN_EXTERN void pn_ssl_domain_free( pn_ssl_domain_t *domain ); +PN_EXTERN void pn_ssl_domain_free(pn_ssl_domain_t *domain); -/** Set the certificate that identifies the local node to the remote. +/** + * Set the certificate that identifies the local node to the remote. * * This certificate establishes the identity for the local node for all SSL sessions * created from this domain. It will be sent to the remote if the remote needs to verify @@ -141,12 +151,13 @@ PN_EXTERN void pn_ssl_domain_free( pn_ssl_domain_t *domain ); * protected. * @return 0 on success */ -PN_EXTERN int pn_ssl_domain_set_credentials( pn_ssl_domain_t *domain, - const char *credential_1, - const char *credential_2, - const char *password); +PN_EXTERN int pn_ssl_domain_set_credentials(pn_ssl_domain_t *domain, + const char *credential_1, + const char *credential_2, + const char *password); -/** Configure the set of trusted CA certificates used by this domain to verify peers. +/** + * Configure the set of trusted CA certificates used by this domain to verify peers. * * If the local SSL client/server needs to verify the identity of the remote, it must * validate the signature of the remote's certificate. This function sets the database of @@ -163,27 +174,31 @@ PN_EXTERN int pn_ssl_domain_set_credentials( pn_ssl_domain_t *domain, PN_EXTERN int pn_ssl_domain_set_trusted_ca_db(pn_ssl_domain_t *domain, const char *certificate_db); -/** Determines the level of peer validation. +/** + * Determines the level of peer validation. * - * ANONYMOUS_PEER does not require a valid certificate, and permits use of ciphers that - * do not provide authentication. + * ANONYMOUS_PEER does not require a valid certificate, and permits + * use of ciphers that do not provide authentication. * - * VERIFY_PEER will only connect to those peers that provide a valid identifying - * certificate signed by a trusted CA and are using an authenticated cipher. + * VERIFY_PEER will only connect to those peers that provide a valid + * identifying certificate signed by a trusted CA and are using an + * authenticated cipher. * - * VERIFY_PEER_NAME is like VERIFY_PEER, but also requires the peer's identity as - * contained in the certificate to be valid (see ::pn_ssl_set_peer_hostname). + * VERIFY_PEER_NAME is like VERIFY_PEER, but also requires the peer's + * identity as contained in the certificate to be valid (see + * ::pn_ssl_set_peer_hostname). * - * ANONYMOUS_PEER is configured by default. + * ANONYMOUS_PEER is configured by default. */ typedef enum { - PN_SSL_VERIFY_NULL=0, /**< internal use only */ - PN_SSL_VERIFY_PEER, /**< require peer to provide a valid identifying certificate */ - PN_SSL_ANONYMOUS_PEER, /**< do not require a certificate nor cipher authorization */ - PN_SSL_VERIFY_PEER_NAME /**< require valid certificate and matching name */ + PN_SSL_VERIFY_NULL = 0, /**< internal use only */ + PN_SSL_VERIFY_PEER, /**< require peer to provide a valid identifying certificate */ + PN_SSL_ANONYMOUS_PEER, /**< do not require a certificate nor cipher authorization */ + PN_SSL_VERIFY_PEER_NAME /**< require valid certificate and matching name */ } pn_ssl_verify_mode_t; -/** Configure the level of verification used on the peer certificate. +/** + * Configure the level of verification used on the peer certificate. * * This method controls how the peer's certificate is validated, if at all. By default, * neither servers nor clients attempt to verify their peers (PN_SSL_ANONYMOUS_PEER). @@ -206,10 +221,11 @@ typedef enum { * @return 0 on success */ PN_EXTERN int pn_ssl_domain_set_peer_authentication(pn_ssl_domain_t *domain, - const pn_ssl_verify_mode_t mode, - const char *trusted_CAs); + const pn_ssl_verify_mode_t mode, + const char *trusted_CAs); -/** Permit a server to accept connection requests from non-SSL clients. +/** + * Permit a server to accept connection requests from non-SSL clients. * * This configures the server to "sniff" the incoming client data stream, and dynamically * determine whether SSL/TLS is being used. This option is disabled by default: only @@ -220,7 +236,8 @@ PN_EXTERN int pn_ssl_domain_set_peer_authentication(pn_ssl_domain_t *domain, */ PN_EXTERN int pn_ssl_domain_allow_unsecured_client(pn_ssl_domain_t *domain); -/** Create a new SSL session object associated with a transport. +/** + * Create a new SSL session object associated with a transport. * * A transport must have an SSL object in order to "speak" SSL over its connection. This * method allocates an SSL object associates it with the transport. @@ -231,7 +248,8 @@ PN_EXTERN int pn_ssl_domain_allow_unsecured_client(pn_ssl_domain_t *domain); */ PN_EXTERN pn_ssl_t *pn_ssl(pn_transport_t *transport); -/** Initialize an SSL session. +/** + * Initialize an SSL session. * * This method configures an SSL object using the configuration provided by the given * domain. @@ -244,15 +262,17 @@ PN_EXTERN pn_ssl_t *pn_ssl(pn_transport_t *transport); * and stored for future session restore (see ::::pn_ssl_resume_status). * @return 0 on success, else an error code. */ -PN_EXTERN int pn_ssl_init( pn_ssl_t *ssl, - pn_ssl_domain_t *domain, - const char *session_id); +PN_EXTERN int pn_ssl_init(pn_ssl_t *ssl, + pn_ssl_domain_t *domain, + const char *session_id); -/** Get the name of the Cipher that is currently in use. +/** + * Get the name of the Cipher that is currently in use. * - * Gets a text description of the cipher that is currently active, or returns FALSE if SSL - * is not active (no cipher). Note that the cipher in use may change over time due to - * renegotiation or other changes to the SSL state. + * Gets a text description of the cipher that is currently active, or + * returns FALSE if SSL is not active (no cipher). Note that the + * cipher in use may change over time due to renegotiation or other + * changes to the SSL state. * * @param[in] ssl the ssl client/server to query. * @param[in,out] buffer buffer of size bytes to hold cipher name @@ -261,14 +281,16 @@ PN_EXTERN int pn_ssl_init( pn_ssl_t *ssl, */ PN_EXTERN bool pn_ssl_get_cipher_name(pn_ssl_t *ssl, char *buffer, size_t size); -/** Get the SSF (security strength factor) of the Cipher that is currently in use. +/** + * Get the SSF (security strength factor) of the Cipher that is currently in use. * * @param[in] ssl the ssl client/server to query. * @return the ssf, note that 0 means no security. */ PN_EXTERN int pn_ssl_get_ssf(pn_ssl_t *ssl); -/** Get the name of the SSL protocol that is currently in use. +/** + * Get the name of the SSL protocol that is currently in use. * * Gets a text description of the SSL protocol that is currently active, or returns FALSE if SSL * is not active. Note that the protocol may change over time due to renegotiation. @@ -281,7 +303,8 @@ PN_EXTERN int pn_ssl_get_ssf(pn_ssl_t *ssl); */ PN_EXTERN bool pn_ssl_get_protocol_name(pn_ssl_t *ssl, char *buffer, size_t size); -/** Check whether the state has been resumed. +/** + * Check whether the state has been resumed. * * Used for client session resume. When called on an active session, indicates whether * the state has been resumed from a previous session. @@ -293,9 +316,10 @@ PN_EXTERN bool pn_ssl_get_protocol_name(pn_ssl_t *ssl, char *buffer, size_t size * @param[in] ssl the ssl session to check * @return status code indicating whether or not the session has been resumed. */ -PN_EXTERN pn_ssl_resume_status_t pn_ssl_resume_status( pn_ssl_t *ssl ); +PN_EXTERN pn_ssl_resume_status_t pn_ssl_resume_status(pn_ssl_t *ssl); -/** Set the expected identity of the remote peer. +/** + * Set the expected identity of the remote peer. * * By default, SSL will use the hostname associated with the connection that * the transport is bound to (see ::pn_connection_set_hostname). This method @@ -316,10 +340,10 @@ PN_EXTERN pn_ssl_resume_status_t pn_ssl_resume_status( pn_ssl_t *ssl ); * given in RFC1034, Section 3.5. * @return 0 on success. */ -PN_EXTERN int pn_ssl_set_peer_hostname( pn_ssl_t *ssl, const char *hostname); +PN_EXTERN int pn_ssl_set_peer_hostname(pn_ssl_t *ssl, const char *hostname); - -/** Access the configured peer identity. +/** + * Access the configured peer identity. * * Return the expected identity of the remote peer, as set by ::pn_ssl_set_peer_hostname. * @@ -331,9 +355,10 @@ PN_EXTERN int pn_ssl_set_peer_hostname( pn_ssl_t *ssl, const char *hostname); * no hostname set. * @return 0 on success. */ -PN_EXTERN int pn_ssl_get_peer_hostname( pn_ssl_t *ssl, char *hostname, size_t *bufsize ); +PN_EXTERN int pn_ssl_get_peer_hostname(pn_ssl_t *ssl, char *hostname, size_t *bufsize); -/** Get the subject from the peers certificate. +/** + * Get the subject from the peers certificate. * * @param[in] ssl the ssl client/server to query. * @return A null terminated string representing the full subject, @@ -353,7 +378,6 @@ typedef enum { PN_SSL_CERT_SUBJECT_COMMON_NAME } pn_ssl_cert_subject_subfield; - /** * Enumeration identifying hashing algorithm. */ @@ -396,7 +420,9 @@ PN_EXTERN int pn_ssl_get_cert_fingerprint(pn_ssl_t *ssl0, */ PN_EXTERN const char* pn_ssl_get_remote_subject_subfield(pn_ssl_t *ssl0, pn_ssl_cert_subject_subfield field); -/** @} */ +/** + * @} + */ #ifdef __cplusplus } http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/terminus.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/terminus.h b/proton-c/include/proton/terminus.h index 43d4d98..345bdda 100644 --- a/proton-c/include/proton/terminus.h +++ b/proton-c/include/proton/terminus.h @@ -33,11 +33,8 @@ extern "C" { /** * @file - * Message terminus (source or target) * - * @defgroup terminus Terminus - * Message terminus (source or target) - * @ingroup link + * @addtogroup terminus * @{ */ @@ -299,7 +296,8 @@ PN_EXTERN pn_data_t *pn_terminus_filter(pn_terminus_t *terminus); */ PN_EXTERN int pn_terminus_copy(pn_terminus_t *terminus, pn_terminus_t *src); -/** @} +/** + * @} */ #ifdef __cplusplus http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/transport.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/transport.h b/proton-c/include/proton/transport.h index 9683a42..adb74bd 100644 --- a/proton-c/include/proton/transport.h +++ b/proton-c/include/proton/transport.h @@ -33,13 +33,8 @@ extern "C" { /** * @file - * Network transport * - * @defgroup transport Transport - * Network transport - * - * State of a network connection being used as a transport for an AMQP connection. - * @ingroup engine + * @addtogroup transport * @{ */ @@ -128,29 +123,38 @@ PN_EXTERN void pn_transport_set_server(pn_transport_t *transport); */ PN_EXTERN void pn_transport_free(pn_transport_t *transport); -/** Retrieve the authenticated user +/** + * @deprecated * - * This is usually used at the the server end to find the name of the authenticated user. - * On the client it will merely return whatever user was passed in to the - * pn_connection_set_user() API of the bound connection. + * Retrieve the authenticated user. * - * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received. + * This is usually used at the the server end to find the name of the + * authenticated user. On the client it will merely return whatever + * user was passed in to the pn_connection_set_user() API of the bound + * connection. + * + * The returned value is only reliable after the + * PN_TRANSPORT_AUTHENTICATED event has been received. * * @param[in] transport the transport * - * @return - * If a the user is anonymous (either no SASL layer is negotiated or the SASL ANONYMOUS mechanism is used) - * then the user will be "anonymous" - * Otherwise a string containing the user is returned. + * @return If a the user is anonymous (either no SASL layer is + * negotiated or the SASL ANONYMOUS mechanism is used) then the user + * will be "anonymous" Otherwise a string containing the user is + * returned. */ PN_EXTERN const char *pn_transport_get_user(pn_transport_t *transport); /** - * Set whether a non authenticated transport connection is allowed + * @deprecated + * + * Set whether a non-authenticated transport connection is allowed. + * + * There are several ways within the AMQP protocol suite to get + * unauthenticated connections: * - * There are several ways within the AMQP protocol suite to get unauthenticated connections: * - Use no SASL layer (with either no TLS or TLS without client certificates) - * - Use an SASL layer but the ANONYMOUS mechanism + * - Use a SASL layer but the ANONYMOUS mechanism * * The default if this option is not set is to allow unauthenticated connections. * @@ -160,6 +164,8 @@ PN_EXTERN const char *pn_transport_get_user(pn_transport_t *transport); PN_EXTERN void pn_transport_require_auth(pn_transport_t *transport, bool required); /** + * @deprecated + * * Tell whether the transport connection is authenticated * * Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN @@ -171,11 +177,13 @@ PN_EXTERN void pn_transport_require_auth(pn_transport_t *transport, bool require PN_EXTERN bool pn_transport_is_authenticated(pn_transport_t *transport); /** + * @deprecated + * * Set whether a non encrypted transport connection is allowed * * There are several ways within the AMQP protocol suite to get encrypted connections: - * - Use TLS/SSL - * - Use an SASL with a mechanism that supports saecurity layers + * - Use TLS + * - Use a SASL with a mechanism that supports saecurity layers * * The default if this option is not set is to allow unencrypted connections. * @@ -185,6 +193,8 @@ PN_EXTERN bool pn_transport_is_authenticated(pn_transport_t *transport); PN_EXTERN void pn_transport_require_encryption(pn_transport_t *transport, bool required); /** + * @deprecated + * * Tell whether the transport connection is encrypted * * Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN @@ -212,7 +222,7 @@ PN_EXTERN pn_condition_t *pn_transport_condition(pn_transport_t *transport); /** * @deprecated */ -PN_EXTERN pn_error_t *pn_transport_error(pn_transport_t *transport); +PN_EXTERN pn_error_t *pn_transport_error(pn_transport_t *transport); /** * Binds the transport to an AMQP connection. @@ -252,7 +262,7 @@ PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace); PN_EXTERN void pn_transport_set_tracer(pn_transport_t *transport, pn_tracer_t tracer); /** - * Get the tracning function used by a transport. + * Get the tracing function used by a transport. * * @param[in] transport a transport object * @return the tracing function used by a transport @@ -260,6 +270,8 @@ PN_EXTERN void pn_transport_set_tracer(pn_transport_t *transport, pn_tracer_t tr PN_EXTERN pn_tracer_t pn_transport_get_tracer(pn_transport_t *transport); /** + * @deprecated + * * Get the application context that is associated with a transport object. * * The application context for a transport may be set using @@ -272,6 +284,7 @@ PN_EXTERN void *pn_transport_get_context(pn_transport_t *transport); /** * @deprecated + * * Set a new application context for a transport object. * * The application context for a transport object may be retrieved using @@ -291,6 +304,8 @@ PN_EXTERN void pn_transport_set_context(pn_transport_t *transport, void *context PN_EXTERN pn_record_t *pn_transport_attachments(pn_transport_t *transport); /** + * @deprecated + * * Log a message using a transport's logging mechanism. * * This can be useful in a debugging context as the log message will @@ -302,6 +317,8 @@ PN_EXTERN pn_record_t *pn_transport_attachments(pn_transport_t *transport); PN_EXTERN void pn_transport_log(pn_transport_t *transport, const char *message); /** + * @deprecated + * * Log a printf formatted message using a transport's logging * mechanism. * @@ -315,6 +332,8 @@ PN_EXTERN void pn_transport_log(pn_transport_t *transport, const char *message); PN_EXTERN void pn_transport_vlogf(pn_transport_t *transport, const char *fmt, va_list ap); /** + * @deprecated + * * Log a printf formatted message using a transport's logging * mechanism. * @@ -327,6 +346,8 @@ PN_EXTERN void pn_transport_vlogf(pn_transport_t *transport, const char *fmt, va PN_EXTERN void pn_transport_logf(pn_transport_t *transport, const char *fmt, ...); /** + * @deprecated + * * Get the maximum allowed channel for a transport. * This will be the minimum of * 1. limit imposed by this proton implementation @@ -339,6 +360,8 @@ PN_EXTERN void pn_transport_logf(pn_transport_t *transport, const char *fmt, ... PN_EXTERN uint16_t pn_transport_get_channel_max(pn_transport_t *transport); /** + * @deprecated + * * Set the maximum allowed channel number for a transport. * Note that this is the maximum channel number allowed, giving a * valid channel number range of [0..channel_max]. Therefore the @@ -358,6 +381,8 @@ PN_EXTERN uint16_t pn_transport_get_channel_max(pn_transport_t *transport); PN_EXTERN int pn_transport_set_channel_max(pn_transport_t *transport, uint16_t channel_max); /** + * @deprecated + * * Get the maximum allowed channel of a transport's remote peer. * * @param[in] transport a transport object @@ -366,6 +391,8 @@ PN_EXTERN int pn_transport_set_channel_max(pn_transport_t *transport, uint16_t c PN_EXTERN uint16_t pn_transport_remote_channel_max(pn_transport_t *transport); /** + * @deprecated + * * Get the maximum frame size of a transport. * * @param[in] transport a transport object @@ -374,6 +401,8 @@ PN_EXTERN uint16_t pn_transport_remote_channel_max(pn_transport_t *transport); PN_EXTERN uint32_t pn_transport_get_max_frame(pn_transport_t *transport); /** + * @deprecated + * * Set the maximum frame size of a transport. * * @param[in] transport a transport object @@ -382,6 +411,8 @@ PN_EXTERN uint32_t pn_transport_get_max_frame(pn_transport_t *transport); PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size); /** + * @deprecated + * * Get the maximum frame size of a transport's remote peer. * * @param[in] transport a transport object @@ -390,6 +421,8 @@ PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t si PN_EXTERN uint32_t pn_transport_get_remote_max_frame(pn_transport_t *transport); /** + * @deprecated + * * Get the idle timeout for a transport. * * A zero idle timeout means heartbeats are disabled. @@ -400,6 +433,8 @@ PN_EXTERN uint32_t pn_transport_get_remote_max_frame(pn_transport_t *transport); PN_EXTERN pn_millis_t pn_transport_get_idle_timeout(pn_transport_t *transport); /** + * @deprecated + * * Set the idle timeout for a transport. * * A zero idle timeout means heartbeats are disabled. @@ -410,6 +445,8 @@ PN_EXTERN pn_millis_t pn_transport_get_idle_timeout(pn_transport_t *transport); PN_EXTERN void pn_transport_set_idle_timeout(pn_transport_t *transport, pn_millis_t timeout); /** + * @deprecated + * * Get the idle timeout for a transport's remote peer. * * A zero idle timeout means heartbeats are disabled. @@ -423,6 +460,7 @@ PN_EXTERN pn_millis_t pn_transport_get_remote_idle_timeout(pn_transport_t *trans * @deprecated */ PN_EXTERN ssize_t pn_transport_input(pn_transport_t *transport, const char *bytes, size_t available); + /** * @deprecated */ @@ -618,7 +656,8 @@ PN_EXTERN uint64_t pn_transport_get_frames_output(const pn_transport_t *transpor */ PN_EXTERN uint64_t pn_transport_get_frames_input(const pn_transport_t *transport); -/** Access the AMQP Connection associated with the transport. +/** + * Access the AMQP Connection associated with the transport. * * @param[in] transport a transport object * @return the connection context for the transport, or NULL if @@ -630,7 +669,8 @@ PN_EXTERN pn_connection_t *pn_transport_connection(pn_transport_t *transport); } #endif -/** @} +/** + * @} */ #endif /* transport.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/type_compat.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/type_compat.h b/proton-c/include/proton/type_compat.h index 9a7422c..fe96994 100644 --- a/proton-c/include/proton/type_compat.h +++ b/proton-c/include/proton/type_compat.h @@ -22,6 +22,10 @@ * */ +/** + * @cond INTERNAL + */ + // Get Boolean #if !defined(__cplusplus) && !defined(__bool_true_false_are_defined) # if __STDC_VERSION__ >= 199901L || __GNUC__ >= 3 || _MSC_VER >=1800 @@ -139,4 +143,8 @@ typedef unsigned __int64 uint64_t; # endif #endif // PNI_DEFINE_SSIZE_T +/** + * @endcond + */ + #endif /* type_compat.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/types.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/types.h b/proton-c/include/proton/types.h index 190f089..2ceadd3 100644 --- a/proton-c/include/proton/types.h +++ b/proton-c/include/proton/types.h @@ -1,7 +1,6 @@ #ifndef PROTON_TYPES_H #define PROTON_TYPES_H 1 - /* * * Licensed to the Apache Software Foundation (ASF) under one @@ -29,11 +28,90 @@ /** * @file - * AMQP type system + * + * @defgroup core Core + * @brief Core protocol entities and event handling + * + * @defgroup connection Connection + * @brief A channel for communication between two peers on a network + * @ingroup core + * + * @defgroup session Session + * @brief A container of links + * @ingroup core + * + * @defgroup link Link + * @brief A channel for transferring messages + * @ingroup core + * + * @defgroup terminus Terminus + * @brief A source or target for messages + * @ingroup core + * + * @defgroup message Message + * @brief A mutable holder of application content + * @ingroup core + * + * @defgroup delivery Delivery + * @brief A message transfer + * @ingroup core + * + * @defgroup condition Condition + * @brief An endpoint error state + * @ingroup core + * + * @defgroup event Event + * @brief Protocol and transport events + * @ingroup core + * + * @defgroup transport Transport + * @brief A network channel supporting an AMQP connection + * @ingroup core + * + * @defgroup sasl SASL + * @brief SASL secure transport layer + * @ingroup core + * + * @defgroup ssl SSL + * @brief SSL secure transport layer + * @ingroup core + * + * @defgroup error Error + * @brief A Proton error + * @ingroup core * * @defgroup types Types - * AMQP type system - * @{ + * @brief Protocol and API data types + * + * @defgroup amqp_types AMQP types + * @brief AMQP data types + * @ingroup types + * + * @defgroup api_types API types + * @brief Additional data types used in the API + * @ingroup types + * + * @defgroup codec Codec + * @brief AMQP data encoding and decoding + * + * @defgroup io IO + * @brief IO integration interfaces + * + * @defgroup connection_driver Connection Driver + * @brief **Experimental** - Low-level IO integration + * @ingroup io + * + * @defgroup proactor Proactor + * @brief **Experimental** - Multithreaded IO + * @ingroup io + * + * @defgroup messenger Messenger + * @deprecated + * @brief **Deprecated** - The Messenger API + * + * @defgroup url URL + * @deprecated + * @brief **Deprecated** - A URL parser */ #ifdef __cplusplus @@ -41,54 +119,116 @@ extern "C" { #endif /** - * @defgroup primitives Primitive Types - * Primitive types - * @{ + * A sequence number. + * + * @ingroup api_types */ - typedef int32_t pn_sequence_t; + +/** + * A span of time in milliseconds. + * + * @ingroup api_types + */ typedef uint32_t pn_millis_t; + +/** + * The maximum value for @ref pn_millis_t. + * + * @ingroup api_types + */ #define PN_MILLIS_MAX (~0U) + +/** + * A span of time in seconds. + * + * @ingroup api_types + */ typedef uint32_t pn_seconds_t; -typedef int64_t pn_timestamp_t; +/** + * A 64-bit timestamp in milliseconds since the Unix epoch. + * + * @ingroup amqp_types + */ +typedef int64_t pn_timestamp_t; +/** + * A 32-bit Unicode code point. + * + * @ingroup amqp_types + */ typedef uint32_t pn_char_t; + +/** + * A 32-bit decimal floating-point number. + * + * @ingroup amqp_types + */ typedef uint32_t pn_decimal32_t; + +/** + * A 64-bit decimal floating-point number. + * + * @ingroup amqp_types + */ typedef uint64_t pn_decimal64_t; + +/** + * A 128-bit decimal floating-point number. + * + * @ingroup amqp_types + */ typedef struct { char bytes[16]; } pn_decimal128_t; + +/** + * A 16-byte universally unique identifier. + * + * @ingroup amqp_types + */ typedef struct { char bytes[16]; } pn_uuid_t; -/** A const byte buffer. */ +/** + * A const byte buffer. + * + * @ingroup api_types + */ typedef struct pn_bytes_t { size_t size; const char *start; } pn_bytes_t; +/** + * Create a @ref pn_bytes_t + * + * @ingroup api_types + */ PN_EXTERN pn_bytes_t pn_bytes(size_t size, const char *start); + static const pn_bytes_t pn_bytes_null = { 0, NULL }; -/** A non-const byte buffer. */ +/** + * A non-const byte buffer. + * + * @ingroup api_types + */ typedef struct pn_rwbytes_t { size_t size; char *start; } pn_rwbytes_t; -PN_EXTERN pn_rwbytes_t pn_rwbytes(size_t size, char *start); -static const pn_bytes_t pn_rwbytes_null = { 0, NULL }; - -/** @} - */ - /** - * @defgroup abstract Abstract Types - * Abstract types - * @{ + * Create a @ref pn_rwbytes_t + * + * @ingroup api_types */ +PN_EXTERN pn_rwbytes_t pn_rwbytes(size_t size, char *start); + +static const pn_bytes_t pn_rwbytes_null = { 0, NULL }; /** * Holds the state flags for an AMQP endpoint. @@ -122,8 +262,7 @@ typedef int pn_state_t; * contains zero or more ::pn_session_t objects, which in turn contain * zero or more ::pn_link_t objects. Each ::pn_link_t object contains * an ordered sequence of ::pn_delivery_t objects. A link is either a - * @link sender Sender @endlink, or a @link receiver Receiver - * @endlink, but never both. + * sender or a receiver but never both. * * @ingroup connection */ @@ -146,8 +285,8 @@ typedef struct pn_session_t pn_session_t; * A pn_link_t object encapsulates all of the endpoint state * associated with an AMQP Link. A pn_link_t object contains an * ordered sequence of ::pn_delivery_t objects representing in-flight - * deliveries. A pn_link_t may be either a @link sender Sender - * @endlink, or a @link receiver Receiver @endlink, but never both. + * deliveries. A pn_link_t may be either sender or a receiver but + * never both. * * A pn_link_t object maintains a pointer to the *current* delivery * within the ordered sequence of deliveries contained by the link @@ -274,21 +413,19 @@ typedef struct pn_collector_t pn_collector_t; typedef struct pn_transport_t pn_transport_t; /** - * An event handler + * @cond INTERNAL * - * A pn_handler_t is target of ::pn_event_t dispatched by the ::pn_reactor_t + * An event handler * - * @ingroup reactor + * A pn_handler_t is target of ::pn_event_t dispatched by the pn_reactor_t */ typedef struct pn_handler_t pn_handler_t; - -/** @} +/** + * @endcond */ + #ifdef __cplusplus } #endif -/** @} - */ - #endif /* types.h */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/7bae4756/proton-c/include/proton/url.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/url.h b/proton-c/include/proton/url.h index 4ff9536..49faa30 100644 --- a/proton-c/include/proton/url.h +++ b/proton-c/include/proton/url.h @@ -1,5 +1,6 @@ #ifndef PROTON_URL_H -#define PROTON_URL_H +#define PROTON_URL_H 1 + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -25,23 +26,29 @@ extern "C" { #endif - /** * @file - * Parsing URLs. * - * @defgroup url URL - * Parsing URLs. -! * @{ + * **Deprecated** + * + * @deprecated + * + * @addtogroup url + * @{ */ -/** A parsed URL */ +/** + * A parsed URL + */ typedef struct pn_url_t pn_url_t; -/** Create an empty URL */ +/** + * Create an empty URL + */ PNX_EXTERN pn_url_t *pn_url(void); -/** Parse a string URL as a pn_url_t. +/** + * Parse a string URL as a pn_url_t. * * URL syntax: * @@ -55,31 +62,34 @@ PNX_EXTERN pn_url_t *pn_url(void); * * `path` can contain any character * - *@param[in] url A URL string. - *@return The parsed pn_url_t or NULL if url is not a valid URL string. + * @param[in] url A URL string. + * @return The parsed pn_url_t or NULL if url is not a valid URL string. */ PNX_EXTERN pn_url_t *pn_url_parse(const char *url); -/** Free a URL */ +/** + * Free a URL */ PNX_EXTERN void pn_url_free(pn_url_t *url); -/** Clear the contents of the URL. */ +/** + * Clear the contents of the URL. + */ PNX_EXTERN void pn_url_clear(pn_url_t *url); /** * Return the string form of a URL. * - * The returned string is owned by the pn_url_t and will become invalid if it - * is modified. + * The returned string is owned by the pn_url_t and will become + * invalid if it is modified. */ PNX_EXTERN const char *pn_url_str(pn_url_t *url); /** - *@name Getters for parts of the URL. + * @name Getters for parts of the URL. * - *Values belong to the URL. May return NULL if the value is not set. + * Values belong to the URL. May return NULL if the value is not set. * - *@{ + * @{ */ PNX_EXTERN const char *pn_url_get_scheme(pn_url_t *url); PNX_EXTERN const char *pn_url_get_username(pn_url_t *url); @@ -87,14 +97,17 @@ PNX_EXTERN const char *pn_url_get_password(pn_url_t *url); PNX_EXTERN const char *pn_url_get_host(pn_url_t *url); PNX_EXTERN const char *pn_url_get_port(pn_url_t *url); PNX_EXTERN const char *pn_url_get_path(pn_url_t *url); -///@} +/** + * @} + */ /** - *@name Setters for parts of the URL. + * @name Setters for parts of the URL. * - *Values are copied. Value can be NULL to indicate the part is not set. + * Values are copied. Value can be NULL to indicate the part is not + * set. * - *@{ + * @{ */ PNX_EXTERN void pn_url_set_scheme(pn_url_t *url, const char *scheme); PNX_EXTERN void pn_url_set_username(pn_url_t *url, const char *username); @@ -102,12 +115,16 @@ PNX_EXTERN void pn_url_set_password(pn_url_t *url, const char *password); PNX_EXTERN void pn_url_set_host(pn_url_t *url, const char *host); PNX_EXTERN void pn_url_set_port(pn_url_t *url, const char *port); PNX_EXTERN void pn_url_set_path(pn_url_t *url, const char *path); -///@} +/** + * @} + */ -///@} +/** + * @} + */ #ifdef __cplusplus } #endif -#endif +#endif /* url.h */ --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org