Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
m2m_ping_req

The function sends ping request to the given IP Address.

Functions

sint8 get_alpn_index (SOCKET sock)
 
sint8 get_error_detail (SOCKET sock, tstrSockErr *pstrErr)
 
NMI_API sint8 m2m_ping_req (uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb)
 The function request to send ping request to the given IP Address. More...
 
sint8 set_alpn_list (SOCKET sock, const char *pcProtocolList)
 

sint8 get_alpn_index ( SOCKET  sock)

This function gets the index of the protocol negotiated via ALPN. It should be called when a SSL socket connection succeeds, in order to determine which application-layer protocol must be used.

Parameters
[in]sockSocket ID obtained by a call to socket. This is the SSL socket to which the ALPN applies.
Returns
The function returns:
  • >0: 1-based index of negotiated protocol with respect to the list previously provided to set_alpn_list.
  • 0: No negotiation occurred (eg TLS peer did not support ALPN).
  • <0: Invalid parameters (socket is not in use, or not an SSL socket).
See Also
Example

References SOCK_ERR_INVALID_ARG, SSL_FLAGS_ACTIVE, TCP_SOCK_MAX, and tstrSocket::u8AlpnStatus.

Referenced by socket_cb().

sint8 get_error_detail ( SOCKET  sock,
tstrSockErr pstrErr 
)

This function gets detail about a socket failure. The application can call this when notified of a socket failure via SOCKET_MSG_CONNECT or SOCKET_MSG_RECV. If used, it must be called before close.

Parameters
[in]sockSocket ID obtained by a call to socket.
[out]pstrErrPointer to structure to be populated with the details of the socket failure.
Returns
The function returns SOCK_ERR_NO_ERROR if the request is successful. In this case pstrErr has been populated. The function returns a negative value if the request is not successful. In this case pstrErr has not been populated.

References tstrSockErr::enuErrSource, NULL, SOCK_ERR_INVALID_ARG, SOCK_ERR_NO_ERROR, TCP_SOCK_MAX, tstrSocket::u8ErrCode, tstrSockErr::u8ErrCode, and tstrSocket::u8ErrSource.

Referenced by socket_cb().

NMI_API sint8 m2m_ping_req ( uint32  u32DstIP,
uint8  u8TTL,
tpfPingCb  fpPingCb 
)

The function request to send ping request to the given IP Address.

Parameters
[in]u32DstIPTarget 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 representative.
[in]u8TTLIP TTL value for the ping request. If set to ZERO, the default value SHALL be used.
[in]fpPingCbCallback will be called to deliver the ping statistics.
Warning
This API should only be used to request one ping at a time; calling this API invalidates callbacks for previous ping requests.
See Also
nmi_inet_addr
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
Parameters
[in]u32DstIPTarget 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 representative.
[in]u8TTLIP TTL value for the ping request. If set to ZERO, the default value SHALL be used.
[in]fpPingCbCallback will be called to deliver the ping statistics.
Warning
This API should only be used to request one ping at a time; calling this API invalidates callbacks for previous ping requests.
See Also
nmi_inet_addr
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.

References gfpPingCb, gu32PingId, M2M_ERR_INVALID_ARG, NULL, SOCKET_CMD_PING, SOCKET_REQUEST, tstrPingCmd::u16PingCount, tstrPingCmd::u32CmdPrivate, tstrPingCmd::u32DestIPAddr, and tstrPingCmd::u8TTL.

sint8 set_alpn_list ( SOCKET  sock,
const char *  pcProtocolList 
)

This function sets the protocol list used for application-layer protocol negotiation (ALPN). If used, it must be called after creating a SSL socket (using socket) and before connecting/binding (using connect or bind) or securing (using secure).

Parameters
[in]sockSocket ID obtained by a call to socket. This is the SSL socket to which the ALPN list applies.
[in]pcProtocolListPointer to the list of protocols available in the application.
The entries in the list must:
  • be separated with ' ' (space).
  • not contain ' ' (space) or '\0' (NUL).
  • be non-zero length.
The list itself must:
  • be terminated with '\0' (NUL).
  • be no longer than ALPN_LIST_MAX_APP_LENGTH, including separators (spaces) and terminator (NUL).
  • contain at least one entry.
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.

Example

The example demonstrates an application using set_alpn_list and get_alpn_index to negotiate secure HTTP/2 (with fallback option of HTTP/1.1).

Main Function

* if (TcpClientSocket >= 0)
* {
* struct sockaddr_in Serv_Addr = {
* .sin_port = _htons(1234),
* .sin_addr.s_addr = inet_addr(SERVER)
* };
* set_alpn_list(TcpClientSocket, "h2 http/1.1");
* connect(TcpClientSocket, &Serv_Addr, sizeof(Serv_Addr));
* }
*

Socket Callback

* if(u8Msg == SOCKET_MSG_CONNECT)
* {
* tstrSocketConnectMsg *pstrConnect = (tstrSocketConnectMsg*)pvMsg;
* if(pstrConnect->s8Error == 0)
* {
* uint8 alpn_index = get_alpn_index(pstrConnect->sock);
* switch (alpn_index)
* {
* case 1:
* printf("Negotiated HTTP/2\n");
* break;
* case 2:
* printf("Negotiated HTTP/1.1\n");
* break;
* case 0:
* printf("Protocol negotiation did not occur\n");
* break;
* }
* }
* }
*

References ALPN_LIST_MAX_APP_LENGTH, ALPN_LIST_MAX_SIZE, m2m_memcpy(), m2m_strlen(), NULL, setsockopt(), SO_SSL_ALPN, SOCK_ERR_INVALID_ARG, SOL_SSL_SOCKET, and TCP_SOCK_MAX.

Referenced by iot_tls_connect(), and sslConnect().