Marco Zecchini
/
Example_RTOS
Rtos API example
Embed:
(wiki syntax)
Show/hide line numbers
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 00025 00026 /** NetworkStack class 00027 * 00028 * Common interface that is shared between hardware that 00029 * can connect to a network over IP. By implementing the 00030 * NetworkStack, a network stack can be used as a target 00031 * for instantiating network sockets. 00032 * @addtogroup netsocket 00033 */ 00034 class NetworkStack 00035 { 00036 public: 00037 virtual ~NetworkStack() {}; 00038 00039 /** Get the local IP address 00040 * 00041 * @return Null-terminated representation of the local IP address 00042 * or null if not yet connected 00043 */ 00044 virtual const char *get_ip_address() = 0; 00045 00046 /** Translates a hostname to an IP address with specific version 00047 * 00048 * The hostname may be either a domain name or an IP address. If the 00049 * hostname is an IP address, no network transactions will be performed. 00050 * 00051 * If no stack-specific DNS resolution is provided, the hostname 00052 * will be resolve using a UDP socket on the stack. 00053 * 00054 * @param host Hostname to resolve 00055 * @param address Destination for the host SocketAddress 00056 * @param version IP version of address to resolve, NSAPI_UNSPEC indicates 00057 * version is chosen by the stack (defaults to NSAPI_UNSPEC) 00058 * @return 0 on success, negative error code on failure 00059 */ 00060 virtual nsapi_error_t gethostbyname(const char *host, 00061 SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC ); 00062 00063 /** Add a domain name server to list of servers to query 00064 * 00065 * @param address Destination for the host address 00066 * @return 0 on success, negative error code on failure 00067 */ 00068 virtual nsapi_error_t add_dns_server(const SocketAddress &address); 00069 00070 /* Set stack options 00071 * 00072 * setstackopt allows an application to pass stack-specific options 00073 * to the underlying stack using stack-specific level and option names, 00074 * or to request generic options using levels from nsapi_stack_level_t. 00075 * 00076 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned 00077 * and the stack is unmodified. 00078 * 00079 * @param level Stack-specific protocol level or nsapi_stack_level_t 00080 * @param optname Level-specific option name 00081 * @param optval Option value 00082 * @param optlen Length of the option value 00083 * @return 0 on success, negative error code on failure 00084 */ 00085 virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen); 00086 00087 /* Get stack options 00088 * 00089 * getstackopt allows an application to retrieve stack-specific options 00090 * to the underlying stack using stack-specific level and option names, 00091 * or to request generic options using levels from nsapi_stack_level_t. 00092 * 00093 * @param level Stack-specific protocol level or nsapi_stack_level_t 00094 * @param optname Level-specific option name 00095 * @param optval Destination for option value 00096 * @param optlen Length of the option value 00097 * @return 0 on success, negative error code on failure 00098 */ 00099 virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen); 00100 00101 protected: 00102 friend class Socket; 00103 friend class UDPSocket; 00104 friend class TCPSocket; 00105 friend class TCPServer; 00106 00107 /** Opens a socket 00108 * 00109 * Creates a network socket and stores it in the specified handle. 00110 * The handle must be passed to following calls on the socket. 00111 * 00112 * A stack may have a finite number of sockets, in this case 00113 * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. 00114 * 00115 * @param handle Destination for the handle to a newly created socket 00116 * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP 00117 * @return 0 on success, negative error code on failure 00118 */ 00119 virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0; 00120 00121 /** Close the socket 00122 * 00123 * Closes any open connection and deallocates any memory associated 00124 * with the socket. 00125 * 00126 * @param handle Socket handle 00127 * @return 0 on success, negative error code on failure 00128 */ 00129 virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0; 00130 00131 /** Bind a specific address to a socket 00132 * 00133 * Binding a socket specifies the address and port on which to recieve 00134 * data. If the IP address is zeroed, only the port is bound. 00135 * 00136 * @param handle Socket handle 00137 * @param address Local address to bind 00138 * @return 0 on success, negative error code on failure. 00139 */ 00140 virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0; 00141 00142 /** Listen for connections on a TCP socket 00143 * 00144 * Marks the socket as a passive socket that can be used to accept 00145 * incoming connections. 00146 * 00147 * @param handle Socket handle 00148 * @param backlog Number of pending connections that can be queued 00149 * simultaneously 00150 * @return 0 on success, negative error code on failure 00151 */ 00152 virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0; 00153 00154 /** Connects TCP socket to a remote host 00155 * 00156 * Initiates a connection to a remote server specified by the 00157 * indicated address. 00158 * 00159 * @param handle Socket handle 00160 * @param address The SocketAddress of the remote host 00161 * @return 0 on success, negative error code on failure 00162 */ 00163 virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0; 00164 00165 /** Accepts a connection on a TCP socket 00166 * 00167 * The server socket must be bound and set to listen for connections. 00168 * On a new connection, creates a network socket and stores it in the 00169 * specified handle. The handle must be passed to following calls on 00170 * the socket. 00171 * 00172 * A stack may have a finite number of sockets, in this case 00173 * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. 00174 * 00175 * This call is non-blocking. If accept would block, 00176 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00177 * 00178 * @param server Socket handle to server to accept from 00179 * @param handle Destination for a handle to the newly created socket 00180 * @param address Destination for the remote address or NULL 00181 * @return 0 on success, negative error code on failure 00182 */ 00183 virtual nsapi_error_t socket_accept(nsapi_socket_t server, 00184 nsapi_socket_t *handle, SocketAddress *address=0) = 0; 00185 00186 /** Send data over a TCP socket 00187 * 00188 * The socket must be connected to a remote host. Returns the number of 00189 * bytes sent from the buffer. 00190 * 00191 * This call is non-blocking. If send would block, 00192 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00193 * 00194 * @param handle Socket handle 00195 * @param data Buffer of data to send to the host 00196 * @param size Size of the buffer in bytes 00197 * @return Number of sent bytes on success, negative error 00198 * code on failure 00199 */ 00200 virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle, 00201 const void *data, nsapi_size_t size) = 0; 00202 00203 /** Receive data over a TCP socket 00204 * 00205 * The socket must be connected to a remote host. Returns the number of 00206 * bytes received into the buffer. 00207 * 00208 * This call is non-blocking. If recv would block, 00209 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00210 * 00211 * @param handle Socket handle 00212 * @param data Destination buffer for data received from the host 00213 * @param size Size of the buffer in bytes 00214 * @return Number of received bytes on success, negative error 00215 * code on failure 00216 */ 00217 virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle, 00218 void *data, nsapi_size_t size) = 0; 00219 00220 /** Send a packet over a UDP socket 00221 * 00222 * Sends data to the specified address. Returns the number of bytes 00223 * sent from the buffer. 00224 * 00225 * This call is non-blocking. If sendto would block, 00226 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00227 * 00228 * @param handle Socket handle 00229 * @param address The SocketAddress of the remote host 00230 * @param data Buffer of data to send to the host 00231 * @param size Size of the buffer in bytes 00232 * @return Number of sent bytes on success, negative error 00233 * code on failure 00234 */ 00235 virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address, 00236 const void *data, nsapi_size_t size) = 0; 00237 00238 /** Receive a packet over a UDP socket 00239 * 00240 * Receives data and stores the source address in address if address 00241 * is not NULL. Returns the number of bytes received into the buffer. 00242 * 00243 * This call is non-blocking. If recvfrom would block, 00244 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00245 * 00246 * @param handle Socket handle 00247 * @param address Destination for the source address or NULL 00248 * @param buffer Destination buffer for data received from the host 00249 * @param size Size of the buffer in bytes 00250 * @return Number of received bytes on success, negative error 00251 * code on failure 00252 */ 00253 virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle, SocketAddress *address, 00254 void *buffer, nsapi_size_t size) = 0; 00255 00256 /** Register a callback on state change of the socket 00257 * 00258 * The specified callback will be called on state changes such as when 00259 * the socket can recv/send/accept successfully and on when an error 00260 * occurs. The callback may also be called spuriously without reason. 00261 * 00262 * The callback may be called in an interrupt context and should not 00263 * perform expensive operations such as recv/send calls. 00264 * 00265 * @param handle Socket handle 00266 * @param callback Function to call on state change 00267 * @param data Argument to pass to callback 00268 */ 00269 virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0; 00270 00271 /* Set stack-specific socket options 00272 * 00273 * The setsockopt allow an application to pass stack-specific hints 00274 * to the underlying stack. For unsupported options, 00275 * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified. 00276 * 00277 * @param handle Socket handle 00278 * @param level Stack-specific protocol level 00279 * @param optname Stack-specific option identifier 00280 * @param optval Option value 00281 * @param optlen Length of the option value 00282 * @return 0 on success, negative error code on failure 00283 */ 00284 virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, 00285 int optname, const void *optval, unsigned optlen); 00286 00287 /* Get stack-specific socket options 00288 * 00289 * The getstackopt allow an application to retrieve stack-specific hints 00290 * from the underlying stack. For unsupported options, 00291 * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. 00292 * 00293 * @param handle Socket handle 00294 * @param level Stack-specific protocol level 00295 * @param optname Stack-specific option identifier 00296 * @param optval Destination for option value 00297 * @param optlen Length of the option value 00298 * @return 0 on success, negative error code on failure 00299 */ 00300 virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, 00301 int optname, void *optval, unsigned *optlen); 00302 }; 00303 00304 00305 /** Convert a raw nsapi_stack_t object into a C++ NetworkStack object 00306 * 00307 * @param stack Reference to an object that can be converted to a stack 00308 * - A raw nsapi_stack_t object 00309 * - A reference to a network stack 00310 * - A reference to a network interface 00311 * @return Reference to the underlying network stack 00312 */ 00313 NetworkStack *nsapi_create_stack(nsapi_stack_t *stack); 00314 NetworkStack *nsapi_create_stack(NetworkStack *stack); 00315 00316 template <typename IF> 00317 NetworkStack *nsapi_create_stack(IF *iface) 00318 { 00319 return nsapi_create_stack(static_cast<NetworkInterface *>(iface)->get_stack()); 00320 } 00321 00322 00323 #endif
Generated on Sun Jul 17 2022 08:25:28 by 1.7.2