Mercurial > code
changeset 386:743b3a1c71c8
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)