Possible protocol level values supported are @ref SOL_SOCKET and @ref SOL_SSL_SOCKET.
-* Possible options when the protocol level is @ref SOL_SOCKET :
-*
-*
-*
-* @ref SO_SSL_BYPASS_X509_VERIF |
-* 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. The option is
-* supported for debugging and testing purposes. The option value should be
-* casted to int type and it is handled as a boolean flag. |
-*
-*
-* @ref SO_SSL_SNI |
-* 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 @ref HOSTNAME_MAX_SIZE. |
-*
-*
-* @ref SO_SSL_ENABLE_SESSION_CACHING |
-* This option allow the TLS to cache the session information for fast
-* TLS session establishment in future connections using the TLS Protocol
-* session resume features. |
-*
-*
+ * 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 socket specified by the socket argument.
*/
- /**@{*/
+/**@{*/
/*!
-@fn \
- NMI_API sint8 setsockopt(SOCKET socket, uint8 u8Level, uint8 option_name,
+@fn \
+ NMI_API sint8 setsockopt(SOCKET socket, uint8 u8Level, uint8 option_name,
const void *option_value, uint16 u16OptionLen);
-@param [in] socket
- Socket handler.
+@param[in] socket
+ Socket handler.
-@param [in] u8Level
- protocol level. See description above.
+@param[in] u8Level
+ Protocol level.\n
+ Supported protocol levels are @ref SOL_SOCKET and @ref SOL_SSL_SOCKET.
-@param [in] option_name
- option to be set. See description above.
+@param[in] option_name
+ Option to be set.\n
+ For protocol level @ref SOL_SOCKET, the supported option names are:\n
+ @ref SO_SET_UDP_SEND_CALLBACK \n
+ @ref SO_TCP_KEEPALIVE \n
+ @ref SO_TCP_KEEPIDLE \n
+ @ref SO_TCP_KEEPINTVL \n
+ @ref SO_TCP_KEEPCNT \n
+ For protocol level @ref SOL_SSL_SOCKET, the supported option names are:\n
+ @ref SO_SSL_BYPASS_X509_VERIF \n
+ @ref SO_SSL_SNI \n
+ @ref SO_SSL_ENABLE_SESSION_CACHING \n
+ @ref SO_SSL_ENABLE_SNI_VALIDATION \n
+ @ref SO_SSL_ALPN \n
-@param [in] option_value
- pointer to user provided value.
+@param[in] option_value
+ Pointer to user provided value.
-@param [in] u16OptionLen
- length of the option value in bytes.
+@param[in] u16OptionLen
+ Length of the option value in bytes. Refer to each option documentation for the required length.
-@sa SOL_SOCKET, SOL_SSL_SOCKET, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP
-
-@return
- The function shall return \ref SOCK_ERR_NO_ERROR for successful operation
- and a negative value (indicating the error) otherwise.
+@return
+ The function shall return \ref SOCK_ERR_NO_ERROR for successful operation
+ and a negative value (indicating the error) otherwise.
*/
NMI_API sint8 WINC1500_EXPORT(setsockopt)(SOCKET socket, uint8 u8Level, uint8 option_name,
- const void *option_value, uint16 u16OptionLen);
+ const void *option_value, uint16 u16OptionLen);
/**@}*/ //SetSocketOptionFn
/** @defgroup GetSocketOptionsFn getsockopt
@@ -1994,54 +2165,163 @@ NMI_API sint8 WINC1500_EXPORT(setsockopt)(SOCKET socket, uint8 u8Level, uint8 op
* Get socket options retrieves
* This Function isn't implemented yet but this is the form that will be released later.
*/
- /**@{*/
+/**@{*/
/*!
-@fn \
- sint8 getsockopt(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8 * pu8OptLen);
+@fn \
+ sint8 getsockopt(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8 * pu8OptLen);
@brief
-@param [in] sock
- Socket Identifier.
-@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.
+@param[in] sock
+ Socket Identifier.
+@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.
+ The function shall return ZERO for successful operation and a negative value otherwise.
*/
-NMI_API sint8 WINC1500_EXPORT(getsockopt)(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8* pu8OptLen);
+NMI_API sint8 WINC1500_EXPORT(getsockopt)(SOCKET sock, uint8 u8Level, uint8 u8OptName, const void *pvOptValue, uint8 *pu8OptLen);
/**@}*/ //GetSocketOptionsFn
-/**@}*/
/** @defgroup PingFn m2m_ping_req
* @ingroup SocketAPI
- * The function sends ping request to the given IP Address.
+ * The function sends ping request to the given IP Address.
*/
- /**@{*/
+/**@{*/
/*!
-@fn \
- NMI_API sint8 m2m_ping_req(uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb);
+@fn \
+ NMI_API sint8 m2m_ping_req(uint32 u32DstIP, uint8 u8TTL, tpfPingCb fpPingCb);
-@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 representative.
-
-@param [in] u8TTL
- IP TTL value for the ping request. If set to ZERO, the default value SHALL be used.
+@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 representative.
-@param [in] fpPingCb
- Callback will be called to deliver the ping statistics.
+@param[in] u8TTL
+ IP TTL value for the ping request. If set to ZERO, the default value SHALL be used.
-@see nmi_inet_addr
-@return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
+@param[in] fpPingCb
+ Callback 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 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);
+
+/*!
+ * @fn 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 @ref socket) and before
+ * connecting/binding (using @ref connect or @ref bind) or securing (using @ref secure).
+ *
+ * @param[in] sock
+ * Socket ID obtained by a call to @ref socket. This is the SSL socket to which
+ * the ALPN list applies.
+ *
+ * @param[in] pcProtocolList
+ * Pointer to the list of protocols available in the application. \n
+ * The entries in the list must: \n
+ * - be separated with ' ' (space). \n
+ * - not contain ' ' (space) or '\0' (NUL). \n
+ * - be non-zero length. \n
+ * .
+ * The list itself must: \n
+ * - be terminated with '\0' (NUL). \n
+ * - be no longer than @ref ALPN_LIST_MAX_APP_LENGTH, including separators (spaces) and terminator (NUL). \n
+ * - contain at least one entry.
+ *
+ * @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
+ *
+ * \section SocketExample9 Example
+ * The example demonstrates an application using @ref set_alpn_list and @ref get_alpn_index to negotiate secure HTTP/2
+ * (with fallback option of HTTP/1.1).
+
+ * \subsection sub5 Main Function
+ * @code
+ * SOCKET TcpClientSocket = socket(AF_INET, SOCK_STREAM, SOCKET_CONFIG_SSL_ON);
+ * if (TcpClientSocket >= 0)
+ * {
+ * struct sockaddr_in Serv_Addr = {
+ * .sin_family = AF_INET,
+ * .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));
+ * }
+ * @endcode
+ * \subsection sub6 Socket Callback
+ * @code
+ * 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;
+ * }
+ * }
+ * }
+ * @endcode
+*/
+sint8 set_alpn_list(SOCKET sock, const char *pcProtocolList);
+/*!
+ * @fn 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.
+ *
+ * @param[in] sock
+ * Socket ID obtained by a call to @ref socket. This is the SSL socket to which
+ * the ALPN applies.
+ *
+ * @return The function returns:\n
+ * - >0: 1-based index of negotiated protocol with respect to the list previously provided to @ref set_alpn_list \n
+ * - 0: No negotiation occurred (eg TLS peer did not support ALPN).\n
+ * - <0: Invalid parameters (socket is not in use, or not an SSL socket).\n
+ *
+ * @see @ref SocketExample9
+*/
+sint8 get_alpn_index(SOCKET sock);
+
+/*!
+ *@fn 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 @ref SOCKET_MSG_CONNECT or @ref SOCKET_MSG_RECV.
+ * If used, it must be called before @ref close.
+
+ * @param[in] sock
+ * Socket ID obtained by a call to @ref socket.
+ *
+ * @param[out] pstrErr
+ * Pointer to structure to be populated with the details of the socket failure.
+ *
+ * @return The function returns @ref 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.
+*/
+sint8 get_error_detail(SOCKET sock, tstrSockErr *pstrErr);
/**@}*/ //PingFn
#ifdef __cplusplus
diff --git a/src/drivers/winc1500/src/m2m_ota.c b/src/drivers/winc1500/src/m2m_ota.c
index 5f0bcc158..ba41ffd5a 100644
--- a/src/drivers/winc1500/src/m2m_ota.c
+++ b/src/drivers/winc1500/src/m2m_ota.c
@@ -4,7 +4,7 @@
*
* \brief NMC1500 IoT OTA Interface.
*
- * Copyright (c) 2016-2018 Microchip Technology Inc. and its subsidiaries.
+ * Copyright (c) 2016-2021 Microchip Technology Inc. and its subsidiaries.
*
* \asf_license_start
*
@@ -32,12 +32,11 @@
*
*/
-
-
/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
INCLUDES
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
#include