NetworkSocketAPI / NetworkSocketAPI

Base class for IP Based Networking Libraries

Dependencies:   DnsQuery

Dependents:   TempTower BSDInterfaceTests HelloBSDInterface ESP8266InterfaceTests ... more

For a complete getting started guide see the wiki...

Network Socket API

The Network Socket API provides a common interface for using sockets on network devices. The API provides a simple class-based interface that should be familiar to users experienced with other socket APIs. Additionally, the API provides a simple interface for implementing network devices, making it easy to connect hardware agnostic programs to new devices.

Network Interfaces

The NetworkInterface provides an abstract class for network devices that support sockets. Devices should provide a DeviceInterface class that inherits this interface and adds implementation specific methods for using the device. A NetworkInterface must be provided to a Socket constructor to open a socket on the interface. Currently two subclasses are defined for common devices, EthernetInterface and WiFiInterface.

Sockets

The Socket class is used for managing network sockets. Once opened, the socket provides a pipe through which data can sent and recieved to a specific endpoint. The socket class can be instantiated as either a TCPSocket or a UDPSocket which defines the protocol used for the connection.

Diff: SocketAddress.h

Revision:
104:d28d8b508e7c
Parent:
94:644df37bb05b
Child:
105:2fd212f8da61
--- a/SocketAddress.h	Tue Apr 19 18:26:12 2016 -0500
+++ b/SocketAddress.h	Tue Apr 19 18:26:21 2016 -0500
@@ -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 @@
 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;