You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2017/01/03 22:02:38 UTC
[06/30] qpid-proton git commit: PROTON-1367: Clean up and reorganize
the C API docs
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-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org