NetworkSocketAPI


NetworkSocketAPI is a simple yet powerful network and socket interface

Getting Started

Table of Contents

  1. Network Socket API
  2. Network Interface
  3. Sockets
  4. Errors
  5. Example

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 Interface

The NetworkStack provides an abstract class for network devices that support sockets. Devices must inherit and implement the NetworkStack class and a network interface as well as adding implementation specific methods for using the device. A NetworkStack must be provided to a Socket constructor to open a socket on the interface. Currently defined network interfaces include:


Sockets

The Socket class is used for managing network sockets. Once opened, the socket provides a pipe through which data can sent and received 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.


Errors

The convention for the NetworkSocketAPI is to have functions that may fail and return a signed integer. To indicate success, the function should return a non-negative integer which may also contain the size of a transaction. To indicate failure the function should return a negative integer which should be one of the following error codes from the nsapi_error_t enum:

/** Enum of standardized error codes 
 *
 *  Valid error codes have negative values and may
 *  be returned by any network operation.
 *
 *  @enum nsapi_error_t
 */
enum nsapi_error_t {
    NSAPI_ERROR_WOULD_BLOCK   = -3001,     /*!< no data is not available but call is non-blocking */
    NSAPI_ERROR_UNSUPPORTED   = -3002,     /*!< unsupported configuration */
    NSAPI_ERROR_NO_CONNECTION = -3003,     /*!< not connected to a network */
    NSAPI_ERROR_NO_SOCKET     = -3004,     /*!< socket not available for use */
    NSAPI_ERROR_NO_ADDRESS    = -3005,     /*!< IP address is not known */
    NSAPI_ERROR_NO_MEMORY     = -3006,     /*!< memory resource not available */
    NSAPI_ERROR_DNS_FAILURE   = -3007,     /*!< DNS failed to complete successfully */
    NSAPI_ERROR_DHCP_FAILURE  = -3008,     /*!< DHCP failed to complete successfully */
    NSAPI_ERROR_AUTH_FAILURE  = -3009,     /*!< connection to access point failed */
    NSAPI_ERROR_DEVICE_ERROR  = -3010,     /*!< failure interfacing with the network processor */
};


Example

Import program
HelloLWIPInterface - main.cpp

00001 /* NetworkSocketAPI Example Program
00002  * Copyright (c) 2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #include "mbed.h"
00018 #include "LWIPInterface.h"
00019 #include "TCPSocket.h"
00020 
00021 LWIPInterface eth;
00022 
00023 DigitalOut led(LED_GREEN);
00024 void blink()
00025 {
00026     led = !led;
00027 }
00028 
00029 int main()
00030 {
00031     Ticker blinky;
00032     blinky.attach(blink, 0.4f);
00033 
00034     printf("NetworkSocketAPI Example\r\n");
00035 
00036     eth.connect();
00037     const char *ip = eth.get_ip_address();
00038     const char *mac = eth.get_mac_address();
00039     printf("IP address is: %s\r\n", ip ? ip : "No IP");
00040     printf("MAC address is: %s\r\n", mac ? mac : "No MAC");
00041     
00042     SocketAddress addr(&eth, "mbed.org");
00043     printf("mbed.org resolved to: %s\r\n", addr.get_ip_address());
00044 
00045     TCPSocket socket(&eth);
00046     socket.connect("4.ifcfg.me", 23);
00047 
00048     char buffer[64];
00049     int count = socket.recv(buffer, sizeof buffer);
00050     printf("public IP address is: %.15s\r\n", &buffer[15]);
00051     
00052     socket.close();
00053     eth.disconnect();
00054 
00055     printf("Done\r\n");
00056 }
All wikipages