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@115:950b19eb0f02, 2016-04-20 (annotated)
- Committer:
- Christopher Haster
- Date:
- Wed Apr 20 19:05:03 2016 -0500
- Revision:
- 115:950b19eb0f02
- Parent:
- 109:5d8bd5752386
- Child:
- 118:96627c4b83d5
Consolidate set_timeout/set_blocking behaviour to avoid ambiguity when both are used and match python behaviour
Who changed what in which revision?
User | Revision | Line number | New 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 |
25:ed7b2a52e8ac | 172 | |
Christopher Haster |
105:2fd212f8da61 | 173 | NetworkStack *_iface; |
Christopher Haster |
89:b1d417383c0d | 174 | void *_socket; |
Christopher Haster |
115:950b19eb0f02 | 175 | int _timeout; |
Christopher Haster |
92:dd5f19874adf | 176 | FunctionPointer _callback; |
Christopher Haster |
25:ed7b2a52e8ac | 177 | }; |
Christopher Haster |
25:ed7b2a52e8ac | 178 | |
Christopher Haster |
25:ed7b2a52e8ac | 179 | #endif |