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@125:ea3a618e0818, 2016-05-25 (annotated)

Committer:
dkato
Date:
Wed May 25 02:45:51 2016 +0000
Revision:
125:ea3a618e0818
Parent:
118:96627c4b83d5 
Fix the path of DnsQuery.lib

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 25:ed7b2a52e8ac 1 /* Socket
Christopher Haster 25:ed7b2a52e8ac 2 * Copyright (c) 2015 ARM Limited
Christopher Haster 25:ed7b2a52e8ac 3 *
Christopher Haster 25:ed7b2a52e8ac 4 * Licensed under the Apache License, Version 2.0 (the "License");
Christopher Haster 25:ed7b2a52e8ac 5 * you may not use this file except in compliance with the License.
Christopher Haster 25:ed7b2a52e8ac 6 * You may obtain a copy of the License at
Christopher Haster 25:ed7b2a52e8ac 7 *
Christopher Haster 25:ed7b2a52e8ac 8 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 25:ed7b2a52e8ac 9 *
Christopher Haster 25:ed7b2a52e8ac 10 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 25:ed7b2a52e8ac 11 * distributed under the License is distributed on an "AS IS" BASIS,
Christopher Haster 25:ed7b2a52e8ac 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 25:ed7b2a52e8ac 13 * See the License for the specific language governing permissions and
Christopher Haster 25:ed7b2a52e8ac 14 * limitations under the License.
Christopher Haster 25:ed7b2a52e8ac 15 */
Christopher Haster 25:ed7b2a52e8ac 16
Christopher Haster 25:ed7b2a52e8ac 17 #ifndef SOCKET_H
Christopher Haster 25:ed7b2a52e8ac 18 #define SOCKET_H
Christopher Haster 25:ed7b2a52e8ac 19
Christopher Haster 89:b1d417383c0d 20 #include "SocketAddress.h"
Christopher Haster 105:2fd212f8da61 21 #include "NetworkStack.h"
Christopher Haster 25:ed7b2a52e8ac 22
Christopher Haster 25:ed7b2a52e8ac 23 /** Abstract socket class
Christopher Haster 25:ed7b2a52e8ac 24 */
Christopher Haster 89:b1d417383c0d 25 class Socket {
Christopher Haster 25:ed7b2a52e8ac 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 53:26b5f1c69822 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 25:ed7b2a52e8ac 40 */
Christopher Haster 105:2fd212f8da61 41 virtual int open(NetworkStack *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 32:2c5fc105fc50 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 32:2c5fc105fc50 70 */
Christopher Haster 98:0f614f1d0398 71 int bind(const char *address, uint16_t port);
Christopher Haster 32:2c5fc105fc50 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 115:950b19eb0f02 89 * set_blocking(false) is equivalent to set_timeout(-1)
Christopher Haster 115:950b19eb0f02 90 * set_blocking(true) is equivalent to set_timeout(0)
Christopher Haster 115:950b19eb0f02 91 *
Christopher Haster 115:950b19eb0f02 92 * @param blocking true for blocking mode, false for non-blocking mode.
Christopher Haster 25:ed7b2a52e8ac 93 */
Christopher Haster 89:b1d417383c0d 94 void set_blocking(bool blocking);
Christopher Haster 89:b1d417383c0d 95
Christopher Haster 103:37decbcb1108 96 /** Set timeout on blocking socket operations
Christopher Haster 103:37decbcb1108 97 *
Christopher Haster 103:37decbcb1108 98 * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
Christopher Haster 103:37decbcb1108 99 * is returned if a blocking operation takes longer than the specified
Christopher Haster 115:950b19eb0f02 100 * timeout. A timeout of -1 removes the timeout from the socket.
Christopher Haster 115:950b19eb0f02 101 *
Christopher Haster 115:950b19eb0f02 102 * set_timeout(-1) is equivalent to set_blocking(false)
Christopher Haster 115:950b19eb0f02 103 * set_timeout(0) is equivalent to set_blocking(true)
Christopher Haster 103:37decbcb1108 104 *
Christopher Haster 103:37decbcb1108 105 * @param timeout Timeout in milliseconds
Christopher Haster 89:b1d417383c0d 106 */
Christopher Haster 115:950b19eb0f02 107 void set_timeout(int timeout);
Christopher Haster 25:ed7b2a52e8ac 108
Christopher Haster 103:37decbcb1108 109 /* Set stack-specific socket options
Christopher Haster 103:37decbcb1108 110 *
Christopher Haster 103:37decbcb1108 111 * The setsockopt allow an application to pass stack-specific hints
Christopher Haster 103:37decbcb1108 112 * to the underlying stack. For unsupported options,
Christopher Haster 103:37decbcb1108 113 * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
Christopher Haster 103:37decbcb1108 114 *
Christopher Haster 103:37decbcb1108 115 * @param level Stack-specific protocol level
Christopher Haster 103:37decbcb1108 116 * @param optname Stack-specific option identifier
Christopher Haster 89:b1d417383c0d 117 * @param optval Option value
Christopher Haster 89:b1d417383c0d 118 * @param optlen Length of the option value
Christopher Haster 103:37decbcb1108 119 * @return 0 on success, negative error code on failure
Christopher Haster 99:f51358e506c1 120 */
Christopher Haster 99:f51358e506c1 121 int setsockopt(int level, int optname, const void *optval, unsigned optlen);
Christopher Haster 25:ed7b2a52e8ac 122
Christopher Haster 103:37decbcb1108 123 /* Get stack-specific socket options
Christopher Haster 103:37decbcb1108 124 *
Christopher Haster 103:37decbcb1108 125 * The getstackopt allow an application to retrieve stack-specific hints
Christopher Haster 103:37decbcb1108 126 * from the underlying stack. For unsupported options,
Christopher Haster 103:37decbcb1108 127 * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
Christopher Haster 103:37decbcb1108 128 *
Christopher Haster 103:37decbcb1108 129 * @param level Stack-specific protocol level
Christopher Haster 103:37decbcb1108 130 * @param optname Stack-specific option identifier
Christopher Haster 103:37decbcb1108 131 * @param optval Destination for option value
Christopher Haster 89:b1d417383c0d 132 * @param optlen Length of the option value
Christopher Haster 103:37decbcb1108 133 * @return 0 on success, negative error code on failure
Christopher Haster 99:f51358e506c1 134 */
Christopher Haster 99:f51358e506c1 135 int getsockopt(int level, int optname, void *optval, unsigned *optlen);
Christopher Haster 58:1caa187fa5af 136
Christopher Haster 92:dd5f19874adf 137 /** Register a callback on state change of the socket
Christopher Haster 103:37decbcb1108 138 *
Christopher Haster 103:37decbcb1108 139 * The specified callback will be called on state changes such as when
Christopher Haster 103:37decbcb1108 140 * the socket can recv/send/accept successfully and on when an error
Christopher Haster 103:37decbcb1108 141 * occurs. The callback may also be called spuriously without reason.
Christopher Haster 103:37decbcb1108 142 *
Christopher Haster 103:37decbcb1108 143 * The callback may be called in an interrupt context and should not
Christopher Haster 103:37decbcb1108 144 * perform expensive operations such as recv/send calls.
Christopher Haster 103:37decbcb1108 145 *
Christopher Haster 92:dd5f19874adf 146 * @param callback Function to call on state change
Christopher Haster 58:1caa187fa5af 147 */
Christopher Haster 92:dd5f19874adf 148 void attach(FunctionPointer callback);
Christopher Haster 58:1caa187fa5af 149
Christopher Haster 103:37decbcb1108 150 /** Register a callback on state change of the socket
Christopher Haster 103:37decbcb1108 151 *
Christopher Haster 103:37decbcb1108 152 * The specified callback will be called on state changes such as when
Christopher Haster 103:37decbcb1108 153 * the socket can recv/send/accept successfully and on when an error
Christopher Haster 103:37decbcb1108 154 * occurs. The callback may also be called spuriously without reason.
Christopher Haster 103:37decbcb1108 155 *
Christopher Haster 103:37decbcb1108 156 * The callback may be called in an interrupt context and should not
Christopher Haster 103:37decbcb1108 157 * perform expensive operations such as recv/send calls.
Christopher Haster 103:37decbcb1108 158 *
Christopher Haster 103:37decbcb1108 159 * @param tptr Pointer to object to call method on
Christopher Haster 103:37decbcb1108 160 * @param mptr Method to call on state change
Christopher Haster 58:1caa187fa5af 161 */
Christopher Haster 92:dd5f19874adf 162 template <typename T, typename M>
Christopher Haster 92:dd5f19874adf 163 void attach(T *tptr, M mptr) {
Christopher Haster 92:dd5f19874adf 164 attach(FunctionPointer(tptr, mptr));
Christopher Haster 92:dd5f19874adf 165 }
Christopher Haster 58:1caa187fa5af 166
Christopher Haster 25:ed7b2a52e8ac 167 protected:
Christopher Haster 90:0a988e4abb72 168 Socket();
Christopher Haster 105:2fd212f8da61 169 int open(NetworkStack *iface, nsapi_protocol_t proto);
Christopher Haster 89:b1d417383c0d 170
Christopher Haster 89:b1d417383c0d 171 static void thunk(void *);
Christopher Haster 118:96627c4b83d5 172 static void wakeup();
Christopher Haster 25:ed7b2a52e8ac 173
Christopher Haster 105:2fd212f8da61 174 NetworkStack *_iface;
Christopher Haster 89:b1d417383c0d 175 void *_socket;
Christopher Haster 115:950b19eb0f02 176 int _timeout;
Christopher Haster 92:dd5f19874adf 177 FunctionPointer _callback;
Christopher Haster 25:ed7b2a52e8ac 178 };
Christopher Haster 25:ed7b2a52e8ac 179
Christopher Haster 25:ed7b2a52e8ac 180 #endif