From 211afb17c43ebf8e90639d44af7c7891b78f3dfa Mon Sep 17 00:00:00 2001 From: Marcelo Aquino Date: Mon, 15 Aug 2016 18:47:09 -0300 Subject: [PATCH] Doxygenize Linux drivers --- drivers/Linux/Client.h | 3 + drivers/Linux/EthernetClient.cpp | 34 +++--- drivers/Linux/EthernetClient.h | 176 ++++++++++++++++++++++++++----- drivers/Linux/IPAddress.h | 106 +++++++++++++++---- drivers/Linux/Stream.h | 2 + 5 files changed, 255 insertions(+), 66 deletions(-) diff --git a/drivers/Linux/Client.h b/drivers/Linux/Client.h index 0169890..067b57d 100644 --- a/drivers/Linux/Client.h +++ b/drivers/Linux/Client.h @@ -24,6 +24,7 @@ #include "Stream.h" #include "IPAddress.h" +#if !DOXYGEN class Client : public Stream { public: @@ -39,8 +40,10 @@ public: virtual void stop() = 0; virtual uint8_t connected() = 0; virtual operator bool() = 0; + protected: uint8_t* rawIPAddress(IPAddress& addr) { return addr.raw_address(); }; }; +#endif #endif diff --git a/drivers/Linux/EthernetClient.cpp b/drivers/Linux/EthernetClient.cpp index 5e80848..387fcaa 100644 --- a/drivers/Linux/EthernetClient.cpp +++ b/drivers/Linux/EthernetClient.cpp @@ -190,18 +190,6 @@ void EthernetClient::stop() { _sock = -1; } -uint8_t EthernetClient::connected() { - if (_sock == -1) return 0; - - if (peek() < 0) { - if (errno == EAGAIN) { - return 1; - } - return 0; - } - return 1; -} - uint8_t EthernetClient::status() { if (_sock == -1) return ETHERNETCLIENT_W5100_CLOSED; @@ -232,13 +220,27 @@ uint8_t EthernetClient::status() { case TCP_CLOSING: return ETHERNETCLIENT_W5100_CLOSING; } - } else { - perror("getsockopt"); } return ETHERNETCLIENT_W5100_CLOSED; } +uint8_t EthernetClient::connected() { + if (_sock == -1) return 0; + + if (peek() < 0) { + if (errno == EAGAIN) { + return 1; + } + return 0; + } + return 1; +} + +int EthernetClient::getSocketNumber() { + return _sock; +} + // the next function allows us to use the client returned by // EthernetServer::available() as the condition in an if-statement. @@ -249,7 +251,3 @@ EthernetClient::operator bool() { bool EthernetClient::operator==(const EthernetClient& rhs) { return _sock == rhs._sock && _sock != -1 && rhs._sock != -1; } - -int EthernetClient::getSocketNumber() { - return _sock; -} diff --git a/drivers/Linux/EthernetClient.h b/drivers/Linux/EthernetClient.h index 0627436..f21f5d3 100644 --- a/drivers/Linux/EthernetClient.h +++ b/drivers/Linux/EthernetClient.h @@ -39,42 +39,160 @@ // debug #if defined(ETHERNETCLIENT_VERBOSE) - #define ETHERNETCLIENT_DEBUG(x,...) debug(x, ##__VA_ARGS__) + #define ETHERNETCLIENT_DEBUG(x,...) debug(x, ##__VA_ARGS__) //!< debug #else - #define ETHERNETCLIENT_DEBUG(x,...) + #define ETHERNETCLIENT_DEBUG(x,...) //!< debug NULL #endif +/** + * EthernetClient class + */ class EthernetClient : public Client { -public: - EthernetClient(); - EthernetClient(int sock); - - uint8_t status(); - virtual int connect(IPAddress ip, uint16_t port); - virtual int connect(const char *host, uint16_t port); - virtual size_t write(uint8_t); - virtual size_t write(const uint8_t *buf, size_t size); - size_t write(const char *str); - size_t write(const char *buffer, size_t size); - virtual int available(); - virtual int read(); - virtual int read(uint8_t *buf, size_t size); - virtual int peek(); - virtual void flush(); - virtual void stop(); - virtual uint8_t connected(); - virtual operator bool(); - virtual bool operator==(const bool value) { return bool() == value; } - virtual bool operator!=(const bool value) { return bool() != value; } - virtual bool operator==(const EthernetClient&); - virtual bool operator!=(const EthernetClient& rhs) { return !this->operator==(rhs); }; - int getSocketNumber(); - - friend class EthernetServer; - private: int _sock; + +public: + /** + * @brief EthernetClient constructor. + */ + EthernetClient(); + /** + * @brief EthernetClient constructor. + * + * @param sock Network socket. + */ + EthernetClient(int sock); + /** + * @brief Initiate a connection with host:port. + * + * @param host host name to resolve or a stringified dotted IP address. + * @param port to connect to. + * @return 1 if SUCCESS or -1 if FAILURE. + */ + virtual int connect(const char *host, uint16_t port); + /** + * @brief Initiate a connection with ip:port. + * + * @param ip to connect to. + * @param port to connect to. + * @return 1 if SUCCESS or -1 if FAILURE. + */ + virtual int connect(IPAddress ip, uint16_t port); + /** + * @brief Write a byte. + * + * @param b byte to write. + * @return 0 if FAILURE or 1 if SUCCESS. + */ + virtual size_t write(uint8_t b); + /** + * @brief Write at most 'size' bytes. + * + * @param buf Buffer to read from. + * @param size of the buffer. + * @return 0 if FAILURE or the number of bytes sent. + */ + virtual size_t write(const uint8_t *buf, size_t size); + /** + * @brief Write a null-terminated string. + * + * @param str String to write. + * @return 0 if FAILURE or number of characters sent. + */ + size_t write(const char *str); + /** + * @brief Write at most 'size' characters. + * + * @param buffer to read from. + * @param size of the buffer. + * @return 0 if FAILURE or the number of characters sent. + */ + size_t write(const char *buffer, size_t size); + /** + * @brief Checks if new data is available. + * + * @return number of bytes available. + */ + virtual int available(); + /** + * @brief Read a byte. + * + * @return 0 if FAILURE or 1 if SUCCESS. + * @note This function will block (until data becomes available or timeout is reached). + */ + virtual int read(); + /** + * @brief Read a number of bytes and store in a buffer. + * + * @return -1 if FAILURE or number of read bytes. + * @note This function will block (until data becomes available or timeout is reached). + */ + virtual int read(uint8_t *buf, size_t size); + /** + * @brief Check if new data are available. + * + * @return 0 if no data, else number of bytes available. + */ + virtual int peek(); + /** + * @brief Flushes the network buffers. + * + * Empty function due to the way TCP works. + */ + virtual void flush(); + /** + * @brief Close the connection gracefully. + * + * Send a FIN and wait 1s for a response. If no response close it forcefully. + */ + virtual void stop(); + /** + * @brief Connection status. + * + * @return state according to W5100 library codes. + */ + uint8_t status(); + /** + * @brief Checks whether the socket is alive. + * + * @return 0 if disconnected or 1 if connected. + */ + virtual uint8_t connected(); + /** + * @brief Get the internal socket file descriptor. + * + * @return an integer, that is the socket number. + */ + int getSocketNumber(); + /** + * @brief Overloaded cast operators. + * + * Allow EthernetClient objects to be used where a bool is expected. + */ + virtual operator bool(); + /** + * @brief Overloaded cast operators. + * + */ + virtual bool operator==(const bool value) { return bool() == value; } + /** + * @brief Overloaded cast operators. + * + */ + virtual bool operator!=(const bool value) { return bool() != value; } + /** + * @brief Overloaded cast operators. + * + */ + virtual bool operator==(const EthernetClient& rhs); + /** + * @brief Overloaded cast operators. + * + */ + virtual bool operator!=(const EthernetClient& rhs) { return !this->operator==(rhs); }; + + friend class EthernetServer; }; #endif diff --git a/drivers/Linux/IPAddress.h b/drivers/Linux/IPAddress.h index f4b05c0..c8e336c 100644 --- a/drivers/Linux/IPAddress.h +++ b/drivers/Linux/IPAddress.h @@ -26,59 +26,127 @@ #include #include -// A class to make it easier to handle and pass around IP addresses - -// class IPAddress: public Printable { +/** + * @brief A class to make it easier to handle and pass around IP addresses + */ class IPAddress { private: union { - uint8_t bytes[4]; // IPv4 address - uint32_t dword; + uint8_t bytes[4]; //!< IPv4 address as an array + uint32_t dword; //!< IPv4 address in 32 bits format } _address; - // Access the raw byte array containing the address. Because this returns a pointer - // to the internal structure rather than a copy of the address this function should only - // be used when you know that the usage of the returned uint8_t* will be transient and not - // stored. + /** + * @brief Access the raw byte array containing the address. + * + * Because this returns a pointer to the internal structure rather than a copy of the address + * this function should only be used when you know that the usage of the returned uint8_t* will + * be transient and not stored. + * + * @return pointer to the internal structure. + */ uint8_t* raw_address() { return _address.bytes; } public: - // Constructors + /** + * @brief IPAddress constructor. + */ IPAddress(); + /** + * @brief IPAddress constructor. + * + * @param first_octet first octet of the IPv4 address. + * @param second_octet second octet of the IPv4 address. + * @param third_octet third octet of the IPv4 address. + * @param fourth_octet fourth octet of the IPv4 address. + */ IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet); + /** + * @brief IPAddress constructor. + * + * @param address to be set from a 32 bits integer. + */ IPAddress(uint32_t address); + /** + * @brief IPAddress constructor. + * + * @param address to be set from a byte array. + */ IPAddress(const uint8_t *address); - + /** + * @brief Set the IP from a array of characters. + * + * @param address to be set. + */ bool fromString(const char *address); + /** + * @brief Set the IP from a string class type. + * + * @param address to be set. + */ bool fromString(const std::string &address) { return fromString(address.c_str()); } - - // Overloaded cast operator to allow IPAddress objects to be used where a pointer - // to a four-byte uint8_t array is expected + /** + * @brief Overloaded cast operator + * + * Allow IPAddress objects to be used where a pointer to a four-byte uint8_t array is expected + */ operator uint32_t() const { return _address.dword; } + /** + * @brief Overloaded cast operator + * + */ bool operator==(const IPAddress& addr) const { return _address.dword == addr._address.dword; } + /** + * @brief Overloaded cast operator + * + */ bool operator==(uint32_t addr) const { return _address.dword == addr; } + /** + * @brief Overloaded cast operator + * + */ bool operator==(const uint8_t* addr) const; - - // Overloaded index operator to allow getting and setting individual octets of the address + /** + * @brief Overloaded index operator. + * + * Allow getting and setting individual octets of the address. + * + */ uint8_t operator[](int index) const { return _address.bytes[index]; } + /** + * @brief Overloaded index operator + * + */ uint8_t& operator[](int index) { return _address.bytes[index]; } - - // Overloaded copy operators to allow initialisation of IPAddress objects from other types + /** + * @brief Overloaded copy operators. + * + * Allow initialisation of IPAddress objects from byte array. + */ IPAddress& operator=(const uint8_t *address); + /** + * @brief Overloaded copy operator. + * + * Allow initialisation of IPAddress objects from a 32 bits integer. + */ IPAddress& operator=(uint32_t address); - + /** + * @brief Convert the IP address to a string. + * + * @return A stringified IP address + */ std::string toString(); friend class Client; diff --git a/drivers/Linux/Stream.h b/drivers/Linux/Stream.h index 0241f6a..226543b 100644 --- a/drivers/Linux/Stream.h +++ b/drivers/Linux/Stream.h @@ -1,6 +1,7 @@ #ifndef Stream_h #define Stream_h +#if !DOXYGEN class Stream { public: virtual size_t write(uint8_t) = 0; @@ -11,5 +12,6 @@ class Stream { virtual int peek() = 0; virtual void flush() = 0; }; +#endif #endif