From c2cbb35cdf74eb204c93d2f53a6ffd1cdfe38c55 Mon Sep 17 00:00:00 2001 From: karutoh Date: Thu, 1 Feb 2024 19:36:28 -0800 Subject: [PATCH] UDP and TCP sockets are documented. --- include/ehs/io/socket/BaseTCP.h | 68 ++++++++++++++++++++++++++++----- include/ehs/io/socket/BaseUDP.h | 34 +++++++++++++++++ 2 files changed, 93 insertions(+), 9 deletions(-) diff --git a/include/ehs/io/socket/BaseTCP.h b/include/ehs/io/socket/BaseTCP.h index 81a7cb1..49ec5c1 100644 --- a/include/ehs/io/socket/BaseTCP.h +++ b/include/ehs/io/socket/BaseTCP.h @@ -30,9 +30,12 @@ namespace ehs virtual ~BaseTCP() = default; + /// Initializes the socket with the defaults. BaseTCP(); - BaseTCP(const AddrType addrType); + /// Properly initializes the socket. + /// @param [in] type The ip version to initialize the socket with. + BaseTCP(AddrType addrType); BaseTCP(BaseTCP&& tcp) noexcept; @@ -42,22 +45,45 @@ namespace ehs BaseTCP& operator=(const BaseTCP& tcp); + /// Explicitly initialize the socket. virtual void Initialize() = 0; + /// Explicitly release resources before it falls off the stack. virtual void Release() = 0; - virtual void Bind(const Str_8& address, unsigned short port) = 0; + /// Binds to socket to a specified address and port. + /// @param [in] address The ip address to bind to. + /// @param [in] port The port to bind to. + /// @note Used for servers. + virtual void Bind(const Str_8& address, UInt_16 port) = 0; + /// Listens for new incoming connections. + /// @note Used for servers. virtual void Listen() = 0; + /// Accepts the new incoming connection. + /// @note Used for servers. virtual BaseTCP* Accept() = 0; - virtual void Connect(const Str_8& address, const unsigned short port) = 0; + /// Connects to a server at the specified address and port. + /// @param [in] address The ip address to connect to. + /// @param [in] port The port to connect to. + /// @note Used for clients. + virtual void Connect(const Str_8& address, UInt_16 port) = 0; - virtual UInt_64 Send(const Byte* const buffer, const UInt_32 size) = 0; + /// Sends data to the connected endpoint. + /// @param [in] buffer The data to send to the endpoint. + /// @param [in] size The size in bytes of data being sent. + virtual UInt_64 Send(const Byte* buffer, UInt_32 size) = 0; - virtual UInt_64 Receive(Byte* const buffer, const UInt_32 size) = 0; + /// Receives data from the connected endpoint. + /// @param [out] buffer The incoming data from the endpoint. + /// @param [in] size The max size of the buffer in bytes to store the data. + /// @returns The size of the incoming data in bytes. + virtual UInt_64 Receive(Byte* buffer, UInt_32 size) = 0; + /// Sends a string to the connected endpoint. + /// @param [in] str The string to send to the endpoint. void SendStr(const Str_8& str); /// Sends a HTTP response to the connected endpoint. @@ -76,37 +102,61 @@ namespace ehs /// @returns The request received. Request RecvReq(); + /// Retrieves the sockets ip version. + /// @returns The ip version. AddrType GetAddressType() const; + /// Retrieves the bound ip address. + /// @returns The ip address. Str_8 GetLocalAddress() const; + /// Retrieves the bound port. + /// @returns The port. unsigned short GetLocalPort() const; + /// Retrieves the ip address of the connected endpoint. + /// @returns The ip address. Str_8 GetRemoteAddress() const; - unsigned short GetRemotePort() const; + /// Retrieves the port of the connected endpoint. + /// @returns The port. + UInt_16 GetRemotePort() const; + /// Retrieves whether or not this socket is connected to a client endpoint. + /// @returns The result. bool IsConnection() const; + /// Retrieves whether of not this socket is bound to an ip address and port. + /// @returns The result. bool IsBound() const; + /// Retrieves whether or not this socket is listening for incoming connections. + /// @returns The result. bool IsListening() const; + /// Retrieves whether or not this socket is connected to an endpoint. + /// @returns The result. bool IsConnected() const; - virtual void SetBlocking(const bool blocking) = 0; + /// Sets whether or not the socket blocks the thread when receiving data. + /// @param [in] blocking Whether or not to block. + virtual void SetBlocking(bool blocking) = 0; + /// Retrieves whether or not when receiving data blocks the thread. + /// @returns The result. virtual bool IsBlocking() const = 0; + /// Retrieves whether or not this socket was initialized. + /// @returns The result. virtual bool IsValid() const = 0; private: Str_8 RecvHeader(); - Str_8 RecvBody(const UInt_64 contentLength); + Str_8 RecvBody(UInt_64 contentLength); UInt_64 RecvChunkSize(); - Str_8 RecvChunk(const UInt_64 chunkSize); + Str_8 RecvChunk(UInt_64 chunkSize); }; } \ No newline at end of file diff --git a/include/ehs/io/socket/BaseUDP.h b/include/ehs/io/socket/BaseUDP.h index f65b926..14c9b73 100644 --- a/include/ehs/io/socket/BaseUDP.h +++ b/include/ehs/io/socket/BaseUDP.h @@ -17,8 +17,11 @@ namespace ehs public: virtual ~BaseUDP() = default; + /// Initializes the socket with the defaults. BaseUDP(); + /// Properly initializes the socket. + /// @param [in] type The ip version to initialize the socket with. BaseUDP(AddrType type); BaseUDP(BaseUDP&& udp) noexcept; @@ -29,26 +32,57 @@ namespace ehs BaseUDP& operator=(const BaseUDP& udp); + /// Explicitly release resources before it falls off the stack. virtual void Release() = 0; + /// Binds to socket to a specified address and port. + /// @param [in] type The ip version to use. + /// @param [in] address The ip address to bind to. + /// @param [in] port The port to bind to. + /// @note Used for servers. virtual void Bind(AddrType type, const Str_8& address, UInt_16 port) = 0; + /// Sends data to the endpoint. + /// @param [in] type The ip version of the endpoint. + /// @param [in] address The ip address of the endpoint. + /// @param [in] port The port of the endpoint is bound to. virtual UInt_64 Send(AddrType type, const Str_8& address, UInt_16 port, const Byte* data, UInt_64 size) = 0; + /// Receives data from the endpoint. + /// @param [out] type The ip version of the endpoint. + /// @param [out] address The ip address of the endpoint. + /// @param [out] port The port of the endpoint. + /// @param [out] data The incoming data from the endpoint. + /// @param [in] size The max size of the buffer in bytes to store the data. + /// @returns The size of the incoming data in bytes. virtual UInt_64 Receive(AddrType* type, Str_8* address, UInt_16* port, Byte* data, UInt_64 size) = 0; + /// Retrieves whether or not this socket is bound to an ip address and port. + /// @returns The result. bool IsBound() const; + /// Sets whether or not the socket blocks the thread when receiving data. + /// @param [in] blocking Whether or not to block. virtual void SetBlocking(bool blocking) = 0; + /// Retrieves whether or not when receiving data blocks the thread. + /// @returns The result. virtual bool IsBlocking() const = 0; + /// Retrieves the bound ip version. + /// @returns The result. AddrType GetLocalAddressType() const; + /// Retrieves the bound ip address. + /// @returns The bound ip address. Str_8 GetLocalAddress() const; + /// Retrieves the bound port. + /// @returns The bound port. UInt_16 GetLocalPort() const; + /// Retrieves whether or not this socket was initialized. + /// @returns The result. virtual bool IsValid() const = 0; }; } \ No newline at end of file