Author: rhs
Date: Mon Nov 12 13:32:40 2012
New Revision: 1408278
URL: http://svn.apache.org/viewvc?rev=1408278&view=rev
Log:
documentation fixes, additions, edits
Modified:
qpid/proton/trunk/proton-c/bindings/python/CMakeLists.txt
qpid/proton/trunk/proton-c/bindings/python/proton.py
qpid/proton/trunk/proton-c/include/proton/driver.h
qpid/proton/trunk/proton-c/include/proton/messenger.h
qpid/proton/trunk/proton-c/include/proton/ssl.h
Modified: qpid/proton/trunk/proton-c/bindings/python/CMakeLists.txt
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/bindings/python/CMakeLists.txt?rev=1408278&r1=1408277&r2=1408278&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/bindings/python/CMakeLists.txt (original)
+++ qpid/proton/trunk/proton-c/bindings/python/CMakeLists.txt Mon Nov 12
13:32:40 2012
@@ -40,7 +40,7 @@ install(CODE "execute_process(COMMAND ${
find_program(EPYDOC_EXE epydoc)
if (EPYDOC_EXE)
- add_custom_target(docs-py COMMAND ${EPYDOC_EXE} --no-private --html
+ add_custom_target(docs-py COMMAND ${EPYDOC_EXE} -v --no-private --html
-o ${CMAKE_CURRENT_BINARY_DIR}/html
${CMAKE_CURRENT_SOURCE_DIR}/proton.py)
add_dependencies(docs docs-py)
Modified: qpid/proton/trunk/proton-c/bindings/python/proton.py
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/bindings/python/proton.py?rev=1408278&r1=1408277&r2=1408278&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/bindings/python/proton.py (original)
+++ qpid/proton/trunk/proton-c/bindings/python/proton.py Mon Nov 12 13:32:40
2012
@@ -267,7 +267,9 @@ operations performed by the L{Messenger}
accept_mode = property(_get_accept_mode, _set_accept_mode,
doc="""
The accept mode for the messenger. Can be set to AUTOMATIC or MANUAL.
-The default is AUTOMATIC.
+The default is AUTOMATIC. If set to MANUAL, then every incoming
+message must be accepted or rejected (either individually or
+cummulatively) via the accept and reject methods.
""")
def _get_incoming_window(self):
@@ -279,7 +281,8 @@ The default is AUTOMATIC.
incoming_window = property(_get_incoming_window, _set_incoming_window,
doc="""
The incoming tracking window for the messenger. The messenger will
-track the status of this many incoming deliveries. Defaults to zero.
+track the remote status of this many incoming deliveries after they
+have been accepted or rejected. Defaults to zero.
""")
def _get_outgoing_window(self):
@@ -291,7 +294,8 @@ track the status of this many incoming d
outgoing_window = property(_get_outgoing_window, _set_outgoing_window,
doc="""
The outgoing tracking window for the messenger. The messenger will
-track the status of this many outgoing deliveries. Defaults to zero.
+track the remote status of this many outgoing deliveries after calling
+send. Defaults to zero.
""")
def start(self):
@@ -345,12 +349,22 @@ track the status of this many outgoing d
@type message: Message
@param message: the message to place in the outgoing queue
+ @return: a tracker
"""
message._pre_encode()
self._check(pn_messenger_put(self._mng, message._msg))
return pn_messenger_outgoing_tracker(self._mng)
def status(self, tracker):
+ """
+ Gets the last known remote state of the delivery associated with
+ the given tracker.
+
+ @type tracker: tracker
+ @param tracker: the tracker whose status is to be retrieved
+
+ @return: one of None, PENDING, REJECTED, or ACCEPTED
+ """
disp = pn_messenger_status(self._mng, tracker);
return STATUSES.get(disp, disp)
@@ -386,6 +400,7 @@ track the status of this many outgoing d
@type message: Message
@param message: the destination message object
+ @return: a tracker
"""
if message is None:
impl = None
@@ -397,6 +412,12 @@ track the status of this many outgoing d
return pn_messenger_incoming_tracker(self._mng)
def accept(self, tracker=None):
+ """
+ Accepts messages retreived from the incoming message queue.
+
+ @type tracker: tracker
+ @param tracker: a tracker as returned by get
+ """
if tracker is None:
tracker = pn_messenger_incoming_tracker(self._mng)
flags = PN_CUMULATIVE
@@ -405,6 +426,12 @@ track the status of this many outgoing d
self._check(pn_messenger_accept(self._mng, tracker, flags))
def reject(self, tracker=None):
+ """
+ Rejects messages retreived from the incoming message queue.
+
+ @type tracker: tracker
+ @param tracker: a tracker as returned by get
+ """
if tracker is None:
tracker = pn_messenger_incoming_tracker(self._mng)
flags = PN_CUMULATIVE
Modified: qpid/proton/trunk/proton-c/include/proton/driver.h
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/driver.h?rev=1408278&r1=1408277&r2=1408278&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/driver.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/driver.h Mon Nov 12 13:32:40 2012
@@ -37,12 +37,12 @@ extern "C" {
* The driver library provides a simple implementation of a driver for
* the proton engine. A driver is responsible for providing input,
* output, and tick events to the bottom half of the engine API. See
- * ::pn_input, ::pn_output, and ::pn_tick. The driver also provides an
- * interface for the application to access the top half of the API
- * when the state of the engine may have changed due to I/O or timing
- * events. Additionally the driver incorporates the SASL engine as
- * well in order to provide a complete network stack: AMQP over SASL
- * over TCP.
+ * ::pn_transport_input, ::pn_transport_output, and
+ * ::pn_transport_tick. The driver also provides an interface for the
+ * application to access the top half of the API when the state of the
+ * engine may have changed due to I/O or timing events. Additionally
+ * the driver incorporates the SASL engine as well in order to provide
+ * a complete network stack: AMQP over SASL over TCP.
*
*/
@@ -298,7 +298,7 @@ pn_connection_t *pn_connector_connection
* @param[in] connection the connection to associate with the
* connector
*/
-void pn_connector_set_connection(pn_connector_t *ctor, pn_connection_t
*connection);
+void pn_connector_set_connection(pn_connector_t *connector, pn_connection_t
*connection);
/** Access the application context that is associated with the
* connector.
Modified: qpid/proton/trunk/proton-c/include/proton/messenger.h
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/messenger.h?rev=1408278&r1=1408277&r2=1408278&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/messenger.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/messenger.h Mon Nov 12 13:32:40
2012
@@ -84,7 +84,7 @@ const char *pn_messenger_get_certificate
/** Sets the private key file for a Messenger.
*
- * @param[in] messenger the messenger
+ * @param[in] messenger the Messenger
* @param[in] private_key a path to a private key file
*
* @return an error code of zero if there is no error
@@ -134,7 +134,7 @@ const char *pn_messenger_get_trusted_cer
* infinite.
*
* @param[in] messenger the messenger
- * @param[timeout] the new timeout for the messenger, in milliseconds
+ * @param[in] timeout the new timeout for the messenger, in milliseconds
*
* @return an error code or zero if there is no error
*/
@@ -164,7 +164,7 @@ void pn_messenger_free(pn_messenger_t *m
*/
int pn_messenger_errno(pn_messenger_t *messenger);
-/** Returns the error info for the Messenger.
+/** Returns the error info for a Messenger.
*
* @param[in] messenger the messenger to check for errors
*
@@ -173,16 +173,73 @@ int pn_messenger_errno(pn_messenger_t *m
*/
const char *pn_messenger_error(pn_messenger_t *messenger);
+/** Gets the accept mode for a Messenger. @see
+ * ::pn_messenger_set_accept_mode
+ *
+ * @param[in] messenger the messenger
+ *
+ * @return one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL
+ */
pn_accept_mode_t pn_messenger_get_accept_mode(pn_messenger_t *messenger);
+/** Set the accept mode for a Messenger. If set to
+ * PN_ACCEPT_MODE_AUTO, the messenger will automatically accept every
+ * message as it is returned by pn_messenger_get(). If set to
+ * PN_ACCEPT_MODE_MANUAL, incoming messages must be manually accepted
+ * or rejected (either individually or cumulatively) via
+ * pn_messenger_accept() and/or pn_messenger_reject().
+ *
+ * @param[in] messenger the messenger to set the accept mode for
+ * @param[in] mode one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL
+ *
+ * @return an error code or zero on success
+ * @see error.h
+ */
int pn_messenger_set_accept_mode(pn_messenger_t *messenger, pn_accept_mode_t
mode);
+/** Gets the outgoing window for a Messenger. @see
+ * ::pn_messenger_set_outgoing_window
+ *
+ * @param[in] messenger the messenger
+ *
+ * @return the outgoing window
+ */
int pn_messenger_get_outgoing_window(pn_messenger_t *messenger);
+/** Sets the outgoing window for a Messenger. If the outgoing window
+ * is set to a positive value, then after each call to
+ * pn_messenger_send, the Messenger will track the status of that
+ * many deliveries. @see ::pn_messenger_status
+ *
+ * @param[in] messenger the Messenger
+ * @param[in] window the number of deliveries to track
+ *
+ * @return an error or zero on success
+ * @see error.h
+ */
int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window);
+/** Gets the incoming window for a Messenger. @see
+ * ::pn_messenger_set_incoming_window
+ *
+ * @param[in] messenger the Messenger
+ *
+ * @return the incoming window
+ */
int pn_messenger_get_incoming_window(pn_messenger_t *messenger);
+/** Sets the incoming window for a Messenger. If the incoming window
+ * is set to a positive value, then after each call to
+ * pn_messenger_accept or pn_messenger_reject, the Messenger will
+ * track the status of that many deliveries. @see
+ * ::pn_messenger_status
+ *
+ * @param[in] messenger the Messenger
+ * @param[in] window the number of deliveries to track
+ *
+ * @return an error or zero on success
+ * @see error.h
+ */
int pn_messenger_set_incoming_window(pn_messenger_t *messenger, int window);
/** Starts a messenger. A messenger cannot send or recv messages until
@@ -238,6 +295,17 @@ int pn_messenger_put(pn_messenger_t *mes
*/
pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t
tracker);
+/** Frees a Messenger from tracking the status associated with a given
+ * tracker. Use the PN_CUMULATIVE flag to indicate everything up to
+ * (and including) the given tracker.
+ *
+ * @param[in] messenger the Messenger
+ * @param[in] tracker identifies a delivery
+ * @param[in] flags 0 or PN_CUMULATIVE
+ *
+ * @return an error code or zero on success
+ * @see error.h
+ */
int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int
flags);
/** Gets the tracker for the message most recently provided to
@@ -302,6 +370,8 @@ pn_subscription_t *pn_messenger_incoming
* tracker.
*
* @param[in] messenger the messenger
+ * @param[in] tracker an incoming tracker
+ * @param[in] flags 0 or PN_CUMULATIVE
*
* @return an error code or zero on success
* @see error.h
@@ -312,7 +382,9 @@ int pn_messenger_accept(pn_messenger_t *
* PN_CUMULATIVE flag to reject everything prior to the supplied
* tracker.
*
- * @param[in] messenger the messenger
+ * @param[in] messenger the Messenger
+ * @param[in] tracker an incoming tracker
+ * @param[in] flags 0 or PN_CUMULATIVE
*
* @return an error code or zero on success
* @see error.h
@@ -321,7 +393,7 @@ int pn_messenger_reject(pn_messenger_t *
/** Returns the number of messages in the outgoing message queue of a
messenger.
*
- * @param[in] the messenger
+ * @param[in] messenger the Messenger
*
* @return the outgoing queue depth
*/
@@ -329,7 +401,7 @@ int pn_messenger_outgoing(pn_messenger_t
/** Returns the number of messages in the incoming message queue of a
messenger.
*
- * @param[in] the messenger
+ * @param[in] messenger the Messenger
*
* @return the incoming queue depth
*/
Modified: qpid/proton/trunk/proton-c/include/proton/ssl.h
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/ssl.h?rev=1408278&r1=1408277&r2=1408278&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/ssl.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/ssl.h Mon Nov 12 13:32:40 2012
@@ -89,9 +89,9 @@ int pn_ssl_init(pn_ssl_t *ssl, pn_ssl_mo
* both SSL servers and SSL clients (if client authentication is required by
the server).
*
* @param[in] ssl the ssl server/client will provide this certificate.
- * @param[in] certificate_path path to file/database containing the identifying
+ * @param[in] certificate_file path to file/database containing the identifying
* certificate.
- * @param[in] private_key_path path to file/database containing the private
key used to
+ * @param[in] private_key_file path to file/database containing the private
key used to
* sign the certificate
* @param[in] password the password used to sign the key, else NULL if key is
not
* protected.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
