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.
NetworkStack.h@112:e0cbb3e43c20, 2016-04-20 (annotated)
- Committer:
- Christopher Haster
- Date:
- Wed Apr 20 03:19:26 2016 -0500
- Revision:
- 112:e0cbb3e43c20
- Parent:
- 105:2fd212f8da61
- Child:
- 114:964eba6394bc
Add standardized stack options
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| Christopher Haster |
105:2fd212f8da61 | 1 | /* NetworkStack |
| Christopher Haster |
105:2fd212f8da61 | 2 | * Copyright (c) 2015 ARM Limited |
| Christopher Haster |
105:2fd212f8da61 | 3 | * |
| Christopher Haster |
105:2fd212f8da61 | 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| Christopher Haster |
105:2fd212f8da61 | 5 | * you may not use this file except in compliance with the License. |
| Christopher Haster |
105:2fd212f8da61 | 6 | * You may obtain a copy of the License at |
| Christopher Haster |
105:2fd212f8da61 | 7 | * |
| Christopher Haster |
105:2fd212f8da61 | 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| Christopher Haster |
105:2fd212f8da61 | 9 | * |
| Christopher Haster |
105:2fd212f8da61 | 10 | * Unless required by applicable law or agreed to in writing, software |
| Christopher Haster |
105:2fd212f8da61 | 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| Christopher Haster |
105:2fd212f8da61 | 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| Christopher Haster |
105:2fd212f8da61 | 13 | * See the License for the specific language governing permissions and |
| Christopher Haster |
105:2fd212f8da61 | 14 | * limitations under the License. |
| Christopher Haster |
105:2fd212f8da61 | 15 | */ |
| Christopher Haster |
105:2fd212f8da61 | 16 | |
| Christopher Haster |
105:2fd212f8da61 | 17 | #ifndef NETWORK_INTERFACE_H |
| Christopher Haster |
105:2fd212f8da61 | 18 | #define NETWORK_INTERFACE_H |
| Christopher Haster |
105:2fd212f8da61 | 19 | |
| Christopher Haster |
105:2fd212f8da61 | 20 | #include "mbed.h" |
| Christopher Haster |
105:2fd212f8da61 | 21 | #include "SocketAddress.h" |
| Christopher Haster |
105:2fd212f8da61 | 22 | |
| Christopher Haster |
105:2fd212f8da61 | 23 | |
| Christopher Haster |
105:2fd212f8da61 | 24 | /** Enum of standardized error codes |
| Christopher Haster |
105:2fd212f8da61 | 25 | * |
| Christopher Haster |
105:2fd212f8da61 | 26 | * Valid error codes have negative values and may |
| Christopher Haster |
105:2fd212f8da61 | 27 | * be returned by any network operation. |
| Christopher Haster |
105:2fd212f8da61 | 28 | * |
| Christopher Haster |
105:2fd212f8da61 | 29 | * @enum nsapi_error_t |
| Christopher Haster |
105:2fd212f8da61 | 30 | */ |
| Christopher Haster |
105:2fd212f8da61 | 31 | enum nsapi_error_t { |
| Christopher Haster |
105:2fd212f8da61 | 32 | NSAPI_ERROR_WOULD_BLOCK = -3001, /*!< no data is not available but call is non-blocking */ |
| Christopher Haster |
105:2fd212f8da61 | 33 | NSAPI_ERROR_UNSUPPORTED = -3002, /*!< unsupported configuration */ |
| Christopher Haster |
105:2fd212f8da61 | 34 | NSAPI_ERROR_NO_CONNECTION = -3003, /*!< not connected to a network */ |
| Christopher Haster |
105:2fd212f8da61 | 35 | NSAPI_ERROR_NO_SOCKET = -3004, /*!< socket not available for use */ |
| Christopher Haster |
105:2fd212f8da61 | 36 | NSAPI_ERROR_NO_ADDRESS = -3005, /*!< IP address is not known */ |
| Christopher Haster |
105:2fd212f8da61 | 37 | NSAPI_ERROR_NO_MEMORY = -3006, /*!< memory resource not available */ |
| Christopher Haster |
105:2fd212f8da61 | 38 | NSAPI_ERROR_DNS_FAILURE = -3007, /*!< DNS failed to complete successfully */ |
| Christopher Haster |
105:2fd212f8da61 | 39 | NSAPI_ERROR_DHCP_FAILURE = -3008, /*!< DHCP failed to complete successfully */ |
| Christopher Haster |
105:2fd212f8da61 | 40 | NSAPI_ERROR_AUTH_FAILURE = -3009, /*!< connection to access point faield */ |
| Christopher Haster |
105:2fd212f8da61 | 41 | NSAPI_ERROR_DEVICE_ERROR = -3010, /*!< failure interfacing with the network procesor */ |
| Christopher Haster |
105:2fd212f8da61 | 42 | }; |
| Christopher Haster |
105:2fd212f8da61 | 43 | |
| Christopher Haster |
105:2fd212f8da61 | 44 | /** Enum of socket protocols |
| Christopher Haster |
105:2fd212f8da61 | 45 | * |
| Christopher Haster |
105:2fd212f8da61 | 46 | * The socket protocol specifies a particular protocol to |
| Christopher Haster |
105:2fd212f8da61 | 47 | * be used with a newly created socket. |
| Christopher Haster |
105:2fd212f8da61 | 48 | * |
| Christopher Haster |
105:2fd212f8da61 | 49 | * @enum nsapi_protocol_t |
| Christopher Haster |
105:2fd212f8da61 | 50 | */ |
| Christopher Haster |
105:2fd212f8da61 | 51 | enum nsapi_protocol_t { |
| Christopher Haster |
105:2fd212f8da61 | 52 | NSAPI_TCP, /*!< Socket is of TCP type */ |
| Christopher Haster |
105:2fd212f8da61 | 53 | NSAPI_UDP, /*!< Socket is of UDP type */ |
| Christopher Haster |
105:2fd212f8da61 | 54 | }; |
| Christopher Haster |
105:2fd212f8da61 | 55 | |
| Christopher Haster |
112:e0cbb3e43c20 | 56 | /* Enum of standardized stack option levels |
| Christopher Haster |
112:e0cbb3e43c20 | 57 | * |
| Christopher Haster |
112:e0cbb3e43c20 | 58 | * @enum nsapi_level_t |
| Christopher Haster |
112:e0cbb3e43c20 | 59 | */ |
| Christopher Haster |
112:e0cbb3e43c20 | 60 | enum nsapi_level_t { |
| Christopher Haster |
112:e0cbb3e43c20 | 61 | NSAPI_STACK, /*!< Stack option level */ |
| Christopher Haster |
112:e0cbb3e43c20 | 62 | NSAPI_SOCKET, /*!< Socket option level */ |
| Christopher Haster |
112:e0cbb3e43c20 | 63 | }; |
| Christopher Haster |
112:e0cbb3e43c20 | 64 | |
| Christopher Haster |
112:e0cbb3e43c20 | 65 | /* Enum of standardized stack options |
| Christopher Haster |
112:e0cbb3e43c20 | 66 | * |
| Christopher Haster |
112:e0cbb3e43c20 | 67 | * These options may not be supported on all stacks, in which |
| Christopher Haster |
112:e0cbb3e43c20 | 68 | * case NSAPI_ERROR_UNSUPPORTED may be returned from setsockopt. |
| Christopher Haster |
112:e0cbb3e43c20 | 69 | * |
| Christopher Haster |
112:e0cbb3e43c20 | 70 | * @enum nsapi_option_t |
| Christopher Haster |
112:e0cbb3e43c20 | 71 | */ |
| Christopher Haster |
112:e0cbb3e43c20 | 72 | enum nsapi_option_t { |
| Christopher Haster |
112:e0cbb3e43c20 | 73 | NSAPI_REUSEADDR, /*!< Allow bind to reuse local addresses */ |
| Christopher Haster |
112:e0cbb3e43c20 | 74 | NSAPI_KEEPALIVE, /*!< Enables sending of keepalive messages */ |
| Christopher Haster |
112:e0cbb3e43c20 | 75 | NSAPI_LINGER, /*!< Keeps close from returning until queues empty */ |
| Christopher Haster |
112:e0cbb3e43c20 | 76 | NSAPI_SNDBUF, /*!< Sets send buffer size */ |
| Christopher Haster |
112:e0cbb3e43c20 | 77 | NSAPI_RCVBUF, /*!< Sets recv buffer size */ |
| Christopher Haster |
112:e0cbb3e43c20 | 78 | }; |
| Christopher Haster |
112:e0cbb3e43c20 | 79 | |
| Christopher Haster |
105:2fd212f8da61 | 80 | /** Maximum size of MAC address representation |
| Christopher Haster |
105:2fd212f8da61 | 81 | */ |
| Christopher Haster |
105:2fd212f8da61 | 82 | #define NSAPI_MAC_SIZE 18 |
| Christopher Haster |
105:2fd212f8da61 | 83 | |
| Christopher Haster |
105:2fd212f8da61 | 84 | /** Maximum number of bytes for MAC address |
| Christopher Haster |
105:2fd212f8da61 | 85 | */ |
| Christopher Haster |
105:2fd212f8da61 | 86 | #define NSAPI_MAC_BYTES 6 |
| Christopher Haster |
105:2fd212f8da61 | 87 | |
| Christopher Haster |
105:2fd212f8da61 | 88 | |
| Christopher Haster |
105:2fd212f8da61 | 89 | /** NetworkStack class |
| Christopher Haster |
105:2fd212f8da61 | 90 | * |
| Christopher Haster |
105:2fd212f8da61 | 91 | * Common interface that is shared between hardware that |
| Christopher Haster |
105:2fd212f8da61 | 92 | * can connect to a network over IP. By implementing the |
| Christopher Haster |
105:2fd212f8da61 | 93 | * NetworkStack, a network stack can be used as a target |
| Christopher Haster |
105:2fd212f8da61 | 94 | * for instantiating network sockets. |
| Christopher Haster |
105:2fd212f8da61 | 95 | */ |
| Christopher Haster |
105:2fd212f8da61 | 96 | class NetworkStack |
| Christopher Haster |
105:2fd212f8da61 | 97 | { |
| Christopher Haster |
105:2fd212f8da61 | 98 | public: |
| Christopher Haster |
105:2fd212f8da61 | 99 | virtual ~NetworkStack() {}; |
| Christopher Haster |
105:2fd212f8da61 | 100 | |
| Christopher Haster |
105:2fd212f8da61 | 101 | /** Get the local IP address |
| Christopher Haster |
105:2fd212f8da61 | 102 | * |
| Christopher Haster |
105:2fd212f8da61 | 103 | * @return Null-terminated representation of the local IP address |
| Christopher Haster |
105:2fd212f8da61 | 104 | * or null if not yet connected |
| Christopher Haster |
105:2fd212f8da61 | 105 | */ |
| Christopher Haster |
105:2fd212f8da61 | 106 | virtual const char *get_ip_address() = 0; |
| Christopher Haster |
105:2fd212f8da61 | 107 | |
| Christopher Haster |
105:2fd212f8da61 | 108 | /** Get the local MAC address |
| Christopher Haster |
105:2fd212f8da61 | 109 | * |
| Christopher Haster |
105:2fd212f8da61 | 110 | * @return Null-terminated representation of the local MAC address |
| Christopher Haster |
105:2fd212f8da61 | 111 | */ |
| Christopher Haster |
105:2fd212f8da61 | 112 | virtual const char *get_mac_address() = 0; |
| Christopher Haster |
105:2fd212f8da61 | 113 | |
| Christopher Haster |
105:2fd212f8da61 | 114 | /** Translates a hostname to an IP address |
| Christopher Haster |
105:2fd212f8da61 | 115 | * |
| Christopher Haster |
105:2fd212f8da61 | 116 | * The hostname may be either a domain name or an IP address. If the |
| Christopher Haster |
105:2fd212f8da61 | 117 | * hostname is an IP address, no network transactions will be performed. |
| Christopher Haster |
105:2fd212f8da61 | 118 | * |
| Christopher Haster |
105:2fd212f8da61 | 119 | * If no stack-specific DNS resolution is provided, the hostname |
| Christopher Haster |
105:2fd212f8da61 | 120 | * will be resolve using a UDP socket on the stack. |
| Christopher Haster |
105:2fd212f8da61 | 121 | * |
| Christopher Haster |
105:2fd212f8da61 | 122 | * @param address Destination for the host SocketAddress |
| Christopher Haster |
105:2fd212f8da61 | 123 | * @param host Hostname to resolve |
| Christopher Haster |
105:2fd212f8da61 | 124 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 125 | */ |
| Christopher Haster |
105:2fd212f8da61 | 126 | virtual int gethostbyname(SocketAddress *address, const char *host); |
| Christopher Haster |
105:2fd212f8da61 | 127 | |
| Christopher Haster |
105:2fd212f8da61 | 128 | /* Set stack-specific stack options |
| Christopher Haster |
105:2fd212f8da61 | 129 | * |
| Christopher Haster |
105:2fd212f8da61 | 130 | * The setstackopt allow an application to pass stack-specific hints |
| Christopher Haster |
105:2fd212f8da61 | 131 | * to the underlying stack. For unsupported options, |
| Christopher Haster |
105:2fd212f8da61 | 132 | * NSAPI_ERROR_UNSUPPORTED is returned and the stack is unmodified. |
| Christopher Haster |
105:2fd212f8da61 | 133 | * |
| Christopher Haster |
105:2fd212f8da61 | 134 | * @param level Stack-specific protocol level |
| Christopher Haster |
105:2fd212f8da61 | 135 | * @param optname Stack-specific option identifier |
| Christopher Haster |
105:2fd212f8da61 | 136 | * @param optval Option value |
| Christopher Haster |
105:2fd212f8da61 | 137 | * @param optlen Length of the option value |
| Christopher Haster |
105:2fd212f8da61 | 138 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 139 | */ |
| Christopher Haster |
105:2fd212f8da61 | 140 | virtual int setstackopt(int level, int optname, const void *optval, unsigned optlen); |
| Christopher Haster |
105:2fd212f8da61 | 141 | |
| Christopher Haster |
105:2fd212f8da61 | 142 | /* Get stack-specific stack options |
| Christopher Haster |
105:2fd212f8da61 | 143 | * |
| Christopher Haster |
105:2fd212f8da61 | 144 | * The getstackopt allow an application to retrieve stack-specific hints |
| Christopher Haster |
105:2fd212f8da61 | 145 | * from the underlying stack. For unsupported options, |
| Christopher Haster |
105:2fd212f8da61 | 146 | * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. |
| Christopher Haster |
105:2fd212f8da61 | 147 | * |
| Christopher Haster |
105:2fd212f8da61 | 148 | * @param level Stack-specific protocol level |
| Christopher Haster |
105:2fd212f8da61 | 149 | * @param optname Stack-specific option identifier |
| Christopher Haster |
105:2fd212f8da61 | 150 | * @param optval Destination for option value |
| Christopher Haster |
105:2fd212f8da61 | 151 | * @param optlen Length of the option value |
| Christopher Haster |
105:2fd212f8da61 | 152 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 153 | */ |
| Christopher Haster |
105:2fd212f8da61 | 154 | virtual int getstackopt(int level, int optname, void *optval, unsigned *optlen); |
| Christopher Haster |
105:2fd212f8da61 | 155 | |
| Christopher Haster |
105:2fd212f8da61 | 156 | protected: |
| Christopher Haster |
105:2fd212f8da61 | 157 | friend class Socket; |
| Christopher Haster |
105:2fd212f8da61 | 158 | friend class UDPSocket; |
| Christopher Haster |
105:2fd212f8da61 | 159 | friend class TCPSocket; |
| Christopher Haster |
105:2fd212f8da61 | 160 | friend class TCPServer; |
| Christopher Haster |
105:2fd212f8da61 | 161 | |
| Christopher Haster |
105:2fd212f8da61 | 162 | /** Opens a socket |
| Christopher Haster |
105:2fd212f8da61 | 163 | * |
| Christopher Haster |
105:2fd212f8da61 | 164 | * Creates a network socket and stores it in the specified handle. |
| Christopher Haster |
105:2fd212f8da61 | 165 | * The handle must be passed to following calls on the socket. |
| Christopher Haster |
105:2fd212f8da61 | 166 | * |
| Christopher Haster |
105:2fd212f8da61 | 167 | * A stack may have a finite number of sockets, in this case |
| Christopher Haster |
105:2fd212f8da61 | 168 | * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. |
| Christopher Haster |
105:2fd212f8da61 | 169 | * |
| Christopher Haster |
105:2fd212f8da61 | 170 | * @param handle Destination for the handle to a newly created socket |
| Christopher Haster |
105:2fd212f8da61 | 171 | * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP |
| Christopher Haster |
105:2fd212f8da61 | 172 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 173 | */ |
| Christopher Haster |
105:2fd212f8da61 | 174 | virtual int socket_open(void **handle, nsapi_protocol_t proto) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 175 | |
| Christopher Haster |
105:2fd212f8da61 | 176 | /** Close the socket |
| Christopher Haster |
105:2fd212f8da61 | 177 | * |
| Christopher Haster |
105:2fd212f8da61 | 178 | * Closes any open connection and deallocates any memory associated |
| Christopher Haster |
105:2fd212f8da61 | 179 | * with the socket. |
| Christopher Haster |
105:2fd212f8da61 | 180 | * |
| Christopher Haster |
105:2fd212f8da61 | 181 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 182 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 183 | */ |
| Christopher Haster |
105:2fd212f8da61 | 184 | virtual int socket_close(void *handle) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 185 | |
| Christopher Haster |
105:2fd212f8da61 | 186 | /** Bind a specific address to a socket |
| Christopher Haster |
105:2fd212f8da61 | 187 | * |
| Christopher Haster |
105:2fd212f8da61 | 188 | * Binding a socket specifies the address and port on which to recieve |
| Christopher Haster |
105:2fd212f8da61 | 189 | * data. If the IP address is zeroed, only the port is bound. |
| Christopher Haster |
105:2fd212f8da61 | 190 | * |
| Christopher Haster |
105:2fd212f8da61 | 191 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 192 | * @param address Local address to bind |
| Christopher Haster |
105:2fd212f8da61 | 193 | * @return 0 on success, negative error code on failure. |
| Christopher Haster |
105:2fd212f8da61 | 194 | */ |
| Christopher Haster |
105:2fd212f8da61 | 195 | virtual int socket_bind(void *handle, const SocketAddress &address) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 196 | |
| Christopher Haster |
105:2fd212f8da61 | 197 | /** Listen for connections on a TCP socket |
| Christopher Haster |
105:2fd212f8da61 | 198 | * |
| Christopher Haster |
105:2fd212f8da61 | 199 | * Marks the socket as a passive socket that can be used to accept |
| Christopher Haster |
105:2fd212f8da61 | 200 | * incoming connections. |
| Christopher Haster |
105:2fd212f8da61 | 201 | * |
| Christopher Haster |
105:2fd212f8da61 | 202 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 203 | * @param backlog Number of pending connections that can be queued |
| Christopher Haster |
105:2fd212f8da61 | 204 | * simultaneously |
| Christopher Haster |
105:2fd212f8da61 | 205 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 206 | */ |
| Christopher Haster |
105:2fd212f8da61 | 207 | virtual int socket_listen(void *handle, int backlog) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 208 | |
| Christopher Haster |
105:2fd212f8da61 | 209 | /** Connects TCP socket to a remote host |
| Christopher Haster |
105:2fd212f8da61 | 210 | * |
| Christopher Haster |
105:2fd212f8da61 | 211 | * Initiates a connection to a remote server specified by the |
| Christopher Haster |
105:2fd212f8da61 | 212 | * indicated address. |
| Christopher Haster |
105:2fd212f8da61 | 213 | * |
| Christopher Haster |
105:2fd212f8da61 | 214 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 215 | * @param address The SocketAddress of the remote host |
| Christopher Haster |
105:2fd212f8da61 | 216 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 217 | */ |
| Christopher Haster |
105:2fd212f8da61 | 218 | virtual int socket_connect(void *handle, const SocketAddress &address) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 219 | |
| Christopher Haster |
105:2fd212f8da61 | 220 | /** Accepts a connection on a TCP socket |
| Christopher Haster |
105:2fd212f8da61 | 221 | * |
| Christopher Haster |
105:2fd212f8da61 | 222 | * The server socket must be bound and set to listen for connections. |
| Christopher Haster |
105:2fd212f8da61 | 223 | * On a new connection, creates a network socket and stores it in the |
| Christopher Haster |
105:2fd212f8da61 | 224 | * specified handle. The handle must be passed to following calls on |
| Christopher Haster |
105:2fd212f8da61 | 225 | * the socket. |
| Christopher Haster |
105:2fd212f8da61 | 226 | * |
| Christopher Haster |
105:2fd212f8da61 | 227 | * A stack may have a finite number of sockets, in this case |
| Christopher Haster |
105:2fd212f8da61 | 228 | * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. |
| Christopher Haster |
105:2fd212f8da61 | 229 | * |
| Christopher Haster |
105:2fd212f8da61 | 230 | * This call is non-blocking. If accept would block, |
| Christopher Haster |
105:2fd212f8da61 | 231 | * NSAPI_ERROR_WOULD_BLOCK is returned immediately. |
| Christopher Haster |
105:2fd212f8da61 | 232 | * |
| Christopher Haster |
105:2fd212f8da61 | 233 | * @param handle Destination for a handle to the newly created sockey |
| Christopher Haster |
105:2fd212f8da61 | 234 | * @param server Socket handle to server to accept from |
| Christopher Haster |
105:2fd212f8da61 | 235 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 236 | */ |
| Christopher Haster |
105:2fd212f8da61 | 237 | virtual int socket_accept(void **handle, void *server) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 238 | |
| Christopher Haster |
105:2fd212f8da61 | 239 | /** Send data over a TCP socket |
| Christopher Haster |
105:2fd212f8da61 | 240 | * |
| Christopher Haster |
105:2fd212f8da61 | 241 | * The socket must be connected to a remote host. Returns the number of |
| Christopher Haster |
105:2fd212f8da61 | 242 | * bytes sent from the buffer. |
| Christopher Haster |
105:2fd212f8da61 | 243 | * |
| Christopher Haster |
105:2fd212f8da61 | 244 | * This call is non-blocking. If send would block, |
| Christopher Haster |
105:2fd212f8da61 | 245 | * NSAPI_ERROR_WOULD_BLOCK is returned immediately. |
| Christopher Haster |
105:2fd212f8da61 | 246 | * |
| Christopher Haster |
105:2fd212f8da61 | 247 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 248 | * @param data Buffer of data to send to the host |
| Christopher Haster |
105:2fd212f8da61 | 249 | * @param size Size of the buffer in bytes |
| Christopher Haster |
105:2fd212f8da61 | 250 | * @return Number of sent bytes on success, negative error |
| Christopher Haster |
105:2fd212f8da61 | 251 | * code on failure |
| Christopher Haster |
105:2fd212f8da61 | 252 | */ |
| Christopher Haster |
105:2fd212f8da61 | 253 | virtual int socket_send(void *handle, const void *data, unsigned size) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 254 | |
| Christopher Haster |
105:2fd212f8da61 | 255 | /** Receive data over a TCP socket |
| Christopher Haster |
105:2fd212f8da61 | 256 | * |
| Christopher Haster |
105:2fd212f8da61 | 257 | * The socket must be connected to a remote host. Returns the number of |
| Christopher Haster |
105:2fd212f8da61 | 258 | * bytes received into the buffer. |
| Christopher Haster |
105:2fd212f8da61 | 259 | * |
| Christopher Haster |
105:2fd212f8da61 | 260 | * This call is non-blocking. If recv would block, |
| Christopher Haster |
105:2fd212f8da61 | 261 | * NSAPI_ERROR_WOULD_BLOCK is returned immediately. |
| Christopher Haster |
105:2fd212f8da61 | 262 | * |
| Christopher Haster |
105:2fd212f8da61 | 263 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 264 | * @param data Destination buffer for data received from the host |
| Christopher Haster |
105:2fd212f8da61 | 265 | * @param size Size of the buffer in bytes |
| Christopher Haster |
105:2fd212f8da61 | 266 | * @return Number of received bytes on success, negative error |
| Christopher Haster |
105:2fd212f8da61 | 267 | * code on failure |
| Christopher Haster |
105:2fd212f8da61 | 268 | */ |
| Christopher Haster |
105:2fd212f8da61 | 269 | virtual int socket_recv(void *handle, void *data, unsigned size) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 270 | |
| Christopher Haster |
105:2fd212f8da61 | 271 | /** Send a packet over a UDP socket |
| Christopher Haster |
105:2fd212f8da61 | 272 | * |
| Christopher Haster |
105:2fd212f8da61 | 273 | * Sends data to the specified address. Returns the number of bytes |
| Christopher Haster |
105:2fd212f8da61 | 274 | * sent from the buffer. |
| Christopher Haster |
105:2fd212f8da61 | 275 | * |
| Christopher Haster |
105:2fd212f8da61 | 276 | * This call is non-blocking. If sendto would block, |
| Christopher Haster |
105:2fd212f8da61 | 277 | * NSAPI_ERROR_WOULD_BLOCK is returned immediately. |
| Christopher Haster |
105:2fd212f8da61 | 278 | * |
| Christopher Haster |
105:2fd212f8da61 | 279 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 280 | * @param address The SocketAddress of the remote host |
| Christopher Haster |
105:2fd212f8da61 | 281 | * @param data Buffer of data to send to the host |
| Christopher Haster |
105:2fd212f8da61 | 282 | * @param size Size of the buffer in bytes |
| Christopher Haster |
105:2fd212f8da61 | 283 | * @return Number of sent bytes on success, negative error |
| Christopher Haster |
105:2fd212f8da61 | 284 | * code on failure |
| Christopher Haster |
105:2fd212f8da61 | 285 | */ |
| Christopher Haster |
105:2fd212f8da61 | 286 | virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 287 | |
| Christopher Haster |
105:2fd212f8da61 | 288 | /** Receive a packet over a UDP socket |
| Christopher Haster |
105:2fd212f8da61 | 289 | * |
| Christopher Haster |
105:2fd212f8da61 | 290 | * Receives data and stores the source address in address if address |
| Christopher Haster |
105:2fd212f8da61 | 291 | * is not NULL. Returns the number of bytes received into the buffer. |
| Christopher Haster |
105:2fd212f8da61 | 292 | * |
| Christopher Haster |
105:2fd212f8da61 | 293 | * This call is non-blocking. If recvfrom would block, |
| Christopher Haster |
105:2fd212f8da61 | 294 | * NSAPI_ERROR_WOULD_BLOCK is returned immediately. |
| Christopher Haster |
105:2fd212f8da61 | 295 | * |
| Christopher Haster |
105:2fd212f8da61 | 296 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 297 | * @param address Destination for the source address or NULL |
| Christopher Haster |
105:2fd212f8da61 | 298 | * @param data Destination buffer for data received from the host |
| Christopher Haster |
105:2fd212f8da61 | 299 | * @param size Size of the buffer in bytes |
| Christopher Haster |
105:2fd212f8da61 | 300 | * @return Number of received bytes on success, negative error |
| Christopher Haster |
105:2fd212f8da61 | 301 | * code on failure |
| Christopher Haster |
105:2fd212f8da61 | 302 | */ |
| Christopher Haster |
105:2fd212f8da61 | 303 | virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 304 | |
| Christopher Haster |
105:2fd212f8da61 | 305 | /** Register a callback on state change of the socket |
| Christopher Haster |
105:2fd212f8da61 | 306 | * |
| Christopher Haster |
105:2fd212f8da61 | 307 | * The specified callback will be called on state changes such as when |
| Christopher Haster |
105:2fd212f8da61 | 308 | * the socket can recv/send/accept successfully and on when an error |
| Christopher Haster |
105:2fd212f8da61 | 309 | * occurs. The callback may also be called spuriously without reason. |
| Christopher Haster |
105:2fd212f8da61 | 310 | * |
| Christopher Haster |
105:2fd212f8da61 | 311 | * The callback may be called in an interrupt context and should not |
| Christopher Haster |
105:2fd212f8da61 | 312 | * perform expensive operations such as recv/send calls. |
| Christopher Haster |
105:2fd212f8da61 | 313 | * |
| Christopher Haster |
105:2fd212f8da61 | 314 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 315 | * @param callback Function to call on state change |
| Christopher Haster |
105:2fd212f8da61 | 316 | * @param data Argument to pass to callback |
| Christopher Haster |
105:2fd212f8da61 | 317 | */ |
| Christopher Haster |
105:2fd212f8da61 | 318 | virtual void socket_attach(void *handle, void (*callback)(void *), void *data) = 0; |
| Christopher Haster |
105:2fd212f8da61 | 319 | |
| Christopher Haster |
105:2fd212f8da61 | 320 | /* Set stack-specific socket options |
| Christopher Haster |
105:2fd212f8da61 | 321 | * |
| Christopher Haster |
105:2fd212f8da61 | 322 | * The setsockopt allow an application to pass stack-specific hints |
| Christopher Haster |
105:2fd212f8da61 | 323 | * to the underlying stack. For unsupported options, |
| Christopher Haster |
105:2fd212f8da61 | 324 | * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified. |
| Christopher Haster |
105:2fd212f8da61 | 325 | * |
| Christopher Haster |
105:2fd212f8da61 | 326 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 327 | * @param level Stack-specific protocol level |
| Christopher Haster |
105:2fd212f8da61 | 328 | * @param optname Stack-specific option identifier |
| Christopher Haster |
105:2fd212f8da61 | 329 | * @param optval Option value |
| Christopher Haster |
105:2fd212f8da61 | 330 | * @param optlen Length of the option value |
| Christopher Haster |
105:2fd212f8da61 | 331 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 332 | */ |
| Christopher Haster |
105:2fd212f8da61 | 333 | virtual int setsockopt(void *handle, int level, int optname, const void *optval, unsigned optlen); |
| Christopher Haster |
105:2fd212f8da61 | 334 | |
| Christopher Haster |
105:2fd212f8da61 | 335 | /* Get stack-specific socket options |
| Christopher Haster |
105:2fd212f8da61 | 336 | * |
| Christopher Haster |
105:2fd212f8da61 | 337 | * The getstackopt allow an application to retrieve stack-specific hints |
| Christopher Haster |
105:2fd212f8da61 | 338 | * from the underlying stack. For unsupported options, |
| Christopher Haster |
105:2fd212f8da61 | 339 | * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. |
| Christopher Haster |
105:2fd212f8da61 | 340 | * |
| Christopher Haster |
105:2fd212f8da61 | 341 | * @param handle Socket handle |
| Christopher Haster |
105:2fd212f8da61 | 342 | * @param level Stack-specific protocol level |
| Christopher Haster |
105:2fd212f8da61 | 343 | * @param optname Stack-specific option identifier |
| Christopher Haster |
105:2fd212f8da61 | 344 | * @param optval Destination for option value |
| Christopher Haster |
105:2fd212f8da61 | 345 | * @param optlen Length of the option value |
| Christopher Haster |
105:2fd212f8da61 | 346 | * @return 0 on success, negative error code on failure |
| Christopher Haster |
105:2fd212f8da61 | 347 | */ |
| Christopher Haster |
105:2fd212f8da61 | 348 | virtual int getsockopt(void *handle, int level, int optname, void *optval, unsigned *optlen); |
| Christopher Haster |
105:2fd212f8da61 | 349 | }; |
| Christopher Haster |
105:2fd212f8da61 | 350 | |
| Christopher Haster |
105:2fd212f8da61 | 351 | #endif |