From d36a0b6b88b553d03abfd99836b6529f0e63cad6 Mon Sep 17 00:00:00 2001 From: Christopher Haster Date: Tue, 19 Apr 2016 17:51:51 -0500 Subject: [PATCH] Revised documentation for Interface classes --- CellularInterface.h | 45 +++++++++++++++++++++++++++++ EthernetInterface.h | 11 +++++--- MeshInterface.h | 7 +++-- NetworkInterface.h | 21 ++++++++------ SocketAddress.h | 69 +++++++++++++++++++++++++++++---------------- TCPServer.h | 2 +- TCPSocket.h | 4 +-- UDPSocket.h | 4 +-- WiFiInterface.h | 19 ++++++++++--- 9 files changed, 134 insertions(+), 48 deletions(-) create mode 100644 CellularInterface.h diff --git a/CellularInterface.h b/CellularInterface.h new file mode 100644 index 0000000000..a65ac62012 --- /dev/null +++ b/CellularInterface.h @@ -0,0 +1,45 @@ +/* CellularInterface + * Copyright (c) 2015 ARM Limited + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef CELLULAR_INTERFACE_H +#define CELLULAR_INTERFACE_H + +#include "NetworkInterface.h" + +/** CellularInterface class + * + * Common interface that is shared between ethernet hardware + */ +class CellularInterface : public NetworkInterface +{ +public: + /** Start the interface + * + * @param apn Optional name of the network to connect to + * @param username Optional username for your APN + * @param password Optional password for your APN + * @return 0 on success, negative error code on failure + */ + virtual int connect(const char *apn = 0, const char *username = 0, const char *password = 0) = 0; + + /** Stop the interface + * + * @return 0 on success, negative error code on failure + */ + virtual int disconnect() = 0; +}; + +#endif diff --git a/EthernetInterface.h b/EthernetInterface.h index a48846f650..8fce3082d0 100644 --- a/EthernetInterface.h +++ b/EthernetInterface.h @@ -1,4 +1,4 @@ -/* Socket +/* EthernetInterface * Copyright (c) 2015 ARM Limited * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -20,18 +20,21 @@ #include "NetworkInterface.h" /** EthernetInterface class - * Common interface that is shared between ethernet hardware + * + * Common interface that is shared between ethernet hardware. */ class EthernetInterface : public NetworkInterface { public: /** Start the interface - * @return 0 on success, negative on failure + * + * @return 0 on success, negative error code on failure */ virtual int connect() = 0; /** Stop the interface - * @return 0 on success, negative on failure + * + * @return 0 on success, negative error code on failure */ virtual int disconnect() = 0; }; diff --git a/MeshInterface.h b/MeshInterface.h index 884708a623..0b1f598a00 100644 --- a/MeshInterface.h +++ b/MeshInterface.h @@ -1,4 +1,4 @@ -/* Socket +/* MeshInterface * Copyright (c) 2015 ARM Limited * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -20,17 +20,20 @@ #include "NetworkInterface.h" /** MeshInterface class - * Common interface that is shared between ethernet hardware + * + * Common interface that is shared between mesh hardware */ class MeshInterface : public NetworkInterface { public: /** Start the interface + * * @return 0 on success, negative on failure */ virtual int connect() = 0; /** Stop the interface + * * @return 0 on success, negative on failure */ virtual int disconnect() = 0; diff --git a/NetworkInterface.h b/NetworkInterface.h index f15a2c16cb..1f35571d6e 100644 --- a/NetworkInterface.h +++ b/NetworkInterface.h @@ -46,7 +46,7 @@ enum nsapi_error_t { * The socket protocol specifies a particular protocol to * be used with a newly created socket. * - * @enum protocol_t + * @enum nsapi_protocol_t */ enum nsapi_protocol_t { NSAPI_TCP, /*!< Socket is of TCP type */ @@ -74,26 +74,29 @@ class NetworkInterface public: virtual ~NetworkInterface() {}; - /** Get the internally stored IP address + /** Get the local IP address * - * @return IP address of the interface or null if not yet connected + * @return Null-terminated representation of the local IP address + * or null if not yet connected */ virtual const char *get_ip_address() = 0; - /** Get the internally stored MAC address + /** Get the local MAC address * - * @return MAC address of the interface + * @return Null-terminated representation of the local MAC address */ virtual const char *get_mac_address() = 0; - /** Translates a host name to an IP address + /** Translates a hostname to an IP address * - * The host name may be either a domain name or an IP address. - * If no stack-specific DNS resolution is provided, the host name + * The hostname may be either a domain name or an IP address. If the + * hostname is an IP address, no network transactions will be performed. + * + * If no stack-specific DNS resolution is provided, the hostname * will be resolve using a UDP socket on the stack. * * @param address Destination for the host SocketAddress - * @param host Host name to lookup + * @param host Hostname to resolve * @return 0 on success, negative error code on failure */ virtual int gethostbyname(SocketAddress *address, const char *host); diff --git a/SocketAddress.h b/SocketAddress.h index 1f93177b5e..4e68053265 100644 --- a/SocketAddress.h +++ b/SocketAddress.h @@ -1,4 +1,4 @@ -/* Socket +/* SocketAddress * Copyright (c) 2015 ARM Limited * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -28,8 +28,11 @@ */ #define NSAPI_IP_BYTES NSAPI_IPv6_BYTES -/** Enum of address families - * @enum nsapi_family_t +/** Enum of IP address versions + * + * The IP version specifies the type of an IP address. + * + * @enum nsapi_version_t */ enum nsapi_version_t { NSAPI_IPv4, /*!< Address is IPv4 */ @@ -56,74 +59,92 @@ enum nsapi_version_t { class NetworkInterface; -/** A general address class composed of the IP address and optional port +/** SocketAddress class + * + * Representation of an IP address and port pair. */ class SocketAddress { public: - /** SocketAddress construction using DNS resolution - * @param iface NetworkInterface to use for DNS resolution - * @param addr Null-terminated hostname that will be resolved + /** Create a SocketAddress from a hostname and port + * + * The hostname may be either a domain name or an IP address. If the + * hostname is an IP address, no network transactions will be performed. + * + * On failure, the IP address and port will be set to zero + * + * @param iface Network stack to use for DNS resolution + * @param host Hostname to resolve * @param port Optional 16-bit port - * @note on failure, IP address and port will be set to zero */ - SocketAddress(NetworkInterface *iface, const char *addr, uint16_t port = 0); + SocketAddress(NetworkInterface *iface, const char *host, uint16_t port = 0); - /** SocketAddress construction - * @param addr Null-terminated IP address + /** Create a SocketAddress from an IP address and port + * + * @param host Null-terminated representation of the IP address * @param port Optional 16-bit port */ SocketAddress(const char *addr = 0, uint16_t port = 0); - /** SocketAddress construction - * @param bytes Bytes to assign to address in big-endian order + /** Create a SocketAddress from a raw IP address and port + * + * @param bytes Raw IP address in big-endian order * @param version IP address version, NSAPI_IPv4 or NSAPI_IPv6 * @param port Optional 16-bit port */ SocketAddress(const void *bytes, nsapi_version_t version, uint16_t port = 0); - /** SocketAddress construction - * @param addr SocketAddress to copy + /** Create a SocketAddress from another SocketAddress + * + * @param address SocketAddress to copy */ SocketAddress(const SocketAddress &addr); /** Set the IP address - * @param addr Null-terminated string representing the IP address + * + * @param addr Null-terminated represention of the IP address */ void set_ip_address(const char *addr); - /** Set the IP address bytes directly - * @param bytes Bytes to assign to address in big-endian order + /** Set the raw IP address + * + * @param bytes Raw IP address in big-endian order * @param version IP address version, NSAPI_IPv4 or NSAPI_IPv6 */ void set_ip_bytes(const void *bytes, nsapi_version_t version); /** Set the port + * * @param port 16-bit port */ void set_port(uint16_t port); /** Get the IP address - * @return The string representation of the IP Address + * + * @return Null-terminated representation of the IP Address */ const char *get_ip_address() const; - /** Get the IP address bytes directly - * @return IP address bytes + /** Get the raw IP address + * + * @return Raw IP address in big-endian order */ const void *get_ip_bytes() const; - /** Get the type of the IP address + /** Get the IP address version + * * @return IP address version, NSAPI_IPv4 or NSAPI_IPv6 */ nsapi_version_t get_ip_version() const; /** Get the port + * * @return The 16-bit port */ uint16_t get_port() const; - /** Determine if address is all zeros - * @return True if address is not zero address + /** Test if address is zero + * + * @return True if address is not zero */ operator bool() const; diff --git a/TCPServer.h b/TCPServer.h index ec2e488316..619056369c 100644 --- a/TCPServer.h +++ b/TCPServer.h @@ -1,4 +1,4 @@ -/* Socket +/* TCPServer * Copyright (c) 2015 ARM Limited * * Licensed under the Apache License, Version 2.0 (the "License"); diff --git a/TCPSocket.h b/TCPSocket.h index f2501e22ee..834b064015 100644 --- a/TCPSocket.h +++ b/TCPSocket.h @@ -1,4 +1,4 @@ -/* Socket +/* TCPSocket * Copyright (c) 2015 ARM Limited * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -53,7 +53,7 @@ public: * Initiates a connection to a remote server specified by either * a domain name or an IP address and a port. * - * @param host Host name of the remote host + * @param host Hostname of the remote host * @param port Port of the remote host * @return 0 on success, negative error code on failure */ diff --git a/UDPSocket.h b/UDPSocket.h index 23c91c92f5..74f8c4a340 100644 --- a/UDPSocket.h +++ b/UDPSocket.h @@ -1,4 +1,4 @@ -/* Socket +/* UDPSocket * Copyright (c) 2015 ARM Limited * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -58,7 +58,7 @@ public: * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned * immediately. * - * @param host Host name of the remote host + * @param host Hostname of the remote host * @param port Port of the remote host * @param data Buffer of data to send to the host * @param size Size of the buffer in bytes diff --git a/WiFiInterface.h b/WiFiInterface.h index 21fa397a66..1a9e267e0b 100644 --- a/WiFiInterface.h +++ b/WiFiInterface.h @@ -1,4 +1,4 @@ -/* Socket +/* WiFiInterface * Copyright (c) 2015 ARM Limited * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -19,7 +19,12 @@ #include "NetworkInterface.h" -/** Enum for WiFi encryption types +/** Enum of WiFi encryption types + * + * The security type specifies a particular security to use when + * connected to a WiFi network + * + * @enum nsapi_protocol_t */ enum nsapi_security_t { NSAPI_SECURITY_NONE = 0, /*!< open access point */ @@ -29,21 +34,27 @@ enum nsapi_security_t { }; /** WiFiInterface class + * * Common interface that is shared between WiFi devices */ class WiFiInterface : public NetworkInterface { public: /** Start the interface + * + * Attempts to connect to a WiFi network. If passphrase is invalid, + * NSAPI_ERROR_AUTH_ERROR is returned. + * * @param ssid Name of the network to connect to * @param pass Security passphrase to connect to the network * @param security Type of encryption for connection - * @return 0 on success, negative on failure + * @return 0 on success, negative error code on failure */ virtual int connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE) = 0; /** Stop the interface - * @return 0 on success, negative on failure + * + * @return 0 on success, negative error code on failure */ virtual int disconnect() = 0; };