1741 lines
57 KiB
C
1741 lines
57 KiB
C
/**
|
|
*
|
|
* \file
|
|
*
|
|
* \brief BSD compatible socket interface.
|
|
*
|
|
* Copyright (c) 2017-2018 Microchip Technology Inc. and its subsidiaries.
|
|
*
|
|
* \asf_license_start
|
|
*
|
|
* \page License
|
|
*
|
|
* Subject to your compliance with these terms, you may use Microchip
|
|
* software and any derivatives exclusively with Microchip products.
|
|
* It is your responsibility to comply with third party license terms applicable
|
|
* to your use of third party software (including open source software) that
|
|
* may accompany Microchip software.
|
|
*
|
|
* THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES,
|
|
* WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE,
|
|
* INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,
|
|
* AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE
|
|
* LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL
|
|
* LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE
|
|
* SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE
|
|
* POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT
|
|
* ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY
|
|
* RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
|
|
* THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
|
|
*
|
|
* \asf_license_stop
|
|
*
|
|
*/
|
|
|
|
/**@defgroup SOCKETAPI SOCKET
|
|
*/
|
|
|
|
#ifndef __SOCKET_H__
|
|
#define __SOCKET_H__
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
|
|
INCLUDES
|
|
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
|
|
|
|
#include "driver/include/m2m_types.h"
|
|
|
|
/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
|
|
MACROS
|
|
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
|
|
/**@defgroup SOCKETDEF Defines
|
|
* @ingroup SOCKETAPI
|
|
* The following list of macros are used to define constants used throughout the socket layer, and SSL Socket options.
|
|
* @{ */
|
|
|
|
#define HOSTNAME_MAX_SIZE 100
|
|
/*!<
|
|
Maximum allowed size for a host domain name passed to the function gethostbyname @ref gethostbyname.
|
|
command value. Used with the setsocketopt function.
|
|
|
|
*/
|
|
|
|
#define SOCKET_BUFFER_MAX_LENGTH 1400
|
|
/*!<
|
|
Maximum allowed size for a socket data buffer. Used with @ref send socket
|
|
function to ensure that the buffer sent is within the allowed range.
|
|
*/
|
|
|
|
#define AF_INET 2
|
|
/*!<
|
|
The AF_INET is the address family used for IPv4. An IPv4 transport address is specified with the @ref sockaddr_in structure.
|
|
(It is the only supported type for the current implementation.)
|
|
*/
|
|
|
|
|
|
#define SOCK_STREAM 1
|
|
/*!<
|
|
One of the IPv4 supported socket types for reliable connection-oriented stream connection.
|
|
Passed to the @ref socket function for the socket creation operation.
|
|
*/
|
|
|
|
#define SOCK_DGRAM 2
|
|
/*!<
|
|
One of the IPv4 supported socket types for unreliable connectionless datagram connection.
|
|
Passed to the @ref socket function for the socket creation operation.
|
|
*/
|
|
|
|
|
|
#define SOCKET_FLAGS_SSL 0x01
|
|
/*!<
|
|
This flag shall be passed to the socket API for SSL session.
|
|
*/
|
|
|
|
#define TCP_SOCK_MAX (7)
|
|
/*!<
|
|
Maximum number of simultaneous TCP sockets.
|
|
*/
|
|
|
|
#define UDP_SOCK_MAX 4
|
|
/*!<
|
|
Maximum number of simultaneous UDP sockets.
|
|
*/
|
|
|
|
#define MAX_SOCKET (TCP_SOCK_MAX + UDP_SOCK_MAX)
|
|
/*!<
|
|
Maximum number of simultaneous sockets.
|
|
*/
|
|
|
|
#define SOL_SOCKET 1
|
|
/*!<
|
|
Socket option.
|
|
Used with the @ref setsockopt function
|
|
*/
|
|
|
|
#define SO_SET_UDP_SEND_CALLBACK 0x00
|
|
/*!<
|
|
Socket option used by the application to enable/disable
|
|
the use of UDP send callbacks.
|
|
Used with the @ref setsockopt function.
|
|
*/
|
|
|
|
#define IP_ADD_MEMBERSHIP 0x01
|
|
/*!<
|
|
Set Socket Option Add Membership command value.
|
|
Used with the @ref setsockopt function.
|
|
*/
|
|
|
|
|
|
#define IP_DROP_MEMBERSHIP 0x02
|
|
/*!<
|
|
Set Socket Option Drop Membership command value.
|
|
Used with the @ref setsockopt function.
|
|
*/
|
|
|
|
|
|
// SSL Socket options
|
|
|
|
#define SOL_SSL_SOCKET 2
|
|
/*!<
|
|
SSL Socket option level.
|
|
Used with the @ref setsockopt function
|
|
*/
|
|
|
|
|
|
#define SO_SSL_BYPASS_X509_VERIF 0x01
|
|
/*!<
|
|
Allow an opened SSL socket to bypass the X509 certificate
|
|
verification process.
|
|
It is highly recommended NOT to use this socket option in production
|
|
software applications. It is intended for debugging and testing
|
|
purposes only.\n
|
|
The option value should be cast to int type and it is handled
|
|
as a boolean flag.
|
|
*/
|
|
|
|
|
|
#define SO_SSL_SNI 0x02
|
|
/*!<
|
|
Set the Server Name Indicator (SNI) for an SSL socket. The
|
|
SNI is a NULL terminated string containing the server name
|
|
associated with the connection. It must not exceed the size
|
|
of HOSTNAME_MAX_SIZE. If the SNI is not a null string, then
|
|
TLS Client Hello messages will include the SNI extension.
|
|
*/
|
|
|
|
|
|
#define SO_SSL_ENABLE_SESSION_CACHING 0x03
|
|
/*!<
|
|
Allow the TLS to cache the session information for fast
|
|
TLS session establishment in future connections using the
|
|
TLS Protocol session resume features.\n
|
|
The option value should be cast to int type and it is handled
|
|
as a boolean flag.
|
|
|
|
*/
|
|
|
|
#define SO_SSL_ENABLE_CERTNAME_VALIDATION 0x04
|
|
/*!<
|
|
Enable internal validation of server name against the server's
|
|
certificate subject common name. If there is no server name
|
|
provided (via the SO_SSL_SNI option), setting this option does
|
|
nothing.\n
|
|
The option value should be cast to int type and it is handled
|
|
as a boolean flag.
|
|
*/
|
|
|
|
#define SO_SSL_ENABLE_SNI_VALIDATION 0x04
|
|
/*!<
|
|
Legacy name for @ref SO_SSL_ENABLE_CERTNAME_VALIDATION.\n
|
|
The option value should be cast to int type and it is handled
|
|
as a boolean flag.
|
|
*/
|
|
//@}
|
|
|
|
/** @defgroup SSLCipherSuiteID TLS Cipher Suite IDs
|
|
* @ingroup TLSDefines
|
|
* The following list of macros defined the list of supported TLS Cipher suites.
|
|
* Each MACRO defines a single Cipher suite.
|
|
* @sa m2m_ssl_set_active_ciphersuites
|
|
* @{
|
|
*/
|
|
|
|
#define SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA NBIT0
|
|
#define SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA256 NBIT1
|
|
#define SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA NBIT2
|
|
#define SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA256 NBIT3
|
|
#define SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 NBIT4
|
|
#define SSL_CIPHER_DHE_RSA_WITH_AES_128_GCM_SHA256 NBIT5
|
|
#define SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA NBIT6
|
|
#define SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA256 NBIT7
|
|
#define SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA NBIT8
|
|
#define SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA256 NBIT9
|
|
#define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA NBIT10
|
|
#define SSL_CIPHER_ECDHE_RSA_WITH_AES_256_CBC_SHA NBIT11
|
|
#define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA256 NBIT12
|
|
#define SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 NBIT13
|
|
#define SSL_CIPHER_ECDHE_RSA_WITH_AES_128_GCM_SHA256 NBIT14
|
|
#define SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 NBIT15
|
|
|
|
|
|
#define SSL_ECC_ONLY_CIPHERS \
|
|
(\
|
|
SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | \
|
|
SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 \
|
|
)
|
|
/*!<
|
|
All supported ECC Ciphers. These ciphers are turned off by default at startup.
|
|
The application may enable them if it has an ECC math engine (like ATECC508).
|
|
*/
|
|
|
|
|
|
#define SSL_DEFAULT_CIPHERS \
|
|
(\
|
|
SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA | \
|
|
SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA256 | \
|
|
SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA | \
|
|
SSL_CIPHER_DHE_RSA_WITH_AES_128_CBC_SHA256 | \
|
|
SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 | \
|
|
SSL_CIPHER_DHE_RSA_WITH_AES_128_GCM_SHA256 | \
|
|
SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA | \
|
|
SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA256 | \
|
|
SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA | \
|
|
SSL_CIPHER_DHE_RSA_WITH_AES_256_CBC_SHA256 \
|
|
)
|
|
/*!<
|
|
All supported Non-ECC Ciphers. This is the default active group after startup.
|
|
Note that firmware may support only a subset of these.
|
|
*/
|
|
//@}
|
|
|
|
/**@defgroup SOCKETBYTEORDER Byte Order
|
|
* @ingroup SOCKETAPI
|
|
* The following list of macros are used to convert between host representation and network byte order.
|
|
* @{ */
|
|
#ifdef _NM_BSP_BIG_END
|
|
#define _htonl(m) (m)
|
|
/*!<
|
|
Convert a 4-byte integer from the Host representation to Network byte order (Host is BE).
|
|
*/
|
|
#define _htons(A) (A)
|
|
/*!<
|
|
Convert a 2-byte integer (short) from Host representation to Network byte order (Host is BE).
|
|
*/
|
|
#else
|
|
#define _htonl(m) \
|
|
(uint32)(((uint32)(m << 24)) | ((uint32)((m & 0x0000FF00) << 8)) | ((uint32)((m & 0x00FF0000) >> 8)) | ((uint32)(((uint32)m) >> 24)))
|
|
/*!<
|
|
Convert a 4-byte integer from Host representation to Network byte order (Host is LE).
|
|
*/
|
|
|
|
#define _htons(A) (uint16)((((uint16) (A)) << 8) | (((uint16) (A)) >> 8))
|
|
/*!<
|
|
Convert a 2-byte integer (short) from Host representation to Network byte order (Host is LE).
|
|
*/
|
|
#endif
|
|
|
|
|
|
#define _ntohl _htonl
|
|
/*!<
|
|
Convert a 4-byte integer from Network byte order to Host representation.
|
|
*/
|
|
|
|
|
|
#define _ntohs _htons
|
|
/*!<
|
|
Convert a 2-byte integer from Network byte order to Host representation.
|
|
*/
|
|
//@}
|
|
|
|
/**************
|
|
Socket Errors
|
|
**************/
|
|
/**@defgroup SocketErrorCode Error Codes
|
|
* @ingroup SOCKETAPI
|
|
* The following list of macros are used to define the possible error codes.
|
|
* Errors are listed in numerical order with the error macro name.
|
|
* @{
|
|
*/
|
|
#define SOCK_ERR_NO_ERROR 0
|
|
/*!<
|
|
Successful socket operation. This code is also used with event @ref SOCKET_MSG_RECV if a socket connection is closed.
|
|
In that case, the application should call @ref close().
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_INVALID_ADDRESS -1
|
|
/*!<
|
|
Socket address is invalid. The socket operation cannot be completed successfully without specifying a valid address
|
|
For example: bind is called without specifying a port number
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_ADDR_ALREADY_IN_USE -2
|
|
/*!<
|
|
Socket operation cannot bind on the given address. Only one IP address per socket, and one socket per IP address is permitted -
|
|
any attempt for a new socket to bind with an IP address already bound to another open socket will return the following error code.
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_MAX_TCP_SOCK -3
|
|
/*!<
|
|
Exceeded the maximum number of TCP sockets. A maximum number of TCP sockets opened simultaneously is defined through TCP_SOCK_MAX.
|
|
It is not permitted to exceed that number at socket creation. Identifies that @ref socket operation failed.
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_MAX_UDP_SOCK -4
|
|
/*!<
|
|
Exceeded the maximum number of UDP sockets. A maximum number of UDP sockets opened simultaneously is defined through UDP_SOCK_MAX.
|
|
It is not permitted to exceed that number at socket creation. Identifies that @ref socket operation failed
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_INVALID_ARG -6
|
|
/*!<
|
|
An invalid argument is passed to a socket function. Identifies that @ref socket operation failed
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_MAX_LISTEN_SOCK -7
|
|
/*!<
|
|
Exceeded the maximum number of TCP passive listening sockets.
|
|
Identifies that @ref listen operation failed.
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_INVALID -9
|
|
/*!<
|
|
The requested socket operation is not valid in the current socket state.
|
|
For example: @ref accept is called on a TCP socket before @ref bind or @ref listen.
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_ADDR_IS_REQUIRED -11
|
|
/*!<
|
|
Destination address is required. Failure to provide the socket address required for the socket operation to be completed.
|
|
The @ref sendto function requires a destination address to send data.
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_CONN_ABORTED -12
|
|
/*!<
|
|
The socket is closed (reset) by the peer. If this error is received, the application should call @ref close().
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_TIMEOUT -13
|
|
/*!<
|
|
The socket pending operation has timed out. The socket remains open.
|
|
*/
|
|
|
|
|
|
#define SOCK_ERR_BUFFER_FULL -14
|
|
/*!<
|
|
No buffer space available to be used for the requested socket operation.
|
|
*/
|
|
|
|
//@}
|
|
|
|
/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
|
|
DATA TYPES
|
|
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
|
|
|
|
/** @defgroup SocketEnums Enumeration/Typedefs
|
|
* @ingroup SOCKETAPI
|
|
* Specific Enumeration-typedefs used for socket operations
|
|
* @{ */
|
|
/*!
|
|
@typedef \
|
|
SOCKET
|
|
|
|
@brief
|
|
Definition for socket handler data type.
|
|
Socket ID,used with all socket operations to uniquely identify the socket handler.
|
|
The ID is uniquely assigned at socket creation when calling @ref socket operation.
|
|
*/
|
|
typedef sint8 SOCKET;
|
|
//@}
|
|
|
|
/*!
|
|
@struct \
|
|
in_addr
|
|
|
|
@brief
|
|
IPv4 address representation.
|
|
|
|
This structure is used as a placeholder for IPV4 address in other structures.
|
|
@see
|
|
sockaddr_in
|
|
*/
|
|
typedef struct{
|
|
uint32 s_addr;
|
|
/*!<
|
|
Network Byte Order representation of the IPv4 address. For example,
|
|
the address "192.168.0.10" is represented as 0x0A00A8C0.
|
|
*/
|
|
}in_addr;
|
|
|
|
|
|
/*!
|
|
@struct \
|
|
sockaddr
|
|
|
|
@brief
|
|
Generic socket address structure.
|
|
|
|
@see \
|
|
sockaddr_in
|
|
*/
|
|
struct sockaddr{
|
|
uint16 sa_family;
|
|
/*!<
|
|
Socket address family.
|
|
*/
|
|
uint8 sa_data[14];
|
|
/*!<
|
|
Maximum size of all the different socket address structures.
|
|
*/
|
|
};
|
|
|
|
/*!
|
|
@struct \
|
|
sockaddr_in
|
|
|
|
@brief
|
|
Socket address structure for IPV4 addresses. Used to specify socket address information to connect to.
|
|
Can be cast to @ref sockaddr structure.
|
|
*/
|
|
struct sockaddr_in{
|
|
uint16 sin_family;
|
|
/*!<
|
|
Specifies the address family(AF).
|
|
Members of AF_INET address family are IPv4 addresses.
|
|
Hence,the only supported value for this is AF_INET.
|
|
*/
|
|
uint16 sin_port;
|
|
/*!<
|
|
Port number of the socket.
|
|
Network sockets are identified by a pair of IP addresses and port number.
|
|
Must be set in the Network Byte Order format , @ref _htons (e.g. _htons(80)).
|
|
Can NOT have zero value.
|
|
*/
|
|
in_addr sin_addr;
|
|
/*!<
|
|
IP Address of the socket.
|
|
The IP address is of type @ref in_addr structure.
|
|
Can be set to "0" to accept any IP address for server operation.
|
|
*/
|
|
uint8 sin_zero[8];
|
|
/*!<
|
|
Padding to make structure the same size as @ref sockaddr.
|
|
*/
|
|
};
|
|
|
|
/**@addtogroup SocketEnums
|
|
* @{ */
|
|
/*!
|
|
@enum \
|
|
tenuSocketCallbackMsgType
|
|
|
|
@brief
|
|
Asynchronous APIs make use of callback functions in-order to return back the results once the corresponding socket operation is completed.
|
|
Hence resuming the normal execution of the application code while the socket operation returns the results.
|
|
Callback functions expect event messages to be passed in, in-order to identify the operation they're returning the results for.
|
|
The following enum identifies the type of events that are received in the callback function.
|
|
|
|
Application Use:
|
|
In order for application developers to handle the pending events from the network controller through the callback functions,
|
|
a function call must be made to the function @ref m2m_wifi_handle_events at least once for each socket operation.
|
|
|
|
@see bind
|
|
@see listen
|
|
@see accept
|
|
@see connect
|
|
@see send
|
|
@see recv
|
|
|
|
*/
|
|
typedef enum{
|
|
SOCKET_MSG_BIND = 1,
|
|
/*!<
|
|
Bind socket event.
|
|
*/
|
|
SOCKET_MSG_LISTEN,
|
|
/*!<
|
|
Listen socket event.
|
|
*/
|
|
SOCKET_MSG_DNS_RESOLVE,
|
|
/*!<
|
|
DNS Resolution event.
|
|
*/
|
|
SOCKET_MSG_ACCEPT,
|
|
/*!<
|
|
Accept socket event.
|
|
*/
|
|
SOCKET_MSG_CONNECT,
|
|
/*!<
|
|
Connect socket event.
|
|
*/
|
|
SOCKET_MSG_RECV,
|
|
/*!<
|
|
Receive socket event.
|
|
*/
|
|
SOCKET_MSG_SEND,
|
|
/*!<
|
|
Send socket event.
|
|
*/
|
|
SOCKET_MSG_SENDTO,
|
|
/*!<
|
|
Sendto socket event.
|
|
*/
|
|
SOCKET_MSG_RECVFROM
|
|
/*!<
|
|
Recvfrom socket event.
|
|
*/
|
|
}tenuSocketCallbackMsgType;
|
|
// @}
|
|
|
|
|
|
/*!
|
|
@struct \
|
|
tstrSocketBindMsg
|
|
|
|
@brief Socket bind status.
|
|
|
|
An asynchronous call to the @ref bind socket operation, returns information through this structure in response.
|
|
This structure together with the event @ref SOCKET_MSG_BIND are passed in parameters to the callback function.
|
|
@see
|
|
bind
|
|
|
|
*/
|
|
typedef struct{
|
|
sint8 status;
|
|
/*!<
|
|
The result of the bind operation.
|
|
Holding a value of ZERO for a successful bind or otherwise a negative
|
|
error code corresponding to @ref SocketErrorCode.
|
|
*/
|
|
}tstrSocketBindMsg;
|
|
|
|
|
|
/*!
|
|
@struct \
|
|
tstrSocketListenMsg
|
|
|
|
@brief Socket listen status.
|
|
|
|
Socket listen information is returned through this structure in response to the asynchronous call to the @ref listen function.
|
|
This structure together with the event @ref SOCKET_MSG_LISTEN are passed-in parameters to the callback function.
|
|
@see
|
|
listen
|
|
*/
|
|
typedef struct{
|
|
sint8 status;
|
|
/*!<
|
|
Holding a value of ZERO for a successful listen or otherwise a negative
|
|
error code corresponding to @ref SocketErrorCode.
|
|
*/
|
|
}tstrSocketListenMsg;
|
|
|
|
|
|
|
|
/*!
|
|
@struct \
|
|
tstrSocketAcceptMsg
|
|
|
|
@brief Socket accept status.
|
|
|
|
Socket accept information is returned through this structure in response to the asynchronous call to the @ref accept function.
|
|
This structure together with the event @ref SOCKET_MSG_ACCEPT are passed-in parameters to the callback function.
|
|
*/
|
|
typedef struct{
|
|
SOCKET sock;
|
|
/*!<
|
|
On a successful @ref accept operation, the return information is the socket ID for the accepted connection with the remote peer.
|
|
Otherwise a negative error code is returned to indicate failure of the accept operation.
|
|
*/
|
|
struct sockaddr_in strAddr;
|
|
/*!<
|
|
Socket address structure for the remote peer.
|
|
*/
|
|
}tstrSocketAcceptMsg;
|
|
|
|
|
|
/*!
|
|
@struct \
|
|
tstrSocketConnectMsg
|
|
|
|
@brief Socket connect status.
|
|
|
|
Socket connect information is returned through this structure in response to the asynchronous call to the @ref connect socket function.
|
|
This structure together with the event @ref SOCKET_MSG_CONNECT are passed-in parameters to the callback function.
|
|
If the application receives this structure with a negative value in s8Error, the application should call @ref close().
|
|
*/
|
|
typedef struct{
|
|
SOCKET sock;
|
|
/*!<
|
|
Socket ID referring to the socket passed to the connect function call.
|
|
*/
|
|
sint8 s8Error;
|
|
/*!<
|
|
Connect error code.
|
|
Holding a value of ZERO for a successful connect or otherwise a negative
|
|
error code corresponding to the type of error.
|
|
*/
|
|
}tstrSocketConnectMsg;
|
|
|
|
|
|
/*!
|
|
@struct \
|
|
tstrSocketRecvMsg
|
|
|
|
@brief Socket recv status.
|
|
|
|
Socket receive information is returned through this structure in response to the asynchronous call to the recv or recvfrom socket functions.
|
|
This structure together with the events @ref SOCKET_MSG_RECV or @ref SOCKET_MSG_RECVFROM are passed-in parameters to the callback function.
|
|
@remark
|
|
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,
|
|
only data up to the buffer size is delivered to the user. The user must call @ref recv again in order to receive the remaining data.
|
|
A negative or zero buffer size indicates an error with the following code:
|
|
@ref SOCK_ERR_NO_ERROR : Socket connection closed. The application should now call @ref close().
|
|
@ref SOCK_ERR_CONN_ABORTED : Socket connection aborted. The application should now call @ref close().
|
|
@ref SOCK_ERR_TIMEOUT : Socket receive timed out. The socket connection remains open.
|
|
*/
|
|
typedef struct{
|
|
uint8 *pu8Buffer;
|
|
/*!<
|
|
Pointer to the USER buffer (passed to @ref recv and @ref recvfrom function) containing the received data chunk.
|
|
*/
|
|
sint16 s16BufferSize;
|
|
/*!<
|
|
The received data chunk size.
|
|
Holds a negative value if there is a receive error or ZERO on success upon reception of close socket message.
|
|
*/
|
|
uint16 u16RemainingSize;
|
|
/*!<
|
|
The number of bytes remaining in the current @ref recv operation.
|
|
*/
|
|
struct sockaddr_in strRemoteAddr;
|
|
/*!<
|
|
Socket address structure for the remote peer. It is valid for @ref SOCKET_MSG_RECVFROM event.
|
|
*/
|
|
}tstrSocketRecvMsg;
|
|
|
|
/**@addtogroup SocketEnums
|
|
* @{ */
|
|
/*!
|
|
@typedef \
|
|
tpfAppSocketCb
|
|
|
|
@brief
|
|
The main socket application callback function. Applications register their main socket application callback through this function by calling @ref registerSocketCallback.
|
|
In response to events received, the following callback function is called to handle the corresponding asynchronous function called. Example: @ref bind, @ref connect,...etc.
|
|
|
|
@param [in] sock
|
|
Socket ID for the callback.
|
|
|
|
The socket callback function is called whenever a new event is received in response
|
|
to socket operations.
|
|
|
|
@param [in] u8Msg
|
|
Socket event type. Possible values are:
|
|
- @ref SOCKET_MSG_BIND
|
|
- @ref SOCKET_MSG_LISTEN
|
|
- @ref SOCKET_MSG_ACCEPT
|
|
- @ref SOCKET_MSG_CONNECT
|
|
- @ref SOCKET_MSG_RECV
|
|
- @ref SOCKET_MSG_SEND
|
|
- @ref SOCKET_MSG_SENDTO
|
|
- @ref SOCKET_MSG_RECVFROM
|
|
|
|
@param [in] pvMsg
|
|
Pointer to message structure. Existing types are:
|
|
- tstrSocketBindMsg
|
|
- tstrSocketListenMsg
|
|
- tstrSocketAcceptMsg
|
|
- tstrSocketConnectMsg
|
|
- tstrSocketRecvMsg
|
|
|
|
@see
|
|
tenuSocketCallbackMsgType
|
|
tstrSocketRecvMsg
|
|
tstrSocketConnectMsg
|
|
tstrSocketAcceptMsg
|
|
tstrSocketListenMsg
|
|
tstrSocketBindMsg
|
|
*/
|
|
typedef void (*tpfAppSocketCb) (SOCKET sock, uint8 u8Msg, void * pvMsg);
|
|
|
|
|
|
/*!
|
|
@typedef \
|
|
tpfAppResolveCb
|
|
|
|
@brief
|
|
DNS resolution callback function.
|
|
Applications requiring DNS resolution should register their callback through this function by calling @ref registerSocketCallback.
|
|
The following callback is triggered in response to an asynchronous call to the @ref gethostbyname function (DNS Resolution callback).
|
|
|
|
@param [in] pu8DomainName
|
|
Domain name of the host.
|
|
|
|
@param [in] u32ServerIP
|
|
Server IPv4 address encoded in Network byte order format. If it is Zero, then the DNS resolution failed.
|
|
*/
|
|
typedef void (*tpfAppResolveCb) (uint8* pu8DomainName, uint32 u32ServerIP);
|
|
|
|
/*!
|
|
@typedef \
|
|
tpfPingCb
|
|
|
|
@brief PING Callback
|
|
|
|
The function delivers the ping statistics for the sent ping triggered by calling
|
|
@ref m2m_ping_req.
|
|
|
|
@param [in] u32IPAddr
|
|
Destination IP.
|
|
|
|
@param [in] u32RTT
|
|
Round Trip Time.
|
|
|
|
@param [in] u8ErrorCode
|
|
Ping error code. It may be one of:
|
|
- PING_ERR_SUCCESS
|
|
- PING_ERR_DEST_UNREACH
|
|
- PING_ERR_TIMEOUT
|
|
*/
|
|
typedef void (*tpfPingCb)(uint32 u32IPAddr, uint32 u32RTT, uint8 u8ErrorCode);
|
|
|
|
/**@}*/
|
|
/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
|
|
FUNCTION PROTOTYPES
|
|
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
|
|
/** \defgroup SocketAPI Functions
|
|
* @ingroup SOCKETAPI
|
|
*/
|
|
|
|
/**@{*/
|
|
/*!
|
|
@fn \
|
|
NMI_API void socketInit(void);
|
|
The function performs the necessary initialization for the socket library through the following steps:
|
|
- A check made by the global variable gbSocketInit, ensuring that initialization for sockets is performed only once,
|
|
in-order to prevent reseting the socket instances already created in the global socket array (gastrSockets).
|
|
- Zero initializations to the global socket array (gastrSockets), which holds the list of TCP sockets.
|
|
- Registers the socket (Host Interface)hif callback function through the call to the hif_register_cb function.
|
|
This facilitates handling all of the socket related functions received through interrupts from the firmware.
|
|
|
|
@return void
|
|
|
|
@remarks
|
|
This initialization function must be invoked before any socket operation is performed.
|
|
No error codes from this initialization function since the socket array is statically allocated based on the maximum number of
|
|
sockets @ref MAX_SOCKET which is tuned to the systems capability.
|
|
\section SocketExample1 Example
|
|
This example demonstrates the use of the socketInit for socket initialization for an mqtt chat application.
|
|
\code
|
|
tstrWifiInitParam param;
|
|
int8_t ret;
|
|
char topic[strlen(MAIN_CHAT_TOPIC) + MAIN_CHAT_USER_NAME_SIZE + 1];
|
|
|
|
//Initialize the board.
|
|
system_init();
|
|
|
|
//Initialize the UART console.
|
|
configure_console();
|
|
|
|
// Initialize the BSP.
|
|
nm_bsp_init();
|
|
|
|
----------
|
|
|
|
// Initialize socket interface.
|
|
socketInit();
|
|
registerSocketCallback(socket_event_handler, socket_resolve_handler);
|
|
|
|
// Connect to router.
|
|
m2m_wifi_connect((char *)DEFAULT_SSID, sizeof(DEFAULT_SSID),
|
|
DEFAULT_AUTH, (char *)DEFAULT_KEY, M2M_WIFI_CH_ALL);
|
|
|
|
\endcode
|
|
*/
|
|
NMI_API void socketInit(void);
|
|
|
|
/*!
|
|
@fn \
|
|
NMI_API void socketDeinit(void);
|
|
|
|
@brief Socket Layer De-initialization
|
|
|
|
The function performs the necessary cleanup for the socket library static data
|
|
It must be invoked only after all desired socket operations have been performed on any active sockets.
|
|
*/
|
|
NMI_API void socketDeinit(void);
|
|
/*!
|
|
@fn \
|
|
NMI_API void registerSocketCallback(tpfAppSocketCb socket_cb, tpfAppResolveCb resolve_cb);
|
|
Register two callback functions one for asynchronous socket events and the other one for DNS callback registering function.
|
|
The registered callback functions are used to retrieve information in response to the asynchronous socket functions called.
|
|
@param [in] socket_cb
|
|
Assignment of callback function to the global callback @ref tpfAppSocketCb gpfAppSocketCb. Delivers
|
|
socket messages to the host application. In response to the asynchronous function calls, such as @ref bind
|
|
@ref listen @ref accept @ref connect
|
|
|
|
@param [in] resolve_cb
|
|
Assignment of callback function to the global callback @ref tpfAppResolveCb gpfAppResolveCb.
|
|
Used for DNS resolving functionality. The DNS resolving technique is determined by the application
|
|
registering the callback.
|
|
NULL is assigned when DNS resolution is not required.
|
|
|
|
@return void
|
|
@remarks
|
|
If any of the socket functionality is not to be used, NULL is passed in as a parameter.
|
|
It must be invoked after @ref socketInit and before other socket layer operations.
|
|
|
|
\section SocketExample2 Example
|
|
This example demonstrates the use of the registerSocketCallback to register a socket callback function with DNS resolution CB set to null
|
|
for a simple UDP server example.
|
|
\code
|
|
tstrWifiInitParam param;
|
|
int8_t ret;
|
|
struct sockaddr_in addr;
|
|
|
|
// Initialize the board
|
|
system_init();
|
|
|
|
//Initialize the UART console.
|
|
configure_console();
|
|
|
|
// Initialize the BSP.
|
|
nm_bsp_init();
|
|
|
|
// Initialize socket address structure.
|
|
addr.sin_family = AF_INET;
|
|
addr.sin_port = _htons(MAIN_WIFI_M2M_SERVER_PORT);
|
|
addr.sin_addr.s_addr = _htonl(MAIN_WIFI_M2M_SERVER_IP);
|
|
|
|
// Initialize Wi-Fi parameters structure.
|
|
memset((uint8_t *)¶m, 0, sizeof(tstrWifiInitParam));
|
|
|
|
// Initialize Wi-Fi driver with data and status callbacks.
|
|
param.pfAppWifiCb = wifi_cb;
|
|
ret = m2m_wifi_init(¶m);
|
|
if (M2M_SUCCESS != ret) {
|
|
printf("main: m2m_wifi_init call error!(%d)\r\n", ret);
|
|
while (1) {
|
|
}
|
|
}
|
|
|
|
// Initialize socket module
|
|
socketInit();
|
|
registerSocketCallback(socket_cb, NULL);
|
|
|
|
// Connect to router.
|
|
m2m_wifi_connect((char *)DEFAULT_SSID, sizeof(DEFAULT_SSID), DEFAULT_AUTH, (char *)DEFAULT_KEY, M2M_WIFI_CH_ALL);
|
|
\endcode
|
|
*/
|
|
NMI_API void registerSocketCallback(tpfAppSocketCb socket_cb, tpfAppResolveCb resolve_cb);
|
|
/*!
|
|
@fn \
|
|
NMI_API SOCKET socket(uint16 u16Domain, uint8 u8Type, uint8 u8Flags);
|
|
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.
|
|
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.
|
|
|
|
@param [in] u16Domain
|
|
Socket family. The only allowed value is AF_INET (IPv4.0) for TCP/UDP sockets.
|
|
|
|
@param [in] u8Type
|
|
Socket type. Allowed values are:
|
|
- [SOCK_STREAM](@ref SOCK_STREAM)
|
|
- [SOCK_DGRAM](@ref SOCK_DGRAM)
|
|
|
|
@param [in] u8Flags
|
|
Used to specify the socket creation flags. It shall be set to zero for normal TCP/UDP sockets,
|
|
or [SOCKET_FLAGS_SSL](@ref SOCKET_FLAGS_SSL) if the socket is used for SSL session. The use of the flag
|
|
[SOCKET_FLAGS_SSL](@ref SOCKET_FLAGS_SSL) has no meaning in case of UDP sockets.
|
|
|
|
@pre
|
|
The @ref socketInit function must be called once at the beginning of the application to initialize the socket handler.
|
|
before any call to the socket function can be made.
|
|
|
|
@see
|
|
connect
|
|
bind
|
|
listen
|
|
accept
|
|
recv
|
|
recvfrom
|
|
send
|
|
sendto
|
|
close
|
|
setsockopt
|
|
getsockopt
|
|
|
|
@return
|
|
On successful socket creation, a non-blocking socket type is created and a socket ID is returned
|
|
In case of failure the function returns a negative value, identifying one of the socket error codes defined.
|
|
For example: @ref SOCK_ERR_INVALID for invalid argument or
|
|
@ref SOCK_ERR_MAX_TCP_SOCK if the number of TCP allocated sockets exceeds the number of available sockets.
|
|
|
|
@remarks
|
|
The socket function must be called before any other related socket functions "e.g. send, recv, close ..etc"
|
|
\section SocketExample3 Example
|
|
This example demonstrates the use of the socket function to allocate the socket, returning the socket handler to be used for other
|
|
socket operations. Socket creation is dependent on the socket type.
|
|
\subsection sub1 UDP example
|
|
@code
|
|
SOCKET UdpServerSocket = -1;
|
|
|
|
UdpServerSocket = socket(AF_INET, SOCK_DGRAM, 0);
|
|
|
|
@endcode
|
|
\subsection sub2 TCP example
|
|
@code
|
|
static SOCKET tcp_client_socket = -1;
|
|
|
|
tcp_client_socket = socket(AF_INET, SOCK_STREAM, 0));
|
|
@endcode
|
|
*/
|
|
NMI_API SOCKET socket(uint16 u16Domain, uint8 u8Type, uint8 u8Flags);
|
|
/*!
|
|
\fn \
|
|
NMI_API sint8 bind(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen);
|
|
Asynchronous bind function associates the provided address and local port to the socket.
|
|
The function can be used with both TCP and UDP sockets. It is mandatory to call the @ref bind function before starting any UDP or TCP server operation.
|
|
Upon socket bind completion, the application will receive a @ref SOCKET_MSG_BIND message in the socket callback.
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
@param [in] pstrAddr
|
|
Pointer to socket address structure "sockaddr_in"
|
|
[sockaddr_in](@ref sockaddr_in)
|
|
|
|
|
|
@param [in] u8AddrLen
|
|
Size of the given socket address structure in bytes.
|
|
|
|
@pre
|
|
The socket function must be called to allocate a socket before passing the socket ID to the bind function.
|
|
|
|
@see socket
|
|
@see connect
|
|
@see listen
|
|
@see accept
|
|
@see recv
|
|
@see recvfrom
|
|
@see send
|
|
@see sendto
|
|
|
|
@return
|
|
The function returns ZERO for successful operations and a negative value otherwise.
|
|
The possible error values are:
|
|
- [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR)
|
|
Indicating that the operation was successful.
|
|
|
|
- [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG)
|
|
Indicating passing invalid arguments such as negative socket ID or NULL socket address structure.
|
|
|
|
- [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID)
|
|
Indicate socket bind failure.
|
|
\section SocketExample4 Example
|
|
This example demonstrates the call of the bind socket operation after a successful socket operation.
|
|
@code
|
|
struct sockaddr_in addr;
|
|
SOCKET udpServerSocket =-1;
|
|
int ret = -1;
|
|
|
|
if(udpServerSocket == -1)
|
|
{
|
|
udpServerSocket = socket(AF_INET,SOCK_DGRAM,0);
|
|
if(udpServerSocket >= 0)
|
|
{
|
|
addr.sin_family = AF_INET;
|
|
addr.sin_port = _htons(UDP_SERVER_PORT);
|
|
addr.sin_addr.s_addr = 0;
|
|
ret = bind(udpServerSocket,(struct sockaddr*)&addr,sizeof(addr));
|
|
|
|
if(ret == 0)
|
|
printf("Bind success!\n");
|
|
else
|
|
{
|
|
printf("Bind Failed. Error code = %d\n",ret);
|
|
close(udpServerSocket);
|
|
}
|
|
else
|
|
{
|
|
printf("UDP Server Socket Creation Failed\n");
|
|
return;
|
|
}
|
|
}
|
|
@endcode
|
|
*/
|
|
NMI_API sint8 bind(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint8 listen(SOCKET sock, uint8 backlog);
|
|
|
|
After successfully binding a socket to an IP address and port on the system, start listening passively for incoming connections.
|
|
The socket must be bound on a local port or the listen operation fails.
|
|
Upon the call to the asynchronous listen function, response is received through the event @ref SOCKET_MSG_LISTEN
|
|
in the socket callback.
|
|
|
|
A successful listen means the TCP server operation is active. If a connection is accepted, then the application socket callback function is
|
|
notified with the new connected socket through the event @ref SOCKET_MSG_ACCEPT. Hence there is no need to call the @ref accept function
|
|
after calling @ref listen.
|
|
|
|
After a connection is accepted, the user is then required to call @ref recv to receive any packets transmitted by the remote host or to recieve notification of socket connection
|
|
termination.
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
@param [in] backlog
|
|
Not used by the current implementation.
|
|
|
|
@pre
|
|
The bind function must be called to assign the port number and IP address to the socket before the listen operation.
|
|
|
|
@see bind
|
|
@see accept
|
|
@see recv
|
|
@see recvfrom
|
|
@see send
|
|
@see sendto
|
|
|
|
@return
|
|
The function returns ZERO for successful operations and a negative value otherwise.
|
|
The possible error values are:
|
|
- [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR)
|
|
Indicating that the operation was successful.
|
|
|
|
- [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG)
|
|
Indicating invalid arguments were passed, such as negative socket ID.
|
|
|
|
- [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID)
|
|
Indicate socket listen failure.
|
|
\section SocketExample5 Example
|
|
This example demonstrates the call of the listen socket operation after a successful socket operation.
|
|
@code
|
|
static void TCP_Socketcallback(SOCKET sock, uint8 u8Msg, void * pvMsg)
|
|
{
|
|
int ret =-1;
|
|
|
|
switch(u8Msg)
|
|
{
|
|
case SOCKET_MSG_BIND:
|
|
{
|
|
tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg;
|
|
if(pstrBind != NULL)
|
|
{
|
|
if(pstrBind->status == 0)
|
|
{
|
|
ret = listen(sock, 0);
|
|
|
|
if(ret <0)
|
|
printf("Listen failure! Error = %d\n",ret);
|
|
}
|
|
else
|
|
{
|
|
M2M_ERR("bind Failure!\n");
|
|
close(sock);
|
|
}
|
|
}
|
|
}
|
|
break;
|
|
|
|
case SOCKET_MSG_LISTEN:
|
|
{
|
|
|
|
tstrSocketListenMsg *pstrListen = (tstrSocketListenMsg*)pvMsg;
|
|
if(pstrListen != NULL)
|
|
{
|
|
if(pstrListen->status == 0)
|
|
{
|
|
ret = accept(sock,NULL,0);
|
|
}
|
|
else
|
|
{
|
|
M2M_ERR("listen Failure!\n");
|
|
close(sock);
|
|
}
|
|
}
|
|
}
|
|
break;
|
|
|
|
case SOCKET_MSG_ACCEPT:
|
|
{
|
|
tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg*)pvMsg;
|
|
|
|
if(pstrAccept->sock >= 0)
|
|
{
|
|
TcpNotificationSocket = pstrAccept->sock;
|
|
recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
|
|
}
|
|
else
|
|
{
|
|
M2M_ERR("accept failure\n");
|
|
}
|
|
}
|
|
break;
|
|
|
|
default:
|
|
break;
|
|
}
|
|
}
|
|
|
|
@endcode
|
|
*/
|
|
NMI_API sint8 listen(SOCKET sock, uint8 backlog);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint8 accept(SOCKET sock, struct sockaddr *addr, uint8 *addrlen);
|
|
The function has no current implementation. An empty deceleration is used to prevent errors when legacy application code is used.
|
|
As it has no effect, it can be safely removed from any application using it.
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
@param [in] addr
|
|
Not used in the current implementation.
|
|
|
|
@param [in] addrlen
|
|
Not used in the current implementation.
|
|
|
|
@return
|
|
The function returns ZERO for successful operations and a negative value otherwise.
|
|
The possible error values are:
|
|
- [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR)
|
|
Indicating that the operation was successful.
|
|
|
|
- [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG)
|
|
Indicating passing invalid arguments such as negative socket ID.
|
|
*/
|
|
NMI_API sint8 accept(SOCKET sock, struct sockaddr *addr, uint8 *addrlen);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint8 connect(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen);
|
|
Establishes a TCP connection with a remote server.
|
|
The asynchronous connect function must be called after receiving a valid socket ID from the @ref socket function.
|
|
The application socket callback function is notified of the result of the connection attempt through the event @ref SOCKET_MSG_CONNECT,
|
|
along with a structure @ref tstrSocketConnectMsg.
|
|
If socket connection fails, the application should call @ref close().
|
|
A successful connect means the TCP session is active. The application is then required to make a call to the @ref recv function
|
|
to receive any packets transmitted by the remote server, unless the application is interrupted by a notification of socket connection
|
|
termination.
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
@param [in] pstrAddr
|
|
Address of the remote server.
|
|
|
|
@param [in] u8AddrLen
|
|
Size of the given socket address structure in bytes.
|
|
Not currently used, implemented for BSD compatibility only.
|
|
@pre
|
|
The socket function must be called to allocate a TCP socket before passing the socket ID to the bind function.
|
|
If the socket is not bound, you do NOT have to call bind before the "connect" function.
|
|
|
|
@see
|
|
socket
|
|
recv
|
|
send
|
|
close
|
|
|
|
@return
|
|
The function returns ZERO for successful operations and a negative value otherwise.
|
|
The possible error values are:
|
|
- [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR)
|
|
Indicating that the operation was successful.
|
|
|
|
- [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG)
|
|
Indicating passing invalid arguments such as negative socket ID or NULL socket address structure.
|
|
|
|
- [SOCK_ERR_INVALID](@ref SOCK_ERR_INVALID)
|
|
Indicate socket connect failure.
|
|
\section SocketExample6 Example
|
|
The example demonstrates a TCP application, showing how the asynchronous call to the connect function is made through the main function and how the
|
|
callback function handles the @ref SOCKET_MSG_CONNECT event.
|
|
\subsection sub3 Main Function
|
|
@code
|
|
struct sockaddr_in Serv_Addr;
|
|
SOCKET TcpClientSocket =-1;
|
|
int ret = -1
|
|
|
|
TcpClientSocket = socket(AF_INET,SOCK_STREAM,0);
|
|
Serv_Addr.sin_family = AF_INET;
|
|
Serv_Addr.sin_port = _htons(1234);
|
|
Serv_Addr.sin_addr.s_addr = inet_addr(SERVER);
|
|
printf("Connected to server via socket %u\n",TcpClientSocket);
|
|
|
|
do
|
|
{
|
|
ret = connect(TcpClientSocket,(sockaddr_in*)&Serv_Addr,sizeof(Serv_Addr));
|
|
if(ret != 0)
|
|
{
|
|
printf("Connection Error\n");
|
|
}
|
|
else
|
|
{
|
|
printf("Connection successful.\n");
|
|
break;
|
|
}
|
|
}while(1)
|
|
@endcode
|
|
\subsection sub4 Socket Callback
|
|
@code
|
|
if(u8Msg == SOCKET_MSG_CONNECT)
|
|
{
|
|
tstrSocketConnectMsg *pstrConnect = (tstrSocketConnectMsg*)pvMsg;
|
|
if(pstrConnect->s8Error == 0)
|
|
{
|
|
uint8 acBuffer[GROWL_MSG_SIZE];
|
|
uint16 u16MsgSize;
|
|
|
|
printf("Connect success!\n");
|
|
|
|
u16MsgSize = FormatMsg(u8ClientID, acBuffer);
|
|
send(sock, acBuffer, u16MsgSize, 0);
|
|
recv(pstrNotification->Socket, (void*)au8Msg,GROWL_DESCRIPTION_MAX_LENGTH, GROWL_RX_TIMEOUT);
|
|
u8Retry = GROWL_CONNECT_RETRY;
|
|
}
|
|
else
|
|
{
|
|
M2M_DBG("Connection Failed, Error: %d\n",pstrConnect->s8Error");
|
|
close(pstrNotification->Socket);
|
|
}
|
|
}
|
|
@endcode
|
|
*/
|
|
NMI_API sint8 connect(SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint16 recv(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec);
|
|
|
|
An asynchrnonous receive function, used to retrieve data from a TCP stream.
|
|
Before calling the recv function, a successful socket connection status must have been received through any of the two socket events
|
|
[SOCKET_MSG_CONNECT] or [SOCKET_MSG_ACCEPT], from the socket callback. Hence, indicating that the socket is already connected to a remote
|
|
host.
|
|
The application receives the required data in response to this asynchronous call through the reception of the event @ref SOCKET_MSG_RECV in the
|
|
socket callback.
|
|
|
|
Receiving the SOCKET_MSG_RECV message in the callback with zero or negative buffer length indicates the following:
|
|
- @ref SOCK_ERR_NO_ERROR : Socket connection closed. The application should now call @ref close().
|
|
- @ref SOCK_ERR_CONN_ABORTED : Socket connection aborted. The application should now call @ref close().
|
|
- @ref SOCK_ERR_TIMEOUT : Socket receive timed out. The socket connection remains open.
|
|
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
|
|
@param [in] pvRecvBuf
|
|
Pointer to a buffer that will hold the received data. The buffer is used
|
|
in the recv callback to deliver the received data to the caller. The buffer must
|
|
be resident in memory (heap or global buffer).
|
|
|
|
@param [in] u16BufLen
|
|
The buffer size in bytes.
|
|
|
|
@param [in] u32Timeoutmsec
|
|
Timeout for the recv function in milli-seconds. If the value is set to ZERO, the timeout
|
|
will be set to infinite (the recv function waits forever). If the timeout period is
|
|
elapsed with no data received, the socket will get a timeout error.
|
|
@pre
|
|
- The socket function must be called to allocate a TCP socket before passing the socket ID to the recv function.
|
|
- The socket in a connected state is expected to receive data through the socket interface.
|
|
|
|
@see socket
|
|
@see connect
|
|
@see bind
|
|
@see listen
|
|
@see recvfrom
|
|
@see close
|
|
|
|
@return
|
|
The function returns ZERO for successful operations and a negative value otherwise.
|
|
The possible error values are:
|
|
- [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR)
|
|
Indicating that the operation was successful.
|
|
|
|
- [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG)
|
|
Indicating passing invalid arguments such as negative socket ID or NULL Recieve buffer.
|
|
|
|
- [SOCK_ERR_BUFFER_FULL](@ref SOCK_ERR_BUFFER_FULL)
|
|
Indicate socket recieve failure.
|
|
\section SocketExample7 Example
|
|
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
|
|
received data when the SOCKET_MSG_RECV event is received.
|
|
@code
|
|
|
|
switch(u8Msg)
|
|
{
|
|
|
|
case SOCKET_MSG_ACCEPT:
|
|
{
|
|
tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg*)pvMsg;
|
|
|
|
if(pstrAccept->sock >= 0)
|
|
{
|
|
recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
|
|
}
|
|
else
|
|
{
|
|
M2M_ERR("accept\n");
|
|
}
|
|
}
|
|
break;
|
|
|
|
|
|
case SOCKET_MSG_RECV:
|
|
{
|
|
tstrSocketRecvMsg *pstrRx = (tstrSocketRecvMsg*)pvMsg;
|
|
|
|
if(pstrRx->s16BufferSize > 0)
|
|
{
|
|
|
|
recv(sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
|
|
}
|
|
else
|
|
{
|
|
printf("Socet recv Error: %d\n",pstrRx->s16BufferSize);
|
|
close(sock);
|
|
}
|
|
}
|
|
break;
|
|
|
|
default:
|
|
break;
|
|
}
|
|
@endcode
|
|
*/
|
|
NMI_API sint16 recv(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint16 recvfrom(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32TimeoutSeconds);
|
|
Receives data from a UDP Scoket.
|
|
|
|
The asynchronous recvfrom function is used to retrieve data from a UDP socket. The socket must already be bound to
|
|
a local port before a call to the recvfrom function is made (i.e message @ref SOCKET_MSG_BIND is received
|
|
with successful status in the socket callback).
|
|
|
|
Upon calling the recvfrom function with a successful return code, the application is expected to receive a notification
|
|
in the socket callback whenever a message is received through the @ref SOCKET_MSG_RECVFROM event.
|
|
|
|
Receiving the SOCKET_MSG_RECVFROM message in the callback with zero, indicates that the socket is closed.
|
|
Whereby a negative buffer length indicates one of the socket error codes such as socket timeout error @ref SOCK_ERR_TIMEOUT
|
|
|
|
The recvfrom callback can also be used to show the IP address of the remote host that sent the frame by
|
|
using the "strRemoteAddr" element in the @ref tstrSocketRecvMsg structure. (refer to the code example)
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
@param [in] pvRecvBuf
|
|
Pointer to a buffer that will hold the received data. The buffer shall be used
|
|
in the recv callback to deliver the received data to the caller. The buffer must
|
|
be resident in memory (heap or global buffer).
|
|
|
|
@param [in] u16BufLen
|
|
The buffer size in bytes.
|
|
|
|
@param [in] u32TimeoutSeconds
|
|
Timeout for the recv function in milli-seconds. If the value is set to ZERO, the timeout
|
|
will be set to infinite (the recv function waits forever).
|
|
|
|
@pre
|
|
- The socket function must be called to allocate a TCP socket before passing the socket ID to the recv function.
|
|
- The socket corresponding to the socket ID must be successfully bound to a local port through the call to a @ref bind function.
|
|
|
|
@see
|
|
socket
|
|
bind
|
|
close
|
|
|
|
@return
|
|
The function returns ZERO for successful operations and a negative value otherwise.
|
|
The possible error values are:
|
|
- [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR)
|
|
Indicating that the operation was successful.
|
|
|
|
- [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG)
|
|
Indicating passing invalid arguments such as negative socket ID or NULL Receive buffer.
|
|
|
|
- [SOCK_ERR_BUFFER_FULL](@ref SOCK_ERR_BUFFER_FULL)
|
|
Indicate socket receive failure.
|
|
\section SocketExample8 Example
|
|
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
|
|
received data when the SOCKET_MSG_RECVFROM event is received.
|
|
@code
|
|
switch(u8Msg)
|
|
{
|
|
|
|
case SOCKET_MSG_BIND:
|
|
{
|
|
tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg;
|
|
|
|
if(pstrBind != NULL)
|
|
{
|
|
if(pstrBind->status == 0)
|
|
{
|
|
recvfrom(sock, gau8SocketTestBuffer, TEST_BUFFER_SIZE, 0);
|
|
}
|
|
else
|
|
{
|
|
M2M_ERR("bind\n");
|
|
}
|
|
}
|
|
}
|
|
break;
|
|
|
|
|
|
case SOCKET_MSG_RECVFROM:
|
|
{
|
|
tstrSocketRecvMsg *pstrRx = (tstrSocketRecvMsg*)pvMsg;
|
|
|
|
if(pstrRx->s16BufferSize > 0)
|
|
{
|
|
//get the remote host address and port number
|
|
uint16 u16port = pstrRx->strRemoteAddr.sin_port;
|
|
uint32 strRemoteHostAddr = pstrRx->strRemoteAddr.sin_addr.s_addr;
|
|
|
|
printf("Received frame with size = %d.\tHost address=%x, Port number = %d\n\n",pstrRx->s16BufferSize,strRemoteHostAddr, u16port);
|
|
|
|
ret = recvfrom(sock,gau8SocketTestBuffer,sizeof(gau8SocketTestBuffer),TEST_RECV_TIMEOUT);
|
|
}
|
|
else
|
|
{
|
|
printf("Socket recv Error: %d\n",pstrRx->s16BufferSize);
|
|
ret = close(sock);
|
|
}
|
|
}
|
|
break;
|
|
|
|
default:
|
|
break;
|
|
}
|
|
@endcode
|
|
*/
|
|
NMI_API sint16 recvfrom(SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint16 send(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 u16Flags);
|
|
Asynchronous sending function, used to send data on a TCP/UDP socket.
|
|
|
|
Called by the application code when there is outgoing data available required to be sent on a specific socket handler.
|
|
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.
|
|
@ref send function is most commonly called for sockets in a connected state.
|
|
After the data is sent, the socket callback function registered using registerSocketCallback(), is expected to receive an event of type
|
|
@ref SOCKET_MSG_SEND holding information containing the number of data bytes sent.
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
@param [in] pvSendBuffer
|
|
Pointer to a buffer holding data to be transmitted.
|
|
|
|
@param [in] u16SendLength
|
|
The buffer size in bytes.
|
|
|
|
@param [in] u16Flags
|
|
Not used in the current implementation.
|
|
|
|
@pre
|
|
Sockets must be initialized using socketInit. \n
|
|
|
|
For TCP Socket:\n
|
|
Must use a successfully connected Socket (so that the intended recipient address is known ahead of sending the data).
|
|
Hence this function is expected to be called after a successful socket connect operation(in client case or accept in the
|
|
the server case).\n
|
|
|
|
For UDP Socket:\n
|
|
UDP sockets most commonly use @ref sendto function, where the destination address is defined. However, in-order to send outgoing data
|
|
using the @ref send function, at least one successful call must be made to the @ref sendto function before consecutive calls to the @ref send function,
|
|
to ensure that the destination address is saved in the firmware.
|
|
|
|
@see
|
|
socketInit
|
|
recv
|
|
sendto
|
|
socket
|
|
connect
|
|
accept
|
|
sendto
|
|
|
|
@warning
|
|
u16SendLength must not exceed @ref SOCKET_BUFFER_MAX_LENGTH. \n
|
|
Use a valid socket identifer through the aprior call to the @ref socket function.
|
|
Must use a valid buffer pointer.
|
|
Successful completion of a call to send() does not guarantee delivery of the message,
|
|
A negative return value indicates only locally-detected errors
|
|
|
|
|
|
@return
|
|
The function shall return @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise.
|
|
*/
|
|
NMI_API sint16 send(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 u16Flags);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint16 sendto(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 flags, struct sockaddr *pstrDestAddr, uint8 u8AddrLen);
|
|
|
|
Asynchronous sending function, used to send data on a UDP socket.
|
|
Called by the application code when there is data required to be sent on a UDP socket.
|
|
The application code is expected to receive data from a successfully bound socket node.
|
|
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
|
|
only with UDP sockets.
|
|
After the data is sent, the socket callback function registered using @ref registerSocketCallback(), is expected to receive an event of type
|
|
@ref SOCKET_MSG_SENDTO.
|
|
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
@param [in] pvSendBuffer
|
|
Pointer to a buffer holding data to be transmitted.
|
|
A NULL value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
@param [in] u16SendLength
|
|
The buffer size in bytes. It must not exceed @ref SOCKET_BUFFER_MAX_LENGTH.
|
|
|
|
@param [in] flags
|
|
Not used in the current implementation
|
|
|
|
@param [in] pstrDestAddr
|
|
The destination address.
|
|
|
|
@param [in] u8AddrLen
|
|
Destination address length in bytes.
|
|
Not used in the current implementation, only included for BSD compatibility.
|
|
@pre
|
|
Sockets must be initialized using socketInit.
|
|
|
|
@see
|
|
socketInit
|
|
recvfrom
|
|
sendto
|
|
socket
|
|
connect
|
|
accept
|
|
send
|
|
|
|
@warning
|
|
u16SendLength must not exceed @ref SOCKET_BUFFER_MAX_LENGTH. \n
|
|
Use a valid socket (returned from socket ).
|
|
A valid buffer pointer must be used (not NULL). \n
|
|
Successful completion of a call to sendto() does not guarantee delivery of the message,
|
|
A negative return value indicates only locally-detected errors
|
|
|
|
@return
|
|
The function returns @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise.
|
|
*/
|
|
NMI_API sint16 sendto(SOCKET sock, void *pvSendBuffer, uint16 u16SendLength, uint16 flags, struct sockaddr *pstrDestAddr, uint8 u8AddrLen);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint8 close(SOCKET sock);
|
|
|
|
Synchronous close function, releases all the socket assigned resources.
|
|
|
|
@param [in] sock
|
|
Socket ID, must hold a non negative value.
|
|
A negative value will return a socket error @ref SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
|
|
|
|
@pre
|
|
Sockets must be initialized through the call of the socketInit function.
|
|
@ref close is called only for valid socket identifiers created through the @ref socket function.
|
|
|
|
@warning
|
|
If @ref close is called while there are still pending messages (sent or received ) they will be discarded.
|
|
|
|
@see
|
|
socketInit
|
|
socket
|
|
|
|
@return
|
|
The function returned @ref SOCK_ERR_NO_ERROR for successful operation and a negative value (indicating the error) otherwise.
|
|
*/
|
|
NMI_API sint8 close(SOCKET sock);
|
|
/*!
|
|
@fn \
|
|
NMI_API uint32 nmi_inet_addr(char *pcIpAddr);
|
|
|
|
Synchronous function which returns a BSD socket compliant Internet Protocol (IPv4) socket address.
|
|
This IPv4 address in the input string parameter could either be specified as a hostname, or as a numeric string representation like n.n.n.n known as the IPv4 dotted-decimal format
|
|
(i.e. "192.168.10.1").
|
|
This function is used whenever an ip address needs to be set in the proper format
|
|
(i.e. for the @ref tstrM2MIPConfig structure).
|
|
|
|
@param [in] pcIpAddr
|
|
A null terminated string containing the IP address in IPv4 dotted-decimal address.
|
|
|
|
@return
|
|
Unsigned 32-bit integer representing the IP address in Network byte order
|
|
(eg. "192.168.10.1" will be expressed as 0x010AA8C0).
|
|
|
|
*/
|
|
NMI_API uint32 nmi_inet_addr(char *pcIpAddr);
|
|
/*!
|
|
@fn \
|
|
NMI_API sint8 gethostbyname(uint8 * pcHostName);
|
|
Asynchronous DNS resolving function. This function uses DNS to resolve a domain name to the corresponding IP address.
|
|
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()
|
|
|
|
@param [in] pcHostName
|
|
NULL terminated string containing the domain name for the remote host.
|
|
Its size must not exceed [HOSTNAME_MAX_SIZE](@ref HOSTNAME_MAX_SIZE).
|
|
|
|
@see
|
|
registerSocketCallback
|
|
|
|
@warning
|
|
Successful completion of a call to gethostbyname() does not guarantee success of the DNS request,
|
|
a negative return value indicates only locally-detected errors
|
|
|
|
@return
|
|
- [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR)
|
|
- [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG)
|
|
*/
|
|
NMI_API sint8 gethostbyname(uint8 * pcHostName);
|
|
|
|
/*!
|
|
@fn \
|
|
NMI_API sint8 setsockopt(SOCKET socket, uint8 u8Level, uint8 option_name,
|
|
const void *option_value, uint16 u16OptionLen);
|
|
|
|
The setsockopt() function shall set the option specified by the option_name
|
|
argument, at the protocol level specified by the level argument, to the value
|
|
pointed to by the option_value argument for the socke specified by the socket argument.
|
|
|
|
Possible Options:
|
|
SO_SET_UDP_SEND_CALLBACK:
|
|
Enable/Disable callback messages for sendto().Since UDP is unreliable by default the user maybe interested (or not)
|
|
in receiving a message of /ref SOCKET_MSG_SENDTO for each call of sendto().
|
|
Enabled if option_value equals /ref BTRUE Disabled otherwise.
|
|
IP_ADD_MEMBERSHIP:
|
|
valid for UDP sockets,this option is used to receive frames sent to a multicast group.
|
|
option_value shall be a pointer to Unsigned 32 bit integer containing the Multicast ipv4 address.
|
|
IP_DROP_MEMBERSHIP:
|
|
valid for UDP sockets,this option is used to Stop receiving frames sent to a multicast group.
|
|
option_value shall be a pointer to Unsigned 32 bit integer containing the Multicast ipv4 address.
|
|
|
|
Possible values for s32Level:
|
|
This argument is ignored.
|
|
|
|
@param [in] socket
|
|
Socket handler.
|
|
|
|
@param [in] u8Level
|
|
protocol level. always SOL_SOCKET for now.
|
|
|
|
@param [in] option_name
|
|
option to be set.
|
|
|
|
@param [in] option_value
|
|
pointer to user provided value.
|
|
|
|
@param [in] u16OptionLen
|
|
length of the option value.
|
|
@warning
|
|
-Note that sending IGMP packets to Join/Leave multicast groups is not currently implemented. \n
|
|
Calling this function will Pass/Filter packets sent to the Multicast address provided in the option_value
|
|
@return
|
|
The function shall return \ref SOCK_ERR_NO_ERROR for successful operation
|
|
and a negative value (indicating the error) otherwise.
|
|
*/
|
|
NMI_API sint8 setsockopt(SOCKET socket, uint8 u8Level, uint8 option_name,
|
|
const void *option_value, uint16 u16OptionLen);
|
|
/*!
|
|
@fn \
|
|
sint8 getsockopt(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8 * pu8OptLen);
|
|
Get socket options retrieves
|
|
This Function isn't implemented yet but this is the form that will be released later.
|
|
@brief
|
|
|
|
|
|
@param [in] sock
|
|
Socket Identifie.
|
|
@param [in] u8Level
|
|
The protocol level of the option.
|
|
@param [in] u8OptName
|
|
The u8OptName argument specifies a single option to get.
|
|
@param [out] pvOptValue
|
|
The pvOptValue argument contains pointer to a buffer containing the option value.
|
|
@param [out] pu8OptLen
|
|
Option value buffer length.
|
|
@return
|
|
The function shall return ZERO for successful operation and a negative value otherwise.
|
|
*/
|
|
NMI_API sint8 getsockopt(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8* pu8OptLen);
|
|
/*!
|
|
* @fn NMI_API sint8 m2m_ping_req(uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb);
|
|
* The function request to send ping request to the given IP Address.
|
|
*
|
|
* @param [in] u32DstIP
|
|
* Target Destination IP Address for the ping request. It must be represented in Network
|
|
* byte order.
|
|
* The function nmi_inet_addr could be used to translate the dotted decimal notation IP
|
|
* to its Network bytes order integer represntative.
|
|
*
|
|
* @param [in] u8TTL
|
|
* IP TTL value for the ping request. If set to ZERO, the default value SHALL be used.
|
|
*
|
|
* @param [in] fpPingCb
|
|
* Callback will be called to deliver the ping statistics.
|
|
*
|
|
* @see nmi_inet_addr
|
|
* @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
|
|
*/
|
|
NMI_API sint8 m2m_ping_req(uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb);
|
|
/**@}*/
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
#endif /* __SOCKET_H__ */
|