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.

Socket.h@103:37decbcb1108, 2016-04-19 (annotated)

Committer:
Christopher Haster
Date:
Tue Apr 19 18:26:12 2016 -0500
Revision:
103:37decbcb1108
Parent:
99:f51358e506c1
Child:
105:2fd212f8da61
Revisited documentation for Socket API

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 89:b1d417383c0d 1 /* Socket
Christopher Haster 89:b1d417383c0d 2 * Copyright (c) 2015 ARM Limited
Christopher Haster 89:b1d417383c0d 3 *
Christopher Haster 89:b1d417383c0d 4 * Licensed under the Apache License, Version 2.0 (the "License");
Christopher Haster 89:b1d417383c0d 5 * you may not use this file except in compliance with the License.
Christopher Haster 89:b1d417383c0d 6 * You may obtain a copy of the License at
Christopher Haster 89:b1d417383c0d 7 *
Christopher Haster 89:b1d417383c0d 8 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 89:b1d417383c0d 9 *
Christopher Haster 89:b1d417383c0d 10 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 89:b1d417383c0d 11 * distributed under the License is distributed on an "AS IS" BASIS,
Christopher Haster 89:b1d417383c0d 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 89:b1d417383c0d 13 * See the License for the specific language governing permissions and
Christopher Haster 89:b1d417383c0d 14 * limitations under the License.
Christopher Haster 89:b1d417383c0d 15 */
Christopher Haster 89:b1d417383c0d 16
Christopher Haster 89:b1d417383c0d 17 #ifndef SOCKET_H
Christopher Haster 89:b1d417383c0d 18 #define SOCKET_H
Christopher Haster 89:b1d417383c0d 19
Christopher Haster 89:b1d417383c0d 20 #include "SocketAddress.h"
Christopher Haster 89:b1d417383c0d 21 #include "NetworkInterface.h"
Christopher Haster 89:b1d417383c0d 22
Christopher Haster 89:b1d417383c0d 23 /** Abstract socket class
Christopher Haster 89:b1d417383c0d 24 */
Christopher Haster 89:b1d417383c0d 25 class Socket {
Christopher Haster 89:b1d417383c0d 26 public:
Christopher Haster 103:37decbcb1108 27 /** Destroy a socket
Christopher Haster 103:37decbcb1108 28 *
Christopher Haster 103:37decbcb1108 29 * Closes socket if the socket is still open
Christopher Haster 89:b1d417383c0d 30 */
Christopher Haster 89:b1d417383c0d 31 virtual ~Socket();
Christopher Haster 90:0a988e4abb72 32
Christopher Haster 103:37decbcb1108 33 /** Opens a socket
Christopher Haster 103:37decbcb1108 34 *
Christopher Haster 103:37decbcb1108 35 * Creates a network socket on the specified network stack.
Christopher Haster 103:37decbcb1108 36 * Not needed if stack is passed to the socket's constructor.
Christopher Haster 103:37decbcb1108 37 *
Christopher Haster 103:37decbcb1108 38 * @param iface Network stack as target for socket
Christopher Haster 103:37decbcb1108 39 * @return 0 on success, negative error code on failure
Christopher Haster 90:0a988e4abb72 40 */
Christopher Haster 90:0a988e4abb72 41 virtual int open(NetworkInterface *iface) = 0;
Christopher Haster 89:b1d417383c0d 42
Christopher Haster 99:f51358e506c1 43 /** Close the socket
Christopher Haster 103:37decbcb1108 44 *
Christopher Haster 103:37decbcb1108 45 * Closes any open connection and deallocates any memory associated
Christopher Haster 103:37decbcb1108 46 * with the socket. Called from destructor if socket is not closed.
Christopher Haster 103:37decbcb1108 47 *
Christopher Haster 103:37decbcb1108 48 * @return 0 on success, negative error code on failure
Christopher Haster 99:f51358e506c1 49 */
Christopher Haster 99:f51358e506c1 50 int close();
Christopher Haster 99:f51358e506c1 51
Christopher Haster 103:37decbcb1108 52 /** Bind a specific address to a socket
Christopher Haster 103:37decbcb1108 53 *
Christopher Haster 103:37decbcb1108 54 * Binding a socket specifies the address and port on which to recieve
Christopher Haster 103:37decbcb1108 55 * data.
Christopher Haster 103:37decbcb1108 56 *
Christopher Haster 103:37decbcb1108 57 * @param port Local port to bind
Christopher Haster 103:37decbcb1108 58 * @return 0 on success, negative error code on failure.
Christopher Haster 98:0f614f1d0398 59 */
Christopher Haster 98:0f614f1d0398 60 int bind(uint16_t port);
Christopher Haster 98:0f614f1d0398 61
Christopher Haster 103:37decbcb1108 62 /** Bind a specific address to a socket
Christopher Haster 103:37decbcb1108 63 *
Christopher Haster 103:37decbcb1108 64 * Binding a socket specifies the address and port on which to recieve
Christopher Haster 103:37decbcb1108 65 * data. If the IP address is zeroed, only the port is bound.
Christopher Haster 103:37decbcb1108 66 *
Christopher Haster 103:37decbcb1108 67 * @param address Null-terminated local address to bind
Christopher Haster 103:37decbcb1108 68 * @param port Local port to bind
Christopher Haster 103:37decbcb1108 69 * @return 0 on success, negative error code on failure.
Christopher Haster 98:0f614f1d0398 70 */
Christopher Haster 98:0f614f1d0398 71 int bind(const char *address, uint16_t port);
Christopher Haster 98:0f614f1d0398 72
Christopher Haster 103:37decbcb1108 73 /** Bind a specific address to a socket
Christopher Haster 103:37decbcb1108 74 *
Christopher Haster 103:37decbcb1108 75 * Binding a socket specifies the address and port on which to recieve
Christopher Haster 103:37decbcb1108 76 * data. If the IP address is zeroed, only the port is bound.
Christopher Haster 103:37decbcb1108 77 *
Christopher Haster 103:37decbcb1108 78 * @param address Local address to bind
Christopher Haster 103:37decbcb1108 79 * @return 0 on success, negative error code on failure.
Christopher Haster 98:0f614f1d0398 80 */
Christopher Haster 98:0f614f1d0398 81 int bind(const SocketAddress &address);
Christopher Haster 98:0f614f1d0398 82
Christopher Haster 89:b1d417383c0d 83 /** Set blocking or non-blocking mode of the socket
Christopher Haster 103:37decbcb1108 84 *
Christopher Haster 103:37decbcb1108 85 * Initially all sockets are in blocking mode. In non-blocking mode
Christopher Haster 103:37decbcb1108 86 * blocking operations such as send/recv/accept return
Christopher Haster 103:37decbcb1108 87 * NSAPI_ERROR_WOULD_BLOCK if they can not continue.
Christopher Haster 103:37decbcb1108 88 *
Christopher Haster 103:37decbcb1108 89 * @param blocking True for blocking mode, false for non-blocking mode.
Christopher Haster 89:b1d417383c0d 90 */
Christopher Haster 89:b1d417383c0d 91 void set_blocking(bool blocking);
Christopher Haster 89:b1d417383c0d 92
Christopher Haster 103:37decbcb1108 93 /** Set timeout on blocking socket operations
Christopher Haster 103:37decbcb1108 94 *
Christopher Haster 103:37decbcb1108 95 * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
Christopher Haster 103:37decbcb1108 96 * is returned if a blocking operation takes longer than the specified
Christopher Haster 103:37decbcb1108 97 * timeout. A timeout of 0 removes a timeout from the socket.
Christopher Haster 103:37decbcb1108 98 *
Christopher Haster 103:37decbcb1108 99 * @param timeout Timeout in milliseconds
Christopher Haster 89:b1d417383c0d 100 */
Christopher Haster 89:b1d417383c0d 101 void set_timeout(unsigned int timeout);
Christopher Haster 89:b1d417383c0d 102
Christopher Haster 103:37decbcb1108 103 /* Set stack-specific socket options
Christopher Haster 103:37decbcb1108 104 *
Christopher Haster 103:37decbcb1108 105 * The setsockopt allow an application to pass stack-specific hints
Christopher Haster 103:37decbcb1108 106 * to the underlying stack. For unsupported options,
Christopher Haster 103:37decbcb1108 107 * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
Christopher Haster 103:37decbcb1108 108 *
Christopher Haster 103:37decbcb1108 109 * @param level Stack-specific protocol level
Christopher Haster 103:37decbcb1108 110 * @param optname Stack-specific option identifier
Christopher Haster 89:b1d417383c0d 111 * @param optval Option value
Christopher Haster 89:b1d417383c0d 112 * @param optlen Length of the option value
Christopher Haster 103:37decbcb1108 113 * @return 0 on success, negative error code on failure
Christopher Haster 99:f51358e506c1 114 */
Christopher Haster 99:f51358e506c1 115 int setsockopt(int level, int optname, const void *optval, unsigned optlen);
Christopher Haster 99:f51358e506c1 116
Christopher Haster 103:37decbcb1108 117 /* Get stack-specific socket options
Christopher Haster 103:37decbcb1108 118 *
Christopher Haster 103:37decbcb1108 119 * The getstackopt allow an application to retrieve stack-specific hints
Christopher Haster 103:37decbcb1108 120 * from the underlying stack. For unsupported options,
Christopher Haster 103:37decbcb1108 121 * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
Christopher Haster 103:37decbcb1108 122 *
Christopher Haster 103:37decbcb1108 123 * @param level Stack-specific protocol level
Christopher Haster 103:37decbcb1108 124 * @param optname Stack-specific option identifier
Christopher Haster 103:37decbcb1108 125 * @param optval Destination for option value
Christopher Haster 89:b1d417383c0d 126 * @param optlen Length of the option value
Christopher Haster 103:37decbcb1108 127 * @return 0 on success, negative error code on failure
Christopher Haster 99:f51358e506c1 128 */
Christopher Haster 99:f51358e506c1 129 int getsockopt(int level, int optname, void *optval, unsigned *optlen);
Christopher Haster 89:b1d417383c0d 130
Christopher Haster 92:dd5f19874adf 131 /** Register a callback on state change of the socket
Christopher Haster 103:37decbcb1108 132 *
Christopher Haster 103:37decbcb1108 133 * The specified callback will be called on state changes such as when
Christopher Haster 103:37decbcb1108 134 * the socket can recv/send/accept successfully and on when an error
Christopher Haster 103:37decbcb1108 135 * occurs. The callback may also be called spuriously without reason.
Christopher Haster 103:37decbcb1108 136 *
Christopher Haster 103:37decbcb1108 137 * The callback may be called in an interrupt context and should not
Christopher Haster 103:37decbcb1108 138 * perform expensive operations such as recv/send calls.
Christopher Haster 103:37decbcb1108 139 *
Christopher Haster 92:dd5f19874adf 140 * @param callback Function to call on state change
Christopher Haster 92:dd5f19874adf 141 */
Christopher Haster 92:dd5f19874adf 142 void attach(FunctionPointer callback);
Christopher Haster 92:dd5f19874adf 143
Christopher Haster 103:37decbcb1108 144 /** Register a callback on state change of the socket
Christopher Haster 103:37decbcb1108 145 *
Christopher Haster 103:37decbcb1108 146 * The specified callback will be called on state changes such as when
Christopher Haster 103:37decbcb1108 147 * the socket can recv/send/accept successfully and on when an error
Christopher Haster 103:37decbcb1108 148 * occurs. The callback may also be called spuriously without reason.
Christopher Haster 103:37decbcb1108 149 *
Christopher Haster 103:37decbcb1108 150 * The callback may be called in an interrupt context and should not
Christopher Haster 103:37decbcb1108 151 * perform expensive operations such as recv/send calls.
Christopher Haster 103:37decbcb1108 152 *
Christopher Haster 103:37decbcb1108 153 * @param tptr Pointer to object to call method on
Christopher Haster 103:37decbcb1108 154 * @param mptr Method to call on state change
Christopher Haster 103:37decbcb1108 155 */
Christopher Haster 92:dd5f19874adf 156 template <typename T, typename M>
Christopher Haster 92:dd5f19874adf 157 void attach(T *tptr, M mptr) {
Christopher Haster 92:dd5f19874adf 158 attach(FunctionPointer(tptr, mptr));
Christopher Haster 92:dd5f19874adf 159 }
Christopher Haster 92:dd5f19874adf 160
Christopher Haster 89:b1d417383c0d 161 protected:
Christopher Haster 90:0a988e4abb72 162 Socket();
Christopher Haster 90:0a988e4abb72 163 int open(NetworkInterface *iface, nsapi_protocol_t proto);
Christopher Haster 89:b1d417383c0d 164
Christopher Haster 89:b1d417383c0d 165 static void thunk(void *);
Christopher Haster 89:b1d417383c0d 166
Christopher Haster 89:b1d417383c0d 167 NetworkInterface *_iface;
Christopher Haster 89:b1d417383c0d 168 void *_socket;
Christopher Haster 89:b1d417383c0d 169 bool _blocking;
Christopher Haster 89:b1d417383c0d 170 unsigned _timeout;
Christopher Haster 92:dd5f19874adf 171 FunctionPointer _callback;
Christopher Haster 89:b1d417383c0d 172 };
Christopher Haster 89:b1d417383c0d 173
Christopher Haster 89:b1d417383c0d 174 #endif