Base class for IP Based Networking Libraries
Dependencies: DnsQuery
Dependents: TempTower BSDInterfaceTests HelloBSDInterface ESP8266InterfaceTests ... more
NetworkStack.h
00001 /* NetworkStack 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 #ifndef NETWORK_INTERFACE_H 00018 #define NETWORK_INTERFACE_H 00019 00020 #include "mbed.h" 00021 #include "SocketAddress.h" 00022 00023 00024 /** Enum of standardized error codes 00025 * 00026 * Valid error codes have negative values and may 00027 * be returned by any network operation. 00028 * 00029 * @enum nsapi_error_t 00030 */ 00031 enum nsapi_error_t { 00032 NSAPI_ERROR_WOULD_BLOCK = -3001, /*!< no data is not available but call is non-blocking */ 00033 NSAPI_ERROR_UNSUPPORTED = -3002, /*!< unsupported functionality */ 00034 NSAPI_ERROR_PARAMETER = -3003, /*!< invalid configuration */ 00035 NSAPI_ERROR_NO_CONNECTION = -3004, /*!< not connected to a network */ 00036 NSAPI_ERROR_NO_SOCKET = -3005, /*!< socket not available for use */ 00037 NSAPI_ERROR_NO_ADDRESS = -3006, /*!< IP address is not known */ 00038 NSAPI_ERROR_NO_MEMORY = -3007, /*!< memory resource not available */ 00039 NSAPI_ERROR_DNS_FAILURE = -3008, /*!< DNS failed to complete successfully */ 00040 NSAPI_ERROR_DHCP_FAILURE = -3009, /*!< DHCP failed to complete successfully */ 00041 NSAPI_ERROR_AUTH_FAILURE = -3010, /*!< connection to access point faield */ 00042 NSAPI_ERROR_DEVICE_ERROR = -3011, /*!< failure interfacing with the network procesor */ 00043 }; 00044 00045 /** Enum of socket protocols 00046 * 00047 * The socket protocol specifies a particular protocol to 00048 * be used with a newly created socket. 00049 * 00050 * @enum nsapi_protocol_t 00051 */ 00052 enum nsapi_protocol_t { 00053 NSAPI_TCP, /*!< Socket is of TCP type */ 00054 NSAPI_UDP, /*!< Socket is of UDP type */ 00055 }; 00056 00057 /* Enum of standardized stack option levels 00058 * 00059 * @enum nsapi_level_t 00060 */ 00061 enum nsapi_level_t { 00062 NSAPI_STACK, /*!< Stack option level */ 00063 NSAPI_SOCKET, /*!< Socket option level */ 00064 }; 00065 00066 /* Enum of standardized stack options 00067 * 00068 * These options may not be supported on all stacks, in which 00069 * case NSAPI_ERROR_UNSUPPORTED may be returned from setsockopt. 00070 * 00071 * @enum nsapi_option_t 00072 */ 00073 enum nsapi_option_t { 00074 NSAPI_REUSEADDR, /*!< Allow bind to reuse local addresses */ 00075 NSAPI_KEEPALIVE, /*!< Enables sending of keepalive messages */ 00076 NSAPI_LINGER, /*!< Keeps close from returning until queues empty */ 00077 NSAPI_SNDBUF, /*!< Sets send buffer size */ 00078 NSAPI_RCVBUF, /*!< Sets recv buffer size */ 00079 }; 00080 00081 00082 /** NetworkStack class 00083 * 00084 * Common interface that is shared between hardware that 00085 * can connect to a network over IP. By implementing the 00086 * NetworkStack, a network stack can be used as a target 00087 * for instantiating network sockets. 00088 */ 00089 class NetworkStack 00090 { 00091 public: 00092 virtual ~NetworkStack() {}; 00093 00094 /** Get the local IP address 00095 * 00096 * @return Null-terminated representation of the local IP address 00097 * or null if not yet connected 00098 */ 00099 virtual const char *get_ip_address() = 0; 00100 00101 /** Translates a hostname to an IP address 00102 * 00103 * The hostname may be either a domain name or an IP address. If the 00104 * hostname is an IP address, no network transactions will be performed. 00105 * 00106 * If no stack-specific DNS resolution is provided, the hostname 00107 * will be resolve using a UDP socket on the stack. 00108 * 00109 * @param address Destination for the host SocketAddress 00110 * @param host Hostname to resolve 00111 * @return 0 on success, negative error code on failure 00112 */ 00113 virtual int gethostbyname(SocketAddress *address, const char *host); 00114 00115 /* Set stack-specific stack options 00116 * 00117 * The setstackopt allow an application to pass stack-specific hints 00118 * to the underlying stack. For unsupported options, 00119 * NSAPI_ERROR_UNSUPPORTED is returned and the stack is unmodified. 00120 * 00121 * @param level Stack-specific protocol level 00122 * @param optname Stack-specific option identifier 00123 * @param optval Option value 00124 * @param optlen Length of the option value 00125 * @return 0 on success, negative error code on failure 00126 */ 00127 virtual int setstackopt(int level, int optname, const void *optval, unsigned optlen); 00128 00129 /* Get stack-specific stack options 00130 * 00131 * The getstackopt allow an application to retrieve stack-specific hints 00132 * from the underlying stack. For unsupported options, 00133 * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. 00134 * 00135 * @param level Stack-specific protocol level 00136 * @param optname Stack-specific option identifier 00137 * @param optval Destination for option value 00138 * @param optlen Length of the option value 00139 * @return 0 on success, negative error code on failure 00140 */ 00141 virtual int getstackopt(int level, int optname, void *optval, unsigned *optlen); 00142 00143 protected: 00144 friend class Socket; 00145 friend class UDPSocket; 00146 friend class TCPSocket; 00147 friend class TCPServer; 00148 00149 /** Opens a socket 00150 * 00151 * Creates a network socket and stores it in the specified handle. 00152 * The handle must be passed to following calls on the socket. 00153 * 00154 * A stack may have a finite number of sockets, in this case 00155 * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. 00156 * 00157 * @param handle Destination for the handle to a newly created socket 00158 * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP 00159 * @return 0 on success, negative error code on failure 00160 */ 00161 virtual int socket_open(void **handle, nsapi_protocol_t proto) = 0; 00162 00163 /** Close the socket 00164 * 00165 * Closes any open connection and deallocates any memory associated 00166 * with the socket. 00167 * 00168 * @param handle Socket handle 00169 * @return 0 on success, negative error code on failure 00170 */ 00171 virtual int socket_close(void *handle) = 0; 00172 00173 /** Bind a specific address to a socket 00174 * 00175 * Binding a socket specifies the address and port on which to recieve 00176 * data. If the IP address is zeroed, only the port is bound. 00177 * 00178 * @param handle Socket handle 00179 * @param address Local address to bind 00180 * @return 0 on success, negative error code on failure. 00181 */ 00182 virtual int socket_bind(void *handle, const SocketAddress &address) = 0; 00183 00184 /** Listen for connections on a TCP socket 00185 * 00186 * Marks the socket as a passive socket that can be used to accept 00187 * incoming connections. 00188 * 00189 * @param handle Socket handle 00190 * @param backlog Number of pending connections that can be queued 00191 * simultaneously 00192 * @return 0 on success, negative error code on failure 00193 */ 00194 virtual int socket_listen(void *handle, int backlog) = 0; 00195 00196 /** Connects TCP socket to a remote host 00197 * 00198 * Initiates a connection to a remote server specified by the 00199 * indicated address. 00200 * 00201 * @param handle Socket handle 00202 * @param address The SocketAddress of the remote host 00203 * @return 0 on success, negative error code on failure 00204 */ 00205 virtual int socket_connect(void *handle, const SocketAddress &address) = 0; 00206 00207 /** Accepts a connection on a TCP socket 00208 * 00209 * The server socket must be bound and set to listen for connections. 00210 * On a new connection, creates a network socket and stores it in the 00211 * specified handle. The handle must be passed to following calls on 00212 * the socket. 00213 * 00214 * A stack may have a finite number of sockets, in this case 00215 * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. 00216 * 00217 * This call is non-blocking. If accept would block, 00218 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00219 * 00220 * @param handle Destination for a handle to the newly created sockey 00221 * @param server Socket handle to server to accept from 00222 * @return 0 on success, negative error code on failure 00223 */ 00224 virtual int socket_accept(void **handle, void *server) = 0; 00225 00226 /** Send data over a TCP socket 00227 * 00228 * The socket must be connected to a remote host. Returns the number of 00229 * bytes sent from the buffer. 00230 * 00231 * This call is non-blocking. If send would block, 00232 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00233 * 00234 * @param handle Socket handle 00235 * @param data Buffer of data to send to the host 00236 * @param size Size of the buffer in bytes 00237 * @return Number of sent bytes on success, negative error 00238 * code on failure 00239 */ 00240 virtual int socket_send(void *handle, const void *data, unsigned size) = 0; 00241 00242 /** Receive data over a TCP socket 00243 * 00244 * The socket must be connected to a remote host. Returns the number of 00245 * bytes received into the buffer. 00246 * 00247 * This call is non-blocking. If recv would block, 00248 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00249 * 00250 * @param handle Socket handle 00251 * @param data Destination buffer for data received from the host 00252 * @param size Size of the buffer in bytes 00253 * @return Number of received bytes on success, negative error 00254 * code on failure 00255 */ 00256 virtual int socket_recv(void *handle, void *data, unsigned size) = 0; 00257 00258 /** Send a packet over a UDP socket 00259 * 00260 * Sends data to the specified address. Returns the number of bytes 00261 * sent from the buffer. 00262 * 00263 * This call is non-blocking. If sendto would block, 00264 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00265 * 00266 * @param handle Socket handle 00267 * @param address The SocketAddress of the remote host 00268 * @param data Buffer of data to send to the host 00269 * @param size Size of the buffer in bytes 00270 * @return Number of sent bytes on success, negative error 00271 * code on failure 00272 */ 00273 virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size) = 0; 00274 00275 /** Receive a packet over a UDP socket 00276 * 00277 * Receives data and stores the source address in address if address 00278 * is not NULL. Returns the number of bytes received into the buffer. 00279 * 00280 * This call is non-blocking. If recvfrom would block, 00281 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00282 * 00283 * @param handle Socket handle 00284 * @param address Destination for the source address or NULL 00285 * @param data Destination buffer for data received from the host 00286 * @param size Size of the buffer in bytes 00287 * @return Number of received bytes on success, negative error 00288 * code on failure 00289 */ 00290 virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size) = 0; 00291 00292 /** Register a callback on state change of the socket 00293 * 00294 * The specified callback will be called on state changes such as when 00295 * the socket can recv/send/accept successfully and on when an error 00296 * occurs. The callback may also be called spuriously without reason. 00297 * 00298 * The callback may be called in an interrupt context and should not 00299 * perform expensive operations such as recv/send calls. 00300 * 00301 * @param handle Socket handle 00302 * @param callback Function to call on state change 00303 * @param data Argument to pass to callback 00304 */ 00305 virtual void socket_attach(void *handle, void (*callback)(void *), void *data) = 0; 00306 00307 /* Set stack-specific socket options 00308 * 00309 * The setsockopt allow an application to pass stack-specific hints 00310 * to the underlying stack. For unsupported options, 00311 * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified. 00312 * 00313 * @param handle Socket handle 00314 * @param level Stack-specific protocol level 00315 * @param optname Stack-specific option identifier 00316 * @param optval Option value 00317 * @param optlen Length of the option value 00318 * @return 0 on success, negative error code on failure 00319 */ 00320 virtual int setsockopt(void *handle, int level, int optname, const void *optval, unsigned optlen); 00321 00322 /* Get stack-specific socket options 00323 * 00324 * The getstackopt allow an application to retrieve stack-specific hints 00325 * from the underlying stack. For unsupported options, 00326 * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. 00327 * 00328 * @param handle Socket handle 00329 * @param level Stack-specific protocol level 00330 * @param optname Stack-specific option identifier 00331 * @param optval Destination for option value 00332 * @param optlen Length of the option value 00333 * @return 0 on success, negative error code on failure 00334 */ 00335 virtual int getsockopt(void *handle, int level, int optname, void *optval, unsigned *optlen); 00336 }; 00337 00338 #endif
Generated on Tue Jul 12 2022 14:52:52 by
1.7.2