Mercurial > code

changeset 386:743b3a1c71c8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Socket: improve doxygen documentation
author David Demelier <markand@malikania.fr>
date Wed, 24 Jun 2015 09:37:43 +0200
parents b732c4431f7d
children 6a7421f7302f
files C++/modules/Socket/Socket.cpp C++/modules/Socket/Socket.h C++/modules/Socket/SocketAddress.h C++/modules/Socket/SocketListener.h C++/modules/Socket/SocketSsl.cpp C++/modules/Socket/SocketSsl.h C++/tests/Socket/main.cpp
diffstat 7 files changed, 97 insertions(+), 66 deletions(-) [+]
line wrap: on
line diff
--- a/C++/modules/Socket/Socket.cpp	Tue Jun 23 15:14:42 2015 +0200
+++ b/C++/modules/Socket/Socket.cpp	Wed Jun 24 09:37:43 2015 +0200
@@ -140,37 +140,6 @@
 	close();
 }
 
-#if 0
-
-std::unique_ptr<SocketAddress> SocketAbstract::address() const
-{
-	socklen_t length;
-	sockaddr_storage ss;
-
-	if (getsockname(m_handle, (sockaddr *)&ss, &length) == Error)
-		throw SocketError(SocketError::System, "getsockname");
-
-	return SocketAddress::decode(ss, length);
-}
-
-#endif
-
-#if 0
-
-void SocketAbstract::bind(const std::unique_ptr<SocketAddress> &address)
-{
-	const auto &sa = address->address();
-	const auto addrlen = address->length();
-
-	if (::bind(m_handle, reinterpret_cast<const sockaddr *>(&sa), addrlen) == Error) {
-		throw SocketError(SocketError::System, "bind");
-	}
-
-	m_state = SocketState::Bound;
-}
-
-#endif
-
 void SocketAbstract::close()
 {
 	if (m_state != SocketState::Closed) {
--- a/C++/modules/Socket/Socket.h	Tue Jun 23 15:14:42 2015 +0200
+++ b/C++/modules/Socket/Socket.h	Wed Jun 24 09:37:43 2015 +0200
@@ -25,14 +25,12 @@
  *
  * User may set the following variables before compiling these files:
  *
- * SOCKET_NO_WSA_INIT	- (bool) Set to false if you don't want Socket class to
- *			  automatically calls WSAStartup() when creating sockets.
+ * - **SOCKET_NO_WSA_INIT**:(bool) Set to false if you don't want Socket class to
+ * automatically calls WSAStartup() when creating sockets. Otherwise, you will need to call
+ * SocketAbstract::init, SocketAbstract::finish yourself.
  *
- *			  Otherwise, you will need to call Socket::init,
- *			  Socket::finish yourself.
- *
- * SOCKET_NO_SSL_INIT	- (bool) Set to false if you don't want OpenSSL to be
- *			  initialized when the first SocketSsl object is created.
+ * - **SOCKET_NO_SSL_INIT**: (bool) Set to false if you don't want OpenSSL to be
+ * initialized when the first SocketSsl object is created.
  */
 
 #include <cstdlib>
@@ -155,12 +153,12 @@
  * @brief Category of error
  */
 enum class SocketState {
-	Opened,				///!< Socket is opened
-	Closed,				///!< Socket has been closed
-	Bound,				///!< Socket is bound to address
-	Connected,			///!< Socket is connected to an end point
-	Disconnected,			///!< Socket is disconnected
-	Timeout				///!< Timeout has occured in a waiting operation
+	Opened,				//!< Socket is opened
+	Closed,				//!< Socket has been closed
+	Bound,				//!< Socket is bound to address
+	Connected,			//!< Socket is connected to an end point
+	Disconnected,			//!< Socket is disconnected
+	Timeout				//!< Timeout has occured in a waiting operation
 };
 
 /* --------------------------------------------------------
@@ -168,7 +166,7 @@
  * -------------------------------------------------------- */
 
 /**
- * @class Socket
+ * @class SocketAbstract
  * @brief Base socket class for socket operations
  */
 class SocketAbstract {
@@ -865,7 +863,7 @@
 	/**
 	 * Overloaded function.
 	 *
-	 * @param data the data
+	 * @param count the maximum number of bytes to receive
 	 * @param info the client information
 	 * @return the string
 	 * @throw SocketError on error
--- a/C++/modules/Socket/SocketAddress.h	Tue Jun 23 15:14:42 2015 +0200
+++ b/C++/modules/Socket/SocketAddress.h	Wed Jun 24 09:37:43 2015 +0200
@@ -116,8 +116,22 @@
 	virtual socklen_t length() const noexcept = 0;
 };
 
+/**
+ * Compare two socket addresses, std::equal is used.
+ *
+ * @param addr1 the first address
+ * @param addr2 the second address
+ * @return true if equals
+ */
 bool operator==(const SocketAddressAbstract &addr1, const SocketAddressAbstract &addr2) noexcept;
 
+/**
+ * Compare two socket addresses, std::lexicographical_compare is used.
+ *
+ * @param addr1 the first address
+ * @param addr2 the second address
+ * @return true if addr1 < addr2
+ */
 bool operator<(const SocketAddressAbstract &addr1, const SocketAddressAbstract &addr2) noexcept;
 
 /**
@@ -205,11 +219,24 @@
 	 */
 	Ipv6() = default;
 
+	/**
+	 * Construct an IPv6 address from storage.
+	 *
+	 * @param ss the storage
+	 * @param length the length
+	 */
 	inline Ipv6(const sockaddr_storage &ss, socklen_t length)
 		: Ip(ss, length)
 	{
 	}
 
+	/**
+	 * Construct an IPv6 address.
+	 *
+	 * @param host the host
+	 * @param port the port
+	 * @throw SocketError on error
+	 */
 	inline Ipv6(const std::string &host, unsigned port)
 		: Ip(host, port, AF_INET6)
 	{
@@ -227,11 +254,24 @@
 	 */
 	Ipv4() = default;
 
+	/**
+	 * Construct an IPv4 address from storage.
+	 *
+	 * @param ss the storage
+	 * @param length the length
+	 */
 	inline Ipv4(const sockaddr_storage &ss, socklen_t length)
 		: Ip(ss, length)
 	{
 	}
 
+	/**
+	 * Construct an IPv4 address.
+	 *
+	 * @param host the host
+	 * @param port the port
+	 * @throw SocketError on error
+	 */
 	inline Ipv4(const std::string &host, unsigned port)
 		: Ip(host, port, AF_INET)
 	{
--- a/C++/modules/Socket/SocketListener.h	Tue Jun 23 15:14:42 2015 +0200
+++ b/C++/modules/Socket/SocketListener.h	Wed Jun 24 09:37:43 2015 +0200
@@ -20,6 +20,9 @@
 #define _SOCKET_LISTENER_NG_H_
 
 /**
+ * @file SocketListener.h
+ * @brief Portable synchronous multiplexer
+ *
  * Feature detection, multiple implementations may be avaible, for example,
  * Linux has poll, select and epoll.
  *
@@ -28,10 +31,11 @@
  * Of course, you can set the variables yourself if you test it with your
  * build system.
  *
- * SOCKET_HAVE_POLL	- Defined on all BSD, Linux. Also defined on Windows
- *			  if _WIN32_WINNT is set to 0x0600 or greater.
- * SOCKET_HAVE_KQUEUE	- Defined on all BSD and Apple.
- * SOCKET_HAVE_EPOLL	- Defined on Linux only.
+ * - **SOCKET_HAVE_POLL**: Defined on all BSD, Linux. Also defined on Windows
+ * if _WIN32_WINNT is set to 0x0600 or greater.
+ *
+ * - **SOCKET_HAVE_KQUEUE**: Defined on all BSD and Apple.
+ * - **SOCKET_HAVE_EPOLL**: Defined on Linux only.
  */
 #if defined(_WIN32)
 #  if _WIN32_WINNT >= 0x0600
@@ -51,14 +55,12 @@
  *
  * The preference priority is ordered from left to right.
  *
- * +---------------+-------------------------+
  * | System        | Backend                 |
- * +---------------+-------------------------+
+ * |---------------|-------------------------|
  * | Linux         | epoll(7)                |
  * | *BSD          | kqueue(2)               |
  * | Windows       | poll(2), select(2)      |
  * | Mac OS X      | kqueue(2)               |
- * +---------------+-------------------------+
  */
 
 #if defined(_WIN32)
@@ -115,6 +117,9 @@
  */
 using SocketTable = std::map<SocketAbstract::Handle, std::pair<SocketAbstract *, int>>;
 
+/**
+ * @brief Namespace for predefined backends
+ */
 namespace backend {
 
 /**
@@ -143,6 +148,9 @@
 	 */
 	inline void unset(const SocketTable &, SocketAbstract &, int, bool) noexcept {}
 
+	/**
+	 * Return the sockets
+	 */
 	std::vector<SocketStatus> wait(const SocketTable &table, int ms);
 };
 
@@ -255,7 +263,7 @@
 } // !backend
 
 /**
- * @class SocketListenerBase
+ * @class SocketListenerAbstract
  * @brief Synchronous multiplexing
  *
  * Convenient wrapper around the select() system call.
--- a/C++/modules/Socket/SocketSsl.cpp	Tue Jun 23 15:14:42 2015 +0200
+++ b/C++/modules/Socket/SocketSsl.cpp	Wed Jun 24 09:37:43 2015 +0200
@@ -40,10 +40,10 @@
 
 } // !namespace
 
-std::mutex SocketSsl::s_sslMutex;
-std::atomic<bool> SocketSsl::s_sslInitialized{false};
+std::mutex SocketAbstractSsl::s_sslMutex;
+std::atomic<bool> SocketAbstractSsl::s_sslInitialized{false};
 
-SocketSsl::SocketSsl(std::unique_ptr<SocketTcp> sc, SSL_CTX *context, SSL *ssl)
+SocketSsl::SocketSsl(SocketTcp<Address> sc, SSL_CTX *context, SSL *ssl)
 	: SocketTcp{std::move(*sc)}
 	, m_context{context, SSL_CTX_free}
 	, m_ssl{ssl, SSL_free}
--- a/C++/modules/Socket/SocketSsl.h	Tue Jun 23 15:14:42 2015 +0200
+++ b/C++/modules/Socket/SocketSsl.h	Wed Jun 24 09:37:43 2015 +0200
@@ -16,11 +16,11 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+#if 0
+
 #ifndef _SOCKET_SSL_NG_H_
 #define _SOCKET_SSL_NG_H_
 
-#if 0
-
 #include <cstdint>
 #include <atomic>
 #include <memory>
@@ -33,6 +33,15 @@
 #include "SocketTcp.h"
 
 /**
+ * This namespace is private.
+ */
+namespace ssl {
+
+
+
+} // !ssl
+
+/**
  * @class SocketSslOptions
  * @brief Options for SocketSsl
  */
@@ -81,7 +90,8 @@
  *
  * This class derives from SocketAbstractTcp and provide SSL support through OpenSSL.
  */
-class SocketSsl : public SocketTcp {
+template <typename Address>
+class SocketSsl : public SocketAbstractTcp<Address> {
 private:
 	using ContextHandle = std::unique_ptr<SSL_CTX, void (*)(SSL_CTX *)>;
 	using SslHandle = std::unique_ptr<SSL, void (*)(SSL *)>;
@@ -126,7 +136,7 @@
 	 * @param context the context
 	 * @param ssl the ssl object
 	 */
-	SocketSsl(std::unique_ptr<SocketTcp> sc, SSL_CTX *context, SSL *ssl);
+	SocketSsl(SocketTcp<Address> sc, SSL_CTX *context, SSL *ssl);
 
 	/**
 	 * Open a SSL socket with the specified family. Automatically
@@ -175,6 +185,6 @@
 	using SocketTcp::recv;
 };
 
-#endif
+#endif // !_SOCKET_SSL_NG_H_
 
-#endif // !_SOCKET_SSL_NG_H_
+#endif
--- a/C++/tests/Socket/main.cpp	Tue Jun 23 15:14:42 2015 +0200
+++ b/C++/tests/Socket/main.cpp	Wed Jun 24 09:37:43 2015 +0200
@@ -170,7 +170,7 @@
 	bool m_added{false};
 	int m_flags{0};
 
-	inline void set(const SocketTable &, SocketAbstract &sc, int flags, bool add) noexcept
+	inline void set(const SocketTable &, SocketAbstract &, int flags, bool add) noexcept
 	{
 		m_callcount ++;
 		m_added = add;
@@ -181,7 +181,10 @@
 	{
 	}
 
-	std::vector<SocketStatus> wait(const SocketTable &table, int ms) {}
+	std::vector<SocketStatus> wait(const SocketTable &, int)
+	{
+		return {};
+	}
 };
 
 class TestBackendSetFail {
@@ -195,7 +198,10 @@
 	{
 	}
 
-	std::vector<SocketStatus> wait(const SocketTable &table, int ms) {}
+	std::vector<SocketStatus> wait(const SocketTable &, int)
+	{
+		return {};
+	}
 };
 
 TEST(ListenerSet, initialAdd)