ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Revised documentation for Interface classes

pull/2216/head^2
Christopher Haster 2016-04-19 17:51:51 -05:00
parent aa2357a836
commit d36a0b6b88
9 changed files with 134 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
CellularInterface.h Normal file
View File

@ -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

11
EthernetInterface.h
View File

@ -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;
};

7
MeshInterface.h
View File

@ -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;

17
NetworkInterface.h
View File

@ -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 hostname to an IP address
*
* The host name may be either a domain name or an IP address.
* 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);

69
SocketAddress.h
View File

@ -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;

2
TCPServer.h
View File

@ -1,4 +1,4 @@
/* Socket
/* TCPServer
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");

2
TCPSocket.h
View File

@ -1,4 +1,4 @@
/* Socket
/* TCPSocket
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");

2
UDPSocket.h
View File

@ -1,4 +1,4 @@
/* Socket
/* UDPSocket
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");

19
WiFiInterface.h
View File

@ -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;
};