Merge branch 'alanxz/master'

Conflicts:
	Makefile.am
	codegen

1 files changed, 38 insertions, 15 deletions

diff --git a/librabbitmq/amqp_ssl_socket.h b/librabbitmq/amqp_ssl_socket.h
index 3bfce51..7f8ea64 100644
--- a/librabbitmq/amqp_ssl_socket.h
+++ b/librabbitmq/amqp_ssl_socket.h
@@ -1,4 +1,5 @@
 /* vim:set ft=c ts=2 sw=2 sts=2 et cindent: */
+/** \file */
 /*
  * Copyright 2012-2013 Michael Steinert
  *
@@ -21,10 +22,6 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
-/**
- * An SSL socket connection.
- */
-
 #ifndef AMQP_SSL_H
 #define AMQP_SSL_H
 
@@ -35,14 +32,28 @@ AMQP_BEGIN_DECLS
 /**
  * Create a new SSL/TLS socket object.
  *
- * Call amqp_socket_close() to release socket resources.
+ * The returned socket object is owned by the \ref amqp_connection_state_t object
+ * and will be destroyed when the state object is destroyed or a new socket
+ * object is created.
+ *
+ * If the socket object creation fails, the \ref amqp_connection_state_t object
+ * will not be changed.
+ *
+ * The object returned by this function can be retrieved from the
+ * amqp_connection_state_t object later using the amqp_get_socket() function.
+ *
+ * Calling this function may result in the underlying SSL library being initialized.
+ * \sa amqp_set_initialize_ssl_library()
  *
+ * \param [in,out] state The connection object that owns the SSL/TLS socket
  * \return A new socket object or NULL if an error occurred.
+ *
+ * \since v0.4.0
  */
 AMQP_PUBLIC_FUNCTION
 amqp_socket_t *
 AMQP_CALL
-amqp_ssl_socket_new(void);
+amqp_ssl_socket_new(amqp_connection_state_t state);
 
 /**
  * Set the CA certificate.
@@ -50,7 +61,10 @@ amqp_ssl_socket_new(void);
  * \param [in,out] self An SSL/TLS socket object.
  * \param [in] cacert Path to the CA cert file in PEM format.
  *
- * \return Zero if successful, -1 otherwise.
+ * \return \ref AMQP_STATUS_OK on success an \ref amqp_status_enum value on
+ *  failure.
+ *
+ * \since v0.4.0
  */
 AMQP_PUBLIC_FUNCTION
 int
@@ -65,7 +79,10 @@ amqp_ssl_socket_set_cacert(amqp_socket_t *self,
  * \param [in] cert Path to the client certificate in PEM foramt.
  * \param [in] key Path to the client key in PEM format.
  *
- * \return Zero if successful, -1 otherwise.
+ * \return \ref AMQP_STATUS_OK on success an \ref amqp_status_enum value on
+ *  failure.
+ *
+ * \since v0.4.0
  */
 AMQP_PUBLIC_FUNCTION
 int
@@ -82,7 +99,10 @@ amqp_ssl_socket_set_key(amqp_socket_t *self,
  * \param [in] key A buffer containing client key in PEM format.
  * \param [in] n The length of the buffer.
  *
- * \return Zero if successful, -1 otherwise.
+ * \return \ref AMQP_STATUS_OK on success an \ref amqp_status_enum value on
+ *  failure.
+ *
+ * \since v0.4.0
  */
 AMQP_PUBLIC_FUNCTION
 int
@@ -101,6 +121,8 @@ amqp_ssl_socket_set_key_buffer(amqp_socket_t *self,
  *
  * \param [in,out] self An SSL/TLS socket object.
  * \param [in] verify Enable or disable peer verification.
+ *
+ * \since v0.4.0
  */
 AMQP_PUBLIC_FUNCTION
 void
@@ -114,8 +136,8 @@ amqp_ssl_socket_set_verify(amqp_socket_t *self,
  * For SSL libraries that require a one-time initialization across
  * a whole program (e.g., OpenSSL) this sets whether or not rabbitmq-c
  * will initialize the SSL library when the first call to
- * amqp_open_ssl_socket() is made. You should call this function with
- * do_init = 0 if the underlying SSL library is intialized somewhere else
+ * amqp_open_socket() is made. You should call this function with
+ * do_init = 0 if the underlying SSL library is initialized somewhere else
  * the program.
  *
  * Failing to initialize or double initialization of the SSL library will
@@ -124,12 +146,13 @@ amqp_ssl_socket_set_verify(amqp_socket_t *self,
  * By default rabbitmq-c will initialize the underlying SSL library
  *
  * NOTE: calling this function after the first socket has been opened with
- * amqp_open_ssl_socket() will not have any effect.
+ * amqp_open_socket() will not have any effect.
  *
- * \param [in] do_initalize If 0 rabbitmq-c will not initialize the SSL
- *                          library, otherwise rabbitmq-c will initialize the
- *                          SL library
+ * \param [in] do_initialize If 0 rabbitmq-c will not initialize the SSL
+ *                           library, otherwise rabbitmq-c will initialize the
+ *                           SSL library
  *
+ * \since v0.4.0
  */
 AMQP_PUBLIC_FUNCTION
 void