From 9f69c771f6f6d5d848adfce8eaeffdc01a607d6b Mon Sep 17 00:00:00 2001 From: Baptiste Wicht Date: Mon, 19 Sep 2016 10:04:09 +0200 Subject: [PATCH] Documentation of the tlib --- tlib/include/tlib/net.hpp | 143 +++++++++++++++++++++++++++++++++++++- 1 file changed, 142 insertions(+), 1 deletion(-) diff --git a/tlib/include/tlib/net.hpp b/tlib/include/tlib/net.hpp index 9a9ed128..bbd4f04a 100644 --- a/tlib/include/tlib/net.hpp +++ b/tlib/include/tlib/net.hpp @@ -5,6 +5,17 @@ // http://www.opensource.org/licenses/MIT) //======================================================================= +/*! + * \file + * \brief Network support for the Thor OS + * + * There are two ways of using the interface: + * * The free functions + * * The socket structure + * + * The second interface is easier and handles more thing automatically. + */ + #ifndef TLIB_NET_H #define TLIB_NET_H @@ -18,6 +29,11 @@ ASSERT_ONLY_THOR_PROGRAM namespace tlib { +/*! + * \brief A network packet abstraction + * + * The resources are automatically freed + */ struct packet { size_t fd; ///< The packet file descriptor char* payload; ///< The payload pointer @@ -29,29 +45,103 @@ struct packet { packet& operator=(const packet& p) = delete; packet(packet&& rhs); - packet& operator=(packet&& rhs); ~packet(); }; +/*! + * \brief Open a socket + * \param domain The socket domain + * \param type The socket type + * \param protocol The socket protocol + * \return The socket file descriptor or an error + */ std::expected socket_open(socket_domain domain, socket_type type, socket_protocol protocol); + +/*! + * \brief Close a socket. + * \param socket_fd The socket file descriptor + */ void socket_close(size_t socket_fd); +/*! + * \brief Prepare a packet + * \param socket_fd The socket file descriptor + * \param desc The packet descriptor + * \return The prepared packet or an error + */ std::expected prepare_packet(size_t socket_fd, void* desc); + +/*! + * \brief Finalize a packet (send it) + * \param socket_fd The socket file descriptor + * \param p The packet to finalize + * \return nothing, or an error + */ std::expected finalize_packet(size_t socket_fd, const packet& p); +/*! + * \brief Send a message through the socket + * \param socket_fd The socket file descriptor + * \param buffer The source buffer + * \param n The message's size + * \return nothing, or an error + */ std::expected send(size_t socket_fd, const char* buffer, size_t n); +/*! + * \brief Listen for messages on the socket + * \param socket_fd The socket file descriptor + * \param l Indicating the listening status + * \return nothing, or an error + */ std::expected listen(size_t socket_fd, bool l); +/*! + * \brief Bind a destination to the datagram socket + * \param socket_fd The socket file descriptor + * \param server The server address + * \return the local port, or an error + */ std::expected client_bind(size_t socket_fd, tlib::ip::address server); + +/*! + * \brief Unbind from destination from the datagram socket + * \param socket_fd The socket file descriptor + * \return nothing, or an error + */ std::expected client_unbind(size_t socket_fd); +/*! + * \brief Connect to a destination to the stream socket + * \param socket_fd The socket file descriptor + * \param server The server address + * \param port The server port + * \return the local port, or an error + */ std::expected connect(size_t socket_fd, tlib::ip::address server, size_t port); + +/*! + * \brief Disconnect from destination from the datagram socket + * \param socket_fd The socket file descriptor + * \return nothing, or an error + */ std::expected disconnect(size_t socket_fd); +/*! + * \brief Wait for a packet, indifinitely + * \param socket_fd The socket file descriptor + * \return the received packet, or an error + */ std::expected wait_for_packet(size_t socket_fd); + +/*! + * \brief Wait for a packet, for the given time in milliseconds + * \param socket_fd The socket file descriptor + * \param ms The maximum time to wait + * \return the received packet, or an error + */ std::expected wait_for_packet(size_t socket_fd, size_t ms); /*! @@ -113,19 +203,62 @@ struct socket { * \param server The IP address */ void client_bind(tlib::ip::address server); + + /*! + * \brief Unbind the client socket + */ void client_unbind(); + /*! + * \brief Connect to the server (stream socket) + * \param server The IP of the server + * \param port The port of the server + */ void connect(tlib::ip::address server, size_t port); + + /*! + * \brief Disconnnect from the server (stream socket) + */ void disconnect(); + /*! + * \brief Listen to the socket (start receiving packets) + */ void listen(bool l); + /*! + * \brief Prepare a packet to send + * \param desc The descriptor of the packet + * \return The prepared packet + */ packet prepare_packet(void* desc); + + /*! + * \brief Finalize the packet (send it) + * \param p The packet to send + */ void finalize_packet(const packet& p); + /*! + * \brief Send a message + * \param buffer The source buffer (the contents) + * \param n The size of the message + */ void send(const char* buffer, size_t n); + /*! + * \brief Wait for a packet, indefinitely. + * \return the received packet + */ packet wait_for_packet(); + + /*! + * \brief Wait for a packet, for ms milliseconds. + * + * If a packet is not received during the given time, the error is set in socket and the received packet is a fake one. + * + * \return the received packet + */ packet wait_for_packet(size_t ms); private: @@ -138,10 +271,18 @@ private: bool _bound; ///< Bind flag }; +/*! + * \brief Switch endianness of a 16 bit value + * \return the input value with switched endianness + */ inline uint16_t switch_endian_16(uint16_t nb) { return (nb >> 8) | (nb << 8); } +/*! + * \brief Switch endianness of a 32 bit value + * \return the input value with switched endianness + */ inline uint32_t switch_endian_32(uint32_t nb) { return ((nb >> 24) & 0xff) | ((nb << 8) & 0xff0000) |