1 /** 2 * 3 * \file 4 * 5 * \brief WINC BSD compatible Socket Interface. 6 * 7 * Copyright (c) 2016-2017 Atmel Corporation. All rights reserved. 8 * 9 * \asf_license_start 10 * 11 * \page License 12 * 13 * Redistribution and use in source and binary forms, with or without 14 * modification, are permitted provided that the following conditions are met: 15 * 16 * 1. Redistributions of source code must retain the above copyright notice, 17 * this list of conditions and the following disclaimer. 18 * 19 * 2. Redistributions in binary form must reproduce the above copyright notice, 20 * this list of conditions and the following disclaimer in the documentation 21 * and/or other materials provided with the distribution. 22 * 23 * 3. The name of Atmel may not be used to endorse or promote products derived 24 * from this software without specific prior written permission. 25 * 26 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 27 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 28 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 29 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 30 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 34 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 35 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36 * POSSIBILITY OF SUCH DAMAGE. 37 * 38 * \asf_license_stop 39 * 40 */ 41 42 #ifndef __SOCKET_H__ 43 #define __SOCKET_H__ 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** \defgroup SocketHeader Socket 50 * BSD compatible socket interface beftween the host layer and the network 51 * protocol stacks in the firmware. 52 * These functions are used by the host application to send or receive 53 * packets and to do other socket operations. 54 */ 55 56 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* 57 INCLUDES 58 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ 59 60 #include "common/include/nm_common.h" 61 #include "driver/include/m2m_types.h" 62 63 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* 64 MACROS 65 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ 66 /** 67 * @defgroup SocketDefines Defines 68 * @ingroup SocketHeader 69 */ 70 71 /** @defgroup IPDefines TCP/IP Defines 72 * @ingroup SocketDefines 73 * The following list of macros are used to define constants used throughout the socket layer. 74 * @{ 75 */ 76 77 /* 78 * HOSTNAME_MAX_SIZE is defined here and also in host_drv/socket/include/m2m_socket_host_if.h 79 * The two definitions must match. 80 */ 81 #define HOSTNAME_MAX_SIZE 64 82 /*!< 83 Maximum allowed size for a host domain name passed to the function gethostbyname @ref gethostbyname. 84 command value. Used with the setsockopt function. 85 86 */ 87 88 #define SOCKET_BUFFER_MAX_LENGTH 1400 89 /*!< 90 Maximum allowed size for a socket data buffer. Used with @ref send socket 91 function to ensure that the buffer sent is within the allowed range. 92 */ 93 94 #define AF_INET 2 95 /*!< 96 The AF_INET is the address family used for IPv4. An IPv4 transport address is specified with the @ref sockaddr_in structure. 97 (It is the only supported type for the current implementation.) 98 */ 99 100 101 #define SOCK_STREAM 1 102 /*!< 103 One of the IPv4 supported socket types for reliable connection-oriented stream connection. 104 Passed to the @ref socket function for the socket creation operation. 105 */ 106 107 #define SOCK_DGRAM 2 108 /*!< 109 One of the IPv4 supported socket types for unreliable connectionless datagram connection. 110 Passed to the @ref socket function for the socket creation operation. 111 */ 112 113 114 #define SOCKET_FLAGS_SSL 0x01 115 /*!< 116 This flag shall be passed to the socket API for SSL session. 117 */ 118 119 #define TCP_SOCK_MAX (7) 120 /*!< 121 Maximum number of simultaneous TCP sockets. 122 */ 123 124 #define UDP_SOCK_MAX 4 125 /*!< 126 Maximum number of simultaneous UDP sockets. 127 */ 128 129 #define MAX_SOCKET (TCP_SOCK_MAX + UDP_SOCK_MAX) 130 /*!< 131 Maximum number of Sockets. 132 */ 133 134 #define SOL_SOCKET 1 135 /*!< 136 Socket option. 137 Used with the @ref setsockopt function 138 */ 139 140 #define SOL_SSL_SOCKET 2 141 /*!< 142 SSL Socket option level. 143 Used with the @ref setsockopt function 144 */ 145 146 #define SO_SET_UDP_SEND_CALLBACK 0x00 147 /*!< 148 Socket option used by the application to enable/disable 149 the use of UDP send callbacks. 150 Used with the @ref setsockopt function. 151 */ 152 153 #define IP_ADD_MEMBERSHIP 0x01 154 /*!< 155 Set Socket Option Add Membership command value (to join a multicast group). 156 Used with the @ref setsockopt function. 157 */ 158 159 160 #define IP_DROP_MEMBERSHIP 0x02 161 /*!< 162 Set Socket Option Drop Membership command value (to leave a multicast group). 163 Used with the @ref setsockopt function. 164 */ 165 //@} 166 167 168 169 /** 170 * @defgroup TLSDefines TLS Defines 171 * @ingroup SocketDefines 172 */ 173 174 175 176 /** @defgroup SSLSocketOptions TLS Socket Options 177 * @ingroup TLSDefines 178 * The following list of macros are used to define SSL Socket options. 179 * @{ 180 * @sa setsockopt 181 */ 182 183 #define SO_SSL_BYPASS_X509_VERIF 0x01 184 /*!< 185 Allow an opened SSL socket to bypass the X509 certificate 186 verification process. 187 It is highly required NOT to use this socket option in production 188 software applications. It is supported for debugging and testing 189 purposes. 190 The option value should be casted to int type and it is handled 191 as a boolean flag. 192 */ 193 194 195 #define SO_SSL_SNI 0x02 196 /*!< 197 Set the Server Name Indicator (SNI) for an SSL socket. The 198 SNI is a NULL terminated string containing the server name 199 associated with the connection. It must not exceed the size 200 of HOSTNAME_MAX_SIZE. 201 */ 202 203 204 #define SO_SSL_ENABLE_SESSION_CACHING 0x03 205 /*!< 206 This option allow the TLS to cache the session information for fast 207 TLS session establishment in future connections using the 208 TLS Protocol session resume features. 209 */ 210 211 212 #define SO_SSL_ENABLE_SNI_VALIDATION 0x04 213 /*!< 214 Enable SNI validation against the server's certificate subject 215 common name. If there is no SNI provided (via the SO_SSL_SNI 216 option), setting this option does nothing. 217 */ 218 219 220 //@} 221 222 223 224 /** @defgroup LegacySSLCipherSuite Legacy names for TLS Cipher Suite IDs 225 * @ingroup TLSDefines 226 * The following list of macros MUST NOT be used. Instead use the new names under SSLCipherSuiteID 227 * @sa sslSetActiveCipherSuites 228 * @{ 229 */ 230 231 #define SSL_ENABLE_RSA_SHA_SUITES 0x01 232 /*!< 233 Enable RSA Hmac_SHA based Cipher suites. For example, 234 TLS_RSA_WITH_AES_128_CBC_SHA 235 */ 236 237 238 #define SSL_ENABLE_RSA_SHA256_SUITES 0x02 239 /*!< 240 Enable RSA Hmac_SHA256 based Cipher suites. For example, 241 TLS_RSA_WITH_AES_128_CBC_SHA256 242 */ 243 244 245 #define SSL_ENABLE_DHE_SHA_SUITES 0x04 246 /*!< 247 Enable DHE Hmac_SHA based Cipher suites. For example, 248 TLS_DHE_RSA_WITH_AES_128_CBC_SHA 249 */ 250 251 252 #define SSL_ENABLE_DHE_SHA256_SUITES 0x08 253 /*!< 254 Enable DHE Hmac_SHA256 based Cipher suites. For example, 255 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 256 */ 257 258 259 #define SSL_ENABLE_RSA_GCM_SUITES 0x10 260 /*!< 261 Enable RSA AEAD based Cipher suites. For example, 262 TLS_RSA_WITH_AES_128_GCM_SHA256 263 */ 264 265 266 #define SSL_ENABLE_DHE_GCM_SUITES 0x20 267 /*!< 268 Enable DHE AEAD based Cipher suites. For example, 269 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 270 */ 271 272 273 #define SSL_ENABLE_ALL_SUITES 0x0000003F 274 /*!< 275 Enable all possible supported cipher suites. 276 */ 277 278 //@} 279 280 281 282 /** @defgroup SSLCipherSuiteID TLS Cipher Suite IDs 283 * @ingroup TLSDefines 284 * The following list of macros defined the list of supported TLS Cipher suites. 285 * Each MACRO defines a single Cipher suite. 286 * @sa m2m_ssl_set_active_ciphersuites 287 * @{ 288 */ 289 290 #define SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA NBIT0 291 #define SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA256 NBIT1 292 #define SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA NBIT2 293 #define SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA256 NBIT3 294 #define SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 NBIT4 295 #define SSL_CIPHER_DHE_RSA_WITH_AES_128_GCM_SHA256 NBIT5 296 #define SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA NBIT6 297 #define SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA256 NBIT7 298 #define SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA NBIT8 299 #define SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA256 NBIT9 300 #define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA NBIT10 301 #define SSL_CIPHER_ECDHE_RSA_WITH_AES_256_CBC_SHA NBIT11 302 #define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA256 NBIT12 303 #define SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 NBIT13 304 #define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_GCM_SHA256 NBIT14 305 #define SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 NBIT15 306 307 308 309 #define SSL_ECC_ONLY_CIPHERS \ 310 (\ 311 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | \ 312 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 \ 313 ) 314 /*!< 315 All ciphers that use ECC crypto only. This execuldes ciphers that use RSA. They use ECDSA instead. 316 These ciphers are turned off by default at startup. 317 The application may enable them if it has an ECC math engine (like ATECC508). 318 */ 319 #define SSL_ECC_ALL_CIPHERS \ 320 (\ 321 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA | \ 322 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | \ 323 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | \ 324 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | \ 325 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 \ 326 ) 327 /*!< 328 All supported ECC Ciphers including those ciphers that depend on RSA and ECC. 329 These ciphers are turned off by default at startup. 330 The application may enable them if it has an ECC math engine (like ATECC508). 331 */ 332 333 #define SSL_NON_ECC_CIPHERS_AES_128 \ 334 (\ 335 SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA | \ 336 SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA256 | \ 337 SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA | \ 338 SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA256 | \ 339 SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 | \ 340 SSL_CIPHER_DHE_RSA_WITH_AES_128_GCM_SHA256 \ 341 ) 342 /*!< 343 All supported AES-128 Ciphers (ECC ciphers are not counted). This is the default active group after startup. 344 */ 345 346 347 #define SSL_ECC_CIPHERS_AES_256 \ 348 (\ 349 SSL_CIPHER_ECDHE_RSA_WITH_AES_256_CBC_SHA \ 350 ) 351 /*!< 352 ECC AES-256 supported ciphers. 353 */ 354 355 356 #define SSL_NON_ECC_CIPHERS_AES_256 \ 357 (\ 358 SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA | \ 359 SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA256 | \ 360 SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA | \ 361 SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA256 \ 362 ) 363 /*!< 364 AES-256 Ciphers. 365 This group is disabled by default at startup because the WINC1500 HW Accelerator 366 supports only AES-128. If the application needs to force AES-256 cipher support, 367 it could enable them (or any of them) explicitly by calling sslSetActiveCipherSuites. 368 */ 369 370 371 #define SSL_CIPHER_ALL \ 372 (\ 373 SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA | \ 374 SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA256 | \ 375 SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA | \ 376 SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA256 | \ 377 SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 | \ 378 SSL_CIPHER_DHE_RSA_WITH_AES_128_GCM_SHA256 | \ 379 SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA | \ 380 SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA256 | \ 381 SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA | \ 382 SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA256 | \ 383 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA | \ 384 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | \ 385 SSL_CIPHER_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | \ 386 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | \ 387 SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | \ 388 SSL_CIPHER_ECDHE_RSA_WITH_AES_256_CBC_SHA \ 389 ) 390 /*!< 391 Turn On All TLS Ciphers. 392 */ 393 394 395 //@} 396 397 398 399 400 /************** 401 Socket Errors 402 **************/ 403 /**@defgroup SocketErrorCode Error Codes 404 * @ingroup SocketHeader 405 * The following list of macros are used to define the possible error codes returned as a result of a call to a socket function. 406 * Errors are listed in numerical order with the error macro name. 407 * @{ 408 */ 409 #define SOCK_ERR_NO_ERROR 0 410 /*!< 411 Successful socket operation 412 */ 413 414 415 #define SOCK_ERR_INVALID_ADDRESS -1 416 /*!< 417 Socket address is invalid. The socket operation cannot be completed successfully without specifying a specific address 418 For example: bind is called without specifying a port number 419 */ 420 421 422 #define SOCK_ERR_ADDR_ALREADY_IN_USE -2 423 /*!< 424 Socket operation cannot bind on the given address. With socket operations, only one IP address per socket is permitted. 425 Any attempt for a new socket to bind with an IP address already bound to another open socket, 426 will return the following error code. States that bind operation failed. 427 */ 428 429 430 #define SOCK_ERR_MAX_TCP_SOCK -3 431 /*!< 432 Exceeded the maximum number of TCP sockets. A maximum number of TCP sockets opened simultaneously is defined through TCP_SOCK_MAX. 433 It is not permitted to exceed that number at socket creation. Identifies that @ref socket operation failed. 434 */ 435 436 437 #define SOCK_ERR_MAX_UDP_SOCK -4 438 /*!< 439 Exceeded the maximum number of UDP sockets. A maximum number of UDP sockets opened simultaneously is defined through UDP_SOCK_MAX. 440 It is not permitted to exceed that number at socket creation. Identifies that @ref socket operation failed 441 */ 442 443 444 #define SOCK_ERR_INVALID_ARG -6 445 /*!< 446 An invalid argument is passed to a function. 447 */ 448 449 450 #define SOCK_ERR_MAX_LISTEN_SOCK -7 451 /*!< 452 Exceeded the maximum number of TCP passive listening sockets. 453 Identifies Identifies that @ref listen operation failed. 454 */ 455 456 457 #define SOCK_ERR_INVALID -9 458 /*!< 459 The requested socket operation is not valid in the 460 current socket state. 461 For example: @ref accept is called on a TCP socket before @ref bind or @ref listen. 462 */ 463 464 465 #define SOCK_ERR_ADDR_IS_REQUIRED -11 466 /*!< 467 Destination address is required. Failure to provide the socket address required for the socket operation to be completed. 468 It is generated as an error to the @ref sendto function when the address required to send the data to is not known. 469 */ 470 471 472 #define SOCK_ERR_CONN_ABORTED -12 473 /*!< 474 The socket is closed by the peer. The local socket is 475 closed also. 476 */ 477 478 479 #define SOCK_ERR_TIMEOUT -13 480 /*!< 481 The socket pending operation has Timedout. 482 */ 483 484 485 #define SOCK_ERR_BUFFER_FULL -14 486 /*!< 487 No buffer space available to be used for the requested socket operation. 488 */ 489 490 #ifdef _NM_BSP_BIG_END 491 492 #define _htonl(m) (m) 493 #define _htons(A) (A) 494 495 #else 496 497 #define _htonl(m) \ 498 (uint32)(((uint32)(m << 24)) | ((uint32)((m & 0x0000FF00) << 8)) | ((uint32)((m & 0x00FF0000) >> 8)) | ((uint32)(m >> 24))) 499 /*!< 500 Convert a 4-byte integer from the host representation to the Network byte order representation. 501 */ 502 503 504 #define _htons(A) (uint16)((((uint16) (A)) << 8) | (((uint16) (A)) >> 8)) 505 /*!< 506 Convert a 2-byte integer (short) from the host representation to the Network byte order representation. 507 */ 508 509 510 #endif 511 512 513 #define _ntohl _htonl 514 /*!< 515 Convert a 4-byte integer from the Network byte order representation to the host representation . 516 */ 517 518 519 #define _ntohs _htons 520 /*!< 521 Convert a 2-byte integer from the Network byte order representation to the host representation . 522 */ 523 //@} 524 525 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* 526 DATA TYPES 527 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ 528 /** @defgroup SocketEnums DataTypes 529 * @ingroup SocketHeader 530 * Specific Enumeration-typedefs used for socket operations 531 * @{ */ 532 533 /*! 534 @typedef \ 535 SOCKET 536 537 @brief 538 Definition for socket handler data type. 539 Socket ID,used with all socket operations to uniquely identify the socket handler. 540 Such an ID is uniquely assigned at socket creation when calling @ref socket operation. 541 */ 542 typedef sint8 SOCKET; 543 544 545 546 /*! 547 @struct \ 548 in_addr 549 550 @brief 551 IPv4 address representation. 552 553 This structure is used as a placeholder for IPV4 address in other structures. 554 @see 555 sockaddr_in 556 */ 557 typedef struct{ 558 uint32 s_addr; 559 /*!< 560 Network Byte Order representation of the IPv4 address. For example, 561 the address "192.168.0.10" is represented as 0x0A00A8C0. 562 */ 563 }in_addr; 564 565 566 /*! 567 @struct \ 568 sockaddr 569 570 @brief 571 Generic socket address structure. 572 573 @see 574 sockaddr_in 575 */ 576 struct sockaddr{ 577 uint16 sa_family; 578 /*!< 579 Socket address family. 580 */ 581 uint8 sa_data[14]; 582 /*!< 583 Maximum size of all the different socket address structures. 584 */ 585 }; 586 587 588 /*! 589 @struct \ 590 sockaddr_in 591 592 @brief 593 Socket address structure for IPV4 addresses. Used to specify socket address information to which to connect to. 594 Can be cast to @ref sockaddr structure. 595 */ 596 struct sockaddr_in{ 597 uint16 sin_family; 598 /*!< 599 Specifies the address family(AF). 600 Members of AF_INET address family are IPv4 addresses. 601 Hence,the only supported value for this is AF_INET. 602 */ 603 uint16 sin_port; 604 /*!< 605 Port number of the socket. 606 Network sockets are identified by a pair of IP addresses and port number. 607 It must be set in the Network Byte Order format , @ref _htons (e.g. _htons(80)). 608 Can NOT have zero value. 609 */ 610 in_addr sin_addr; 611 /*!< 612 IP Address of the socket. 613 The IP address is of type @ref in_addr structure. 614 Can be set to "0" to accept any IP address for server operation. non zero otherwise. 615 */ 616 uint8 sin_zero[8]; 617 /*!< 618 Padding to make structure the same size as @ref sockaddr. 619 */ 620 }; 621 //@} 622 /**@defgroup AsyncCalback Asynchronous Events 623 * @ingroup SocketEnums 624 * Specific Enumeration used for asynchronous operations 625 * @{ */ 626 /*! 627 @enum \ 628 tenuSocketCallbackMsgType 629 630 @brief 631 Asynchronous APIs, make use of callback functions, in-order to return back the results once the corresponding socket operation is completed. 632 Hence resuming the normal execution of the application code while the socket operation returns the results. 633 Callback functions expect event messages to be passed in, in-order to identify the operation they're returning the results for. 634 The following enum identifies the type of events that are received in the callback function. 635 636 Application Use: 637 In order for application developers to handle the pending events from the network controller through the callback functions. 638 A function call must be made to the function @ref m2m_wifi_handle_events at least once for each socket operation. 639 640 @see 641 bind 642 listen 643 accept 644 connect 645 send 646 recv 647 648 */ 649 typedef enum{ 650 SOCKET_MSG_BIND = 1, 651 /*!< 652 Bind socket event. 653 */ 654 SOCKET_MSG_LISTEN, 655 /*!< 656 Listen socket event. 657 */ 658 SOCKET_MSG_DNS_RESOLVE, 659 /*!< 660 DNS Resolution event. 661 */ 662 SOCKET_MSG_ACCEPT, 663 /*!< 664 Accept socket event. 665 */ 666 SOCKET_MSG_CONNECT, 667 /*!< 668 Connect socket event. 669 */ 670 SOCKET_MSG_RECV, 671 /*!< 672 Receive socket event. 673 */ 674 SOCKET_MSG_SEND, 675 /*!< 676 Send socket event. 677 */ 678 SOCKET_MSG_SENDTO, 679 /*!< 680 sendto socket event. 681 */ 682 SOCKET_MSG_RECVFROM 683 /*!< 684 Recvfrom socket event. 685 */ 686 }tenuSocketCallbackMsgType; 687 688 689 /*! 690 @struct \ 691 tstrSocketBindMsg 692 693 @brief Socket bind status. 694 695 An asynchronous call to the @ref bind socket operation, returns information through this structure in response. 696 This structure together with the event @ref SOCKET_MSG_BIND are passed in paramters to the callback function. 697 @see 698 bind 699 700 */ 701 typedef struct{ 702 sint8 status; 703 /*!< 704 The result of the bind operation. 705 Holding a value of ZERO for a successful bind or otherwise a negative 706 error code corresponding to the type of error. 707 */ 708 }tstrSocketBindMsg; 709 710 711 /*! 712 @struct \ 713 tstrSocketListenMsg 714 715 @brief Socket listen status. 716 717 Socket listen information is returned through this structure in response to the asynchronous call to the @ref listen function. 718 This structure together with the event @ref SOCKET_MSG_LISTEN are passed-in parameters to the callback function. 719 @see 720 listen 721 */ 722 typedef struct{ 723 sint8 status; 724 /*!< 725 Holding a value of ZERO for a successful listen or otherwise a negative 726 error code corresponding to the type of error. 727 */ 728 }tstrSocketListenMsg; 729 730 731 732 /*! 733 @struct \ 734 tstrSocketAcceptMsg 735 736 @brief Socket accept status. 737 738 Socket accept information is returned through this structure in response to the asynchronous call to the @ref accept function. 739 This structure together with the event @ref SOCKET_MSG_ACCEPT are passed-in parameters to the callback function. 740 */ 741 typedef struct{ 742 SOCKET sock; 743 /*!< 744 On a successful @ref accept operation, the return information is the socket ID for the accepted connection with the remote peer. 745 Otherwise a negative error code is returned to indicate failure of the accept operation. 746 */ 747 struct sockaddr_in strAddr; 748 /*!< 749 Socket address structure for the remote peer. 750 */ 751 }tstrSocketAcceptMsg; 752 753 754 /*! 755 @struct \ 756 tstrSocketConnectMsg 757 758 @brief Socket connect status. 759 760 Socket connect information is returned through this structure in response to the asynchronous call to the @ref connect socket function. 761 This structure together with the event @ref SOCKET_MSG_CONNECT are passed-in parameters to the callback function. 762 */ 763 typedef struct{ 764 SOCKET sock; 765 /*!< 766 Socket ID referring to the socket passed to the connect function call. 767 */ 768 sint8 s8Error; 769 /*!< 770 Connect error code. 771 Holding a value of ZERO for a successful connect or otherwise a negative 772 error code corresponding to the type of error. 773 */ 774 }tstrSocketConnectMsg; 775 776 777 /*! 778 @struct \ 779 tstrSocketRecvMsg 780 781 @brief Socket recv status. 782 783 Socket receive information is returned through this structure in response to the asynchronous call to the recv or recvfrom socket functions. 784 This structure together with the events @ref SOCKET_MSG_RECV or @ref SOCKET_MSG_RECVFROM are passed-in parameters to the callback function. 785 @remark 786 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 787 delivered to the user in a number of consecutive chunks according to the USER Buffer size. 788 a negative or zero buffer size indicates an error with the following code: 789 @ref SOCK_ERR_NO_ERROR : Socket connection closed 790 @ref SOCK_ERR_CONN_ABORTED : Socket connection aborted 791 @SOCK_ERR_TIMEOUT : Socket receive timed out 792 */ 793 typedef struct{ 794 uint8 *pu8Buffer; 795 /*!< 796 Pointer to the USER buffer (passed to @ref recv and @ref recvfrom function) containing the received data chunk. 797 */ 798 sint16 s16BufferSize; 799 /*!< 800 The received data chunk size. 801 Holds a negative value if there is a receive error or ZERO on success upon reception of close socket message. 802 */ 803 uint16 u16RemainingSize; 804 /*!< 805 The number of bytes remaining in the current @ref recv operation. 806 */ 807 struct sockaddr_in strRemoteAddr; 808 /*!< 809 Socket address structure for the remote peer. It is valid for @ref SOCKET_MSG_RECVFROM event. 810 */ 811 }tstrSocketRecvMsg; 812 813 814 /*! 815 @typedef \ 816 tpfAppSocketCb 817 818 @brief 819 The main socket application callback function. Applications register their main socket application callback through this function by calling @ref registerSocketCallback. 820 In response to events received, the following callback function is called to handle the corresponding asynchronous function called. Example: @ref bind, @ref connect,...etc. 821 822 @param [in] sock 823 Socket ID for the callback. 824 825 The socket callback function is called whenever a new event is recived in response 826 to socket operations. 827 828 @param [in] u8Msg 829 Socket event type. Possible values are: 830 - @ref SOCKET_MSG_BIND 831 - @ref SOCKET_MSG_LISTEN 832 - @ref SOCKET_MSG_ACCEPT 833 - @ref SOCKET_MSG_CONNECT 834 - @ref SOCKET_MSG_RECV 835 - @ref SOCKET_MSG_SEND 836 - @ref SOCKET_MSG_SENDTO 837 - @ref SOCKET_MSG_RECVFROM 838 839 @param [in] pvMsg 840 Pointer to message structure. Existing types are: 841 - tstrSocketBindMsg 842 - tstrSocketListenMsg 843 - tstrSocketAcceptMsg 844 - tstrSocketConnectMsg 845 - tstrSocketRecvMsg 846 847 @see 848 tenuSocketCallbackMsgType 849 tstrSocketRecvMsg 850 tstrSocketConnectMsg 851 tstrSocketAcceptMsg 852 tstrSocketListenMsg 853 tstrSocketBindMsg 854 */ 855 typedef void (*tpfAppSocketCb) (SOCKET sock, uint8 u8Msg, void * pvMsg); 856 857 858 /*! 859 @typedef \ 860 tpfAppResolveCb 861 862 @brief 863 DNS resolution callback function. 864 Applications requiring DNS resolution should register their callback through this function by calling @ref registerSocketCallback. 865 The following callback is triggered in response to asynchronous call to the @ref gethostbyname function (DNS Resolution callback). 866 867 @param [in] pu8DomainName 868 Domain name of the host. 869 870 @param [in] u32ServerIP 871 Server IPv4 address encoded in NW byte order format. If it is Zero, then the DNS resolution failed. 872 */ 873 typedef void (*tpfAppResolveCb) (uint8* pu8DomainName, uint32 u32ServerIP); 874 875 /*! 876 @typedef \ 877 tpfPingCb 878 879 @brief PING Callback 880 881 The function delivers the ping statistics for the sent ping triggered by calling 882 m2m_ping_req. 883 884 @param [in] u32IPAddr 885 Destination IP. 886 887 @param [in] u32RTT 888 Round Trip Time. 889 890 @param [in] u8ErrorCode 891 Ping error code. It may be one of: 892 - PING_ERR_SUCCESS 893 - PING_ERR_DEST_UNREACH 894 - PING_ERR_TIMEOUT 895 */ 896 typedef void (*tpfPingCb)(uint32 u32IPAddr, uint32 u32RTT, uint8 u8ErrorCode); 897 898 /**@}*/ 899 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* 900 FUNCTION PROTOTYPES 901 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/ 902 /** \defgroup SocketAPI Function 903 * @ingroup SocketHeader 904 */ 905 906 /** @defgroup SocketInitalizationFn socketInit 907 * @ingroup SocketAPI 908 * The function performs the necessary initializations for the socket library through the following steps: 909 - A check made by the global variable gbSocketInit, ensuring that initialization for sockets is performed only once, 910 in-order to prevent reseting the socket instances already created in the global socket array (gastrSockets). 911 - Zero initializations to the global socket array (gastrSockets), which holds the list of TCP sockets. 912 - Registers the socket (Host Interface)hif callback function through the call to the hif_register_cb function. 913 This facilitates handling all of the socket related functions received through interrupts from the firmware. 914 915 */ 916 /**@{*/ 917 /*! 918 @fn \ 919 NMI_API void socketInit(void); 920 921 @param [in] void 922 923 @return void 924 925 @remarks 926 This initialization function must be invoked before any socket operation is performed. 927 No error codes from this initialization function since the socket array is statically allocated based in the maximum number of 928 sockets @ref MAX_SOCKET based on the systems capability. 929 \section Example 930 This example demonstrates the use of the socketinit for socket initialization for an mqtt chat application. 931 \code 932 tstrWifiInitParam param; 933 int8_t ret; 934 char topic[strlen(MAIN_CHAT_TOPIC) + MAIN_CHAT_USER_NAME_SIZE + 1]; 935 936 //Initialize the board. 937 system_init(); 938 939 //Initialize the UART console. 940 configure_console(); 941 942 // Initialize the BSP. 943 nm_bsp_init(); 944 945 ---------- 946 947 // Initialize socket interface. 948 socketInit(); 949 registerSocketCallback(socket_event_handler, socket_resolve_handler); 950 951 // Connect to router. 952 m2m_wifi_connect((char *)MAIN_WLAN_SSID, sizeof(MAIN_WLAN_SSID), 953 MAIN_WLAN_AUTH, (char *)MAIN_WLAN_PSK, M2M_WIFI_CH_ALL); 954 955 \endcode 956 */ 957 NMI_API void socketInit(void); 958 959 960 /*! 961 @fn \ 962 NMI_API void socketDeinit(void); 963 964 @brief Socket Layer De-initialization 965 966 The function performs the necessary cleanup for the socket library static data 967 It must be invoked as the last any socket operation is performed on any active sockets. 968 */ 969 NMI_API void socketDeinit(void); 970 971 972 /** @} */ 973 /** @defgroup SocketCallbackFn registerSocketCallback 974 * @ingroup SocketAPI 975 Register two callback functions one for asynchronous socket events and the other one for DNS callback registering function. 976 The registered callback functions are used to retrieve information in response to the asynchronous socket functions called. 977 */ 978 /**@{*/ 979 980 981 /*! 982 @fn \ 983 NMI_API void registerSocketCallback(tpfAppSocketCb socket_cb, tpfAppResolveCb resolve_cb); 984 985 @param [in] tpfAppSocketCb 986 Assignment of callback function to the global callback @ref tpfAppSocketCb gpfAppSocketCb. Delivers 987 socket messages to the host application. In response to the asynchronous function calls, such as @ref bind 988 @ref listen @ref accept @ref connect 989 990 @param [in] tpfAppResolveCb 991 Assignment of callback function to the global callback @ref tpfAppResolveCb gpfAppResolveCb. 992 Used for DNS resolving functionalities. The DNS resolving technique is determined by the application 993 registering the callback. 994 NULL is assigned when, DNS resolution is not required. 995 996 @return void 997 @remarks 998 If any of the socket functionalities is not to be used, NULL is passed in as a parameter. 999 It must be invoked after socketinit and before other socket layer operations. 1000 1001 \section Example 1002 This example demonstrates the use of the registerSocketCallback to register a socket callback function with DNS resolution CB set to null 1003 for a simple UDP server example. 1004 \code 1005 tstrWifiInitParam param; 1006 int8_t ret; 1007 struct sockaddr_in addr; 1008 1009 // Initialize the board 1010 system_init(); 1011 1012 //Initialize the UART console. 1013 configure_console(); 1014 1015 // Initialize the BSP. 1016 nm_bsp_init(); 1017 1018 // Initialize socket address structure. 1019 addr.sin_family = AF_INET; 1020 addr.sin_port = _htons(MAIN_WIFI_M2M_SERVER_PORT); 1021 addr.sin_addr.s_addr = _htonl(MAIN_WIFI_M2M_SERVER_IP); 1022 1023 // Initialize Wi-Fi parameters structure. 1024 memset((uint8_t *)¶m, 0, sizeof(tstrWifiInitParam)); 1025 1026 // Initialize Wi-Fi driver with data and status callbacks. 1027 param.pfAppWifiCb = wifi_cb; 1028 ret = m2m_wifi_init(¶m); 1029 if (M2M_SUCCESS != ret) { 1030 printf("main: m2m_wifi_init call error!(%d)\r\n", ret); 1031 while (1) { 1032 } 1033 } 1034 1035 // Initialize socket module 1036 socketInit(); 1037 registerSocketCallback(socket_cb, NULL); 1038 1039 // Connect to router. 1040 m2m_wifi_connect((char *)MAIN_WLAN_SSID, sizeof(MAIN_WLAN_SSID), MAIN_WLAN_AUTH, (char *)MAIN_WLAN_PSK, M2M_WIFI_CH_ALL); 1041 \endcode 1042 */ 1043 NMI_API void registerSocketCallback(tpfAppSocketCb socket_cb, tpfAppResolveCb resolve_cb); 1044 1045 1046 /** @} */ 1047 1048 /** @defgroup SocketFn socket 1049 * @ingroup SocketAPI 1050 * 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. 1051 * 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. 1052 * 1053 */ 1054 /**@{*/ 1055 /*! 1056 @fn \ 1057 NMI_API SOCKET socket(uint16 u16Domain, uint8 u8Type, uint8 u8Flags); 1058 1059 1060 @param [in] u16Domain 1061 Socket family. The only allowed value is AF_INET (IPv4.0) for TCP/UDP sockets. 1062 1063 @param [in] u8Type 1064 Socket type. Allowed values are: 1065 - [SOCK_STREAM](@ref SOCK_STREAM) 1066 - [SOCK_DGRAM](@ref SOCK_DGRAM) 1067 1068 @param [in] u8Flags 1069 Used to specify the socket creation flags. It shall be set to zero for normal TCP/UDP sockets. 1070 It could be @ref SOCKET_FLAGS_SSL if the socket is used for SSL session. The use of the flag 1071 @ref SOCKET_FLAGS_SSL has no meaning in case of UDP sockets. 1072 1073 @pre 1074 The @ref socketInit function must be called once at the beginning of the application to initialize the socket handler. 1075 before any call to the socket function can be made. 1076 1077 @see 1078 connect 1079 bind 1080 listen 1081 accept 1082 recv 1083 recvfrom 1084 send 1085 sendto 1086 close 1087 setsockopt 1088 getsockopt 1089 1090 @return 1091 On successful socket creation, a non-blocking socket type is created and a socket ID is returned 1092 In case of failure the function returns a negative value, identifying one of the socket error codes defined. 1093 For example: @ref SOCK_ERR_INVALID for invalid argument or 1094 @ref SOCK_ERR_MAX_TCP_SOCK if the number of TCP allocated sockets exceeds the number of available sockets. 1095 1096 @remarks 1097 The socket function must be called a priori to any other related socket functions "e.g. send, recv, close ..etc" 1098 \section Example 1099 This example demonstrates the use of the socket function to allocate the socket, returning the socket handler to be used for other 1100 socket operations. Socket creation is dependent on the socket type. 1101 \subsection sub1 UDP example 1102 @code 1103 SOCKET UdpServerSocket = -1; 1104 1105 UdpServerSocket = socket(AF_INET, SOCK_DGRAM, 0); 1106 1107 @endcode 1108 \subsection sub2 TCP example 1109 @code 1110 static SOCKET tcp_client_socket = -1; 1111 1112 tcp_client_socket = socket(AF_INET, SOCK_STREAM, 0)); 1113 @endcode 1114 \subsection sub3 SSL example 1115 @code 1116 static SOCKET ssl_socket = -1; 1117 1118 ssl_socket = socket(AF_INET, SOCK_STREAM, SOCK_FLAGS_SSL)); 1119 @endcode 1120 */ 1121 NMI_API SOCKET socket(uint16 u16Domain, uint8 u8Type, uint8 u8Flags); 1122 1123 1124 /** @} */ 1125 /** @defgroup BindFn bind 1126 * @ingroup SocketAPI 1127 * Asynchronous bind function associates the provided address and local port to the socket. 1128 * 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. 1129 * Upon socket bind completion, the application will receive a @ref SOCKET_MSG_BIND message in the socket callback. 1130 */ 1131 /**@{*/ 1132 /*! 1133 \fn \ 1134 NMI_API sint8 bind(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen); 1135 1136 1137 @param [in] sock 1138 Socket ID, must hold a non negative value. 1139 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1140 1141 @param [in] pstrAddr 1142 Pointer to socket address structure "sockaddr_in" 1143 [sockaddr_in](@ref sockaddr_in) 1144 1145 1146 @param [in] u8AddrLen 1147 Size of the given socket address structure in bytes. 1148 1149 @pre 1150 The socket function must be called to allocate a socket before passing the socket ID to the bind function. 1151 1152 @see 1153 socket 1154 connect 1155 listen 1156 accept 1157 recv 1158 recvfrom 1159 send 1160 sendto 1161 1162 @return 1163 The function returns ZERO for successful operations and a negative value otherwise. 1164 The possible error values are: 1165 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 1166 Indicating that the operation was successful. 1167 1168 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 1169 Indicating passing invalid arguments such as negative socket ID or NULL socket address structure. 1170 1171 - [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID) 1172 Indicate socket bind failure. 1173 \section Example 1174 This example demonstrates the call of the bind socket operation after a successful socket operation. 1175 @code 1176 struct sockaddr_in addr; 1177 SOCKET udpServerSocket =-1; 1178 int ret = -1; 1179 1180 if(udpServerSocket == -1) 1181 { 1182 udpServerSocket = socket(AF_INET, SOCK_DGRAM, 0); 1183 if(udpServerSocket >= 0) 1184 { 1185 addr.sin_family = AF_INET; 1186 addr.sin_port = _htons(1234); 1187 addr.sin_addr.s_addr = 0; 1188 ret = bind(udpServerSocket,(struct sockaddr*)&addr,sizeof(addr)); 1189 1190 if(ret != 0) 1191 { 1192 printf("Bind Failed. Error code = %d\n",ret); 1193 close(udpServerSocket); 1194 } 1195 } 1196 else 1197 { 1198 printf("UDP Server Socket Creation Failed\n"); 1199 return; 1200 } 1201 } 1202 @endcode 1203 */ 1204 NMI_API sint8 bind(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen); 1205 1206 1207 /** @} */ 1208 1209 /** @defgroup ListenFn listen 1210 * @ingroup SocketAPI 1211 * After successful socket binding to an IP address and port on the system, start listening on a passive socket for incoming connections. 1212 The socket must be bound on a local port or the listen operation fails. 1213 Upon the call to the asynchronous listen function, response is received through the event [SOCKET_MSG_BIND](@ref SOCKET_MSG_BIND) 1214 in the socket callback. 1215 A successful listen means the TCP server operation is active. If a connection is accepted, then the application socket callback function is 1216 notified with the new connected socket through the event @ref SOCKET_MSG_ACCEPT. Hence there is no need to call the @ref accept function 1217 after calling @ref listen. 1218 1219 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 1220 termination. 1221 */ 1222 /**@{*/ 1223 /*! 1224 @fn \ 1225 NMI_API sint8 listen(SOCKET sock, uint8 backlog); 1226 1227 @param [in] sock 1228 Socket ID, must hold a non negative value. 1229 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1230 1231 @param [in] backlog 1232 Not used by the current implementation. 1233 1234 @pre 1235 The bind function must be called to assign the port number and IP address to the socket before the listen operation. 1236 1237 @see 1238 bind 1239 accept 1240 recv 1241 recvfrom 1242 send 1243 sendto 1244 1245 @return 1246 The function returns ZERO for successful operations and a negative value otherwise. 1247 The possible error values are: 1248 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 1249 Indicating that the operation was successful. 1250 1251 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 1252 Indicating passing invalid arguments such as negative socket ID. 1253 1254 - [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID) 1255 Indicate socket listen failure. 1256 \section Example 1257 This example demonstrates the call of the listen socket operation after a successful socket operation. 1258 @code 1259 static void TCP_Socketcallback(SOCKET sock, uint8 u8Msg, void * pvMsg) 1260 { 1261 int ret =-1; 1262 1263 switch(u8Msg) 1264 { 1265 case SOCKET_MSG_BIND: 1266 { 1267 tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg; 1268 if(pstrBind != NULL) 1269 { 1270 if(pstrBind->status == 0) 1271 { 1272 ret = listen(sock, 0); 1273 1274 if(ret <0) 1275 printf("Listen failure! Error = %d\n",ret); 1276 } 1277 else 1278 { 1279 M2M_ERR("bind Failure!\n"); 1280 close(sock); 1281 } 1282 } 1283 } 1284 break; 1285 1286 case SOCKET_MSG_LISTEN: 1287 { 1288 1289 tstrSocketListenMsg *pstrListen = (tstrSocketListenMsg*)pvMsg; 1290 if(pstrListen != NULL) 1291 { 1292 if(pstrListen->status == 0) 1293 { 1294 ret = accept(sock,NULL,0); 1295 } 1296 else 1297 { 1298 M2M_ERR("listen Failure!\n"); 1299 close(sock); 1300 } 1301 } 1302 } 1303 break; 1304 1305 case SOCKET_MSG_ACCEPT: 1306 { 1307 tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg*)pvMsg; 1308 1309 if(pstrAccept->sock >= 0) 1310 { 1311 TcpNotificationSocket = pstrAccept->sock; 1312 recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT); 1313 } 1314 else 1315 { 1316 M2M_ERR("accept failure\n"); 1317 } 1318 } 1319 break; 1320 1321 default: 1322 break; 1323 } 1324 } 1325 1326 @endcode 1327 */ 1328 NMI_API sint8 listen(SOCKET sock, uint8 backlog); 1329 /** @} */ 1330 /** @defgroup AcceptFn accept 1331 * @ingroup SocketAPI 1332 * The function has no current implementation. An empty deceleration is used to prevent errors when legacy application code is used. 1333 * 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. 1334 */ 1335 /**@{*/ 1336 /*! 1337 @fn \ 1338 NMI_API sint8 accept(SOCKET sock, struct sockaddr *addr, uint8 *addrlen); 1339 1340 @param [in] sock 1341 Socket ID, must hold a non negative value. 1342 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1343 @param [in] addr 1344 Not used in the current implementation. 1345 1346 @param [in] addrlen 1347 Not used in the current implementation. 1348 1349 @return 1350 The function returns ZERO for successful operations and a negative value otherwise. 1351 The possible error values are: 1352 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 1353 Indicating that the operation was successful. 1354 1355 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 1356 Indicating passing invalid arguments such as negative socket ID. 1357 */ 1358 NMI_API sint8 accept(SOCKET sock, struct sockaddr *addr, uint8 *addrlen); 1359 /** @} */ 1360 /** @defgroup ConnectFn connect 1361 * @ingroup SocketAPI 1362 * Establishes a TCP connection with a remote server. 1363 The asynchronous connect function must be called after receiving a valid socket ID from the @ref socket function. 1364 The application socket callback function is notified of a successful new socket connection through the event @ref SOCKET_MSG_CONNECT. 1365 A successful connect means the TCP session is active. The application is then required to make a call to the @ref recv 1366 to receive any packets transmitted by the remote server, unless the application is interrupted by a notification of socket connection 1367 termination. 1368 */ 1369 /**@{*/ 1370 /*! 1371 @fn \ 1372 NMI_API sint8 connect(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen); 1373 1374 @param [in] sock 1375 Socket ID, must hold a non negative value. 1376 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1377 1378 @param [in] pstrAddr 1379 Address of the remote server. 1380 @param [in] pstrAddr 1381 Pointer to socket address structure "sockaddr_in" 1382 [sockaddr_in](@ref sockaddr_in) 1383 1384 @param [in] u8AddrLen 1385 Size of the given socket address structure in bytes. 1386 Not currently used, implemented for BSD compatibility only. 1387 @pre 1388 The socket function must be called to allocate a TCP socket before passing the socket ID to the bind function. 1389 If the socket is not bound, you do NOT have to call bind before the "connect" function. 1390 1391 @see 1392 socket 1393 recv 1394 send 1395 close 1396 1397 @return 1398 The function returns ZERO for successful operations and a negative value otherwise. 1399 The possible error values are: 1400 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 1401 Indicating that the operation was successful. 1402 1403 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 1404 Indicating passing invalid arguments such as negative socket ID or NULL socket address structure. 1405 1406 - [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID) 1407 Indicate socket connect failure. 1408 \section Example 1409 The example demonstrates a TCP application, showing how the asynchronous call to the connect function is made through the main function and how the 1410 callback function handles the @ref SOCKET_MSG_CONNECT event. 1411 \subsection sub1 Main Function 1412 @code 1413 struct sockaddr_in Serv_Addr; 1414 SOCKET TcpClientSocket =-1; 1415 int ret = -1 1416 1417 TcpClientSocket = socket(AF_INET,SOCK_STREAM,0); 1418 Serv_Addr.sin_family = AF_INET; 1419 Serv_Addr.sin_port = _htons(1234); 1420 Serv_Addr.sin_addr.s_addr = inet_addr(SERVER); 1421 printf("Connected to server via socket %u\n",TcpClientSocket); 1422 1423 do 1424 { 1425 ret = connect(TcpClientSocket,(sockaddr_in*)&Serv_Addr,sizeof(Serv_Addr)); 1426 if(ret != 0) 1427 { 1428 printf("Connection Error\n"); 1429 } 1430 else 1431 { 1432 printf("Connection successful.\n"); 1433 break; 1434 } 1435 }while(1) 1436 @endcode 1437 \subsection sub2 Socket Callback 1438 @code 1439 if(u8Msg == SOCKET_MSG_CONNECT) 1440 { 1441 tstrSocketConnectMsg *pstrConnect = (tstrSocketConnectMsg*)pvMsg; 1442 if(pstrConnect->s8Error == 0) 1443 { 1444 uint8 acBuffer[GROWL_MSG_SIZE]; 1445 uint16 u16MsgSize; 1446 1447 printf("Connect success!\n"); 1448 1449 u16MsgSize = FormatMsg(u8ClientID, acBuffer); 1450 send(sock, acBuffer, u16MsgSize, 0); 1451 recv(pstrNotification->Socket, (void*)au8Msg,GROWL_DESCRIPTION_MAX_LENGTH, GROWL_RX_TIMEOUT); 1452 u8Retry = GROWL_CONNECT_RETRY; 1453 } 1454 else 1455 { 1456 M2M_DBG("Connection Failed, Error: %d\n",pstrConnect->s8Error"); 1457 close(pstrNotification->Socket); 1458 } 1459 } 1460 @endcode 1461 */ 1462 NMI_API sint8 connect(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen); 1463 /** @} */ 1464 /** @defgroup ReceiveFn recv 1465 * @ingroup SocketAPI 1466 * An asynchronous receive function, used to retrieve data from a TCP stream. 1467 Before calling the recv function, a successful socket connection status must have been received through any of the two socket events 1468 [SOCKET_MSG_CONNECT] or [SOCKET_MSG_ACCEPT], from the socket callback. Hence, indicating that the socket is already connected to a remote 1469 host. 1470 The application receives the required data in response to this asynchronous call through the reception of the event @ref SOCKET_MSG_RECV in the 1471 socket callback. 1472 1473 Receiving the SOCKET_MSG_RECV message in the callback with zero or negative buffer length indicates the following: 1474 - SOCK_ERR_NO_ERROR : Socket connection closed 1475 - SOCK_ERR_CONN_ABORTED : Socket connection aborted 1476 - SOCK_ERR_TIMEOUT : Socket receive timed out 1477 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. 1478 */ 1479 /**@{*/ 1480 /*! 1481 @fn \ 1482 NMI_API sint16 recv(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec); 1483 1484 @param [in] sock 1485 Socket ID, must hold a non negative value. 1486 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1487 1488 1489 @param [in] pvRecvBuf 1490 Pointer to a buffer that will hold the received data. The buffer is used 1491 in the recv callback to deliver the received data to the caller. The buffer must 1492 be resident in memory (heap or global buffer). 1493 1494 @param [in] u16BufLen 1495 The buffer size in bytes. 1496 1497 @param [in] u32Timeoutmsec 1498 Timeout for the recv function in milli-seconds. If the value is set to ZERO, the timeout 1499 will be set to infinite (the recv function waits forever). If the timeout period is 1500 elapsed with no data received, the socket will get a timeout error. 1501 @pre 1502 - The socket function must be called to allocate a TCP socket before passing the socket ID to the recv function. 1503 - The socket in a connected state is expected to receive data through the socket interface. 1504 1505 @see 1506 socket 1507 connect 1508 bind 1509 listen 1510 recvfrom 1511 close 1512 1513 1514 @return 1515 The function returns ZERO for successful operations and a negative value otherwise. 1516 The possible error values are: 1517 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 1518 Indicating that the operation was successful. 1519 1520 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 1521 Indicating passing invalid arguments such as negative socket ID or NULL Recieve buffer. 1522 1523 - [SOCK_ERR_BUFFER_FULL](@ref SOCK_ERR_BUFFER_FULL) 1524 Indicate socket receive failure. 1525 \section Example 1526 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 1527 received data when the SOCKET_MSG_RECV event is received. 1528 @code 1529 1530 switch(u8Msg) 1531 { 1532 1533 case SOCKET_MSG_ACCEPT: 1534 { 1535 tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg*)pvMsg; 1536 1537 if(pstrAccept->sock >= 0) 1538 { 1539 recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT); 1540 } 1541 else 1542 { 1543 M2M_ERR("accept\n"); 1544 } 1545 } 1546 break; 1547 1548 1549 case SOCKET_MSG_RECV: 1550 { 1551 tstrSocketRecvMsg *pstrRx = (tstrSocketRecvMsg*)pvMsg; 1552 1553 if(pstrRx->s16BufferSize > 0) 1554 { 1555 1556 recv(sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT); 1557 } 1558 else 1559 { 1560 printf("Socet recv Error: %d\n",pstrRx->s16BufferSize); 1561 close(sock); 1562 } 1563 } 1564 break; 1565 1566 default: 1567 break; 1568 } 1569 } 1570 @endcode 1571 */ 1572 NMI_API sint16 recv(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec); 1573 /** @} */ 1574 /** @defgroup ReceiveFromSocketFn recvfrom 1575 * @ingroup SocketAPI 1576 * Receives data from a UDP Socket. 1577 * 1578 * The asynchronous recvfrom function is used to retrieve data from a UDP socket. The socket must already be bound to 1579 * a local port before a call to the recvfrom function is made (i.e message @ref SOCKET_MSG_BIND is received 1580 * with successful status in the socket callback). 1581 * 1582 * Upon calling the recvfrom function with a successful return code, the application is expected to receive a notification 1583 * in the socket callback whenever a message is received through the @ref SOCKET_MSG_RECVFROM event. 1584 * 1585 * Receiving the SOCKET_MSG_RECVFROM message in the callback with zero, indicates that the socket is closed. 1586 * Whereby a negative buffer length indicates one of the socket error codes such as socket timeout error @SOCK_ERR_TIMEOUT: 1587 * 1588 * The recvfrom callback can also be used to show the IP address of the remote host that sent the frame by 1589 * using the "strRemoteAddr" element in the @ref tstrSocketRecvMsg structure. (refer to the code example) 1590 */ 1591 /**@{*/ 1592 /*! 1593 @fn \ 1594 NMI_API sint16 recvfrom(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32TimeoutSeconds); 1595 1596 @param [in] sock 1597 Socket ID, must hold a non negative value. 1598 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1599 1600 @param [in] pvRecvBuf 1601 Pointer to a buffer that will hold the received data. The buffer shall be used 1602 in the recv callback to deliver the received data to the caller. The buffer must 1603 be resident in memory (heap or global buffer). 1604 1605 @param [in] u16BufLen 1606 The buffer size in bytes. 1607 1608 @param [in] u32TimeoutSeconds 1609 Timeout for the recv function in milli-seconds. If the value is set to ZERO, the timeout 1610 will be set to infinite (the recv function waits forever). 1611 1612 @pre 1613 - The socket function must be called to allocate a UDP socket before passing the socket ID to the recvfrom function. 1614 - The socket corresponding to the socket ID must be successfully bound to a local port through the call to a @ref bind function. 1615 1616 @see 1617 socket 1618 bind 1619 close 1620 1621 @return 1622 The function returns ZERO for successful operations and a negative value otherwise. 1623 The possible error values are: 1624 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 1625 Indicating that the operation was successful. 1626 1627 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 1628 Indicating passing invalid arguments such as negative socket ID or NULL Receive buffer. 1629 1630 - [SOCK_ERR_BUFFER_FULL](@ref SOCK_ERR_BUFFER_FULL) 1631 Indicate socket receive failure. 1632 \section Example 1633 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 1634 received data when the SOCKET_MSG_RECVFROM event is received. 1635 @code 1636 switch(u8Msg) 1637 { 1638 1639 case SOCKET_MSG_BIND: 1640 { 1641 tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg; 1642 1643 if(pstrBind != NULL) 1644 { 1645 if(pstrBind->status == 0) 1646 { 1647 recvfrom(sock, gau8SocketTestBuffer, TEST_BUFFER_SIZE, 0); 1648 } 1649 else 1650 { 1651 M2M_ERR("bind\n"); 1652 } 1653 } 1654 } 1655 break; 1656 1657 1658 case SOCKET_MSG_RECVFROM: 1659 { 1660 tstrSocketRecvMsg *pstrRx = (tstrSocketRecvMsg*)pvMsg; 1661 1662 if(pstrRx->s16BufferSize > 0) 1663 { 1664 //get the remote host address and port number 1665 uint16 u16port = pstrRx->strRemoteAddr.sin_port; 1666 uint32 strRemoteHostAddr = pstrRx->strRemoteAddr.sin_addr.s_addr; 1667 1668 printf("Recieved frame with size = %d.\tHost address=%x, Port number = %d\n\n",pstrRx->s16BufferSize,strRemoteHostAddr, u16port); 1669 1670 ret = recvfrom(sock,gau8SocketTestBuffer,sizeof(gau8SocketTestBuffer),TEST_RECV_TIMEOUT); 1671 } 1672 else 1673 { 1674 printf("Socet recv Error: %d\n",pstrRx->s16BufferSize); 1675 ret = close(sock); 1676 } 1677 } 1678 break; 1679 1680 default: 1681 break; 1682 } 1683 } 1684 @endcode 1685 */ 1686 NMI_API sint16 recvfrom(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec); 1687 /** @} */ 1688 /** @defgroup SendFn send 1689 * @ingroup SocketAPI 1690 * Asynchronous sending function, used to send data on a TCP/UDP socket. 1691 1692 * Called by the application code when there is outgoing data available required to be sent on a specific socket handler. 1693 * 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. 1694 * @ref send function is most commonly called for sockets in a connected state. 1695 * After the data is sent, the socket callback function registered using registerSocketCallback(), is expected to receive an event of type 1696 * @ref SOCKET_MSG_SEND holding information containing the number of data bytes sent. 1697 */ 1698 /**@{*/ 1699 /*! 1700 @fn \ 1701 NMI_API sint16 send(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 u16Flags); 1702 1703 @param [in] sock 1704 Socket ID, must hold a non negative value. 1705 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1706 1707 @param [in] pvSendBuffer 1708 Pointer to a buffer holding data to be transmitted. 1709 1710 @param [in] u16SendLength 1711 The buffer size in bytes. 1712 1713 @param [in] u16Flags 1714 Not used in the current implementation. 1715 1716 @pre 1717 Sockets must be initialized using socketInit. \n 1718 1719 For TCP Socket:\n 1720 Must use a successfully connected Socket (so that the intended recipient address is known ahead of sending the data). 1721 Hence this function is expected to be called after a successful socket connect operation(in client case or accept in the 1722 the server case).\n 1723 1724 For UDP Socket:\n 1725 UDP sockets most commonly use @ref sendto function, where the destination address is defined. However, in-order to send outgoing data 1726 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, 1727 to ensure that the destination address is saved in the firmware. 1728 1729 @see 1730 socketInit 1731 recv 1732 sendto 1733 socket 1734 connect 1735 accept 1736 sendto 1737 1738 @warning 1739 u16SendLength must not exceed @ref SOCKET_BUFFER_MAX_LENGTH. \n 1740 Use a valid socket identifier through the a prior call to the @ref socket function. 1741 Must use a valid buffer pointer. 1742 Successful completion of a call to send() does not guarantee delivery of the message, 1743 A negative return value indicates only locally-detected errors 1744 1745 1746 @return 1747 The function shall return @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise. 1748 */ 1749 NMI_API sint16 send(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 u16Flags); 1750 /** @} */ 1751 /** @defgroup SendToSocketFn sendto 1752 * @ingroup SocketAPI 1753 * Asynchronous sending function, used to send data on a UDP socket. 1754 * Called by the application code when there is data required to be sent on a UDP socket handler. 1755 * The application code is expected to receive data from a successful bounded socket node. 1756 * 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 1757 * only with UDP sockets. 1758 * After the data is sent, the socket callback function registered using registerSocketCallback(), is expected to receive an event of type 1759 * @ref SOCKET_MSG_SENDTO. 1760 */ 1761 /**@{*/ 1762 /*! 1763 @fn \ 1764 NMI_API sint16 sendto(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 flags, struct sockaddr *pstrDestAddr, uint8 u8AddrLen); 1765 1766 @param [in] sock 1767 Socket ID, must hold a non negative value. 1768 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1769 1770 @param [in] pvSendBuffer 1771 Pointer to a buffer holding data to be transmitted. 1772 A NULL value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1773 1774 @param [in] u16SendLength 1775 The buffer size in bytes. It must not exceed @ref SOCKET_BUFFER_MAX_LENGTH. 1776 1777 @param [in] flags 1778 Not used in the current implementation 1779 1780 @param [in] pstrDestAddr 1781 The destination address. 1782 1783 @param [in] u8AddrLen 1784 Destination address length in bytes. 1785 Not used in the current implementation, only included for BSD compatibility. 1786 @pre 1787 Sockets must be initialized using socketInit. 1788 1789 @see 1790 socketInit 1791 recvfrom 1792 sendto 1793 socket 1794 connect 1795 accept 1796 send 1797 1798 @warning 1799 u16SendLength must not exceed @ref SOCKET_BUFFER_MAX_LENGTH. \n 1800 Use a valid socket (returned from socket ). 1801 A valid buffer pointer must be used (not NULL). \n 1802 Successful completion of a call to sendto() does not guarantee delivery of the message, 1803 A negative return value indicates only locally-detected errors 1804 1805 @return 1806 The function returns @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise. 1807 */ 1808 NMI_API sint16 sendto(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 flags, struct sockaddr *pstrDestAddr, uint8 u8AddrLen); 1809 /** @} */ 1810 /** @defgroup CloseSocketFn close 1811 * @ingroup SocketAPI 1812 * Synchronous close function, releases all the socket assigned resources. 1813 */ 1814 /**@{*/ 1815 /*! 1816 @fn \ 1817 NMI_API sint8 close(SOCKET sock); 1818 1819 @param [in] sock 1820 Socket ID, must hold a non negative value. 1821 A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in. 1822 1823 @pre 1824 Sockets must be initialized through the call of the socketInit function. 1825 @ref close is called only for valid socket identifiers created through the @ref socket function. 1826 1827 @warning 1828 If @ref close is called while there are still pending messages (sent or received ) they will be discarded. 1829 1830 @see 1831 socketInit 1832 socket 1833 1834 @return 1835 The function returned @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise. 1836 */ 1837 NMI_API sint8 winc1500_close(SOCKET sock); 1838 1839 1840 /** @} */ 1841 /** @defgroup InetAddressFn nmi_inet_addr 1842 * @ingroup SocketAPI 1843 * Synchronous function which returns a BSD socket compliant Internet Protocol (IPv4) socket address. 1844 * 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 1845 * (i.e. "192.168.10.1"). 1846 * This function is used whenever an ip address needs to be set in the proper format 1847 * (i.e. for the @ref tstrM2MIPConfig structure). 1848 */ 1849 /**@{*/ 1850 /*! 1851 @fn \ 1852 NMI_API uint32 nmi_inet_addr(char *pcIpAddr); 1853 1854 @param [in] pcIpAddr 1855 A null terminated string containing the IP address in IPv4 dotted-decimal address. 1856 1857 @return 1858 Unsigned 32-bit integer representing the IP address in Network byte order 1859 (eg. "192.168.10.1" will be expressed as 0x010AA8C0). 1860 1861 */ 1862 NMI_API uint32 nmi_inet_addr(char *pcIpAddr); 1863 1864 1865 /** @} */ 1866 /** @defgroup gethostbynameFn gethostbyname 1867 * @ingroup SocketAPI 1868 * Asynchronous DNS resolving function. This function use DNS to resolve a domain name into the corresponding IP address. 1869 * 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() 1870 */ 1871 /**@{*/ 1872 /*! 1873 @fn \ 1874 NMI_API sint8 gethostbyname(uint8 * pcHostName); 1875 1876 @param [in] pcHostName 1877 NULL terminated string containing the domain name for the remote host. 1878 Its size must not exceed [HOSTNAME_MAX_SIZE](@ref HOSTNAME_MAX_SIZE). 1879 1880 @see 1881 registerSocketCallback 1882 1883 @warning 1884 Successful completion of a call to gethostbyname() does not guarantee success of the DNS request, 1885 a negative return value indicates only locally-detected errors 1886 1887 @return 1888 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) 1889 - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG) 1890 */ 1891 NMI_API sint8 gethostbyname(uint8 * pcHostName); 1892 1893 1894 /** @} */ 1895 /** @defgroup sslEnableCertExpirationCheckFn sslEnableCertExpirationCheck 1896 * @ingroup SocketAPI 1897 * Configure the behavior of the SSL Library for Certificate Expiry Validation. 1898 */ 1899 /**@{*/ 1900 /*! 1901 @fn \ 1902 NMI_API sint8 sslEnableCertExpirationCheck(tenuSslCertExpSettings enuValidationSetting); 1903 1904 @param [in] enuValidationSetting 1905 See @ref tenuSslCertExpSettings for details. 1906 1907 @return 1908 - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR) for successful operation and negative error code otherwise. 1909 1910 @sa tenuSslCertExpSettings 1911 */ 1912 NMI_API sint8 sslEnableCertExpirationCheck(tenuSslCertExpSettings enuValidationSetting); 1913 1914 1915 /** @} */ 1916 1917 /** @defgroup SetSocketOptionFn setsockopt 1918 * @ingroup SocketAPI 1919 *The setsockopt() function shall set the option specified by the option_name 1920 * argument, at the protocol level specified by the level argument, to the value 1921 * pointed to by the option_value argument for the socket specified by the socket argument. 1922 * 1923 * <p>Possible protocol level values supported are @ref SOL_SOCKET and @ref SOL_SSL_SOCKET. 1924 * Possible options when the protocol level is @ref SOL_SOCKET :</p> 1925 * <table style="width: 100%"> 1926 * <tr> 1927 * <td style="height: 22px"><strong>@ref SO_SET_UDP_SEND_CALLBACK</strong></td> 1928 * <td style="height: 22px">Enable/Disable callback messages for sendto(). 1929 * Since UDP is unreliable by default the user maybe interested (or not) in 1930 * receiving a message of @ref SOCKET_MSG_SENDTO for each call of sendto(). 1931 * Enabled if option value equals @ref TRUE, disabled otherwise.</td> 1932 * </tr> 1933 * <tr> 1934 * <td><strong>@ref IP_ADD_MEMBERSHIP</strong></td> 1935 * <td>Valid for UDP sockets. This option is used to receive frames sent to 1936 * a multicast group. option_value shall be a pointer to Unsigned 32-bit 1937 * integer containing the multicast IPv4 address. </td> 1938 * </tr> 1939 * <tr> 1940 * <td><strong>@ref IP_DROP_MEMBERSHIP</strong></td> 1941 * <td>Valid for UDP sockets. This option is used to stop receiving frames 1942 * sent to a multicast group. option_value shall be a pointer to Unsigned 1943 * 32-bit integer containing the multicast IPv4 address.</td> 1944 * </tr> 1945 * </table> 1946 * <p>Possible options when the protcol leve is @ref SOL_SSL_SOCKET</p> 1947 * <table style="width: 100%"> 1948 * <tr> 1949 * <td style="height: 22px"><strong> 1950 * @ref SO_SSL_BYPASS_X509_VERIF</strong></td> 1951 * <td style="height: 22px">Allow an opened SSL socket to bypass the X509 1952 * certificate verification process. It is highly recommended <strong>NOT</strong> to use 1953 * this socket option in production software applications. The option is 1954 * supported for debugging and testing purposes. The option value should be 1955 * casted to int type and it is handled as a boolean flag.</td> 1956 * </tr> 1957 * <tr> 1958 * <td><strong>@ref SO_SSL_SNI</strong></td> 1959 * <td>Set the Server Name Indicator (SNI) for an SSL socket. The SNI is a 1960 * null terminated string containing the server name associated with the 1961 * connection. It must not exceed the size of @ref HOSTNAME_MAX_SIZE.</td> 1962 * </tr> 1963 * <tr> 1964 * <td><strong>@ref SO_SSL_ENABLE_SESSION_CACHING</strong></td> 1965 * <td>This option allow the TLS to cache the session information for fast 1966 * TLS session establishment in future connections using the TLS Protocol 1967 * session resume features.</td> 1968 * </tr> 1969 * </table> 1970 */ 1971 /**@{*/ 1972 /*! 1973 @fn \ 1974 NMI_API sint8 setsockopt(SOCKET socket, uint8 u8Level, uint8 option_name, 1975 const void *option_value, uint16 u16OptionLen); 1976 1977 @param [in] sock 1978 Socket handler. 1979 1980 @param [in] level 1981 protocol level. See description above. 1982 1983 @param [in] option_name 1984 option to be set. See description above. 1985 1986 @param [in] option_value 1987 pointer to user provided value. 1988 1989 @param [in] option_len 1990 length of the option value in bytes. 1991 @return 1992 The function shall return \ref SOCK_ERR_NO_ERROR for successful operation 1993 and a negative value (indicating the error) otherwise. 1994 @sa SOL_SOCKET, SOL_SSL_SOCKET, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP 1995 */ 1996 NMI_API sint8 setsockopt(SOCKET socket, uint8 u8Level, uint8 option_name, 1997 const void *option_value, uint16 u16OptionLen); 1998 1999 2000 /** @} */ 2001 /** @defgroup GetSocketOptionsFn getsockopt 2002 * @ingroup SocketAPI 2003 * Get socket options retrieves 2004 * This Function isn't implemented yet but this is the form that will be released later. 2005 */ 2006 /**@{*/ 2007 /*! 2008 @fn \ 2009 sint8 getsockopt(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8 * pu8OptLen); 2010 2011 @brief 2012 2013 @param [in] sock 2014 Socket Identifie. 2015 @param [in] u8Level 2016 The protocol level of the option. 2017 @param [in] u8OptName 2018 The u8OptName argument specifies a single option to get. 2019 @param [out] pvOptValue 2020 The pvOptValue argument contains pointer to a buffer containing the option value. 2021 @param [out] pu8OptLen 2022 Option value buffer length. 2023 @return 2024 The function shall return ZERO for successful operation and a negative value otherwise. 2025 */ 2026 NMI_API sint8 getsockopt(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8* pu8OptLen); 2027 /** @} */ 2028 2029 /**@}*/ 2030 /** @defgroup PingFn m2m_ping_req 2031 * @ingroup SocketAPI 2032 * The function sends ping request to the given IP Address. 2033 */ 2034 /**@{*/ 2035 /*! 2036 @fn \ 2037 NMI_API sint8 m2m_ping_req(uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb); 2038 2039 @param [in] u32DstIP 2040 Target Destination IP Address for the ping request. It must be represented in Network byte order. 2041 The function nmi_inet_addr could be used to translate the dotted decimal notation IP 2042 to its Network bytes order integer represntative. 2043 2044 @param [in] u8TTL 2045 IP TTL value for the ping request. If set to ZERO, the dfault value SHALL be used. 2046 2047 @param [in] fpPingCb 2048 Callback will be called to deliver the ping statistics. 2049 2050 @see nmi_inet_addr 2051 @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. 2052 */ 2053 NMI_API sint8 m2m_ping_req(uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb); 2054 /**@}*/ 2055 2056 2057 #ifdef __cplusplus 2058 } 2059 #endif /* __cplusplus */ 2060 2061 #endif /* __SOCKET_H__ */ 2062
