apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dr...@apache.org
Subject svn commit: r415781 - /apr/apr-util/trunk/include/apr_ssl.h
Date Tue, 20 Jun 2006 19:35:46 GMT
Author: dreid
Date: Tue Jun 20 12:35:45 2006
New Revision: 415781

URL: http://svn.apache.org/viewvc?rev=415781&view=rev
Log:
Docs drop for the ssl code

Modified:
    apr/apr-util/trunk/include/apr_ssl.h

Modified: apr/apr-util/trunk/include/apr_ssl.h
URL: http://svn.apache.org/viewvc/apr/apr-util/trunk/include/apr_ssl.h?rev=415781&r1=415780&r2=415781&view=diff
==============================================================================
--- apr/apr-util/trunk/include/apr_ssl.h (original)
+++ apr/apr-util/trunk/include/apr_ssl.h Tue Jun 20 12:35:45 2006
@@ -48,31 +48,148 @@
  */
 typedef struct apr_ssl_socket    apr_ssl_socket_t;
 
+/**
+ * @fn apr_status_t apr_ssl_factory_create(apr_ssl_factory_t **newFactory,
+                                           const char *privateKeyFilename, 
+                                           const char *certificateFilename, 
+                                           const char *digestTypeToUse, 
+                                           apr_pool_t *pool)
+ * @brief Attempts to create an SSL "factory". The "factory" is then 
+ *        used to create sockets. If a private key filename
+ *        is passed then the created factory will assume it is to be used
+ *        in a server context.
+ * @param newFactory The newly created factory
+ * @param privateKeyFilename
+ * @param certificateFilename X509 certificate file
+ * @param digestTypeToUse A string identifying the type of digest scheme 
+ *                        to use
+ * @param pool The pool to use for memory allocations
+ * @return an APR_ status code
+ */
 APU_DECLARE(apr_status_t) apr_ssl_factory_create(apr_ssl_factory_t **,
-                                                 const char *, const char *, const char *,
apr_pool_t *);
-
-
-
+                                                 const char *, 
+                                                 const char *, 
+                                                 const char *, 
+                                                 apr_pool_t *);
+
+
+/**
+ * @fn apr_status_t apr_ssl_socket_create(apr_ssl_socket_t **newSock,
+                                                int family,
+                                                int type,
+                                                int protocol,
+                                                apr_ssl_factory_t *factory,
+                                                apr_pool_t *pool)
+ * @brief Create an ssl socket.
+ * @param newSock The new socket that has been set up.
+ * @param family The address family of the socket (e.g., APR_INET).
+ * @param type The type of the socket (e.g., SOCK_STREAM).
+ * @param protocol The protocol of the socket (e.g., APR_PROTO_TCP).
+ * @param factory The factory that it will be produced from
+ * @param pool The pool for the apr_socket_t and associated storage.
+ * @return APR_SUCCESS on succesful creation.
+ * @see apr_socket_create
+ */
 APU_DECLARE(apr_status_t) apr_ssl_socket_create(apr_ssl_socket_t **,
                                                 int, int, int,
                                                 apr_ssl_factory_t *,
                                                 apr_pool_t *);
-
+/**
+ * @fn apr_status_t apr_ssl_socket_close(apr_ssl_socket_t *sock)
+ * @brief Close a socket. This terminates the SSL connections as well
+ *        as closing the system socket.
+ * @param sock The socket to close 
+ */
 APU_DECLARE(apr_status_t) apr_ssl_socket_close(apr_ssl_socket_t *);
 
-APU_DECLARE(apr_status_t) apr_ssl_socket_connect(apr_ssl_socket_t *, apr_sockaddr_t *);
-
+/**
+ * @fn apr_status_t apr_ssl_socket_connect(apr_ssl_socket_t *sock, 
+                                           apr_sockaddr_t *sa)
+ * @brief Try and connect the provided SSL socket with the socket
+ *        described by the provided address.
+ * @param sock The SSL socket we wish to use for our side of the connection 
+ * @param sa The address we wish to connect to.
+ */
+APU_DECLARE(apr_status_t) apr_ssl_socket_connect(apr_ssl_socket_t *, 
+                                                 apr_sockaddr_t *);
+
+/**
+ * @fn apr_status_t apr_ssl_socket_send(apr_ssl_socket_t *sock,
+                                              const char *buf,
+                                              apr_size_t *len)
+ * @brief Try and send data over the SSL connection.
+ * @param sock The socket to send the data over.
+ * @param buf The buffer which contains the data to be sent. 
+ * @param len On entry, the number of bytes to send; on exit, the number
+ *            of bytes sent.
+ * @remark
+ * <PRE>
+ * This function attempts to cope with teh various encentricities of
+ * the SSL implementations in a seamless manner.
+ * This functions acts like a blocking write by default.  To change 
+ * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
+ * socket option.
+ *
+ * It is possible for both bytes to be sent and an error to be returned.
+ *
+ * APR_EINTR is never returned.
+ * </PRE>
+ */
 APU_DECLARE(apr_status_t) apr_ssl_socket_send(apr_ssl_socket_t *,
                                               const char *,
                                               apr_size_t *);
 
+/**
+ * @fn apr_status_t apr_ssl_socket_recv(apr_ssl_socket_t *sock,
+                                        char *buf, 
+                                        apr_size_t *len);
+
+ * @brief Read data from the SSL connection.
+ * @param sock The socket to read the data from.
+ * @param buf The buffer to store the data in. 
+ * @param len On entry, the number of bytes to receive; on exit, the number
+ *            of bytes received.
+ * @remark
+ * <PRE>
+ * This functions acts like a blocking read by default.  To change 
+ * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
+ * socket option.
+ * The number of bytes actually received is stored in argument 3.
+ *
+ * It is possible for both bytes to be received and an APR_EOF or
+ * other error to be returned.
+ *
+ * APR_EINTR is never returned.
+ * </PRE>
+ */
 APU_DECLARE(apr_status_t) apr_ssl_socket_recv(apr_ssl_socket_t *,
                                               char *, apr_size_t *);
 
-APU_DECLARE(apr_status_t) apr_ssl_socket_bind(apr_ssl_socket_t *, apr_sockaddr_t *);
-
-APU_DECLARE(apr_status_t) apr_ssl_socket_listen(apr_ssl_socket_t *, apr_int32_t);
-
+/**
+ * @see apr_socket_bind
+ */
+APU_DECLARE(apr_status_t) apr_ssl_socket_bind(apr_ssl_socket_t *, 
+                                              apr_sockaddr_t *);
+
+/**
+ * @see apr_socket_listen
+ */
+APU_DECLARE(apr_status_t) apr_ssl_socket_listen(apr_ssl_socket_t *, 
+                                                apr_int32_t);
+
+/**
+ * @fn apr_status_t apr_ssl_socket_accept(apr_ssl_socket_t **newSock,
+                                          apr_ssl_socket_t *sock,
+                                          apr_pool_t *pool)
+ * @brief Accept a new connection request on an SSL socket. This creates
+ *        and returns a new SSL enabled socket. The enw socket will
+ *        "belong" to the same factory that created the original socket.
+ * @param newSock A copy of the socket that is connected to the socket that
+ *                made the connection request.  This is the socket which should
+ *                be used for all future communication.
+ * @param sock The socket we are listening on.
+ * @param pool The pool for the new socket.
+ */
 APU_DECLARE(apr_status_t) apr_ssl_socket_accept(apr_ssl_socket_t **,
                                                 apr_ssl_socket_t *,
                                                 apr_pool_t *);



Mime
View raw message