qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@apache.org
Subject svn commit: r1408278 - in /qpid/proton/trunk/proton-c: bindings/python/CMakeLists.txt bindings/python/proton.py include/proton/driver.h include/proton/messenger.h include/proton/ssl.h
Date Mon, 12 Nov 2012 13:32:41 GMT
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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message