Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
NetworkStack.h
00001 00002 /* NetworkStack 00003 * Copyright (c) 2015 ARM Limited 00004 * 00005 * Licensed under the Apache License, Version 2.0 (the "License"); 00006 * you may not use this file except in compliance with the License. 00007 * You may obtain a copy of the License at 00008 * 00009 * http://www.apache.org/licenses/LICENSE-2.0 00010 * 00011 * Unless required by applicable law or agreed to in writing, software 00012 * distributed under the License is distributed on an "AS IS" BASIS, 00013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00014 * See the License for the specific language governing permissions and 00015 * limitations under the License. 00016 */ 00017 00018 #ifndef NETWORK_STACK_H 00019 #define NETWORK_STACK_H 00020 00021 #include "nsapi_types.h" 00022 #include "netsocket/SocketAddress.h" 00023 #include "netsocket/NetworkInterface.h" 00024 #include "DNS.h" 00025 00026 // Predeclared classes 00027 class OnboardNetworkStack; 00028 00029 /** NetworkStack class 00030 * 00031 * Common interface that is shared between hardware that 00032 * can connect to a network over IP. By implementing the 00033 * NetworkStack, a network stack can be used as a target 00034 * for instantiating network sockets. 00035 * @addtogroup netsocket 00036 */ 00037 class NetworkStack: public DNS { 00038 public: 00039 virtual ~NetworkStack() {}; 00040 00041 /** Get the local IP address 00042 * 00043 * @return Null-terminated representation of the local IP address 00044 * or null if not yet connected 00045 */ 00046 virtual const char *get_ip_address(); 00047 00048 /** Translates a hostname to an IP address with specific version 00049 * 00050 * The hostname may be either a domain name or an IP address. If the 00051 * hostname is an IP address, no network transactions will be performed. 00052 * 00053 * If no stack-specific DNS resolution is provided, the hostname 00054 * will be resolve using a UDP socket on the stack. 00055 * 00056 * @param host Hostname to resolve 00057 * @param address Destination for the host SocketAddress 00058 * @param version IP version of address to resolve, NSAPI_UNSPEC indicates 00059 * version is chosen by the stack (defaults to NSAPI_UNSPEC) 00060 * @return 0 on success, negative error code on failure 00061 */ 00062 virtual nsapi_error_t gethostbyname(const char *host, 00063 SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC ); 00064 00065 /** Hostname translation callback (asynchronous) 00066 * 00067 * Callback will be called after DNS resolution completes or a failure occurs. 00068 * 00069 * Callback should not take more than 10ms to execute, otherwise it might 00070 * prevent underlying thread processing. A portable user of the callback 00071 * should not make calls to network operations due to stack size limitations. 00072 * The callback should not perform expensive operations such as socket recv/send 00073 * calls or blocking operations. 00074 * 00075 * @param status 0 on success, negative error code on failure 00076 * @param address On success, destination for the host SocketAddress 00077 */ 00078 typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t; 00079 00080 /** Translates a hostname to an IP address (asynchronous) 00081 * 00082 * The hostname may be either a domain name or an IP address. If the 00083 * hostname is an IP address, no network transactions will be performed. 00084 * 00085 * If no stack-specific DNS resolution is provided, the hostname 00086 * will be resolve using a UDP socket on the stack. 00087 * 00088 * Call is non-blocking. Result of the DNS operation is returned by the callback. 00089 * If this function returns failure, callback will not be called. In case result 00090 * is success (IP address was found from DNS cache), callback will be called 00091 * before function returns. 00092 * 00093 * @param host Hostname to resolve 00094 * @param callback Callback that is called for result 00095 * @param version IP version of address to resolve, NSAPI_UNSPEC indicates 00096 * version is chosen by the stack (defaults to NSAPI_UNSPEC) 00097 * @return 0 on immediate success, 00098 * negative error code on immediate failure or 00099 * a positive unique id that represents the hostname translation operation 00100 * and can be passed to cancel 00101 */ 00102 virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, 00103 nsapi_version_t version = NSAPI_UNSPEC ); 00104 00105 /** Cancels asynchronous hostname translation 00106 * 00107 * When translation is cancelled, callback will not be called. 00108 * 00109 * @param id Unique id of the hostname translation operation 00110 * @return 0 on success, negative error code on failure 00111 */ 00112 virtual nsapi_error_t gethostbyname_async_cancel(int id); 00113 00114 /** Add a domain name server to list of servers to query 00115 * 00116 * @param address Destination for the host address 00117 * @return 0 on success, negative error code on failure 00118 */ 00119 virtual nsapi_error_t add_dns_server(const SocketAddress &address); 00120 00121 /** Get a domain name server from a list of servers to query 00122 * 00123 * Returns a DNS server address for a index. If returns error no more 00124 * DNS servers to read. 00125 * 00126 * @param index Index of the DNS server, starts from zero 00127 * @param address Destination for the host address 00128 * @return 0 on success, negative error code on failure 00129 */ 00130 virtual nsapi_error_t get_dns_server(int index, SocketAddress *address); 00131 00132 /* Set stack options 00133 * 00134 * setstackopt allows an application to pass stack-specific options 00135 * to the underlying stack using stack-specific level and option names, 00136 * or to request generic options using levels from nsapi_stack_level_t. 00137 * 00138 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned 00139 * and the stack is unmodified. 00140 * 00141 * @param level Stack-specific protocol level or nsapi_stack_level_t 00142 * @param optname Level-specific option name 00143 * @param optval Option value 00144 * @param optlen Length of the option value 00145 * @return 0 on success, negative error code on failure 00146 */ 00147 virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen); 00148 00149 /* Get stack options 00150 * 00151 * getstackopt allows an application to retrieve stack-specific options 00152 * to the underlying stack using stack-specific level and option names, 00153 * or to request generic options using levels from nsapi_stack_level_t. 00154 * 00155 * @param level Stack-specific protocol level or nsapi_stack_level_t 00156 * @param optname Level-specific option name 00157 * @param optval Destination for option value 00158 * @param optlen Length of the option value 00159 * @return 0 on success, negative error code on failure 00160 */ 00161 virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen); 00162 00163 /** Dynamic downcast to a OnboardNetworkStack */ 00164 virtual OnboardNetworkStack *onboardNetworkStack() 00165 { 00166 return 0; 00167 } 00168 00169 protected: 00170 friend class InternetSocket; 00171 friend class UDPSocket; 00172 friend class TCPSocket; 00173 friend class TCPServer; 00174 00175 /** Opens a socket 00176 * 00177 * Creates a network socket and stores it in the specified handle. 00178 * The handle must be passed to following calls on the socket. 00179 * 00180 * A stack may have a finite number of sockets, in this case 00181 * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. 00182 * 00183 * @param handle Destination for the handle to a newly created socket 00184 * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP 00185 * @return 0 on success, negative error code on failure 00186 */ 00187 virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0; 00188 00189 /** Close the socket 00190 * 00191 * Closes any open connection and deallocates any memory associated 00192 * with the socket. 00193 * 00194 * @param handle Socket handle 00195 * @return 0 on success, negative error code on failure 00196 */ 00197 virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0; 00198 00199 /** Bind a specific address to a socket 00200 * 00201 * Binding a socket specifies the address and port on which to receive 00202 * data. If the IP address is zeroed, only the port is bound. 00203 * 00204 * @param handle Socket handle 00205 * @param address Local address to bind 00206 * @return 0 on success, negative error code on failure. 00207 */ 00208 virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0; 00209 00210 /** Listen for connections on a TCP socket 00211 * 00212 * Marks the socket as a passive socket that can be used to accept 00213 * incoming connections. 00214 * 00215 * @param handle Socket handle 00216 * @param backlog Number of pending connections that can be queued 00217 * simultaneously 00218 * @return 0 on success, negative error code on failure 00219 */ 00220 virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0; 00221 00222 /** Connects TCP socket to a remote host 00223 * 00224 * Initiates a connection to a remote server specified by the 00225 * indicated address. 00226 * 00227 * @param handle Socket handle 00228 * @param address The SocketAddress of the remote host 00229 * @return 0 on success, negative error code on failure 00230 */ 00231 virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0; 00232 00233 /** Accepts a connection on a TCP socket 00234 * 00235 * The server socket must be bound and set to listen for connections. 00236 * On a new connection, creates a network socket and stores it in the 00237 * specified handle. The handle must be passed to following calls on 00238 * the socket. 00239 * 00240 * A stack may have a finite number of sockets, in this case 00241 * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. 00242 * 00243 * This call is non-blocking. If accept would block, 00244 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00245 * 00246 * @param server Socket handle to server to accept from 00247 * @param handle Destination for a handle to the newly created socket 00248 * @param address Destination for the remote address or NULL 00249 * @return 0 on success, negative error code on failure 00250 */ 00251 virtual nsapi_error_t socket_accept(nsapi_socket_t server, 00252 nsapi_socket_t *handle, SocketAddress *address = 0) = 0; 00253 00254 /** Send data over a TCP socket 00255 * 00256 * The socket must be connected to a remote host. Returns the number of 00257 * bytes sent from the buffer. 00258 * 00259 * This call is non-blocking. If send would block, 00260 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00261 * 00262 * @param handle Socket handle 00263 * @param data Buffer of data to send to the host 00264 * @param size Size of the buffer in bytes 00265 * @return Number of sent bytes on success, negative error 00266 * code on failure 00267 */ 00268 virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle, 00269 const void *data, nsapi_size_t size) = 0; 00270 00271 /** Receive data over a TCP socket 00272 * 00273 * The socket must be connected to a remote host. Returns the number of 00274 * bytes received into the buffer. 00275 * 00276 * This call is non-blocking. If recv would block, 00277 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00278 * 00279 * @param handle Socket handle 00280 * @param data Destination buffer for data received from the host 00281 * @param size Size of the buffer in bytes 00282 * @return Number of received bytes on success, negative error 00283 * code on failure 00284 */ 00285 virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle, 00286 void *data, nsapi_size_t size) = 0; 00287 00288 /** Send a packet over a UDP socket 00289 * 00290 * Sends data to the specified address. Returns the number of bytes 00291 * sent from the buffer. 00292 * 00293 * This call is non-blocking. If sendto would block, 00294 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00295 * 00296 * @param handle Socket handle 00297 * @param address The SocketAddress of the remote host 00298 * @param data Buffer of data to send to the host 00299 * @param size Size of the buffer in bytes 00300 * @return Number of sent bytes on success, negative error 00301 * code on failure 00302 */ 00303 virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address, 00304 const void *data, nsapi_size_t size) = 0; 00305 00306 /** Receive a packet over a UDP socket 00307 * 00308 * Receives data and stores the source address in address if address 00309 * is not NULL. Returns the number of bytes received into the buffer. 00310 * 00311 * This call is non-blocking. If recvfrom would block, 00312 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00313 * 00314 * @param handle Socket handle 00315 * @param address Destination for the source address or NULL 00316 * @param buffer Destination buffer for data received from the host 00317 * @param size Size of the buffer in bytes 00318 * @return Number of received bytes on success, negative error 00319 * code on failure 00320 */ 00321 virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle, SocketAddress *address, 00322 void *buffer, nsapi_size_t size) = 0; 00323 00324 /** Register a callback on state change of the socket 00325 * 00326 * The specified callback will be called on state changes such as when 00327 * the socket can recv/send/accept successfully and on when an error 00328 * occurs. The callback may also be called spuriously without reason. 00329 * 00330 * The callback may be called in an interrupt context and should not 00331 * perform expensive operations such as recv/send calls. 00332 * 00333 * @param handle Socket handle 00334 * @param callback Function to call on state change 00335 * @param data Argument to pass to callback 00336 */ 00337 virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0; 00338 00339 /* Set stack-specific socket options 00340 * 00341 * The setsockopt allow an application to pass stack-specific hints 00342 * to the underlying stack. For unsupported options, 00343 * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified. 00344 * 00345 * @param handle Socket handle 00346 * @param level Stack-specific protocol level 00347 * @param optname Stack-specific option identifier 00348 * @param optval Option value 00349 * @param optlen Length of the option value 00350 * @return 0 on success, negative error code on failure 00351 */ 00352 virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, 00353 int optname, const void *optval, unsigned optlen); 00354 00355 /* Get stack-specific socket options 00356 * 00357 * The getstackopt allow an application to retrieve stack-specific hints 00358 * from the underlying stack. For unsupported options, 00359 * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. 00360 * 00361 * @param handle Socket handle 00362 * @param level Stack-specific protocol level 00363 * @param optname Stack-specific option identifier 00364 * @param optval Destination for option value 00365 * @param optlen Length of the option value 00366 * @return 0 on success, negative error code on failure 00367 */ 00368 virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, 00369 int optname, void *optval, unsigned *optlen); 00370 00371 private: 00372 00373 /** Call in callback 00374 * 00375 * Callback is used to call the call in method of the network stack. 00376 */ 00377 typedef mbed::Callback<nsapi_error_t (int delay_ms, mbed::Callback<void()> user_cb)> call_in_callback_cb_t; 00378 00379 /** Get a call in callback 00380 * 00381 * Get a call in callback from the network stack context. 00382 * 00383 * Callback should not take more than 10ms to execute, otherwise it might 00384 * prevent underlying thread processing. A portable user of the callback 00385 * should not make calls to network operations due to stack size limitations. 00386 * The callback should not perform expensive operations such as socket recv/send 00387 * calls or blocking operations. 00388 * 00389 * @return Call in callback 00390 */ 00391 virtual call_in_callback_cb_t get_call_in_callback(); 00392 00393 /** Call a callback after a delay 00394 * 00395 * Call a callback from the network stack context after a delay. If function 00396 * returns error callback will not be called. 00397 * 00398 * @param delay Delay in milliseconds 00399 * @param func Callback to be called 00400 * @return 0 on success, negative error code on failure 00401 */ 00402 virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func); 00403 }; 00404 00405 /** Convert a raw nsapi_stack_t object into a C++ NetworkStack object 00406 * 00407 * @param stack Reference to an object that can be converted to a stack 00408 * - A raw nsapi_stack_t object 00409 * - A reference to a network stack 00410 * - A reference to a network interface 00411 * @return Reference to the underlying network stack 00412 */ 00413 NetworkStack *nsapi_create_stack(nsapi_stack_t *stack); 00414 NetworkStack *nsapi_create_stack(NetworkStack *stack); 00415 00416 template <typename IF> 00417 NetworkStack *nsapi_create_stack(IF *iface) 00418 { 00419 return nsapi_create_stack(static_cast<NetworkInterface *>(iface)->get_stack()); 00420 } 00421 00422 00423 #endif
Generated on Tue Aug 9 2022 00:37:16 by
