Delta
/
NNN50_WIFI_API
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.
Dependents: NNN50_CE_Test_UDP NNN50_linux_firmware NNN50_SoftAP_HelloWorld NNN50_BLEWIFISensor ... more
Embed:
(wiki syntax)
Show/hide line numbers
socket.h
Go to the documentation of this file.
00001 /** 00002 * 00003 * \file 00004 * 00005 * \brief WINC BSD compatible Socket Interface. 00006 * 00007 * Copyright (c) 2016-2017 Atmel Corporation. All rights reserved. 00008 * 00009 * \asf_license_start 00010 * 00011 * \page License 00012 * 00013 * Redistribution and use in source and binary forms, with or without 00014 * modification, are permitted provided that the following conditions are met: 00015 * 00016 * 1. Redistributions of source code must retain the above copyright notice, 00017 * this list of conditions and the following disclaimer. 00018 * 00019 * 2. Redistributions in binary form must reproduce the above copyright notice, 00020 * this list of conditions and the following disclaimer in the documentation 00021 * and/or other materials provided with the distribution. 00022 * 00023 * 3. The name of Atmel may not be used to endorse or promote products derived 00024 * from this software without specific prior written permission. 00025 * 00026 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 00027 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00028 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 00029 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 00030 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00031 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 00032 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00033 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 00034 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 00035 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 00036 * POSSIBILITY OF SUCH DAMAGE. 00037 * 00038 * \asf_license_stop 00039 * 00040 */ 00041 00042 #ifndef __SOCKET_H__ 00043 #define __SOCKET_H__ 00044 00045 #ifdef __cplusplus 00046 extern "C" { 00047 #endif 00048 00049 /** \defgroup SocketHeader Socket 00050 * BSD compatible socket interface beftween the host layer and the network 00051 * protocol stacks in the firmware. 00052 * These functions are used by the host application to send or receive 00053 * packets and to do other socket operations. 00054 */ 00055 00056 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* 00057 INCLUDES 00058 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ 00059 00060 #include "common/include/nm_common.h" 00061 #include "driver/include/m2m_types.h" 00062 00063 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* 00064 MACROS 00065 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ 00066 /** 00067 * @defgroup SocketDefines Defines 00068 * @ingroup SocketHeader 00069 */ 00070 00071 /** @defgroup IPDefines TCP/IP Defines 00072 * @ingroup SocketDefines 00073 * The following list of macros are used to define constants used throughout the socket layer. 00074 * @{ 00075 */ 00076 00077 /* 00078 * HOSTNAME_MAX_SIZE is defined here and also in host_drv/socket/include/m2m_socket_host_if.h 00079 * The two definitions must match. 00080 */ 00081 #define HOSTNAME_MAX_SIZE 64 00082 /*!< 00083 Maximum allowed size for a host domain name passed to the function gethostbyname @ref gethostbyname. 00084 command value. Used with the setsockopt function. 00085 00086 */ 00087 00088 #define SOCKET_BUFFER_MAX_LENGTH 1400 00089 /*!< 00090 Maximum allowed size for a socket data buffer. Used with @ref send socket 00091 function to ensure that the buffer sent is within the allowed range. 00092 */ 00093 00094 #define AF_INET 2 00095 /*!< 00096 The AF_INET is the address family used for IPv4. An IPv4 transport address is specified with the @ref sockaddr_in structure. 00097 (It is the only supported type for the current implementation.) 00098 */ 00099 00100 00101 #define SOCK_STREAM 1 00102 /*!< 00103 One of the IPv4 supported socket types for reliable connection-oriented stream connection. 00104 Passed to the @ref socket function for the socket creation operation. 00105 */ 00106 00107 #define SOCK_DGRAM 2 00108 /*!< 00109 One of the IPv4 supported socket types for unreliable connectionless datagram connection. 00110 Passed to the @ref socket function for the socket creation operation. 00111 */ 00112 00113 00114 #define SOCKET_FLAGS_SSL 0x01 00115 /*!< 00116 This flag shall be passed to the socket API for SSL session. 00117 */ 00118 00119 #define TCP_SOCK_MAX (7) 00120 /*!< 00121 Maximum number of simultaneous TCP sockets. 00122 */ 00123 00124 #define UDP_SOCK_MAX 4 00125 /*!< 00126 Maximum number of simultaneous UDP sockets. 00127 */ 00128 00129 #define MAX_SOCKET (TCP_SOCK_MAX + UDP_SOCK_MAX) 00130 /*!< 00131 Maximum number of Sockets. 00132 */ 00133 00134 #define SOL_SOCKET 1 00135 /*!< 00136 Socket option. 00137 Used with the @ref setsockopt function 00138 */ 00139 00140 #define SOL_SSL_SOCKET 2 00141 /*!< 00142 SSL Socket option level. 00143 Used with the @ref setsockopt function 00144 */ 00145 00146 #define SO_SET_UDP_SEND_CALLBACK 0x00 00147 /*!< 00148 Socket option used by the application to enable/disable 00149 the use of UDP send callbacks. 00150 Used with the @ref setsockopt function. 00151 */ 00152 00153 #define IP_ADD_MEMBERSHIP 0x01 00154 /*!< 00155 Set Socket Option Add Membership command value (to join a multicast group). 00156 Used with the @ref setsockopt function. 00157 */ 00158 00159 00160 #define IP_DROP_MEMBERSHIP 0x02 00161 /*!< 00162 Set Socket Option Drop Membership command value (to leave a multicast group). 00163 Used with the @ref setsockopt function. 00164 */ 00165 //@} 00166 00167 00168 00169 /** 00170 * @defgroup TLSDefines TLS Defines 00171 * @ingroup SocketDefines 00172 */ 00173 00174 00175 00176 /** @defgroup SSLSocketOptions TLS Socket Options 00177 * @ingroup TLSDefines 00178 * The following list of macros are used to define SSL Socket options. 00179 * @{ 00180 * @sa setsockopt 00181 */ 00182 00183 #define SO_SSL_BYPASS_X509_VERIF 0x01 00184 /*!< 00185 Allow an opened SSL socket to bypass the X509 certificate 00186 verification process. 00187 It is highly required NOT to use this socket option in production 00188 software applications. It is supported for debugging and testing 00189 purposes. 00190 The option value should be casted to int type and it is handled 00191 as a boolean flag. 00192 */ 00193 00194 00195 #define SO_SSL_SNI 0x02 00196 /*!< 00197 Set the Server Name Indicator (SNI) for an SSL socket. The 00198 SNI is a NULL terminated string containing the server name 00199 associated with the connection. It must not exceed the size 00200 of HOSTNAME_MAX_SIZE. 00201 */ 00202 00203 00204 #define SO_SSL_ENABLE_SESSION_CACHING 0x03 00205 /*!< 00206 This option allow the TLS to cache the session information for fast 00207 TLS session establishment in future connections using the 00208 TLS Protocol session resume features. 00209 */ 00210 00211 00212 #define SO_SSL_ENABLE_SNI_VALIDATION 0x04 00213 /*!< 00214 Enable SNI validation against the server's certificate subject 00215 common name. If there is no SNI provided (via the SO_SSL_SNI 00216 option), setting this option does nothing. 00217 */ 00218 00219 00220 //@} 00221 00222 00223 00224 /** @defgroup LegacySSLCipherSuite Legacy names for TLS Cipher Suite IDs 00225 * @ingroup TLSDefines 00226 * The following list of macros MUST NOT be used. Instead use the new names under SSLCipherSuiteID 00227 * @sa sslSetActiveCipherSuites 00228 * @{ 00229 */ 00230 00231 #define SSL_ENABLE_RSA_SHA_SUITES 0x01 00232 /*!< 00233 Enable RSA Hmac_SHA based Cipher suites. For example, 00234 TLS_RSA_WITH_AES_128_CBC_SHA 00235 */ 00236 00237 00238 #define SSL_ENABLE_RSA_SHA256_SUITES 0x02 00239 /*!< 00240 Enable RSA Hmac_SHA256 based Cipher suites. For example, 00241 TLS_RSA_WITH_AES_128_CBC_SHA256 00242 */ 00243 00244 00245 #define SSL_ENABLE_DHE_SHA_SUITES 0x04 00246 /*!< 00247 Enable DHE Hmac_SHA based Cipher suites. For example, 00248 TLS_DHE_RSA_WITH_AES_128_CBC_SHA 00249 */ 00250 00251 00252 #define SSL_ENABLE_DHE_SHA256_SUITES 0x08 00253 /*!< 00254 Enable DHE Hmac_SHA256 based Cipher suites. For example, 00255 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 00256 */ 00257 00258 00259 #define SSL_ENABLE_RSA_GCM_SUITES 0x10 00260 /*!< 00261 Enable RSA AEAD based Cipher suites. For example, 00262 TLS_RSA_WITH_AES_128_GCM_SHA256 00263 */ 00264 00265 00266 #define SSL_ENABLE_DHE_GCM_SUITES 0x20 00267 /*!< 00268 Enable DHE AEAD based Cipher suites. For example, 00269 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 00270 */ 00271 00272 00273 #define SSL_ENABLE_ALL_SUITES 0x0000003F 00274 /*!< 00275 Enable all possible supported cipher suites. 00276 */ 00277 00278 //@} 00279 00280 00281 00282 /** @defgroup SSLCipherSuiteID TLS Cipher Suite IDs 00283 * @ingroup TLSDefines 00284 * The following list of macros defined the list of supported TLS Cipher suites. 00285 * Each MACRO defines a single Cipher suite. 00286 * @sa m2m_ssl_set_active_ciphersuites 00287 * @{ 00288 */ 00289 00290 #define SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA NBIT0 00291 #define SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA256 NBIT1 00292 #define SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA NBIT2 00293 #define SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA256 NBIT3 00294 #define SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 NBIT4 00295 #define SSL_CIPHER_DHE_RSA_WITH_AES_128_GCM_SHA256 NBIT5 00296 #define SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA NBIT6 00297 #define SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA256 NBIT7 00298 #define SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA NBIT8 00299 #define SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA256 NBIT9 00300 #define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA NBIT10 00301 #define SSL_CIPHER_ECDHE_RSA_WITH_AES_256_CBC_SHA NBIT11 00302 #define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA256 NBIT12 00303 #define SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 NBIT13 00304 #define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_GCM_SHA256 NBIT14 00305 #define SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 NBIT15 00306 00307 00308 00309 #define SSL_ECC_ONLY_CIPHERS \ 00310 (\ 00311 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | \ 00312 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 \ 00313 ) 00314 /*!< 00315 All ciphers that use ECC crypto only. This execuldes ciphers that use RSA. They use ECDSA instead. 00316 These ciphers are turned off by default at startup. 00317 The application may enable them if it has an ECC math engine (like ATECC508). 00318 */ 00319 #define SSL_ECC_ALL_CIPHERS \ 00320 (\ 00321 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA | \ 00322 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | \ 00323 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | \ 00324 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | \ 00325 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 \ 00326 ) 00327 /*!< 00328 All supported ECC Ciphers including those ciphers that depend on RSA and ECC. 00329 These ciphers are turned off by default at startup. 00330 The application may enable them if it has an ECC math engine (like ATECC508). 00331 */ 00332 00333 #define SSL_NON_ECC_CIPHERS_AES_128 \ 00334 (\ 00335 SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA | \ 00336 SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA256 | \ 00337 SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA | \ 00338 SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA256 | \ 00339 SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 | \ 00340 SSL_CIPHER_DHE_RSA_WITH_AES_128_GCM_SHA256 \ 00341 ) 00342 /*!< 00343 All supported AES-128 Ciphers (ECC ciphers are not counted). This is the default active group after startup. 00344 */ 00345 00346 00347 #define SSL_ECC_CIPHERS_AES_256 \ 00348 (\ 00349 SSL_CIPHER_ECDHE_RSA_WITH_AES_256_CBC_SHA \ 00350 ) 00351 /*!< 00352 ECC AES-256 supported ciphers. 00353 */ 00354 00355 00356 #define SSL_NON_ECC_CIPHERS_AES_256 \ 00357 (\ 00358 SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA | \ 00359 SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA256 | \ 00360 SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA | \ 00361 SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA256 \ 00362 ) 00363 /*!< 00364 AES-256 Ciphers. 00365 This group is disabled by default at startup because the WINC1500 HW Accelerator 00366 supports only AES-128. If the application needs to force AES-256 cipher support, 00367 it could enable them (or any of them) explicitly by calling sslSetActiveCipherSuites. 00368 */ 00369 00370 00371 #define SSL_CIPHER_ALL \ 00372 (\ 00373 SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA | \ 00374 SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA256 | \ 00375 SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA | \ 00376 SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA256 | \ 00377 SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 | \ 00378 SSL_CIPHER_DHE_RSA_WITH_AES_128_GCM_SHA256 | \ 00379 SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA | \ 00380 SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA256 | \ 00381 SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA | \ 00382 SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA256 | \ 00383 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA | \ 00384 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | \ 00385 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | \ 00386 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | \ 00387 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | \ 00388 SSL_CIPHER_ECDHE_RSA_WITH_AES_256_CBC_SHA \ 00389 ) 00390 /*!< 00391 Turn On All TLS Ciphers. 00392 */ 00393 00394 00395 //@} 00396 00397 00398 00399 00400 /************** 00401 Socket Errors 00402 **************/ 00403 /**@defgroup SocketErrorCode Error Codes 00404 * @ingroup SocketHeader 00405 * The following list of macros are used to define the possible error codes returned as a result of a call to a socket function. 00406 * Errors are listed in numerical order with the error macro name. 00407 * @{ 00408 */ 00409 #define SOCK_ERR_NO_ERROR 0 00410 /*!< 00411 Successful socket operation 00412 */ 00413 00414 00415 #define SOCK_ERR_INVALID_ADDRESS -1 00416 /*!< 00417 Socket address is invalid. The socket operation cannot be completed successfully without specifying a specific address 00418 For example: bind is called without specifying a port number 00419 */ 00420 00421 00422 #define SOCK_ERR_ADDR_ALREADY_IN_USE -2 00423 /*!< 00424 Socket operation cannot bind on the given address. With socket operations, only one IP address per socket is permitted. 00425 Any attempt for a new socket to bind with an IP address already bound to another open socket, 00426 will return the following error code. States that bind operation failed. 00427 */ 00428 00429 00430 #define SOCK_ERR_MAX_TCP_SOCK -3 00431 /*!< 00432 Exceeded the maximum number of TCP sockets. A maximum number of TCP sockets opened simultaneously is defined through TCP_SOCK_MAX. 00433 It is not permitted to exceed that number at socket creation. Identifies that @ref socket operation failed. 00434 */ 00435 00436 00437 #define SOCK_ERR_MAX_UDP_SOCK -4 00438 /*!< 00439 Exceeded the maximum number of UDP sockets. A maximum number of UDP sockets opened simultaneously is defined through UDP_SOCK_MAX. 00440 It is not permitted to exceed that number at socket creation. Identifies that @ref socket operation failed 00441 */ 00442 00443 00444 #define SOCK_ERR_INVALID_ARG -6 00445 /*!< 00446 An invalid argument is passed to a function. 00447 */ 00448 00449 00450 #define SOCK_ERR_MAX_LISTEN_SOCK -7 00451 /*!< 00452 Exceeded the maximum number of TCP passive listening sockets. 00453 Identifies Identifies that @ref listen operation failed. 00454 */ 00455 00456 00457 #define SOCK_ERR_INVALID -9 00458 /*!< 00459 The requested socket operation is not valid in the 00460 current socket state. 00461 For example: @ref accept is called on a TCP socket before @ref bind or @ref listen. 00462 */ 00463 00464 00465 #define SOCK_ERR_ADDR_IS_REQUIRED -11 00466 /*!< 00467 Destination address is required. Failure to provide the socket address required for the socket operation to be completed. 00468 It is generated as an error to the @ref sendto function when the address required to send the data to is not known. 00469 */ 00470 00471 00472 #define SOCK_ERR_CONN_ABORTED -12 00473 /*!< 00474 The socket is closed by the peer. The local socket is 00475 closed also. 00476 */ 00477 00478 00479 #define SOCK_ERR_TIMEOUT -13 00480 /*!< 00481 The socket pending operation has Timedout. 00482 */ 00483 00484 00485 #define SOCK_ERR_BUFFER_FULL -14 00486 /*!< 00487 No buffer space available to be used for the requested socket operation. 00488 */ 00489 00490 #ifdef _NM_BSP_BIG_END 00491 00492 #define _htonl(m) (m) 00493 #define _htons(A) (A) 00494 00495 #else 00496 00497 #define _htonl(m) \ 00498 (uint32)(((uint32)(m << 24)) | ((uint32)((m & 0x0000FF00) << 8)) | ((uint32)((m & 0x00FF0000) >> 8)) | ((uint32)(m >> 24))) 00499 /*!< 00500 Convert a 4-byte integer from the host representation to the Network byte order representation. 00501 */ 00502 00503 00504 #define _htons(A) (uint16)((((uint16) (A)) << 8) | (((uint16) (A)) >> 8)) 00505 /*!< 00506 Convert a 2-byte integer (short) from the host representation to the Network byte order representation. 00507 */ 00508 00509 00510 #endif 00511 00512 00513 #define _ntohl _htonl 00514 /*!< 00515 Convert a 4-byte integer from the Network byte order representation to the host representation . 00516 */ 00517 00518 00519 #define _ntohs _htons 00520 /*!< 00521 Convert a 2-byte integer from the Network byte order representation to the host representation . 00522 */ 00523 //@} 00524 00525 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* 00526 DATA TYPES 00527 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ 00528 /** @defgroup SocketEnums DataTypes 00529 * @ingroup SocketHeader 00530 * Specific Enumeration-typedefs used for socket operations 00531 * @{ */ 00532 00533 /*! 00534 @typedef \ 00535 SOCKET 00536 00537 @brief 00538 Definition for socket handler data type. 00539 Socket ID,used with all socket operations to uniquely identify the socket handler. 00540 Such an ID is uniquely assigned at socket creation when calling @ref socket operation. 00541 */ 00542 typedef sint8 SOCKET; 00543 00544 00545 00546 /*! 00547 @struct \ 00548 in_addr 00549 00550 @brief 00551 IPv4 address representation. 00552 00553 This structure is used as a placeholder for IPV4 address in other structures. 00554 @see 00555 sockaddr_in 00556 */ 00557 typedef struct{ 00558 uint32 s_addr; 00559 /*!< 00560 Network Byte Order representation of the IPv4 address. For example, 00561 the address "192.168.0.10" is represented as 0x0A00A8C0. 00562 */ 00563 }in_addr; 00564 00565 00566 /*! 00567 @struct \ 00568 sockaddr 00569 00570 @brief 00571 Generic socket address structure. 00572 00573 @see 00574 sockaddr_in 00575 */ 00576 struct sockaddr{ 00577 uint16 sa_family ; 00578 /*!< 00579 Socket address family. 00580 */ 00581 uint8 sa_data [14]; 00582 /*!< 00583 Maximum size of all the different socket address structures. 00584 */ 00585 }; 00586 00587 00588 /*! 00589 @struct \ 00590 sockaddr_in 00591 00592 @brief 00593 Socket address structure for IPV4 addresses. Used to specify socket address information to which to connect to. 00594 Can be cast to @ref sockaddr structure. 00595 */ 00596 struct sockaddr_in{ 00597 uint16 sin_family ; 00598 /*!< 00599 Specifies the address family(AF). 00600 Members of AF_INET address family are IPv4 addresses. 00601 Hence,the only supported value for this is AF_INET. 00602 */ 00603 uint16 sin_port ; 00604 /*!< 00605 Port number of the socket. 00606 Network sockets are identified by a pair of IP addresses and port number. 00607 It must be set in the Network Byte Order format , @ref _htons (e.g. _htons(80)). 00608 Can NOT have zero value. 00609 */ 00610 in_addr sin_addr ; 00611 /*!< 00612 IP Address of the socket. 00613 The IP address is of type @ref in_addr structure. 00614 Can be set to "0" to accept any IP address for server operation. non zero otherwise. 00615 */ 00616 uint8 sin_zero [8]; 00617 /*!< 00618 Padding to make structure the same size as @ref sockaddr. 00619 */ 00620 }; 00621 //@} 00622 /**@defgroup AsyncCalback Asynchronous Events 00623 * @ingroup SocketEnums 00624 * Specific Enumeration used for asynchronous operations 00625 * @{ */ 00626 /*! 00627 @enum \ 00628 tenuSocketCallbackMsgType 00629 00630 @brief 00631 Asynchronous APIs, make use of callback functions, in-order to return back the results once the corresponding socket operation is completed. 00632 Hence resuming the normal execution of the application code while the socket operation returns the results. 00633 Callback functions expect event messages to be passed in, in-order to identify the operation they're returning the results for. 00634 The following enum identifies the type of events that are received in the callback function. 00635 00636 Application Use: 00637 In order for application developers to handle the pending events from the network controller through the callback functions. 00638 A function call must be made to the function @ref m2m_wifi_handle_events at least once for each socket operation. 00639 00640 @see 00641 bind 00642 listen 00643 accept 00644 connect 00645 send 00646 recv 00647 00648 */ 00649 typedef enum{ 00650 SOCKET_MSG_BIND = 1, 00651 /*!< 00652 Bind socket event. 00653 */ 00654 SOCKET_MSG_LISTEN , 00655 /*!< 00656 Listen socket event. 00657 */ 00658 SOCKET_MSG_DNS_RESOLVE , 00659 /*!< 00660 DNS Resolution event. 00661 */ 00662 SOCKET_MSG_ACCEPT , 00663 /*!< 00664 Accept socket event. 00665 */ 00666 SOCKET_MSG_CONNECT , 00667 /*!< 00668 Connect socket event. 00669 */ 00670 SOCKET_MSG_RECV , 00671 /*!< 00672 Receive socket event. 00673 */ 00674 SOCKET_MSG_SEND , 00675 /*!< 00676 Send socket event. 00677 */ 00678 SOCKET_MSG_SENDTO , 00679 /*!< 00680 sendto socket event. 00681 */ 00682 SOCKET_MSG_RECVFROM 00683 /*!< 00684 Recvfrom socket event. 00685 */ 00686 }tenuSocketCallbackMsgType; 00687 00688 00689 /*! 00690 @struct \ 00691 tstrSocketBindMsg 00692 00693 @brief Socket bind status. 00694 00695 An asynchronous call to the @ref bind socket operation, returns information through this structure in response. 00696 This structure together with the event @ref SOCKET_MSG_BIND are passed in paramters to the callback function. 00697 @see 00698 bind 00699 00700 */ 00701 typedef struct{ 00702 sint8 status; 00703 /*!< 00704 The result of the bind operation. 00705 Holding a value of ZERO for a successful bind or otherwise a negative 00706 error code corresponding to the type of error. 00707 */ 00708 }tstrSocketBindMsg; 00709 00710 00711 /*! 00712 @struct \ 00713 tstrSocketListenMsg 00714 00715 @brief Socket listen status. 00716 00717 Socket listen information is returned through this structure in response to the asynchronous call to the @ref listen function. 00718 This structure together with the event @ref SOCKET_MSG_LISTEN are passed-in parameters to the callback function. 00719 @see 00720 listen 00721 */ 00722 typedef struct{ 00723 sint8 status; 00724 /*!< 00725 Holding a value of ZERO for a successful listen or otherwise a negative 00726 error code corresponding to the type of error. 00727 */ 00728 }tstrSocketListenMsg; 00729 00730 00731 00732 /*! 00733 @struct \ 00734 tstrSocketAcceptMsg 00735 00736 @brief Socket accept status. 00737 00738 Socket accept information is returned through this structure in response to the asynchronous call to the @ref accept function. 00739 This structure together with the event @ref SOCKET_MSG_ACCEPT are passed-in parameters to the callback function. 00740 */ 00741 typedef struct{ 00742 SOCKET sock; 00743 /*!< 00744 On a successful @ref accept operation, the return information is the socket ID for the accepted connection with the remote peer. 00745 Otherwise a negative error code is returned to indicate failure of the accept operation. 00746 */ 00747 struct sockaddr_in strAddr; 00748 /*!< 00749 Socket address structure for the remote peer. 00750 */ 00751 }tstrSocketAcceptMsg; 00752 00753 00754 /*! 00755 @struct \ 00756 tstrSocketConnectMsg 00757 00758 @brief Socket connect status. 00759 00760 Socket connect information is returned through this structure in response to the asynchronous call to the @ref connect socket function. 00761 This structure together with the event @ref SOCKET_MSG_CONNECT are passed-in parameters to the callback function. 00762 */ 00763 typedef struct{ 00764 SOCKET sock; 00765 /*!< 00766 Socket ID referring to the socket passed to the connect function call. 00767 */ 00768 sint8 s8Error; 00769 /*!< 00770 Connect error code. 00771 Holding a value of ZERO for a successful connect or otherwise a negative 00772 error code corresponding to the type of error. 00773 */ 00774 }tstrSocketConnectMsg; 00775 00776 00777 /*! 00778 @struct \ 00779 tstrSocketRecvMsg 00780 00781 @brief Socket recv status. 00782 00783 Socket receive information is returned through this structure in response to the asynchronous call to the recv or recvfrom socket functions. 00784 This structure together with the events @ref SOCKET_MSG_RECV or @ref SOCKET_MSG_RECVFROM are passed-in parameters to the callback function. 00785 @remark 00786 In case the received data from the remote peer is larger than the USER buffer size defined during the asynchronous call to the @ref recv function, the data is 00787 delivered to the user in a number of consecutive chunks according to the USER Buffer size. 00788 a negative or zero buffer size indicates an error with the following code: 00789 @ref SOCK_ERR_NO_ERROR : Socket connection closed 00790 @ref SOCK_ERR_CONN_ABORTED : Socket connection aborted 00791 @SOCK_ERR_TIMEOUT : Socket receive timed out 00792 */ 00793 typedef struct{ 00794 uint8 *pu8Buffer; 00795 /*!< 00796 Pointer to the USER buffer (passed to @ref recv and @ref recvfrom function) containing the received data chunk. 00797 */ 00798 sint16 s16BufferSize; 00799 /*!< 00800 The received data chunk size. 00801 Holds a negative value if there is a receive error or ZERO on success upon reception of close socket message. 00802 */ 00803 uint16 u16RemainingSize; 00804 /*!< 00805 The number of bytes remaining in the current @ref recv operation. 00806 */ 00807 struct sockaddr_in strRemoteAddr; 00808 /*!< 00809 Socket address structure for the remote peer. It is valid for @ref SOCKET_MSG_RECVFROM event. 00810 */ 00811 }tstrSocketRecvMsg; 00812 00813 00814 /*! 00815 @typedef \ 00816 tpfAppSocketCb 00817 00818 @brief 00819 The main socket application callback function. Applications register their main socket application callback through this function by calling @ref registerSocketCallback. 00820 In response to events received, the following callback function is called to handle the corresponding asynchronous function called. Example: @ref bind, @ref connect,...etc. 00821 00822 @param [in] sock 00823 Socket ID for the callback. 00824 00825 The socket callback function is called whenever a new event is recived in response 00826 to socket operations. 00827 00828 @param [in] u8Msg 00829 Socket event type. Possible values are: 00830 - @ref SOCKET_MSG_BIND 00831 - @ref SOCKET_MSG_LISTEN 00832 - @ref SOCKET_MSG_ACCEPT 00833 - @ref SOCKET_MSG_CONNECT 00834 - @ref SOCKET_MSG_RECV 00835 - @ref SOCKET_MSG_SEND 00836 - @ref SOCKET_MSG_SENDTO 00837 - @ref SOCKET_MSG_RECVFROM 00838 00839 @param [in] pvMsg 00840 Pointer to message structure. Existing types are: 00841 - tstrSocketBindMsg 00842 - tstrSocketListenMsg 00843 - tstrSocketAcceptMsg 00844 - tstrSocketConnectMsg 00845 - tstrSocketRecvMsg 00846 00847 @see 00848 tenuSocketCallbackMsgType 00849 tstrSocketRecvMsg 00850 tstrSocketConnectMsg 00851 tstrSocketAcceptMsg 00852 tstrSocketListenMsg 00853 tstrSocketBindMsg 00854 */ 00855 typedef void (*tpfAppSocketCb) (SOCKET sock, uint8 u8Msg, void * pvMsg); 00856 00857 00858 /*! 00859 @typedef \ 00860 tpfAppResolveCb 00861 00862 @brief 00863 DNS resolution callback function. 00864 Applications requiring DNS resolution should register their callback through this function by calling @ref registerSocketCallback. 00865 The following callback is triggered in response to asynchronous call to the @ref gethostbyname function (DNS Resolution callback). 00866 00867 @param [in] pu8DomainName 00868 Domain name of the host. 00869 00870 @param [in] u32ServerIP 00871 Server IPv4 address encoded in NW byte order format. If it is Zero, then the DNS resolution failed. 00872 */ 00873 typedef void (*tpfAppResolveCb) (uint8* pu8DomainName, uint32 u32ServerIP); 00874 00875 /*! 00876 @typedef \ 00877 tpfPingCb 00878 00879 @brief PING Callback 00880 00881 The function delivers the ping statistics for the sent ping triggered by calling 00882 m2m_ping_req. 00883 00884 @param [in] u32IPAddr 00885 Destination IP. 00886 00887 @param [in] u32RTT 00888 Round Trip Time. 00889 00890 @param [in] u8ErrorCode 00891 Ping error code. It may be one of: 00892 - PING_ERR_SUCCESS 00893 - PING_ERR_DEST_UNREACH 00894 - PING_ERR_TIMEOUT 00895 */ 00896 typedef void (*tpfPingCb)(uint32 u32IPAddr, uint32 u32RTT, uint8 u8ErrorCode); 00897 00898 /**@}*/ 00899 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* 00900 FUNCTION PROTOTYPES 00901 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ 00902 /** \defgroup SocketAPI Function 00903 * @ingroup SocketHeader 00904 */ 00905 00906 /** @defgroup SocketInitalizationFn socketInit 00907 * @ingroup SocketAPI 00908 * The function performs the necessary initializations for the socket library through the following steps: 00909 - A check made by the global variable gbSocketInit, ensuring that initialization for sockets is performed only once, 00910 in-order to prevent reseting the socket instances already created in the global socket array (gastrSockets). 00911 - Zero initializations to the global socket array (gastrSockets), which holds the list of TCP sockets. 00912 - Registers the socket (Host Interface)hif callback function through the call to the hif_register_cb function. 00913 This facilitates handling all of the socket related functions received through interrupts from the firmware. 00914 00915 */ 00916 /**@{*/ 00917 /*! 00918 @fn \ 00919 NMI_API void socketInit(void); 00920 00921 @param [in] void 00922 00923 @return void 00924 00925 @remarks 00926 This initialization function must be invoked before any socket operation is performed. 00927 No error codes from this initialization function since the socket array is statically allocated based in the maximum number of 00928 sockets @ref MAX_SOCKET based on the systems capability. 00929 \section Example 00930 This example demonstrates the use of the socketinit for socket initialization for an mqtt chat application. 00931 \code 00932 tstrWifiInitParam param; 00933 int8_t ret; 00934 char topic[strlen(MAIN_CHAT_TOPIC) + MAIN_CHAT_USER_NAME_SIZE + 1]; 00935 00936 //Initialize the board. 00937 system_init(); 00938 00939 //Initialize the UART console. 00940 configure_console(); 00941 00942 // Initialize the BSP. 00943 nm_bsp_init(); 00944 00945 ---------- 00946 00947 // Initialize socket interface. 00948 socketInit(); 00949 registerSocketCallback(socket_event_handler, socket_resolve_handler); 00950 00951 // Connect to router. 00952 m2m_wifi_connect((char *)MAIN_WLAN_SSID, sizeof(MAIN_WLAN_SSID), 00953 MAIN_WLAN_AUTH, (char *)MAIN_WLAN_PSK, M2M_WIFI_CH_ALL); 00954 00955 \endcode 00956 */ 00957 NMI_API void socketInit (void); 00958 00959 00960 /*! 00961 @fn \ 00962 NMI_API void socketDeinit(void); 00963 00964 @brief Socket Layer De-initialization 00965 00966 The function performs the necessary cleanup for the socket library static data 00967 It must be invoked as the last any socket operation is performed on any active sockets. 00968 */ 00969 NMI_API void socketDeinit(void); 00970 00971 00972 /** @} */ 00973 /** @defgroup SocketCallbackFn registerSocketCallback 00974 * @ingroup SocketAPI 00975 Register two callback functions one for asynchronous socket events and the other one for DNS callback registering function. 00976 The registered callback functions are used to retrieve information in response to the asynchronous socket functions called. 00977 */ 00978 /**@{*/ 00979 00980 00981 /*! 00982 @fn \ 00983 NMI_API void registerSocketCallback(tpfAppSocketCb socket_cb, tpfAppResolveCb resolve_cb); 00984 00985 @param [in] tpfAppSocketCb 00986 Assignment of callback function to the global callback @ref tpfAppSocketCb gpfAppSocketCb. Delivers 00987 socket messages to the host application. In response to the asynchronous function calls, such as @ref bind 00988 @ref listen @ref accept @ref connect 00989 00990 @param [in] tpfAppResolveCb 00991 Assignment of callback function to the global callback @ref tpfAppResolveCb gpfAppResolveCb. 00992 Used for DNS resolving functionalities. The DNS resolving technique is determined by the application 00993 registering the callback. 00994 NULL is assigned when, DNS resolution is not required. 00995 00996 @return void 00997 @remarks 00998 If any of the socket functionalities is not to be used, NULL is passed in as a parameter. 00999 It must be invoked after socketinit and before other socket layer operations. 01000 01001 \section Example 01002 This example demonstrates the use of the registerSocketCallback to register a socket callback function with DNS resolution CB set to null 01003 for a simple UDP server example. 01004 \code 01005 tstrWifiInitParam param; 01006 int8_t ret; 01007 struct sockaddr_in addr; 01008 01009 // Initialize the board 01010 system_init(); 01011 01012 //Initialize the UART console. 01013 configure_console(); 01014 01015 // Initialize the BSP. 01016 nm_bsp_init(); 01017 01018 // Initialize socket address structure. 01019 addr.sin_family = AF_INET; 01020 addr.sin_port = _htons(MAIN_WIFI_M2M_SERVER_PORT); 01021 addr.sin_addr.s_addr = _htonl(MAIN_WIFI_M2M_SERVER_IP); 01022 01023 // Initialize Wi-Fi parameters structure. 01024 memset((uint8_t *)¶m, 0, sizeof(tstrWifiInitParam)); 01025 01026 // Initialize Wi-Fi driver with data and status callbacks. 01027 param.pfAppWifiCb = wifi_cb; 01028 ret = m2m_wifi_init(¶m); 01029 if (M2M_SUCCESS != ret) { 01030 printf("main: m2m_wifi_init call error!(%d)\r\n", ret); 01031 while (1) { 01032 } 01033 } 01034 01035 // Initialize socket module 01036 socketInit(); 01037 registerSocketCallback(socket_cb, NULL); 01038 01039 // Connect to router. 01040 m2m_wifi_connect((char *)MAIN_WLAN_SSID, sizeof(MAIN_WLAN_SSID), MAIN_WLAN_AUTH, (char *)MAIN_WLAN_PSK, M2M_WIFI_CH_ALL); 01041 \endcode 01042 */ 01043 NMI_API void registerSocketCallback (tpfAppSocketCb socket_cb, tpfAppResolveCb resolve_cb); 01044 01045 01046 /** @} */ 01047 01048 /** @defgroup SocketFn socket 01049 * @ingroup SocketAPI 01050 * Synchronous socket allocation function based on the specified socket type. Created sockets are non-blocking and their possible types are either TCP or a UDP sockets. 01051 * The maximum allowed number of TCP sockets is @ref TCP_SOCK_MAX sockets while the maximum number of UDP sockets that can be created simultaneously is @ref UDP_SOCK_MAX sockets. 01052 * 01053 */ 01054 /**@{*/ 01055 /*! 01056 @fn \ 01057 NMI_API SOCKET socket(uint16 u16Domain, uint8 u8Type, uint8 u8Flags); 01058 01059 01060 @param [in] u16Domain 01061 Socket family. The only allowed value is AF_INET (IPv4.0) for TCP/UDP sockets. 01062 01063 @param [in] u8Type 01064 Socket type. Allowed values are: 01065 - [SOCK_STREAM](@ref SOCK_STREAM) 01066 - [SOCK_DGRAM](@ref SOCK_DGRAM) 01067 01068 @param [in] u8Flags 01069 Used to specify the socket creation flags. It shall be set to zero for normal TCP/UDP sockets. 01070 It could be @ref SOCKET_FLAGS_SSL if the socket is used for SSL session. The use of the flag 01071 @ref SOCKET_FLAGS_SSL has no meaning in case of UDP sockets. 01072 01073 @pre 01074 The @ref socketInit function must be called once at the beginning of the application to initialize the socket handler. 01075 before any call to the socket function can be made. 01076 01077 @see 01078 connect 01079 bind 01080 listen 01081 accept 01082 recv 01083 recvfrom 01084 send 01085 sendto 01086 close 01087 setsockopt 01088 getsockopt 01089 01090 @return 01091 On successful socket creation, a non-blocking socket type is created and a socket ID is returned 01092 In case of failure the function returns a negative value, identifying one of the socket error codes defined. 01093 For example: @ref SOCK_ERR_INVALID for invalid argument or 01094 @ref SOCK_ERR_MAX_TCP_SOCK if the number of TCP allocated sockets exceeds the number of available sockets. 01095 01096 @remarks 01097 The socket function must be called a priori to any other related socket functions "e.g. send, recv, close ..etc" 01098 \section Example 01099 This example demonstrates the use of the socket function to allocate the socket, returning the socket handler to be used for other 01100 socket operations. Socket creation is dependent on the socket type. 01101 \subsection sub1 UDP example 01102 @code 01103 SOCKET UdpServerSocket = -1; 01104 01105 UdpServerSocket = socket(AF_INET, SOCK_DGRAM, 0); 01106 01107 @endcode 01108 \subsection sub2 TCP example 01109 @code 01110 static SOCKET tcp_client_socket = -1; 01111 01112 tcp_client_socket = socket(AF_INET, SOCK_STREAM, 0)); 01113 @endcode 01114 \subsection sub3 SSL example 01115 @code 01116 static SOCKET ssl_socket = -1; 01117 01118 ssl_socket = socket(AF_INET, SOCK_STREAM, SOCK_FLAGS_SSL)); 01119 @endcode 01120 */ 01121 NMI_API SOCKET socket (uint16 u16Domain, uint8 u8Type, uint8 u8Flags); 01122 01123 01124 /** @} */ 01125 /** @defgroup BindFn bind 01126 * @ingroup SocketAPI 01127 * Asynchronous bind function associates the provided address and local port to the socket. 01128 * The function can be used with both TCP and UDP sockets it's mandatory to call the @ref bind function before starting any UDP or TCP server operation. 01129 * Upon socket bind completion, the application will receive a @ref SOCKET_MSG_BIND message in the socket callback. 01130 */ 01131 /**@{*/ 01132 /*! 01133 \fn \ 01134 NMI_API sint8 bind(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen); 01135 01136 01137 @param [in] sock 01138 Socket ID, must hold a non negative value. 01139 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01140 01141 @param [in] pstrAddr 01142 Pointer to socket address structure "sockaddr_in" 01143 [sockaddr_in](@ref sockaddr_in) 01144 01145 01146 @param [in] u8AddrLen 01147 Size of the given socket address structure in bytes. 01148 01149 @pre 01150 The socket function must be called to allocate a socket before passing the socket ID to the bind function. 01151 01152 @see 01153 socket 01154 connect 01155 listen 01156 accept 01157 recv 01158 recvfrom 01159 send 01160 sendto 01161 01162 @return 01163 The function returns ZERO for successful operations and a negative value otherwise. 01164 The possible error values are: 01165 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 01166 Indicating that the operation was successful. 01167 01168 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 01169 Indicating passing invalid arguments such as negative socket ID or NULL socket address structure. 01170 01171 - [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID) 01172 Indicate socket bind failure. 01173 \section Example 01174 This example demonstrates the call of the bind socket operation after a successful socket operation. 01175 @code 01176 struct sockaddr_in addr; 01177 SOCKET udpServerSocket =-1; 01178 int ret = -1; 01179 01180 if(udpServerSocket == -1) 01181 { 01182 udpServerSocket = socket(AF_INET, SOCK_DGRAM, 0); 01183 if(udpServerSocket >= 0) 01184 { 01185 addr.sin_family = AF_INET; 01186 addr.sin_port = _htons(1234); 01187 addr.sin_addr.s_addr = 0; 01188 ret = bind(udpServerSocket,(struct sockaddr*)&addr,sizeof(addr)); 01189 01190 if(ret != 0) 01191 { 01192 printf("Bind Failed. Error code = %d\n",ret); 01193 close(udpServerSocket); 01194 } 01195 } 01196 else 01197 { 01198 printf("UDP Server Socket Creation Failed\n"); 01199 return; 01200 } 01201 } 01202 @endcode 01203 */ 01204 NMI_API sint8 nmi_bind(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen);//Tsungta 01205 /** @} */ 01206 01207 /** @defgroup ListenFn listen 01208 * @ingroup SocketAPI 01209 * After successful socket binding to an IP address and port on the system, start listening on a passive socket for incoming connections. 01210 The socket must be bound on a local port or the listen operation fails. 01211 Upon the call to the asynchronous listen function, response is received through the event [SOCKET_MSG_BIND](@ref SOCKET_MSG_BIND) 01212 in the socket callback. 01213 A successful listen means the TCP server operation is active. If a connection is accepted, then the application socket callback function is 01214 notified with the new connected socket through the event @ref SOCKET_MSG_ACCEPT. Hence there is no need to call the @ref accept function 01215 after calling @ref listen. 01216 01217 After a connection is accepted, the user is then required to call the @ref recv to receive any packets transmitted by the remote host or to receive notification of socket connection 01218 termination. 01219 */ 01220 /**@{*/ 01221 /*! 01222 @fn \ 01223 NMI_API sint8 listen(SOCKET sock, uint8 backlog); 01224 01225 @param [in] sock 01226 Socket ID, must hold a non negative value. 01227 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01228 01229 @param [in] backlog 01230 Not used by the current implementation. 01231 01232 @pre 01233 The bind function must be called to assign the port number and IP address to the socket before the listen operation. 01234 01235 @see 01236 bind 01237 accept 01238 recv 01239 recvfrom 01240 send 01241 sendto 01242 01243 @return 01244 The function returns ZERO for successful operations and a negative value otherwise. 01245 The possible error values are: 01246 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 01247 Indicating that the operation was successful. 01248 01249 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 01250 Indicating passing invalid arguments such as negative socket ID. 01251 01252 - [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID) 01253 Indicate socket listen failure. 01254 \section Example 01255 This example demonstrates the call of the listen socket operation after a successful socket operation. 01256 @code 01257 static void TCP_Socketcallback(SOCKET sock, uint8 u8Msg, void * pvMsg) 01258 { 01259 int ret =-1; 01260 01261 switch(u8Msg) 01262 { 01263 case SOCKET_MSG_BIND: 01264 { 01265 tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg; 01266 if(pstrBind != NULL) 01267 { 01268 if(pstrBind->status == 0) 01269 { 01270 ret = listen(sock, 0); 01271 01272 if(ret <0) 01273 printf("Listen failure! Error = %d\n",ret); 01274 } 01275 else 01276 { 01277 M2M_ERR("bind Failure!\n"); 01278 close(sock); 01279 } 01280 } 01281 } 01282 break; 01283 01284 case SOCKET_MSG_LISTEN: 01285 { 01286 01287 tstrSocketListenMsg *pstrListen = (tstrSocketListenMsg*)pvMsg; 01288 if(pstrListen != NULL) 01289 { 01290 if(pstrListen->status == 0) 01291 { 01292 ret = accept(sock,NULL,0); 01293 } 01294 else 01295 { 01296 M2M_ERR("listen Failure!\n"); 01297 close(sock); 01298 } 01299 } 01300 } 01301 break; 01302 01303 case SOCKET_MSG_ACCEPT: 01304 { 01305 tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg*)pvMsg; 01306 01307 if(pstrAccept->sock >= 0) 01308 { 01309 TcpNotificationSocket = pstrAccept->sock; 01310 recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT); 01311 } 01312 else 01313 { 01314 M2M_ERR("accept failure\n"); 01315 } 01316 } 01317 break; 01318 01319 default: 01320 break; 01321 } 01322 } 01323 01324 @endcode 01325 */ 01326 NMI_API sint8 nmi_listen(SOCKET sock, uint8 backlog);//Tsungta 01327 /** @} */ 01328 /** @defgroup AcceptFn accept 01329 * @ingroup SocketAPI 01330 * The function has no current implementation. An empty deceleration is used to prevent errors when legacy application code is used. 01331 * For recent application use, the accept function can be safer as it has no effect and could be safely removed from any application using it. 01332 */ 01333 /**@{*/ 01334 /*! 01335 @fn \ 01336 NMI_API sint8 accept(SOCKET sock, struct sockaddr *addr, uint8 *addrlen); 01337 01338 @param [in] sock 01339 Socket ID, must hold a non negative value. 01340 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01341 @param [in] addr 01342 Not used in the current implementation. 01343 01344 @param [in] addrlen 01345 Not used in the current implementation. 01346 01347 @return 01348 The function returns ZERO for successful operations and a negative value otherwise. 01349 The possible error values are: 01350 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 01351 Indicating that the operation was successful. 01352 01353 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 01354 Indicating passing invalid arguments such as negative socket ID. 01355 */ 01356 NMI_API sint8 nmi_accept(SOCKET sock, struct sockaddr *addr, uint8 *addrlen);//Tsungta 01357 /** @} */ 01358 /** @defgroup ConnectFn connect 01359 * @ingroup SocketAPI 01360 * Establishes a TCP connection with a remote server. 01361 The asynchronous connect function must be called after receiving a valid socket ID from the @ref socket function. 01362 The application socket callback function is notified of a successful new socket connection through the event @ref SOCKET_MSG_CONNECT. 01363 A successful connect means the TCP session is active. The application is then required to make a call to the @ref recv 01364 to receive any packets transmitted by the remote server, unless the application is interrupted by a notification of socket connection 01365 termination. 01366 */ 01367 /**@{*/ 01368 /*! 01369 @fn \ 01370 NMI_API sint8 connect(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen); 01371 01372 @param [in] sock 01373 Socket ID, must hold a non negative value. 01374 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01375 01376 @param [in] pstrAddr 01377 Address of the remote server. 01378 @param [in] pstrAddr 01379 Pointer to socket address structure "sockaddr_in" 01380 [sockaddr_in](@ref sockaddr_in) 01381 01382 @param [in] u8AddrLen 01383 Size of the given socket address structure in bytes. 01384 Not currently used, implemented for BSD compatibility only. 01385 @pre 01386 The socket function must be called to allocate a TCP socket before passing the socket ID to the bind function. 01387 If the socket is not bound, you do NOT have to call bind before the "connect" function. 01388 01389 @see 01390 socket 01391 recv 01392 send 01393 close 01394 01395 @return 01396 The function returns ZERO for successful operations and a negative value otherwise. 01397 The possible error values are: 01398 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 01399 Indicating that the operation was successful. 01400 01401 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 01402 Indicating passing invalid arguments such as negative socket ID or NULL socket address structure. 01403 01404 - [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID) 01405 Indicate socket connect failure. 01406 \section Example 01407 The example demonstrates a TCP application, showing how the asynchronous call to the connect function is made through the main function and how the 01408 callback function handles the @ref SOCKET_MSG_CONNECT event. 01409 \subsection sub1 Main Function 01410 @code 01411 struct sockaddr_in Serv_Addr; 01412 SOCKET TcpClientSocket =-1; 01413 int ret = -1 01414 01415 TcpClientSocket = socket(AF_INET,SOCK_STREAM,0); 01416 Serv_Addr.sin_family = AF_INET; 01417 Serv_Addr.sin_port = _htons(1234); 01418 Serv_Addr.sin_addr.s_addr = inet_addr(SERVER); 01419 printf("Connected to server via socket %u\n",TcpClientSocket); 01420 01421 do 01422 { 01423 ret = connect(TcpClientSocket,(sockaddr_in*)&Serv_Addr,sizeof(Serv_Addr)); 01424 if(ret != 0) 01425 { 01426 printf("Connection Error\n"); 01427 } 01428 else 01429 { 01430 printf("Connection successful.\n"); 01431 break; 01432 } 01433 }while(1) 01434 @endcode 01435 \subsection sub2 Socket Callback 01436 @code 01437 if(u8Msg == SOCKET_MSG_CONNECT) 01438 { 01439 tstrSocketConnectMsg *pstrConnect = (tstrSocketConnectMsg*)pvMsg; 01440 if(pstrConnect->s8Error == 0) 01441 { 01442 uint8 acBuffer[GROWL_MSG_SIZE]; 01443 uint16 u16MsgSize; 01444 01445 printf("Connect success!\n"); 01446 01447 u16MsgSize = FormatMsg(u8ClientID, acBuffer); 01448 send(sock, acBuffer, u16MsgSize, 0); 01449 recv(pstrNotification->Socket, (void*)au8Msg,GROWL_DESCRIPTION_MAX_LENGTH, GROWL_RX_TIMEOUT); 01450 u8Retry = GROWL_CONNECT_RETRY; 01451 } 01452 else 01453 { 01454 M2M_DBG("Connection Failed, Error: %d\n",pstrConnect->s8Error"); 01455 close(pstrNotification->Socket); 01456 } 01457 } 01458 @endcode 01459 */ 01460 NMI_API sint8 nmi_connect(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen);//Tsungta 01461 /** @} */ 01462 /** @defgroup ReceiveFn recv 01463 * @ingroup SocketAPI 01464 * An asynchronous receive function, used to retrieve data from a TCP stream. 01465 Before calling the recv function, a successful socket connection status must have been received through any of the two socket events 01466 [SOCKET_MSG_CONNECT] or [SOCKET_MSG_ACCEPT], from the socket callback. Hence, indicating that the socket is already connected to a remote 01467 host. 01468 The application receives the required data in response to this asynchronous call through the reception of the event @ref SOCKET_MSG_RECV in the 01469 socket callback. 01470 01471 Receiving the SOCKET_MSG_RECV message in the callback with zero or negative buffer length indicates the following: 01472 - SOCK_ERR_NO_ERROR : Socket connection closed 01473 - SOCK_ERR_CONN_ABORTED : Socket connection aborted 01474 - SOCK_ERR_TIMEOUT : Socket receive timed out 01475 The application code is expected to close the socket through the call to the @ref close function upon the appearance of the above mentioned errors. 01476 */ 01477 /**@{*/ 01478 /*! 01479 @fn \ 01480 NMI_API sint16 recv(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec); 01481 01482 @param [in] sock 01483 Socket ID, must hold a non negative value. 01484 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01485 01486 01487 @param [in] pvRecvBuf 01488 Pointer to a buffer that will hold the received data. The buffer is used 01489 in the recv callback to deliver the received data to the caller. The buffer must 01490 be resident in memory (heap or global buffer). 01491 01492 @param [in] u16BufLen 01493 The buffer size in bytes. 01494 01495 @param [in] u32Timeoutmsec 01496 Timeout for the recv function in milli-seconds. If the value is set to ZERO, the timeout 01497 will be set to infinite (the recv function waits forever). If the timeout period is 01498 elapsed with no data received, the socket will get a timeout error. 01499 @pre 01500 - The socket function must be called to allocate a TCP socket before passing the socket ID to the recv function. 01501 - The socket in a connected state is expected to receive data through the socket interface. 01502 01503 @see 01504 socket 01505 connect 01506 bind 01507 listen 01508 recvfrom 01509 close 01510 01511 01512 @return 01513 The function returns ZERO for successful operations and a negative value otherwise. 01514 The possible error values are: 01515 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 01516 Indicating that the operation was successful. 01517 01518 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 01519 Indicating passing invalid arguments such as negative socket ID or NULL Recieve buffer. 01520 01521 - [SOCK_ERR_BUFFER_FULL](@ref SOCK_ERR_BUFFER_FULL) 01522 Indicate socket receive failure. 01523 \section Example 01524 The example demonstrates a code snippet for the calling of the recv function in the socket callback upon notification of the accept or connect events, and the parsing of the 01525 received data when the SOCKET_MSG_RECV event is received. 01526 @code 01527 01528 switch(u8Msg) 01529 { 01530 01531 case SOCKET_MSG_ACCEPT: 01532 { 01533 tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg*)pvMsg; 01534 01535 if(pstrAccept->sock >= 0) 01536 { 01537 recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT); 01538 } 01539 else 01540 { 01541 M2M_ERR("accept\n"); 01542 } 01543 } 01544 break; 01545 01546 01547 case SOCKET_MSG_RECV: 01548 { 01549 tstrSocketRecvMsg *pstrRx = (tstrSocketRecvMsg*)pvMsg; 01550 01551 if(pstrRx->s16BufferSize > 0) 01552 { 01553 01554 recv(sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT); 01555 } 01556 else 01557 { 01558 printf("Socet recv Error: %d\n",pstrRx->s16BufferSize); 01559 close(sock); 01560 } 01561 } 01562 break; 01563 01564 default: 01565 break; 01566 } 01567 } 01568 @endcode 01569 */ 01570 NMI_API sint16 recv (SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec); 01571 /** @} */ 01572 /** @defgroup ReceiveFromSocketFn recvfrom 01573 * @ingroup SocketAPI 01574 * Receives data from a UDP Socket. 01575 * 01576 * The asynchronous recvfrom function is used to retrieve data from a UDP socket. The socket must already be bound to 01577 * a local port before a call to the recvfrom function is made (i.e message @ref SOCKET_MSG_BIND is received 01578 * with successful status in the socket callback). 01579 * 01580 * Upon calling the recvfrom function with a successful return code, the application is expected to receive a notification 01581 * in the socket callback whenever a message is received through the @ref SOCKET_MSG_RECVFROM event. 01582 * 01583 * Receiving the SOCKET_MSG_RECVFROM message in the callback with zero, indicates that the socket is closed. 01584 * Whereby a negative buffer length indicates one of the socket error codes such as socket timeout error @SOCK_ERR_TIMEOUT: 01585 * 01586 * The recvfrom callback can also be used to show the IP address of the remote host that sent the frame by 01587 * using the "strRemoteAddr" element in the @ref tstrSocketRecvMsg structure. (refer to the code example) 01588 */ 01589 /**@{*/ 01590 /*! 01591 @fn \ 01592 NMI_API sint16 recvfrom(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32TimeoutSeconds); 01593 01594 @param [in] sock 01595 Socket ID, must hold a non negative value. 01596 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01597 01598 @param [in] pvRecvBuf 01599 Pointer to a buffer that will hold the received data. The buffer shall be used 01600 in the recv callback to deliver the received data to the caller. The buffer must 01601 be resident in memory (heap or global buffer). 01602 01603 @param [in] u16BufLen 01604 The buffer size in bytes. 01605 01606 @param [in] u32TimeoutSeconds 01607 Timeout for the recv function in milli-seconds. If the value is set to ZERO, the timeout 01608 will be set to infinite (the recv function waits forever). 01609 01610 @pre 01611 - The socket function must be called to allocate a UDP socket before passing the socket ID to the recvfrom function. 01612 - The socket corresponding to the socket ID must be successfully bound to a local port through the call to a @ref bind function. 01613 01614 @see 01615 socket 01616 bind 01617 close 01618 01619 @return 01620 The function returns ZERO for successful operations and a negative value otherwise. 01621 The possible error values are: 01622 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 01623 Indicating that the operation was successful. 01624 01625 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 01626 Indicating passing invalid arguments such as negative socket ID or NULL Receive buffer. 01627 01628 - [SOCK_ERR_BUFFER_FULL](@ref SOCK_ERR_BUFFER_FULL) 01629 Indicate socket receive failure. 01630 \section Example 01631 The example demonstrates a code snippet for the calling of the recvfrom function in the socket callback upon notification of a successful bind event, and the parsing of the 01632 received data when the SOCKET_MSG_RECVFROM event is received. 01633 @code 01634 switch(u8Msg) 01635 { 01636 01637 case SOCKET_MSG_BIND: 01638 { 01639 tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg; 01640 01641 if(pstrBind != NULL) 01642 { 01643 if(pstrBind->status == 0) 01644 { 01645 recvfrom(sock, gau8SocketTestBuffer, TEST_BUFFER_SIZE, 0); 01646 } 01647 else 01648 { 01649 M2M_ERR("bind\n"); 01650 } 01651 } 01652 } 01653 break; 01654 01655 01656 case SOCKET_MSG_RECVFROM: 01657 { 01658 tstrSocketRecvMsg *pstrRx = (tstrSocketRecvMsg*)pvMsg; 01659 01660 if(pstrRx->s16BufferSize > 0) 01661 { 01662 //get the remote host address and port number 01663 uint16 u16port = pstrRx->strRemoteAddr.sin_port; 01664 uint32 strRemoteHostAddr = pstrRx->strRemoteAddr.sin_addr.s_addr; 01665 01666 printf("Recieved frame with size = %d.\tHost address=%x, Port number = %d\n\n",pstrRx->s16BufferSize,strRemoteHostAddr, u16port); 01667 01668 ret = recvfrom(sock,gau8SocketTestBuffer,sizeof(gau8SocketTestBuffer),TEST_RECV_TIMEOUT); 01669 } 01670 else 01671 { 01672 printf("Socet recv Error: %d\n",pstrRx->s16BufferSize); 01673 ret = close(sock); 01674 } 01675 } 01676 break; 01677 01678 default: 01679 break; 01680 } 01681 } 01682 @endcode 01683 */ 01684 NMI_API sint16 recvfrom (SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec); 01685 /** @} */ 01686 /** @defgroup SendFn send 01687 * @ingroup SocketAPI 01688 * Asynchronous sending function, used to send data on a TCP/UDP socket. 01689 01690 * Called by the application code when there is outgoing data available required to be sent on a specific socket handler. 01691 * The only difference between this function and the similar @ref sendto function, is the type of socket the data is sent on and the parameters passed in. 01692 * @ref send function is most commonly called for sockets in a connected state. 01693 * After the data is sent, the socket callback function registered using registerSocketCallback(), is expected to receive an event of type 01694 * @ref SOCKET_MSG_SEND holding information containing the number of data bytes sent. 01695 */ 01696 /**@{*/ 01697 /*! 01698 @fn \ 01699 NMI_API sint16 send(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 u16Flags); 01700 01701 @param [in] sock 01702 Socket ID, must hold a non negative value. 01703 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01704 01705 @param [in] pvSendBuffer 01706 Pointer to a buffer holding data to be transmitted. 01707 01708 @param [in] u16SendLength 01709 The buffer size in bytes. 01710 01711 @param [in] u16Flags 01712 Not used in the current implementation. 01713 01714 @pre 01715 Sockets must be initialized using socketInit. \n 01716 01717 For TCP Socket:\n 01718 Must use a successfully connected Socket (so that the intended recipient address is known ahead of sending the data). 01719 Hence this function is expected to be called after a successful socket connect operation(in client case or accept in the 01720 the server case).\n 01721 01722 For UDP Socket:\n 01723 UDP sockets most commonly use @ref sendto function, where the destination address is defined. However, in-order to send outgoing data 01724 using the @ref send function, at least one successful call must be made to the @ref sendto function a priori the consecutive calls to the @ref send function, 01725 to ensure that the destination address is saved in the firmware. 01726 01727 @see 01728 socketInit 01729 recv 01730 sendto 01731 socket 01732 connect 01733 accept 01734 sendto 01735 01736 @warning 01737 u16SendLength must not exceed @ref SOCKET_BUFFER_MAX_LENGTH. \n 01738 Use a valid socket identifier through the a prior call to the @ref socket function. 01739 Must use a valid buffer pointer. 01740 Successful completion of a call to send() does not guarantee delivery of the message, 01741 A negative return value indicates only locally-detected errors 01742 01743 01744 @return 01745 The function shall return @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise. 01746 */ 01747 NMI_API sint16 nmi_send(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 u16Flags);//Tsungta 01748 /** @} */ 01749 /** @defgroup SendToSocketFn sendto 01750 * @ingroup SocketAPI 01751 * Asynchronous sending function, used to send data on a UDP socket. 01752 * Called by the application code when there is data required to be sent on a UDP socket handler. 01753 * The application code is expected to receive data from a successful bounded socket node. 01754 * The only difference between this function and the similar @ref send function, is the type of socket the data is received on. This function works 01755 * only with UDP sockets. 01756 * After the data is sent, the socket callback function registered using registerSocketCallback(), is expected to receive an event of type 01757 * @ref SOCKET_MSG_SENDTO. 01758 */ 01759 /**@{*/ 01760 /*! 01761 @fn \ 01762 NMI_API sint16 sendto(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 flags, struct sockaddr *pstrDestAddr, uint8 u8AddrLen); 01763 01764 @param [in] sock 01765 Socket ID, must hold a non negative value. 01766 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01767 01768 @param [in] pvSendBuffer 01769 Pointer to a buffer holding data to be transmitted. 01770 A NULL value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01771 01772 @param [in] u16SendLength 01773 The buffer size in bytes. It must not exceed @ref SOCKET_BUFFER_MAX_LENGTH. 01774 01775 @param [in] flags 01776 Not used in the current implementation 01777 01778 @param [in] pstrDestAddr 01779 The destination address. 01780 01781 @param [in] u8AddrLen 01782 Destination address length in bytes. 01783 Not used in the current implementation, only included for BSD compatibility. 01784 @pre 01785 Sockets must be initialized using socketInit. 01786 01787 @see 01788 socketInit 01789 recvfrom 01790 sendto 01791 socket 01792 connect 01793 accept 01794 send 01795 01796 @warning 01797 u16SendLength must not exceed @ref SOCKET_BUFFER_MAX_LENGTH. \n 01798 Use a valid socket (returned from socket ). 01799 A valid buffer pointer must be used (not NULL). \n 01800 Successful completion of a call to sendto() does not guarantee delivery of the message, 01801 A negative return value indicates only locally-detected errors 01802 01803 @return 01804 The function returns @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise. 01805 */ 01806 NMI_API sint16 sendto (SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 flags, struct sockaddr *pstrDestAddr, uint8 u8AddrLen); 01807 /** @} */ 01808 /** @defgroup CloseSocketFn close 01809 * @ingroup SocketAPI 01810 * Synchronous close function, releases all the socket assigned resources. 01811 */ 01812 /**@{*/ 01813 /*! 01814 @fn \ 01815 NMI_API sint8 close(SOCKET sock); 01816 01817 @param [in] sock 01818 Socket ID, must hold a non negative value. 01819 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 01820 01821 @pre 01822 Sockets must be initialized through the call of the socketInit function. 01823 @ref close is called only for valid socket identifiers created through the @ref socket function. 01824 01825 @warning 01826 If @ref close is called while there are still pending messages (sent or received ) they will be discarded. 01827 01828 @see 01829 socketInit 01830 socket 01831 01832 @return 01833 The function returned @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise. 01834 */ 01835 NMI_API sint8 nmi_close(SOCKET sock);//Tsungta 01836 01837 NMI_API char * inet_ntoa(in_addr in);//Tsungta 01838 01839 /** @} */ 01840 /** @defgroup InetAddressFn nmi_inet_addr 01841 * @ingroup SocketAPI 01842 * Synchronous function which returns a BSD socket compliant Internet Protocol (IPv4) socket address. 01843 * This IPv4 address in the input string parameter could either be specified as a host name, or as a numeric string representation like n.n.n.n known as the IPv4 dotted-decimal format 01844 * (i.e. "192.168.10.1"). 01845 * This function is used whenever an ip address needs to be set in the proper format 01846 * (i.e. for the @ref tstrM2MIPConfig structure). 01847 */ 01848 /**@{*/ 01849 /*! 01850 @fn \ 01851 NMI_API uint32 nmi_inet_addr(char *pcIpAddr); 01852 01853 @param [in] pcIpAddr 01854 A null terminated string containing the IP address in IPv4 dotted-decimal address. 01855 01856 @return 01857 Unsigned 32-bit integer representing the IP address in Network byte order 01858 (eg. "192.168.10.1" will be expressed as 0x010AA8C0). 01859 01860 */ 01861 NMI_API uint32 nmi_inet_addr (char *pcIpAddr); 01862 01863 01864 /** @} */ 01865 /** @defgroup gethostbynameFn gethostbyname 01866 * @ingroup SocketAPI 01867 * Asynchronous DNS resolving function. This function use DNS to resolve a domain name into the corresponding IP address. 01868 * A call to this function will cause a DNS request to be sent and the response will be delivered to the DNS callback function registered using registerSocketCallback() 01869 */ 01870 /**@{*/ 01871 /*! 01872 @fn \ 01873 NMI_API sint8 gethostbyname(uint8 * pcHostName); 01874 01875 @param [in] pcHostName 01876 NULL terminated string containing the domain name for the remote host. 01877 Its size must not exceed [HOSTNAME_MAX_SIZE](@ref HOSTNAME_MAX_SIZE). 01878 01879 @see 01880 registerSocketCallback 01881 01882 @warning 01883 Successful completion of a call to gethostbyname() does not guarantee success of the DNS request, 01884 a negative return value indicates only locally-detected errors 01885 01886 @return 01887 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 01888 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 01889 */ 01890 NMI_API sint8 gethostbyname (uint8 * pcHostName); 01891 01892 01893 /** @} */ 01894 /** @defgroup sslEnableCertExpirationCheckFn sslEnableCertExpirationCheck 01895 * @ingroup SocketAPI 01896 * Configure the behavior of the SSL Library for Certificate Expiry Validation. 01897 */ 01898 /**@{*/ 01899 /*! 01900 @fn \ 01901 NMI_API sint8 sslEnableCertExpirationCheck(tenuSslCertExpSettings enuValidationSetting); 01902 01903 @param [in] enuValidationSetting 01904 See @ref tenuSslCertExpSettings for details. 01905 01906 @return 01907 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) for successful operation and negative error code otherwise. 01908 01909 @sa tenuSslCertExpSettings 01910 */ 01911 NMI_API sint8 sslEnableCertExpirationCheck (tenuSslCertExpSettings enuValidationSetting); 01912 01913 01914 /** @} */ 01915 01916 /** @defgroup SetSocketOptionFn setsockopt 01917 * @ingroup SocketAPI 01918 *The setsockopt() function shall set the option specified by the option_name 01919 * argument, at the protocol level specified by the level argument, to the value 01920 * pointed to by the option_value argument for the socket specified by the socket argument. 01921 * 01922 * <p>Possible protocol level values supported are @ref SOL_SOCKET and @ref SOL_SSL_SOCKET. 01923 * Possible options when the protocol level is @ref SOL_SOCKET :</p> 01924 * <table style="width: 100%"> 01925 * <tr> 01926 * <td style="height: 22px"><strong>@ref SO_SET_UDP_SEND_CALLBACK</strong></td> 01927 * <td style="height: 22px">Enable/Disable callback messages for sendto(). 01928 * Since UDP is unreliable by default the user maybe interested (or not) in 01929 * receiving a message of @ref SOCKET_MSG_SENDTO for each call of sendto(). 01930 * Enabled if option value equals @ref TRUE, disabled otherwise.</td> 01931 * </tr> 01932 * <tr> 01933 * <td><strong>@ref IP_ADD_MEMBERSHIP</strong></td> 01934 * <td>Valid for UDP sockets. This option is used to receive frames sent to 01935 * a multicast group. option_value shall be a pointer to Unsigned 32-bit 01936 * integer containing the multicast IPv4 address. </td> 01937 * </tr> 01938 * <tr> 01939 * <td><strong>@ref IP_DROP_MEMBERSHIP</strong></td> 01940 * <td>Valid for UDP sockets. This option is used to stop receiving frames 01941 * sent to a multicast group. option_value shall be a pointer to Unsigned 01942 * 32-bit integer containing the multicast IPv4 address.</td> 01943 * </tr> 01944 * </table> 01945 * <p>Possible options when the protcol leve is @ref SOL_SSL_SOCKET</p> 01946 * <table style="width: 100%"> 01947 * <tr> 01948 * <td style="height: 22px"><strong> 01949 * @ref SO_SSL_BYPASS_X509_VERIF</strong></td> 01950 * <td style="height: 22px">Allow an opened SSL socket to bypass the X509 01951 * certificate verification process. It is highly recommended <strong>NOT</strong> to use 01952 * this socket option in production software applications. The option is 01953 * supported for debugging and testing purposes. The option value should be 01954 * casted to int type and it is handled as a boolean flag.</td> 01955 * </tr> 01956 * <tr> 01957 * <td><strong>@ref SO_SSL_SNI</strong></td> 01958 * <td>Set the Server Name Indicator (SNI) for an SSL socket. The SNI is a 01959 * null terminated string containing the server name associated with the 01960 * connection. It must not exceed the size of @ref HOSTNAME_MAX_SIZE.</td> 01961 * </tr> 01962 * <tr> 01963 * <td><strong>@ref SO_SSL_ENABLE_SESSION_CACHING</strong></td> 01964 * <td>This option allow the TLS to cache the session information for fast 01965 * TLS session establishment in future connections using the TLS Protocol 01966 * session resume features.</td> 01967 * </tr> 01968 * </table> 01969 */ 01970 /**@{*/ 01971 /*! 01972 @fn \ 01973 NMI_API sint8 setsockopt(SOCKET socket, uint8 u8Level, uint8 option_name, 01974 const void *option_value, uint16 u16OptionLen); 01975 01976 @param [in] sock 01977 Socket handler. 01978 01979 @param [in] level 01980 protocol level. See description above. 01981 01982 @param [in] option_name 01983 option to be set. See description above. 01984 01985 @param [in] option_value 01986 pointer to user provided value. 01987 01988 @param [in] option_len 01989 length of the option value in bytes. 01990 @return 01991 The function shall return \ref SOCK_ERR_NO_ERROR for successful operation 01992 and a negative value (indicating the error) otherwise. 01993 @sa SOL_SOCKET, SOL_SSL_SOCKET, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP 01994 */ 01995 NMI_API sint8 setsockopt (SOCKET socket , uint8 u8Level, uint8 option_name, 01996 const void *option_value, uint16 u16OptionLen); 01997 01998 01999 /** @} */ 02000 /** @defgroup GetSocketOptionsFn getsockopt 02001 * @ingroup SocketAPI 02002 * Get socket options retrieves 02003 * This Function isn't implemented yet but this is the form that will be released later. 02004 */ 02005 /**@{*/ 02006 /*! 02007 @fn \ 02008 sint8 getsockopt(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8 * pu8OptLen); 02009 02010 @brief 02011 02012 @param [in] sock 02013 Socket Identifie. 02014 @param [in] u8Level 02015 The protocol level of the option. 02016 @param [in] u8OptName 02017 The u8OptName argument specifies a single option to get. 02018 @param [out] pvOptValue 02019 The pvOptValue argument contains pointer to a buffer containing the option value. 02020 @param [out] pu8OptLen 02021 Option value buffer length. 02022 @return 02023 The function shall return ZERO for successful operation and a negative value otherwise. 02024 */ 02025 NMI_API sint8 getsockopt (SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8* pu8OptLen); 02026 /** @} */ 02027 02028 /**@}*/ 02029 /** @defgroup PingFn m2m_ping_req 02030 * @ingroup SocketAPI 02031 * The function sends ping request to the given IP Address. 02032 */ 02033 /**@{*/ 02034 /*! 02035 @fn \ 02036 NMI_API sint8 m2m_ping_req(uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb); 02037 02038 @param [in] u32DstIP 02039 Target Destination IP Address for the ping request. It must be represented in Network byte order. 02040 The function nmi_inet_addr could be used to translate the dotted decimal notation IP 02041 to its Network bytes order integer represntative. 02042 02043 @param [in] u8TTL 02044 IP TTL value for the ping request. If set to ZERO, the dfault value SHALL be used. 02045 02046 @param [in] fpPingCb 02047 Callback will be called to deliver the ping statistics. 02048 02049 @see nmi_inet_addr 02050 @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. 02051 */ 02052 NMI_API sint8 m2m_ping_req (uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb); 02053 /**@}*/ 02054 02055 02056 #ifdef __cplusplus 02057 } 02058 #endif /* __cplusplus */ 02059 02060 #endif /* __SOCKET_H__ */ 02061 02062 02063
Generated on Wed Jul 13 2022 16:32:37 by
1.7.2