AudioConsole/AudioConsole.X/Source/winc3400_142/driver/include/m2m_wifi.h

/*******************************************************************************
  File Name:
    m2m_wifi.h

  Summary:
    WINC3400 WLAN Application Interface

  Description:
    WINC3400 WLAN Application Interface
 *******************************************************************************/

//DOM-IGNORE-BEGIN
/*******************************************************************************
* Copyright (C) 2021 Microchip Technology Inc. and its subsidiaries.
*
* 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.
*******************************************************************************/
//DOM-IGNORE-END

/** @defgroup m2m_wifi WLAN
    @{
        @defgroup   WLANCallbacks   Callbacks
        @brief
            Provides detail on the available callbacks for the Wlan APIs.
        @defgroup   WlanDefines     Defines
        @brief
            Specifies the macros and defines used by the Wlan APIs.
        @defgroup   WlanEnums       Enumerations and Typedefs
        @brief
            Specifies the enums and Data Structures used by the Wlan APIs.
        @defgroup   WLANAPI         Functions
        @brief
            Here are listed all the functions that implement the Wlan APIs.
        @{
            @defgroup   WLANINIT        Initialization
            @brief
                Here are listed all the functions that implement the Wlan Initialization APIs.
            @defgroup   WLANEVTS        Wlan Events
            @brief
                Here are listed all the functions that implement the Wlan Events APIs.
            @defgroup   WLANCONNECT     Connection
            @brief
                Here are listed all the functions that implement the Wifi Connection APIs.
            @defgroup   WLANSCAN        Scanning
            @brief
                Here are listed all the functions that implement the Wifi Scanning APIs.
            @defgroup   WLANAP          Hot-Spot (Access-Point)
            @brief
                Here are listed all the functions that implement the Wifi Hot-Spot (Access-Point) APIs.
            @defgroup   WLANETH         Bypass Mode
            @brief
                Here are listed all the functions that implement the Bypass Mode APIs.
            @defgroup   WLANROAMING     Roaming
            @brief
                Here are listed all the functions that implement the Wifi Roaming APIs.
            @defgroup   WLANPS          Power Save
            @brief
                Here are listed all the functions that implement the Power-Save APIs.
            @defgroup   WLANCONF        Configuration
            @brief
                Here are listed all the functions that implement the Wlan Configuration APIs.
            @defgroup   WLANTIME        System Time
            @brief
                Here are listed all the functions that implement the System Time APIs.
            @defgroup   WLANPROVISION   Provisioning
            @brief
                Here are listed all the functions that implement the Wifi Provisioning APIs.
            @defgroup   WLANCRYPTO      Crypto
            @brief
                Here are listed all the functions that implement the Wifi Crypto APIs.
            @cond P2P_DOC
            @defgroup   WLANP2P         P2P
            @brief
                Here are listed all the functions that implement the Wifi P2P APIs.
            @endcond
            @cond MON_DOC
            @defgroup   WLANMON         Monitoring Mode
            @brief
                Here are listed all the functions that implement the Wifi Monitoring Mode APIs.
            @endcond
            @defgroup   BLEAPI          BLE
            @brief
                Here are listed all the functions that implement the BLE APIs.
        @}
    @}
 */

#ifndef __M2M_WIFI_H__
#define __M2M_WIFI_H__

/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
INCLUDES
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/

#include "nm_common.h"
#include "m2m_types.h"
#include "nmdrv.h"

/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
Callbacks
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/

/**@addtogroup WLANCallbacks
 * @{
 */
/*!
@typedef void (*tpfAppWifiCb)(uint8_t u8MsgType, void* pvMsg);

@brief
    This is the main callback function for the Wi-Fi driver and is responsible for processing
    any M2M_WIFI events that are received on the Wi-Fi interface.
    These events (notifications) are usually received in response to earlier Wi-Fi requests such
    as @ref m2m_wifi_request_scan, @ref m2m_wifi_connect_open, @ref m2m_wifi_get_connection_info
    @ref m2m_wifi_req_curr_rssi, @ref m2m_wifi_get_system_time, etc.

    Most Wi-Fi APIs are implemented in an asynchronous mode and calling them generates information
    that is then passed back to the application via this callback. For instance, a set of detected
    networks to be passed back as a result to a call to @ref m2m_wifi_request_scan.

    Applications must ensure a callback function is registered with the Wi-Fi driver by
    calling @ref m2m_wifi_init.
@param[in]  u8MsgType
    Type of notification. Possible types are:
       - @ref M2M_WIFI_RESP_CON_STATE_CHANGED
       - @ref M2M_WIFI_RESP_CONN_INFO
       - @ref M2M_WIFI_REQ_DHCP_CONF
       - @ref M2M_WIFI_REQ_WPS
       - @ref M2M_WIFI_RESP_IP_CONFLICT
       - @ref M2M_WIFI_RESP_SCAN_DONE
       - @ref M2M_WIFI_RESP_SCAN_RESULT
       - @ref M2M_WIFI_RESP_CURRENT_RSSI
       - @ref M2M_WIFI_RESP_CLIENT_INFO
       - @ref M2M_WIFI_RESP_PROVISION_INFO
       - @ref M2M_WIFI_RESP_DEFAULT_CONNECT
       - @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET (If Bypass mode is active)
       - @ref M2M_WIFI_RESP_WIFI_RX_PACKET (If monitoring mode is active)

@param[in]  pvMsg
    A pointer to a buffer containing the notification parameters (if any).
    It should be cast to the correct data type corresponding to the notification type.

@see
    tstrM2mWifiStateChanged
    tstrM2MWPSInfo
    tstrM2mScanDone
    tstrM2mWifiscanResult
    m2m_wifi_init
*/
typedef void (*tpfAppWifiCb)(uint8_t u8MsgType, const void *const pvMsg);

/*!
@typedef void (*tpfAppEthCb)(uint8_t u8MsgType, void* pvMsg, void* pvCtrlBuf);

@brief
    Ethernet (Bypass mode) notification callback function receiving Bypass mode events as
    defined in the Wi-Fi responses enumeration @ref tenuM2mStaCmd.

    If bypass mode is enabled, applications must ensure this callback function is registered
    with the Wi-Fi driver by calling @ref m2m_wifi_init.

@param[in]  u8MsgType
    Type of notification. Possible types are:
        - @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET

@param[in]  pvMsg
    A pointer to a buffer containing the notification parameters (if any).
    It should be cast to the correct data type corresponding to the notification type.

    For example, it could be a pointer to the buffer holding the received frame in case
    a @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET event is received.

@param[in]  pvControlBuf
    A pointer to control buffer describing the accompanied message.
    This must be cast to the data type @ref tstrM2mIpCtrlBuf in case of @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET event.

@warning
    Make sure that the application defines ETH_MODE.

@see
    m2m_wifi_init
*/
typedef void (*tpfAppEthCb) (uint8_t u8MsgType, const void *const pvMsg,const void *const pvCtrlBuf);

/**@cond MON_DOC
 */
/*!
@typedef void (*tpfAppMonCb)(tstrM2MWifiRxPacketInfo* pstrWifiRxPacket, uint8_t* pu8Payload, uint16_t u16PayloadSize);

@brief
    Wi-Fi monitoring mode callback function. This function delivers all received wi-Fi packets
    to the application. Applications requiring to operate in monitoring mode need to call the
    function @ref m2m_wifi_enable_monitoring_mode, in which, each Wi-Fi frame received will invoke
    a single call to this callback function.
    Monitoring mode may be disabled by calling @ref m2m_wifi_disable_monitoring_mode.

@param[in]  pstrWifiRxPacket
    Pointer to a structure holding the Wi-Fi packet header parameters.

@param[in]  pu8Payload
    Pointer to the buffer holding the Wi-Fi packet payload information required by the application
    starting from the defined OFFSET by the application (when calling @ref m2m_wifi_enable_monitoring_mode).
    Could hold a value of NULL, if the application does not need any data from the payload.

@param[in]  u16PayloadSize
    The size of the payload in bytes.

@see
    m2m_wifi_enable_monitoring_mode,
    m2m_wifi_init

@warning
    u16PayloadSize should not exceed the buffer size given through m2m_wifi_enable_monitoring_mode.
*/
typedef void (*tpfAppMonCb)(tstrM2MWifiRxPacketInfo *pstrWifiRxPacket, uint8_t *pu8Payload, uint16_t u16PayloadSize);
/**@endcond*/ //MON_DOC
/**@}*/     //WLANCallbacks

/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
Enums and Data structures
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/

/**@addtogroup  WlanEnums
 * @{
 */
/*!
@enum   \
    tenuWifiState
@brief
    Enumeration for Wi-Fi state
    The following is used to track the state of the wifi (not initialized, initialized or started)

@remarks
    This is useful when putting the WINC in "download mode" to access the flash via SPI. By using
    @ref m2m_wifi_get_state and checking against the desired state, it is possible to validate if
    the Application can proceed with the WINC flash access or not.
*/
typedef enum {
    WIFI_STATE_DEINIT,
    /*!< Wifi is not initialized */
    WIFI_STATE_INIT,
    /*!< Wifi has been initialized. WINC flash access is possible via m2m_flash APIs. */
    WIFI_STATE_START,
    /*!< Wifi has started */
} tenuWifiState;

/*!
@enum   \
    tenuCredStoreOption
@brief

@remarks

*/
typedef enum {
    WIFI_CRED_DONTSAVE,
    /*!< Credentials will not be stored in WINC flash. */
    WIFI_CRED_SAVE_UNENCRYPTED,
    /*!< Credentials will be stored unencrypted in WINC flash. */
    WIFI_CRED_SAVE_ENCRYPTED
    /*!< Credentials will be stored encrypted in WINC flash.
            The encryption is not secure; it is merely intended to prevent sensitive information
            being leaked by an opportunistic read of WINC flash contents.
            The encryption keys involve WINC efuse contents, so WINC efuses should not be written
            while this option is in use. */
} tenuCredStoreOption;

/*!
@enum   \
    tenuTlsCertExpSettings

@brief  TLS Certificate Expiry Validation Options

@remarks
*/
typedef enum {
    TLS_CERT_EXP_CHECK_DISABLE,
    /*!<
        Certificate expiry is not checked.
        Server authentication does not depend on expiry of certificates.
    */
    TLS_CERT_EXP_CHECK_ENABLE,
    /*!<
        Certificate expiry is checked and current time is required.
        Server authentication fails if a certificate has expired or the current time is unknown.
    */
    TLS_CERT_EXP_CHECK_EN_IF_SYS_TIME
    /*!<
        Certificate expiry is only checked if current time is known.
        Server authentication fails if a certificate has expired; passes if the current time is unknown.
    */
} tenuTlsCertExpSettings;

/*!
@enum   \
    tenu1xOption
@brief

@remarks

*/
typedef enum {
    WIFI_1X_BYPASS_SERVER_AUTH,
    /*!< Server authentication for 802.1x connections. Values are of type int.\n
        0: Authenticate server; Default, Recommended.\n
        1: Bypass server authentication.\n
    */
    WIFI_1X_TIME_VERIF_MODE,
    /*!< Mode for checking expiry of server certificate chain.
        Values are of type @ref tenuTlsCertExpSettings.
        Default is @ref TLS_CERT_EXP_CHECK_EN_IF_SYS_TIME.
    */
    WIFI_1X_SESSION_CACHING,
    /*!< TLS session caching on/off for 802.1x connections. Values are of type int.\n
        0: Session caching off.\n
        1: Session caching on; Default.\n
        Note that the WINC implementation of PEAPv0 does not support session caching; this setting is ignored for PEAPv0 methods.
    */
    WIFI_1X_SPECIFIC_ROOTCERT,
    /*!< SHA1 digest of subject name of the root certificate to be used during server authentication. Values are:\n
        20-byte arrays: authentication is limited to this particular root certificate; Recommended\n
        0-byte array: authentication can succeed with any certificate in the WINC root certificate store; Default.\n
    */
} tenu1xOption;

/*!
@struct     \
    tstrEthInitParam

@brief
    Structure to hold Ethernet interface parameters.
    Structure is to be defined and have its attributes set, based on the application's functionality
    before a call is made to initialize the wi-fi operations by calling the
    @ref m2m_wifi_init function.
    Part of the wi-fi configuration structure @ref tstrWifiInitParam.
    Applications shouldn't need to define this structure, if the bypass mode is not defined.

@see
    tpfAppEthCb
    tpfAppWifiCb
    m2m_wifi_init

@warning
    Make sure that application defines ETH_MODE before using @ref tstrEthInitParam.
*/
typedef struct {
    tpfAppEthCb  pfAppEthCb;       /*!< Callback for Ethernet interface. */
    uint8_t  *au8ethRcvBuf;          /*!< Pointer to Receive Buffer of Ethernet Packet */
    uint16_t u16ethRcvBufSize;       /*!< Size of Receive Buffer for Ethernet Packet */
    uint8_t  u8EthernetEnable;       /*!< Enable Ethernet mode flag */
} tstrEthInitParam;

/*!
@struct \
    tstrM2mIpCtrlBuf

@brief
    Structure holding the incoming buffer's data size information, indicating the data size of the
    buffer and the remaining buffer's data size. The data of the buffer which holds the packet sent
    to the host when in the bypass mode, is placed in the @ref tstrEthInitParam::au8ethRcvBuf attribute.
    This following information is retrieved in the host when an event
    @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET is received in the Wi-Fi callback function
    @ref tpfAppWifiCb.

    The application is expected to use this structure's information to determine if there is still incoming data to be received from the firmware.

@see
    tpfAppWifiCb
    tpfAppEthCb
    tstrEthInitParam

@warning
     Make sure that ETHERNET/bypass mode is defined before using @ref tstrM2mIpCtrlBuf

 */
typedef struct {
    uint16_t  u16DataSize;          /*!< Size of the received data in bytes. */
    uint16_t  u16RemainingDataSize; /*!< Size of the remaining data bytes to be delivered to host. */
} tstrM2mIpCtrlBuf;

/**
@struct     \
    tstrWifiInitParam

@brief
    Structure, holding the Wi-fi configuration attributes such as the wi-fi callback , monitoring mode callback and Ethernet parameter initialization structure.
    Such configuration parameters are required to be set before calling the wi-fi initialization function @ref m2m_wifi_init.
    @ref pfAppWifiCb attribute must be set to handle the wi-fi callback operations.
    @ref pfAppMonCb attribute, is optional based on whether the application requires the monitoring mode configuration, and can there not
    be set before the initialization.
    @ref strEthInitParam structure, is another optional configuration based on whether the bypass mode is set.

 @see
     tpfAppEthCb
     tpfAppMonCb
     tstrEthInitParam
*/
typedef struct {
    tpfAppWifiCb pfAppWifiCb;          /*!< Callback for Wi-Fi notifications. */
    tpfAppMonCb  pfAppMonCb;           /*!< Callback for monitoring interface. */
    tstrEthInitParam strEthInitParam ; /*!< Structure to hold Ethernet interface parameters. */
    uint8_t      GainTableIndex;       /*!< Gain Table index to be used to configure the WiFi and BLE gains. */
} tstrWifiInitParam;

typedef struct {
    uint8_t           *pu8Bssid;
    /*!< Pointer to BSSID (6 bytes). Optional (may be NULL).
            If present, this restricts the connection attempt to APs that have a matching BSSID. */
    uint8_t           *pu8Ssid;
    /*!< Pointer to SSID. Required. */
    uint8_t           u8SsidLen;
    /*!< Length of SSID in bytes. Permitted values are between 0 and 32. */
    tenuM2mScanCh   enuChannel;
    /*!< Wi-Fi channel to connect on.
            If an appropriate AP cannot be found on this channel then connection fails.
            @ref M2M_WIFI_CH_ALL may be used to allow scanning of all channels. */
} tstrNetworkId;

/* Legacy Wep param structure. */
typedef struct {
    uint8_t   u8KeyIndx;
    uint8_t   u8KeySz;
    uint8_t   au8WepKey[WEP_104_KEY_STRING_SIZE + 1]; // NULL terminated
    uint8_t   __PAD24__[3];
} tstrM2mWifiWepParams;

/* Legacy 802.1x MsChapv2 param structure. */
typedef struct {
    uint8_t   au8UserName[21];    // NULL terminated
    uint8_t   au8Passwd[41];      // NULL terminated
} tstr1xAuthCredentials;

typedef struct {
    uint8_t   *pu8Psk;
    /*!< Pointer to PSK, represented as an ASCII string (64 characters, representing 32 bytes).
            Must be NULL if Passphrase is provided instead. */
    uint8_t   *pu8Passphrase;
    /*!< Pointer to Passphrase (Printable ASCII).
            Must be NULL if PSK is provided instead. */
    uint8_t   u8PassphraseLen;
    /*!< Length of Passphrase. Permitted values are between 8 and 63.
            This field is ignored if pu8Passphrase == NULL. */
} tstrAuthPsk;

typedef struct {
    uint8_t   *pu8WepKey;
    /*!< Pointer to WEP Key, represented as an ASCII string.
            (10 or 26 characters, representing 5 or 13 bytes.) */
    uint8_t   u8KeySz;
    /*!< Size of WEP Key string.
            Permitted values are @ref WEP_40_KEY_STRING_SIZE or @ref WEP_104_KEY_STRING_SIZE. */
    uint8_t   u8KeyIndx;
    /*!< WEP Key Index in the range 1 to 4. */
} tstrAuthWep;

typedef struct {
    uint8_t   *pu8Domain;
    /*!< Pointer to Domain of authentication server (printable ASCII), including '@' or '\'
            separator character as appropriate. Use NULL if there is no domain information.
            The Domain will be either prepended or appended to the UserName, depending on the
            setting of field bPrependDomain. \n
            Example 1: if [Domain] is "@my_domain" and bPrependDomain is false, then the EAP
            identity response is "[UserName]@my_domain". \n
            Example 2: if [Domain] is "my_domain\" and bPrependDomain is true, then the EAP
            identity response is "my_domain\[UserName]". */
    uint8_t   *pu8UserName;
    /*!< Pointer to UserName (ASCII).
            This will be sent (encrypted) in the tunneled EAP identity response (if applicable)
            and used during MSCHAPv2 authentication. If bUnencryptedUserName is true then it will
            also be sent (unencrypted) in the initial EAP identity response. */
    uint8_t   *pu8Password;
    /*!< Pointer to MSCHAPv2 Password (ASCII).
            This will be used during MSCHAPv2 authentication. */
    uint16_t  u16DomainLen;
    /*!< Length of Domain (in ASCII characters), including '@' or '\' separator character as
            appropriate.
            Permitted values are such that u16DomainLen + u16UserNameLen is between 0 and
            @ref M2M_AUTH_1X_USER_LEN_MAX. */
    uint16_t  u16UserNameLen;
    /*!< Length of UserName (in ASCII characters).
            Permitted values are such that u16DomainLen + u16UserNameLen is between 0 and
            @ref M2M_AUTH_1X_USER_LEN_MAX. */
    uint16_t  u16PasswordLen;
    /*!< Length of Password (in ASCII characters).
            Permitted values are between 0 and @ref M2M_AUTH_1X_PASSWORD_LEN_MAX. */
    bool    bUnencryptedUserName;
    /*!< Determines whether UserName or "anonymous" is sent (unencrypted) in the initial EAP
            identity response. Domain is sent in both cases. \n
            true: UserName is sent in the initial EAP identity response (not recommended).
            false: "anonymous" is sent in the initial EAP identity response. This setting is
            recommended for tunneled methods. MSCHAPv2 is always a tunneled method. */
    bool    bPrependDomain;
    /*!< Determines whether Domain is prepended or appended to UserName in EAP identity responses.
            true: Domain is prepended to UserName - [Domain][UserName].
            false: Domain is appended to UserName - [UserName][Domain]. */
} tstrAuth1xMschap2;

typedef struct {
    uint8_t   *pu8Domain;
    /*!< Pointer to Domain of authentication server (printable ASCII), including '@' or '\'
            separator character as appropriate. Use NULL if there is no domain information.
            The Domain will be either prepended or appended to the UserName, depending on the
            setting of field bPrependDomain. \n
            Example 1: if [Domain] is "@my_domain" and bPrependDomain is false, then the EAP
            identity response is "[UserName]@my_domain". \n
            Example 2: if [Domain] is "my_domain\" and bPrependDomain is true, then the EAP
            identity response is "my_domain\[UserName]". */
    uint8_t   *pu8UserName;
    /*!< Pointer to UserName (ASCII).
            This will be sent (encrypted) in the tunneled EAP identity response.
            If bUnencryptedUserName is true then it will also be sent (unencrypted) in the initial
            EAP identity response. */
    uint8_t   *pu8PrivateKey_Mod;
    /*!< Pointer to PrivateKey modulus (raw data).
            This will be used during TLS client authentication. */
    uint8_t   *pu8PrivateKey_Exp;
    /*!< Pointer to PrivateKey exponent (raw data).
            This will be used during TLS client authentication. */
    uint8_t   *pu8Certificate;
    /*!< Pointer to TLS client certificate corresponding to PrivateKey.
            This will be used during TLS client authentication. */
    uint16_t  u16DomainLen;
    /*!< Length of Domain (in ASCII characters), including '@' or '\' separator character as
            appropriate.
            Permitted values are such that u16DomainLen + u16UserNameLen is between 0 and
            @ref M2M_AUTH_1X_USER_LEN_MAX. */
    uint16_t  u16UserNameLen;
    /*!< Length of UserName (in ASCII characters).
            Permitted values are such that u16DomainLen + u16UserNameLen is between 0 and
            @ref M2M_AUTH_1X_USER_LEN_MAX. */
    uint16_t  u16PrivateKeyLen;
    /*!< Length of PrivateKey_Mod (in bytes).
            Permitted values are between 0 and @ref M2M_AUTH_1X_PRIVATEKEY_LEN_MAX, typically 128 or 256.
            PrivateKey_Exp must be the same length as modulus, pre-padded with 0s if necessary. */
    uint16_t  u16CertificateLen;
    /*!< Length of Certificate (in bytes).
            Permitted values are between 0 and @ref M2M_AUTH_1X_CERT_LEN_MAX. */
    bool    bUnencryptedUserName;
    /*!< Determines whether UserName or "anonymous" is sent (unencrypted) in the initial EAP
            identity response. Domain is sent in both cases. \n
            true: UserName is sent in the initial EAP identity response (required for EAP-TLS).
            false: "anonymous" is sent in the initial EAP identity response. This setting is
            recommended for tunneled methods such as EAP-PEAP/TLS. */
    bool    bPrependDomain;
    /*!< Determines whether Domain is prepended or appended to UserName in EAP identity responses.
            true: Domain is prepended to UserName - [Domain][UserName].
            false: Domain is appended to UserName - [UserName][Domain]. */
} tstrAuth1xTls;
/**@}*/     //WlanEnums

/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
FUNCTION PROTOTYPES
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/

#ifdef __cplusplus
extern "C" {
#endif

/*!
@ingroup WLANINIT
@fn \
    void m2m_wifi_download_mode(void);

@brief
    Prepares the WINC before downloading any data (Firmware, Certificates, etc).

@details
    This function should be called before attempting to download any data to the WINC.
    Performs the appropriate WINC driver initialization, this includes bus initialization,
    interrupt enabling and it halts the chip to allow for the firmware downloads. Firmware
    can be downloaded through a number of interfaces, UART, I2C and SPI.

@pre
    Prior to call m2m_wifi_download_mode, the Application should ensure that the wifi is not
    initialized. This can be done by calling @ref m2m_wifi_get_state and in case the wifi state
    differs from @ref WIFI_STATE_DEINIT, a @ref m2m_wifi_deinit needs to be issued.

@return
    The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
*/
int8_t m2m_wifi_download_mode(void);

/*!
@ingroup WLANINIT
@fn \
    int8_t m2m_wifi_init(tstrWifiInitParam * pWifiInitParam);

@brief
    Synchronous API to initialize the WINC driver.

@details
    This function initializes the WINC driver by registering the callback function for the M2M_WIFI layer
    (also the callback function for bypass mode/monitoring mode if defined), initializing the host
    interface layer and the bus interfaces. Wi-Fi callback registering is essential to allow the
    handling of the events received, in response to the asynchronous Wi-Fi operations.

    The possible Wi-Fi events that are expected to be received through the callback
    function (provided by the application) to the M2M_WIFI layer are listed below:

     - @ref M2M_WIFI_RESP_CON_STATE_CHANGED
     - @ref M2M_WIFI_RESP_CONN_INFO
     - @ref M2M_WIFI_REQ_DHCP_CONF
     - @ref M2M_WIFI_REQ_WPS
     - @ref M2M_WIFI_RESP_IP_CONFLICT
     - @ref M2M_WIFI_RESP_SCAN_DONE
     - @ref M2M_WIFI_RESP_SCAN_RESULT
     - @ref M2M_WIFI_RESP_CURRENT_RSSI
     - @ref M2M_WIFI_RESP_CLIENT_INFO
     - @ref M2M_WIFI_RESP_PROVISION_INFO
     - @ref M2M_WIFI_RESP_DEFAULT_CONNECT
     - @ref M2M_WIFI_RESP_ETHERNET_RX_PACKET (if bypass mode is enabled)
     - @ref M2M_WIFI_RESP_WIFI_RX_PACKET (if monitoring mode is enabled)

    Any application using the WINC driver must call this function at the start of its main function.

@param[in]  pWifiInitParam
    This is a pointer to a variable of type @ref tstrWifiInitParam which contains pointers to the
    application WIFI layer callback function, monitoring mode callback and @ref tstrEthInitParam
    structure (which contains initialization settings for bypass mode).

@return
    The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.

@pre
    Prior to this function call, the application should initialize the BSP using @ref nm_bsp_init.
    Also, the application must provide a callback function responsible for receiving all the
    wi-fi events that are received on the M2M_WIFI layer.

@warning
    Failure to successfully complete indicates that the driver could not be initialized and
    a fatal error will prevent the application from proceeding, proper error handling should be
    implemented by the application.

@see
    m2m_wifi_deinit
    m2m_wifi_init_hold
    m2m_wifi_init_start
    m2m_wifi_reinit
    m2m_wifi_reinit_hold
    m2m_wifi_reinit_start
    m2m_wifi_download_mode
    tstrWifiInitParam
    tenuM2mStaCmd
*/
int8_t m2m_wifi_init(tstrWifiInitParam *pWifiInitParam);

/*!
@ingroup WLANINIT
@fn \
    int8_t m2m_wifi_deinit(void * arg);

@brief
    Synchronous API to de-initialize the WINC driver and host interface.

@details
    De-initialization function for the WINC driver.
    De-initializes the host interface and frees any resources used by the M2M_WIFI layer.
    This function must be called in the application closing phase to ensure that all
    resources have been correctly released.

@param[in]  arg
    Opaque argument, not used in current implementation. Application should use null.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC,
    and a negative value otherwise.

@note
    This function must be called at the de-initialization stage of the application.
    Generally this function should be the last function before switching off the chip
    and it should be followed only by @ref nm_bsp_deinit function call.
    Every function call of @ref m2m_wifi_init should be matched with a call to m2m_wifi_deinit.

@see
    nm_bsp_deinit
    m2m_wifi_init
    m2m_wifi_init_hold
    m2m_wifi_init_start
    m2m_wifi_reinit
    m2m_wifi_reinit_hold
    m2m_wifi_reinit_start
    m2m_wifi_download_mode
    m2m_wifi_download_mode
*/
int8_t  m2m_wifi_deinit(void *arg);

/*!
@ingroup WLANINIT
@fn \
    int8_t m2m_wifi_init_hold(void);

@brief
    First part of @ref m2m_wifi_init, up to the point of initializing SPI for flash access.

@see
    m2m_wifi_init
    m2m_wifi_deinit
    m2m_wifi_init_start
    m2m_wifi_reinit
    m2m_wifi_reinit_hold
    m2m_wifi_reinit_start
    m2m_wifi_download_mode
*/
int8_t m2m_wifi_init_hold(void);

/*!
@ingroup WLANINIT
@fn \
    int8_t m2m_wifi_init_start(tstrWifiInitParam *pWifiInitParam);

@brief
    Second part of @ref m2m_wifi_init, continuing from where @ref m2m_wifi_init_hold left off.

@param[in]  pWifiInitParam
    This is a pointer to a variable of type @ref tstrWifiInitParam which contains pointers to the
    application WIFI layer callback function (see @ref tpfAppWifiCb), monitoring mode callback
    (see @ref tpfAppEthCb) and @ref tstrEthInitParam structure (which contains initialization
    settings for bypass mode).

@see
    m2m_wifi_init
    m2m_wifi_deinit
    m2m_wifi_init_hold
    m2m_wifi_reinit
    m2m_wifi_reinit_hold
    m2m_wifi_reinit_start
    m2m_wifi_download_mode
    tstrWifiInitParam
*/
int8_t m2m_wifi_init_start(tstrWifiInitParam *pWifiInitParam);

/*!
@ingroup WLANINIT
@fn \
    int8_t m2m_wifi_reinit(tstrWifiInitParam *pWifiInitParam);

@brief
    De-initialize and then initialize wifi. Resets the WINC.

@param[in]  pWifiInitParam
    This is a pointer to a variable of type @ref tstrWifiInitParam which contains pointers to the
    application WIFI layer callback function (see @ref tpfAppWifiCb), monitoring mode callback
    (see @ref tpfAppEthCb) and @ref tstrEthInitParam structure (which contains initialization
    settings for bypass mode).

@note
    m2m_wifi_reinit wraps a call to @ref m2m_wifi_deinit and to @ref m2m_wifi_init.

@see
    m2m_wifi_init
    m2m_wifi_deinit
    m2m_wifi_init_hold
    m2m_wifi_init_start
    m2m_wifi_reinit_hold
    m2m_wifi_reinit_start
    m2m_wifi_download_mode
    tstrWifiInitParam
*/
int8_t m2m_wifi_reinit(tstrWifiInitParam *pWifiInitParam);

/*!
@ingroup WLANINIT
@fn \
    int8_t m2m_wifi_reinit_hold(void);

@brief
    First part of @ref m2m_wifi_reinit, up to the point of initializing SPI for flash access.

@note
    m2m_wifi_reinit_hold wraps a call to @ref m2m_wifi_deinit and to @ref m2m_wifi_init_hold.

@see
    m2m_wifi_init
    m2m_wifi_deinit
    m2m_wifi_init_hold
    m2m_wifi_init_start
    m2m_wifi_reinit
    m2m_wifi_reinit_start
    m2m_wifi_download_mode
*/
int8_t m2m_wifi_reinit_hold(void);

/*!
@ingroup WLANINIT
@fn \
    int8_t m2m_wifi_reinit_start(tstrWifiInitParam *pWifiInitParam);

@brief
    Second part of @ref m2m_wifi_reinit, continuing from where m2m_wifi_reinit_hold left off.

@param[in]  pWifiInitParam
    This is a pointer to the @ref tstrWifiInitParam structure which contains pointers to the
    application WIFI layer callback function (see @ref tpfAppWifiCb), monitoring mode callback
    (see @ref tpfAppEthCb) and @ref tstrEthInitParam structure (which contains initialization
    settings for bypass mode).

@see
    m2m_wifi_init
    m2m_wifi_deinit
    m2m_wifi_init_hold
    m2m_wifi_init_start
    m2m_wifi_reinit
    m2m_wifi_reinit_hold
    m2m_wifi_download_mode
    tstrWifiInitParam
*/
int8_t m2m_wifi_reinit_start(tstrWifiInitParam *pWifiInitParam);

/*!
@ingroup WLANEVTS
@fn \
    int8_t m2m_wifi_handle_events(void);

@brief
    Synchronous M2M event handler function.

@details
    This function is responsible for handling interrupts received from the WINC firmware.
    Applications should call this function periodically in-order to receive the events that are to
    be handled by the callback functions implemented by the application.

    Handle the various events received from the WINC.
    Whenever an event happens in the WINC (e.g. Connection, Disconnection, DHCP, etc),
    the WINC will interrupt the host to let it know that a new event has occurred. The host driver
    will attempt to handle these events whenever the application decides to do so by calling
    the m2m_wifi_handle_events function.
    It is mandatory to call this function periodically and independently of any other condition.
    It is ideal to include this function in the main and the most frequent loop of the
    host application.

@pre
    Prior to receiving events, the WINC driver should have been successfully initialized by calling the @ref m2m_wifi_init function.

@warning
    Failure to successfully complete this function indicates bus errors and hence a fatal error that will prevent the application from proceeding.

@return
    The function returns @ref M2M_SUCCESS for successful interrupt handling and a negative value otherwise.
*/
int8_t m2m_wifi_handle_events(void);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_delete_sc(char *pcSsid, uint8_t u8SsidLen);

@brief
    Asynchronous API that deletes connection credentials (PSK, WEP key, 802.1X password) from WINC
    flash. Either deletes all credentials, or for a specific SSID.

@details
    Causes WINC to delete connection credentials. If the parameter is NULL, then WINC will delete
    all credentials from flash. Otherwise WINC will only delete credentials for matching SSID.
    Callback will report the status of the operation (success or not).

@param[in]  pcSsid
    SSID to match on when deleting credentials.
    SSID must not contain '\0'.
    NULL is a valid argument here, in which case all credentials are deleted.

@param[in]  u8SsidLen
    Length of SSID provided in pcSsid. Must be less than @ref M2M_MAX_SSID_LEN.
    This parameter is ignored if pcSsid is NULL.

@pre
    Prior to deleting credentials, the WINC driver should have been successfully initialized by calling the
    @ref m2m_wifi_init function.

@warning
    The option to delete for a specific SSID is currently not supported; all credentials are
    deleted regardless of the input parameters.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
*/
int8_t m2m_wifi_delete_sc(char *pcSsid, uint8_t u8SsidLen);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_default_connect(void);

@brief
    Asynchronous API that attempts to reconnect to the last-associated access point.

@details
    Asynchronous Wi-Fi connection function. An application calling this function will cause
    the firmware to attempt to reconnect to the access point with which it had last successfully connected.
    A failure to connect will result in a response of @ref M2M_WIFI_RESP_DEFAULT_CONNECT
    indicating a connection error as defined in the structure @ref tstrM2MDefaultConnResp.

    Possible errors are:
    @ref M2M_DEFAULT_CONN_EMPTY_LIST indicating that the connection list is empty, or
    @ref M2M_DEFAULT_CONN_SCAN_MISMATCH indicating a mismatch for the saved AP name.

@pre
    Prior to connecting, the WINC driver should have been successfully initialized by calling the
    @ref m2m_wifi_init function.

@warning
    This function must be called in station mode only.
    It is important to note that successful completion of a call to m2m_wifi_default_connect
    does not guarantee success of the WIFI connection; a negative return value indicates only
    locally-detected errors.

@see
    m2m_wifi_connect

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
*/
int8_t m2m_wifi_default_connect(void);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_connect_open(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId);

@brief
    Asynchronous API to connect to an access point using open authentication.

@details
    Asynchronous Wi-Fi connection function. An application calling this function will cause the
    firmware to attempt to connect to an access point matching the details in pstrNetworkId, with
    open authentication.
    On successful connection, the connection details may be saved in WINC flash, according to
    the option selected in enuCredStoreOption.
    Once connection has been attempted (whether successful or otherwise), a response event
    @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function @ref tpfAppWifiCb
    provided during initialization @ref m2m_wifi_init.

    Possible results indicated by the response event are:
    - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed.
    - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded.

@pre
    Prior to attempting connection, the WINC driver must have been initialized by calling the
    @ref m2m_wifi_init function.

@warning
    This function is handled in station mode only.

@param[in]  enuCredStoreOption
    Option to specify whether connection details (i.e. the contents of pstrNetworkId) are stored in
    WINC flash and, if so, whether they are encrypted before storing.

@param[in]  pstrNetworkId
    Structure specifying SSID/BSSID and Wi-Fi channel.

@return
    The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise.
*/
int8_t m2m_wifi_connect_open(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_connect_wep(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuthWep *pstrAuthWep);

@brief
    Asynchronous API to connect to an access point using WEP authentication.

@details
    Asynchronous Wi-Fi connection function. An application calling this function will cause the
    firmware to attempt to connect to an access point matching the details in pstrNetworkId, with
    the WEP key provided in pstrAuthWep.
    On successful connection, the connection details may be saved in WINC flash, according to
    the option selected in enuCredStoreOption.
    Once connection has been attempted (whether successful or otherwise), a response event
    @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function @ref tpfAppWifiCb
    provided during initialization @ref m2m_wifi_init.

    Possible results indicated by the response event are:
    - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed.
    - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded.

@pre
    Prior to attempting connection, the WINC driver must have been initialized by calling the
    @ref m2m_wifi_init function.

@warning
    This function is handled in station mode only.

@param[in]  enuCredStoreOption
    Option to specify whether connection details (i.e. the contents of pstrNetworkId and pstrAuthWep) are stored in
    WINC flash and, if so, whether they are encrypted before storing.

@param[in]  pstrNetworkId
    Structure specifying SSID/BSSID and Wi-Fi channel.

@param[in]  pstrAuthWep
    Structure specifying the WEP key.

@return
    The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise.
*/
int8_t m2m_wifi_connect_wep(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuthWep *pstrAuthWep);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_connect_psk(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuthPsk *pstrAuthPsk);

@brief
    Asynchronous API to connect to an access point using WPA(2) PSK authentication.

@details
    Asynchronous Wi-Fi connection function. An application calling this function will cause the
    firmware to attempt to connect to an access point matching the details in pstrNetworkId, with
    the PSK passphrase provided in pstrAuthPsk.
    On successful connection, the connection details may be saved in WINC flash, according to
    the option selected in enuCredStoreOption.
    Once connection has been attempted (whether successful or otherwise), a response event
    @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function @ref tpfAppWifiCb
    provided during initialization @ref m2m_wifi_init.

    Possible results indicated by the response event are:
    - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed.
    - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded.

@pre
    Prior to attempting connection, the WINC driver must have been initialized by calling the
    @ref m2m_wifi_init function.

@warning
    This function is handled in station mode only.

@param[in]  enuCredStoreOption
    Option to specify whether connection details (i.e. the contents of pstrNetworkId and pstrAuthPsk) are stored in
    WINC flash and, if so, whether they are encrypted before storing.

@param[in]  pstrNetworkId
    Structure specifying SSID/BSSID and Wi-Fi channel.

@param[in]  pstrAuthPsk
    Structure specifying the Passphrase/PSK.

@return
    The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise.
*/
int8_t m2m_wifi_connect_psk(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuthPsk *pstrAuthPsk);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_1x_set_option(tenu1xOption enuOptionName, const void *pOptionValue, size_t OptionLen);

@brief
    API to set (write) options relating to Wi-Fi connection using WPA(2) Enterprise authentication.

@details
    The following options can be set:\n
        @ref WIFI_1X_BYPASS_SERVER_AUTH\n
        @ref WIFI_1X_TIME_VERIF_MODE\n
        @ref WIFI_1X_SESSION_CACHING\n
        @ref WIFI_1X_SPECIFIC_ROOTCERT\n
    The setting applies to all subsequent connection attempts via @ref m2m_wifi_connect_1x_mschap2
    or @ref m2m_wifi_connect_1x_tls.\n
    Connection attempts via @ref m2m_wifi_default_connect use the
    settings which were in place at the time of the original connection.

@param[in]  enuOptionName
    The option to set.

@param[in]  pOptionValue
    Pointer to a buffer containing the value to set. The buffer must be at least as long as OptionLen.
    If OptionLen is 0, then pOptionValue may be NULL.

@param[in]  OptionLen
    The length of the option value being set.

@return
    The function returns @ref M2M_SUCCESS if the parameters are valid and @ref M2M_ERR_INVALID_ARG otherwise.
*/
int8_t m2m_wifi_1x_set_option(tenu1xOption enuOptionName, const void *pOptionValue, size_t OptionLen);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_1x_get_option(tenu1xOption enuOptionName, void *pOptionValue, size_t *pOptionLen);

@brief
    API to get (read) options relating to Wi-Fi connection using WPA(2) Enterprise authentication.

@details
    The following options can be read:\n
        @ref WIFI_1X_BYPASS_SERVER_AUTH\n
        @ref WIFI_1X_TIME_VERIF_MODE\n
        @ref WIFI_1X_SESSION_CACHING\n
        @ref WIFI_1X_SPECIFIC_ROOTCERT\n

@param[in]      enuOptionName
    The option to get.

@param[out]     pOptionValue
    Pointer to a buffer to be filled with the value being read. The buffer must be at least as long as the length in pOptionLen

@param[inout]  pOptionLen
    Pointer to a length.
    When calling the function, this length must be the length of the buffer available for reading the option value.
    When the function returns, this length is the length of the data that has been populated by the function.

@return
    The function returns @ref M2M_SUCCESS if the parameters are valid and @ref M2M_ERR_INVALID_ARG otherwise.
*/
int8_t m2m_wifi_1x_get_option(tenu1xOption enuOptionName, void *pOptionValue, size_t *pOptionLen);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_connect_1x_mschap2(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuth1xMschap2 *pstrAuth1xMschap2);

@brief
    Asynchronous API to connect to an access point using WPA(2) Enterprise authentication with
    MS-CHAP-V2 credentials.

@details
    Asynchronous Wi-Fi connection function. An application calling this function will cause the
    firmware to attempt to connect to an access point matching the details in pstrNetworkId, with
    the Enterprise MS-CHAP-V2 credentials provided in pstrAuth1xMschap2.
    On successful connection, the connection details may be saved in WINC flash, according to
    the option selected in enuCredStoreOption.
    Once connection has been attempted (whether successful or otherwise), a response event
    @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function tpfAppWifiCb
    provided during initialization @ref m2m_wifi_init.

    Possible results indicated by the response event are:
    - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed.
    - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded.

@pre
    Prior to attempting connection, the WINC driver must have been initialized by calling the
    @ref m2m_wifi_init function.

@warning
    This function is handled in station mode only.

@param[in]  enuCredStoreOption
    Option to specify whether connection details (i.e. the contents of pstrNetworkId and pstrAuth1xMschap2) are stored
    in WINC flash and, if so, whether they are encrypted before storing.

@param[in]  pstrNetworkId
    Structure specifying SSID/BSSID and Wi-Fi channel.

@param[in]  pstrAuth1xMschap2
    Structure specifying the MS-CHAP-V2 credentials.

@return
    The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise.
*/
int8_t m2m_wifi_connect_1x_mschap2(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuth1xMschap2 *pstrAuth1xMschap2);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_connect_1x_tls(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuth1xTls *pstrAuth1xTls);

@brief
    Asynchronous API to connect to an access point using WPA(2) Enterprise authentication with
    MS-CHAP-V2 credentials.

@details
    Asynchronous Wi-Fi connection function. An application calling this function will cause the
    firmware to attempt to connect to an access point matching the details in pstrNetworkId, with
    the Enterprise TLS credentials provided in pstrAuth1xTls.
    On successful connection, the connection details may be saved in WINC flash, according to
    the option selected in enuCredStoreOption.
    Once connection has been attempted (whether successful or otherwise), a response event
    @ref M2M_WIFI_RESP_CON_STATE_CHANGED will be sent to the callback function @ref tpfAppWifiCb
    provided during initialization @ref m2m_wifi_init.

    Possible results indicated by the response event are:
    - @ref M2M_WIFI_DISCONNECTED if the connection attempt failed.
    - @ref M2M_WIFI_CONNECTED if the connection attempt succeeded.

@pre
    Prior to attempting connection, the WINC driver must have been initialized by calling the
    @ref m2m_wifi_init function.

@warning
    This function is handled in station mode only.

@param[in]  enuCredStoreOption
    Option to specify whether connection details (i.e. the contents of pstrNetworkId and pstrAuth1xTls) are stored in
    WINC flash and, if so, whether they are encrypted before storing.

@param[in]  pstrNetworkId
    Structure specifying SSID/BSSID and Wi-Fi channel.

@param[in]  pstrAuth1xTls
    Structure specifying the EAP-TLS credentials.

@return
    The function returns @ref M2M_SUCCESS if the connect request has been successfully passed to the firmware and a negative value otherwise.
*/
int8_t m2m_wifi_connect_1x_tls(tenuCredStoreOption enuCredStoreOption, tstrNetworkId *pstrNetworkId, tstrAuth1xTls *pstrAuth1xTls);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_connect(char *pcSsid, uint8_t u8SsidLen, uint8_t u8SecType, void *pvAuthInfo, uint16_t u16Ch);

@brief
    Legacy asynchronous API to request connection to a specified access point.

@details
    This API is maintained for purposes of compatibility with legacy applications. It is
    implemented as a wrapper for the following new APIs:
        @ref m2m_wifi_connect_open
        @ref m2m_wifi_connect_wep
        @ref m2m_wifi_connect_psk
        @ref m2m_wifi_connect_1x_mschap2
        @ref m2m_wifi_connect_1x_tls
    These new APIs allow more flexibility and it is recommended that applications use them instead.

@param[in]  pcSsid
    A buffer holding the SSID corresponding to the requested AP.
    SSID must not contain '\0'.

@param[in]  u8SsidLen
    Length of the given SSID (not including any NULL termination).
    A length greater than or equal to @ref M2M_MAX_SSID_LEN will result in a negative error
    @ref M2M_ERR_FAIL.

@param[in]  u8SecType
    Wi-Fi security type security for the network. It can be one of the following types:
        -@ref M2M_WIFI_SEC_OPEN
        -@ref M2M_WIFI_SEC_WEP
        -@ref M2M_WIFI_SEC_WPA_PSK
        -@ref M2M_WIFI_SEC_802_1X
    A value outside these possible values will result in a negative return error @ref M2M_ERR_FAIL.

@param[in]  pvAuthInfo
    Authentication parameters required for completing the connection. Its type is based on the
    security type. If the authentication parameters are NULL or are greater than the maximum length
    of the authentication parameters length as defined by @ref M2M_MAX_PSK_LEN a negative error will
    return @ref M2M_ERR_FAIL indicating connection failure.

@param[in]  u16Ch
    Wi-Fi channel number as defined in @ref tenuM2mScanCh enumeration. Specifying a channel number
    greater than @ref M2M_WIFI_CH_14 returns a negative error @ref M2M_ERR_FAIL, unless
    the value is @ref M2M_WIFI_CH_ALL, since this indicates that the firmware should scan all channels
    to find the SSID specified in parameter pcSsid.

    Failure to find the connection match will return a negative error
    @ref M2M_DEFAULT_CONN_SCAN_MISMATCH.

@pre
    Prior to a successful connection request, the wi-fi driver must have been successfully initialized
    through the call of the @ref m2m_wifi_init function.

@warning
    If there is a '\0' character within the first u8SsidLen characters, then this function will assume
    that the input u8SsidLen was incorrect, set length to strlen(pcSsid) and continue.\n
    It is recommended that the following Wi-Fi connect APIs are used instead:
    @ref m2m_wifi_connect_open
    @ref m2m_wifi_connect_wep
    @ref m2m_wifi_connect_psk
    @ref m2m_wifi_connect_1x_mschap2
    @ref m2m_wifi_connect_1x_tls

    Additionally:
    - This function must be called in station mode only.
    - Successful completion of this function does not guarantee success of the WIFI connection, and
    a negative return value indicates only locally-detected errors.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tuniM2MWifiAuth
    tstr1xAuthCredentials
    tstrM2mWifiWepParams
*/
int8_t m2m_wifi_connect(char *pcSsid, uint8_t u8SsidLen, uint8_t u8SecType, void *pvAuthInfo, uint16_t u16Ch);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_connect_sc(char *pcSsid, uint8_t u8SsidLen, uint8_t u8SecType, void *pvAuthInfo, uint16_t u16Ch, uint8_t u8NoSaveCred);

@brief
    Legacy asynchronous API to request connection to a specific AP with the option to save credentials in Flash.

@details
    This API is maintained for purposes of compatibility with legacy applications. It is
    implemented as a wrapper for the following new APIs:
        @ref m2m_wifi_connect_open
        @ref m2m_wifi_connect_wep
        @ref m2m_wifi_connect_psk
        @ref m2m_wifi_connect_1x_mschap2
        @ref m2m_wifi_connect_1x_tls
    These new APIs allow more flexibility and it is recommended that applications use them instead.

@param[in]  pcSsid
    A buffer holding the SSID corresponding to the requested AP.
    SSID must not contain '\0'.

@param[in]  u8SsidLen
    Length of the given SSID (not including any NULL termination).
    A length greater than or equal to @ref M2M_MAX_SSID_LEN will result in a negative error
    @ref M2M_ERR_FAIL.

@param[in]  u8SecType
    Wi-Fi security type security for the network (see @ref tenuM2mSecType). It can be one of the following types:
        -@ref M2M_WIFI_SEC_OPEN
        -@ref M2M_WIFI_SEC_WEP
        -@ref M2M_WIFI_SEC_WPA_PSK
        -@ref M2M_WIFI_SEC_802_1X
    A value outside these possible values will result in a negative return error @ref M2M_ERR_FAIL.

@param[in]  pvAuthInfo
    Authentication parameters required for completing the connection. Its type is based on the
    security type. If the authentication parameters are NULL or are greater than the maximum length
    of the authentication parameters length as defined by @ref M2M_MAX_PSK_LEN a negative error will
    return @ref M2M_ERR_FAIL indicating connection failure.

@param[in]  u16Ch
    Wi-Fi channel number as defined in @ref tenuM2mScanCh enumeration. Specification of a channel
    number greater than @ref M2M_WIFI_CH_14 returns a negative error @ref M2M_ERR_FAIL unless
    the value is @ref M2M_WIFI_CH_ALL. A channel number of @ref M2M_WIFI_CH_ALL indicates that the
    firmware should scan all channels to find the SSID specified in parameter pcSsid.

    Failure to find the connection match will return a negative error
    @ref M2M_DEFAULT_CONN_SCAN_MISMATCH.

@param[in]  u8SaveCred
    Option to store the access point SSID and password into the WINC flash memory or not.

@pre
    Prior to a successful connection request, the wi-fi driver must have been successfully initialized through the call of the @ref m2m_wifi_init function.

@warning
    If there is a '\0' character within the first u8SsidLen characters, then this function will assume
    that the input u8SsidLen was incorrect, set length to strlen(pcSsid) and continue.\n
    It is recommended that the following Wi-Fi connect APIs are used instead:
    @ref m2m_wifi_connect_open
    @ref m2m_wifi_connect_wep
    @ref m2m_wifi_connect_psk
    @ref m2m_wifi_connect_1x_mschap2
    @ref m2m_wifi_connect_1x_tls

    Additionally:
    - This function must be called in station mode only.
    - Successful completion of this function does not guarantee success of the WIFI connection, and
    a negative return value indicates only locally-detected errors.

@see
    tuniM2MWifiAuth
    tenuM2mSecType
    tstr1xAuthCredentials
    tstrM2mWifiWepParams

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
*/
int8_t m2m_wifi_connect_sc(char *pcSsid, uint8_t u8SsidLen, uint8_t u8SecType, void *pvAuthInfo, uint16_t u16Ch, uint8_t u8NoSaveCred);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_disconnect(void);

@brief
    Synchronous API to request disconnection from a network.

@details
    Request a Wi-Fi disconnect from the currently connected AP.
    The connection status will be indicated to the application via a @ref M2M_WIFI_RESP_CON_STATE_CHANGED event.
    The status will be one of those defined in @ref tenuM2mConnState, with @ref M2M_WIFI_DISCONNECTED indicating
    a successful disconnection.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@pre
    Disconnection request must be made to a successfully connected AP. If the WINC is not in the connected state, a call to this function will hold insignificant.

@warning
    This function must be called in station mode only.

@see
    m2m_wifi_connect
    m2m_wifi_connect_sc
    m2m_wifi_default_connect
    m2m_wifi_connect_open
    m2m_wifi_connect_wep
    m2m_wifi_connect_psk
    m2m_wifi_connect_1x_mschap2
    m2m_wifi_connect_1x_tls
*/
int8_t m2m_wifi_disconnect(void);

/*!
@ingroup WLANPROVISION
@fn \
    int8_t m2m_wifi_start_provision_mode(tstrM2MAPConfig *pstrAPConfig, char *pcHttpServerDomainName, uint8_t bEnableHttpRedirect);

@brief
    Asynchronous API for control of Wi-Fi provisioning functionality.

@details
    This function allows the application to start the WINC in 'provisioning mode', a special mode
    that triggers the WINC to create a Wi-Fi access point, DHCP server, and HTTP server.

    The HTTP server presents a provisioning page to a connected client which lists the access points
    detected in the vicinity of the WINC, and allows one of these to be selected and any appropriate
    credentials to be entered. This allows a headless system to be provisioned (configured to
    connect with an access point).

    Provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO.

@param[in]  pstrAPConfig
    AP configuration parameters as defined in @ref tstrM2MAPConfig configuration structure.
    If a NULL value is passed in, the call will result in a negative error @ref M2M_ERR_FAIL.

@param[in]  pcHttpServerDomainName
    Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page.
    The domain name can have one of the following 3 forms:
    - 1. "wincprov.com"
    - 2. "http://wincprov.com"
    - 3. "https://wincprov.com"

    Forms 1 and 2 are equivalent, they will both start a plain http server, while form 3
    will start a secure HTTP provisioning Session (HTTP over SSL connection).

@param[in]  bEnableHttpRedirect
    A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server
    domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS).
    Possible values are:
        - Zero:     DO NOT use HTTP Redirect. In this case, the associated device could open the provisioning
                    page ONLY when the HTTP Provision URL of the WINC HTTP Server is correctly written on the browser.
        - Non-Zero: Use HTTP Redirect. In this case, all http traffic (http://URL) from the associated
                    device (Phone, PC, etc) will be redirected to the WINC HTTP Provisioning Home page.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup.
    Registering the callback is done through passing it to the initialization @ref m2m_wifi_init function.
    - The event @ref M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info.

@warning
    Do not use ".local" in the pcHttpServerDomainName.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tpfAppWifiCb
    m2m_wifi_init
    M2M_WIFI_RESP_PROVISION_INFO
    m2m_wifi_stop_provision_mode
    tstrM2MAPConfig

@section WIFIExample1 Example
  The example demonstrates a code snippet for how provisioning is triggered and the response event
  received accordingly.

@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_PROVISION_INFO:
        {
            tstrM2MProvisionInfo    *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg;
            if(pstrProvInfo->u8Status == M2M_SUCCESS)
            {
                tstrNetworkId   strNetworkId = {NULL, pstrProvInfo->au8SSID, (uint8_t)strlen((char*)(pstrProvInfo->au8SSID)), M2M_WIFI_CH_ALL};
                tstrAuthPsk     strAuthPsk = {NULL, pstrProvInfo->au8Password, (uint8_t)strlen((char*)(pstrProvInfo->au8Password))};
                m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk);

                printf("PROV SSID : %s\n",pstrProvInfo->au8SSID);
                printf("PROV PSK  : %s\n",pstrProvInfo->au8Password);
            }
            else
            {
                printf("(ERR) Provisioning Failed\n");
            }
        }
        break;

        default:
        break;
    }
}

int main()
{
    tstrWifiInitParam param;
    param.pfAppWifiCb = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        tstrM2MAPConfig apConfig;
        uint8_t           bEnableRedirect = 1;

        strcpy(apConfig.au8SSID, "WINC_SSID");
        apConfig.u8ListenChannel = 1;
        apConfig.u8SecType       = M2M_WIFI_SEC_OPEN;
        apConfig.u8SsidHide      = 0;

        // IP Address
        apConfig.au8DHCPServerIP[0] = 192;
        apConfig.au8DHCPServerIP[1] = 168;
        apConfig.au8DHCPServerIP[2] = 1;
        apConfig.au8DHCPServerIP[3] = 1;

        m2m_wifi_start_provision_mode(&apConfig, "atmelwincconf.com", bEnableRedirect);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_start_provision_mode(tstrM2MAPConfig *pstrAPConfig, char *pcHttpServerDomainName, uint8_t bEnableHttpRedirect);

/*!
@ingroup WLANPROVISION
@fn \
    int8_t m2m_wifi_start_provision_mode_ext(tstrM2MAPModeConfig *pstrAPModeConfig, char *pcHttpServerDomainName, uint8_t bEnableHttpRedirect);

@brief
    Asynchronous API for control of Wi-Fi provisioning functionality with extended options.

@details
    This function allows the application to start the WINC in 'provisioning mode', a special mode
    that triggers the WINC to create a Wi-Fi access point, DHCP server, and HTTP server.

    The HTTP server presents a provisioning page to a connected client which lists the access points
    detected in the vicinity of the WINC, and allows one of these to be selected and any appropriate
    credentials to be entered. This allows a headless system to be provisioned (configured to
    connect with an access point).

    Provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO.

@param[in]  pstrAPModeConfig
    AP configuration parameters as defined in @ref tstrM2MAPModeConfig configuration structure.
    A NULL value passed in, will result in a negative error @ref M2M_ERR_FAIL.

@param[in]  pcHttpServerDomainName
    Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page.
    The domain name can have one of the following 3 forms:
    - 1. "wincprov.com"
    - 2. "http://wincprov.com"
    - 3. "https://wincprov.com"

    The forms 1 and 2 are equivalent, they both will start a plain http server, while form 3
    will start a secure HTTP provisioning Session (HTTP over SSL connection).

@param[in]  bEnableHttpRedirect
    A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server
    domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS).
    Possible values are:
        - Zero:     DO NOT use HTTP Redirect. In this case the associated device could open the
                    provisioning page ONLY when the HTTP Provision URL of the WINC HTTP Server is
                    correctly written on the browser.
        - Non-Zero: Use HTTP Redirect. In this case, all http traffic (http://URL) from the
                    associated device (Phone, PC, ...etc) will be redirected to the WINC HTTP
                    Provisioning Home page.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at startup.
    Registering the callback is done through passing it to the initialization @ref m2m_wifi_init function.
    - The event @ref M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info.

@warning
    Do not use ".local" in the pcHttpServerDomainName.

@see
    tpfAppWifiCb
    m2m_wifi_init
    M2M_WIFI_RESP_PROVISION_INFO
    m2m_wifi_stop_provision_mode
    tstrM2MAPModeConfig

@section WIFIExample12 Example
  The example demonstrates a code snippet for how provisioning is triggered and the response event
  received accordingly.

@code
    #include "m2m_wifi.h"
    #include "m2m_types.h"

    void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
    {
        switch(u8WiFiEvent)
        {
        case M2M_WIFI_RESP_PROVISION_INFO:
            {
                tstrM2MProvisionInfo    *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg;
                if(pstrProvInfo->u8Status == M2M_SUCCESS)
                {
                    tstrNetworkId   strNetworkId = {NULL, pstrProvInfo->au8SSID, (uint8_t)strlen((char*)(pstrProvInfo->au8SSID)), M2M_WIFI_CH_ALL};
                    tstrAuthPsk     strAuthPsk = {NULL, pstrProvInfo->au8Password, (uint8_t)strlen((char*)(pstrProvInfo->au8Password))};
                    m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk);

                    printf("PROV SSID : %s\n",pstrProvInfo->au8SSID);
                    printf("PROV PSK  : %s\n",pstrProvInfo->au8Password);
                }
                else
                {
                    printf("(ERR) Provisioning Failed\n");
                }
            }
            break;

            default:
            break;
        }
    }

    int main()
    {
        tstrWifiInitParam   param;

        param.pfAppWifiCb   = wifi_event_cb;
        if(!m2m_wifi_init(&param))
        {
            tstrM2MAPModeConfig apModeConfig;
            uint8_t               bEnableRedirect = 1;

            strcpy(apModeConfig.au8SSID, "WINC_SSID");
            apModeConfig.strApConfig.u8ListenChannel    = 1;
            apModeConfig.strApConfig.u8SecType          = M2M_WIFI_SEC_OPEN;
            apModeConfig.strApConfig.u8SsidHide         = 0;

            // IP Address
            apModeConfig.strApConfig.au8DHCPServerIP[0] = 192;
            apModeConfig.strApConfig.au8DHCPServerIP[1] = 168;
            apModeConfig.strApConfig.au8DHCPServerIP[2] = 1;
            apModeConfig.strApConfig.au8DHCPServerIP[3] = 1;

            // Default router IP
            memcpy(apModeConfig.strApConfigExt.au8DefRouterIP, apModeConfig.strApConfig.au8DHCPServerIP, 4);

            // DNS Server IP
            memcpy(apModeConfig.strApConfigExt.au8DNSServerIP, apModeConfig.strApConfig.au8DHCPServerIP, 4);

            // Subnet mask
            apModeConfig.strApConfigExt.au8SubnetMask[0] = 255;
            apModeConfig.strApConfigExt.au8SubnetMask[1] = 255;
            apModeConfig.strApConfigExt.au8SubnetMask[2] = 255;
            apModeConfig.strApConfigExt.au8SubnetMask[3] = 0;

            m2m_wifi_start_provision_mode_ext(&apModeConfig, "atmelwincconf.com", bEnableRedirect);

            while(1)
            {
                m2m_wifi_handle_events(NULL);
            }
        }
    }
@endcode
*/
int8_t m2m_wifi_start_provision_mode_ext(tstrM2MAPModeConfig *pstrAPModeConfig, char *pcHttpServerDomainName, uint8_t bEnableHttpRedirect);

/*!
@ingroup WLANPROVISION
@fn \
    int8_t m2m_wifi_stop_provision_mode(void);

@brief
    Synchronous API for terminating provisioning mode on the WINC.

@details
    This function will terminate any currently active provisioning mode on the WINC, returning the WINC to idle.

@pre
    An active provisioning session must be active before it is terminated through this function.

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.

@see
    m2m_wifi_start_provision_mode
*/
int8_t m2m_wifi_stop_provision_mode(void);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_get_connection_info(void);

@brief
    Asynchronous API for retrieving the WINC connection status.

@details
    Requests the connection status from the WINC including information regarding any access
    point to which it is currently connected, or any non-AP station that is connected to the WINC.
    All information will be returned to the application via the Wi-Fi notification callback through
    the event @ref M2M_WIFI_RESP_CONN_INFO.

    The connection info can be retrieved using the structure @ref tstrM2MConnInfo which contains:
    - Connection Security
    - Connection RSSI
    - Remote MAC address
    - Remote IP address
    - SSID of the network (in cases where the WINC is in non-AP mode)

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at
    startup. Registering the callback is done through passing it to the initialization
    @ref m2m_wifi_init function.
    - The event @ref M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the
    requested connection info.

@warning
    - In case the WINC is operating in AP mode or P2P mode, the SSID field will be returned as a NULL string.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    M2M_WIFI_RESP_CONN_INFO,
    tstrM2MConnInfo
@section WIFIExample2 Example
  The code snippet shows an example of how wi-fi connection information is retrieved .
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_CONN_INFO:
        {
            tstrM2MConnInfo     *pstrConnInfo = (tstrM2MConnInfo*)pvMsg;

            printf("CONNECTED AP INFO\n");
            printf("SSID                : %s\n",pstrConnInfo->acSSID);
            printf("SEC TYPE            : %d\n",pstrConnInfo->u8SecType);
            printf("Signal Strength     : %d\n", pstrConnInfo->s8RSSI);
            printf("Local IP Address    : %d.%d.%d.%d\n",
                pstrConnInfo->au8IPAddr[0] , pstrConnInfo->au8IPAddr[1], pstrConnInfo->au8IPAddr[2], pstrConnInfo->au8IPAddr[3]);
        }
        break;

    case M2M_WIFI_REQ_DHCP_CONF:
        {
            // Get the current AP information.
            m2m_wifi_get_connection_info();
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // connect to the default AP
        m2m_wifi_default_connect();

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_get_connection_info(void);

/*!
@ingroup WLANCONF
@fn \
    int8_t m2m_wifi_set_mac_address(uint8_t au8MacAddress[6]);

@brief
    Asynchronous API for assigning a MAC address to the WINC.

@details
    This function is intended to allow non-production software to assign a MAC address to the WINC.

@warning
    This function is intended for development use only and not for use in production software.

@param[in]  au8MacAddress
    MAC Address to be provisioned to the WINC.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
*/
int8_t m2m_wifi_set_mac_address(uint8_t au8MacAddress[6]);

/*!
@ingroup WLANWPS
@fn \
    int8_t m2m_wifi_wps(uint8_t u8TriggerType,const char * pcPinNumber);

@brief
    Asynchronous API to engage the WINC Wi-Fi Protected Setup (enrollee) function.

@details
    This function can be called to make the WINC enter WPS (Wi-Fi Protected Setup) mode. The result
    is passed to the Wi-Fi notification callback with the event @ref M2M_WIFI_REQ_WPS.

@param[in]  u8TriggerType
    WPS Trigger method. This may be:
    - @ref WPS_PIN_TRIGGER   Push button method
    - @ref WPS_PBC_TRIGGER   Pin method

@param[in]  pcPinNumber
    Valid only if the u8TriggerType is @ref WPS_PIN_TRIGGER, this parameter contains the PIN number.
    The number must follow the format as given in the WSC1.0 specification.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@warning
    This function is not allowed in AP or P2P modes.

@pre
    - A Wi-Fi notification callback of type (@ref tpfAppWifiCb MUST be implemented and registered at
    startup. Registering the callback is done through passing it to @ref m2m_wifi_init.
    - The event @ref M2M_WIFI_REQ_WPS must be handled in the callback to receive the WPS status.
    - The WINC device MUST be in IDLE or STA mode. If AP or P2P mode is active, the WPS will not be performed.
    - The @ref m2m_wifi_handle_events MUST be called periodically to receive
    the responses in the callback.

@see
    tpfAppWifiCb
    m2m_wifi_init
    M2M_WIFI_REQ_WPS
    tenuWPSTrigger
    tstrM2MWPSInfo

@section WIFIExample3 Example
  The code snippet shows an example of how wi-fi WPS is triggered .
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_REQ_WPS:
        {
            tstrM2MWPSInfo  *pstrWPS = (tstrM2MWPSInfo*)pvMsg;
            if(pstrWPS->u8AuthType != 0)
            {
                // establish Wi-Fi connection
                tstrNetworkId   strNetworkId = {NULL, pstrWPS->au8SSID, (uint8_t)strlen((char*)(pstrWPS->au8SSID)), pstrWPS->u8Ch};
                if(pstrWPS->u8AuthType == M2M_WIFI_SEC_OPEN)
                {
                    m2m_wifi_connect_open(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId);
                }
                else
                {
                    tstrAuthPsk     strAuthPsk = {NULL, pstrWPS->au8PSK, (uint8_t)strlen((char*)(pstrWPS->au8PSK))};
                    m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk);
                }

                printf("WPS SSID           : %s\n",pstrWPS->au8SSID);
                printf("WPS PSK            : %s\n",pstrWPS->au8PSK);
                printf("WPS SSID Auth Type : %s\n",pstrWPS->u8AuthType == M2M_WIFI_SEC_OPEN ? "OPEN" : "WPA/WPA2");
                printf("WPS Channel        : %d\n",pstrWPS->u8Ch);
            }
            else
            {
                printf("(ERR) WPS Is not enabled OR Timed out\n");
            }
        }
        break;

    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Trigger WPS in Push button mode.
        m2m_wifi_wps(WPS_PBC_TRIGGER, NULL);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_wps(uint8_t u8TriggerType, const char  *pcPinNumber);

/*!
@ingroup WLANWPS
@fn \
    int8_t m2m_wifi_wps_disable(void);

@brief
    Asynchronous API that disables Wi-Fi Protected Setup mode in the WINC.

@pre
    WINC should be already in WPS mode using @ref m2m_wifi_wps.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_wps
*/
int8_t m2m_wifi_wps_disable(void);

/**@cond P2P_DOC
 */
/*!
@ingroup WLANP2P
@fn \
    int8_t m2m_wifi_p2p(uint8_t u8Channel);

@brief
    Asynchronous API for enabling Wi-Fi Direct (P2P) mode in the WINC.

@param[in]  u8Channel
    P2P Listen RF channel. According to the P2P standard, it must hold only one of the following values 1, 6 or 11.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at
      initialization. Registering the callback is done through passing it to the @ref m2m_wifi_init.
    - The events @ref M2M_WIFI_RESP_CON_STATE_CHANGED and @ref M2M_WIFI_REQ_DHCP_CONF must be handled in the callback.
    - The @ref m2m_wifi_handle_events MUST be called to receive the responses in the callback.

@warning
    - This function is not available in the WINC 3400
    - This function is not allowed in AP or STA modes.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tpfAppWifiCb
    m2m_wifi_init
    M2M_WIFI_RESP_CON_STATE_CHANGED
    M2M_WIFI_REQ_DHCP_CONF
    tstrM2mWifiStateChanged

@section WIFIExample4 Example
  The code snippet shows an example of how the p2p mode operates.
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_CON_STATE_CHANGED:
        {
            tstrM2mWifiStateChanged *pstrWifiState = (tstrM2mWifiStateChanged*)pvMsg;
            M2M_INFO("Wifi State :: %s :: ErrCode %d\n", pstrWifiState->u8CurrState? "CONNECTED":"DISCONNECTED",pstrWifiState->u8ErrCode);

            // Do something
        }
        break;

    case M2M_WIFI_REQ_DHCP_CONF:
        {
            uint8_t   *pu8IPAddress = (uint8_t*)pvMsg;

            printf("P2P IP Address \"%u.%u.%u.%u\"\n",pu8IPAddress[0],pu8IPAddress[1],pu8IPAddress[2],pu8IPAddress[3]);
        }
        break;

    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Trigger P2P
        m2m_wifi_p2p(M2M_WIFI_CH_1);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_p2p(uint8_t u8Channel);

/*!
@ingroup WLANP2P
@fn \
    int8_t m2m_wifi_p2p_disconnect(void);

@brief
    Synchronous API to disable Wi-Fi Direct (P2P) Mode on the WINC.

@pre
    The p2p mode must be enabled and active before a disconnect can be called.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_p2p
*/
int8_t m2m_wifi_p2p_disconnect(void);
/**@endcond*/ //P2P_DOC

/*!
@ingroup WLANAP
@fn \
    int8_t m2m_wifi_enable_ap(const tstrM2MAPConfig* pstrM2MAPConfig);

@brief
    Asynchronous API to enable access point (AKA "hot-spot") mode on the WINC.

@details
    The WINC supports the ability to operate as an access point with the following limitations:
    - Only 1 station may be associated at any given time.
    - Open system and WEP are the only security suites supported.

@param[in]  pstrM2MAPConfig
    A structure holding the AP configurations.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@warning
    This function is not allowed in P2P or STA modes.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb  MUST be implemented and registered at initialization. Registering the callback
    is done through passing it to the @ref m2m_wifi_init.
    - The event @ref M2M_WIFI_REQ_DHCP_CONF must be handled in the callback.
    - The @ref m2m_wifi_handle_events MUST be called to receive the responses in the callback.

@see
    tpfAppWifiCb
    tenuM2mSecType
    m2m_wifi_init
    M2M_WIFI_REQ_DHCP_CONF
    tstrM2mWifiStateChanged
    tstrM2MAPConfig

@section WIFIExample5 Example
  The code snippet demonstrates how the AP mode is enabled after the driver is initialized in the application's main function and the handling
  of the event @ref M2M_WIFI_REQ_DHCP_CONF, to indicate successful connection.
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_REQ_DHCP_CONF:
        {
            uint8_t   *pu8IPAddress = (uint8_t*)pvMsg;

            printf("Associated STA has IP Address \"%u.%u.%u.%u\"\n",pu8IPAddress[0],pu8IPAddress[1],pu8IPAddress[2],pu8IPAddress[3]);
        }
        break;

    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam param;
    param.pfAppWifiCb = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        tstrM2MAPConfig     apConfig;

        strcpy(apConfig.au8SSID, "WINC_SSID");
        apConfig.u8ListenChannel = 1;
        apConfig.u8SecType       = M2M_WIFI_SEC_OPEN;
        apConfig.u8SsidHide      = 0;

        // IP Address
        apConfig.au8DHCPServerIP[0] = 192;
        apConfig.au8DHCPServerIP[1] = 168;
        apConfig.au8DHCPServerIP[2] = 1;
        apConfig.au8DHCPServerIP[3] = 1;

        // Trigger AP
        m2m_wifi_enable_ap(&apConfig);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_enable_ap(const tstrM2MAPConfig *pstrM2MAPConfig);

/*!
@ingroup WLANAP
@fn \
    int8_t m2m_wifi_enable_ap_ext(const tstrM2MAPModeConfig *pstrM2MAPModeConfig);

@brief
    Asynchronous API to enable access point (AKA "hot-spot") mode on the WINC with extended options.

@details
    The WINC supports the ability to operate as an access point with the following limitations:
    - Only 1 station may be associated at any given time.
    - Open system and WEP are the only security suites supported.

@param[in]  pstrM2MAPModeConfig
    A structure holding the AP configurations.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@warning
    This function is not allowed in P2P or STA modes.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb  MUST be implemented and registered at initialization. Registering the callback
    is done through passing it to the @ref m2m_wifi_init.
    - The event @ref M2M_WIFI_REQ_DHCP_CONF must be handled in the callback.
    - The @ref m2m_wifi_handle_events MUST be called to receive the responses in the callback.

@see
    tpfAppWifiCb
    tenuM2mSecType
    m2m_wifi_init
    M2M_WIFI_REQ_DHCP_CONF
    tstrM2mWifiStateChanged
    tstrM2MAPModeConfig

@section WIFIExample13 Example
  The code snippet demonstrates how the AP mode is enabled after the driver is initialized in the application's main function and the handling
  of the event @ref M2M_WIFI_REQ_DHCP_CONF, to indicate successful connection.
@code
    #include "m2m_wifi.h"
    #include "m2m_types.h"

    void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
    {
        switch(u8WiFiEvent)
        {
        case M2M_WIFI_REQ_DHCP_CONF:
            {
                uint8_t   *pu8IPAddress = (uint8_t*)pvMsg;

                printf("Associated STA has IP Address \"%u.%u.%u.%u\"\n",pu8IPAddress[0],pu8IPAddress[1],pu8IPAddress[2],pu8IPAddress[3]);
            }
            break;

        default:
            break;
        }
    }

    int main()
    {
        tstrWifiInitParam   param;

        param.pfAppWifiCb   = wifi_event_cb;
        if(!m2m_wifi_init(&param))
        {
            tstrM2MAPModeConfig     apModeConfig;

            strcpy(apModeConfig.strApConfig.au8SSID, "WINC_SSID");
            apModeConfig.strApConfig.u8ListenChannel    = 1;
            apModeConfig.strApConfig.u8SecType          = M2M_WIFI_SEC_OPEN;
            apModeConfig.strApConfig.u8SsidHide         = 0;

            // IP Address
            apModeConfig.strApConfig.au8DHCPServerIP[0] = 192;
            apModeConfig.strApConfig.au8DHCPServerIP[1] = 168;
            apModeConfig.strApConfig.au8DHCPServerIP[2] = 1;
            apModeConfig.strApConfig.au8DHCPServerIP[3] = 1;

            // Default router IP
            memcpy(apModeConfig.strApConfigExt.au8DefRouterIP, apModeConfig.strApConfig.au8DHCPServerIP, 4);

            // DNS Server IP
            memcpy(apModeConfig.strApConfigExt.au8DNSServerIP, apModeConfig.strApConfig.au8DHCPServerIP, 4);

            // Subnet mask
            apModeConfig.strApConfigExt.au8SubnetMask[0] = 255;
            apModeConfig.strApConfigExt.au8SubnetMask[1] = 255;
            apModeConfig.strApConfigExt.au8SubnetMask[2] = 255;
            apModeConfig.strApConfigExt.au8SubnetMask[3] = 0;

            // Trigger AP
            m2m_wifi_enable_ap_ext(&apModeConfig);

            while(1)
            {
                m2m_wifi_handle_events(NULL);
            }
        }
    }
@endcode
*/
int8_t m2m_wifi_enable_ap_ext(const tstrM2MAPModeConfig *pstrM2MAPModeConfig);

/*!
@ingroup WLANAP
@fn \
    int8_t m2m_wifi_disable_ap(void);

@brief
    Synchronous API to disable access point mode on the WINC.

@details
    Must be called only when the AP is enabled through the @ref m2m_wifi_enable_ap
    function. Otherwise the call to this function will not be useful.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_enable_ap
*/
int8_t m2m_wifi_disable_ap(void);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_set_static_ip(tstrM2MIPConfig * pstrStaticIPConf);

@brief
    Asynchronous API to manually assign a (static) IP address to the WINC.

@details
    Assigns a static IP address to the WINC.
    Typically an infrastructure access point will be able to provide an IP address to all clients
    after they associate. The WINC will request configuration via DHCP automatically after
    successfully connecting to an access point.
    This function should only be called in the event that the network has no DHCP server or in case the application
    wants to assign a predefined known IP address and the application.
    This function can be used to assign a static IP address in case the application knows the specifics of the network.
    The user must keep in mind that assigning a static IP address might
    result in an IP address conflict. In case of an IP address conflict observed
    by the WINC the user will get a response of @ref M2M_WIFI_RESP_IP_CONFLICT
    in the wifi callback. The application is then responsible to either solve the
    conflict or assign another IP address.

@pre
    The application must first call @ref m2m_wifi_enable_dhcp to request that DHCP functionality is
    disabled prior to calling this function.

@warning
    Exercise caution using this function.
    DHCP is the preferred method for configuring IP addresses.

@param[in]  pstrStaticIPConf
    Pointer to a structure holding the static IP configuration (IP, Gateway, subnet mask and DNS address).

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tstrM2MIPConfig
*/
int8_t m2m_wifi_set_static_ip(tstrM2MIPConfig *pstrStaticIPConf);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_request_dhcp_client(void);

@brief
    Legacy (deprecated) Asynchronous API for starting a DHCP client on the WINC.

@details
    This is a legacy API and is no longer supported. Calls to this API will not result in any
    changes being made to the state of the WINC.

@warning
    This function has been deprecated. DHCP is used automatically when the WINC connects.

@return
    This function always returns @ref M2M_SUCCESS.
*/
int8_t m2m_wifi_request_dhcp_client(void);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_request_dhcp_server(uint8_t* addr);

@brief
    Legacy (deprecated) asynchronous function to start a DHCP client on the WINC.

@details
    This is a legacy API and is no longer supported. Calls to this API will not result in any
    changes being made to the state of the WINC.

@param[in]  addr
    The address to issue to a connected client (only one client is supported)

@warning
    This function is legacy and exists only for compatibility with older applications.
    DHCP server is started automatically when enabling the AP mode.

@return
    This function always returns @ref M2M_SUCCESS.
*/
int8_t m2m_wifi_request_dhcp_server(uint8_t *addr);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_enable_dhcp(uint8_t u8DhcpEn);

@brief
    Asynchronous function to control the DHCP client functionality within the WINC.

@details
    This function allows the application to control the behaviour of the DHCP client function within
    the WINC once it has associated with an access point. DHCP client functionality is enabled by
    default.

@param[in]  u8DhcpEn
    The state of the DHCP client feature after successful association with an access point:
    - 1: Enables DHCP client after connection.
    - 0: Disables DHCP client after connection.

@return
    The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise.

@warning
    DHCP client is enabled by default.
    This Function should be called to disable DHCP client operation before using @ref m2m_wifi_set_static_ip.

@see
    m2m_wifi_set_static_ip
*/
int8_t m2m_wifi_enable_dhcp(uint8_t u8DhcpEn);

/*!
@ingroup WLANSCAN
@fn \
    int8_t m2m_wifi_set_scan_options(tstrM2MScanOption* ptstrM2MScanOption);

@brief
    Synchronous API for configuring the behaviour of the WINC network scanning functions.

@details
    This function allows the application to tune the scanning behaviour of the WINC using the
    parameters described in @ref tstrM2MScanOption.

@param[in]  ptstrM2MScanOption;
    Pointer to the structure holding the Scan Parameters.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tenuM2mScanCh
    m2m_wifi_request_scan
    tstrM2MScanOption
*/
int8_t m2m_wifi_set_scan_options(tstrM2MScanOption *ptstrM2MScanOption);

/*!
@ingroup WLANSCAN
@fn \
    int8_t m2m_wifi_set_stop_scan_on_first(uint8_t u8StopScanOption);

@brief
    Synchronous API for enabling/disabling the stop scan on first result of the WINC IC's network scanning functions.

@details
    Allows for enabling/disabling of stop scan on first result. When enabled, the WINC will stop the scan as soon as
    it detects a network and return the results to the host. Setting is persistent and will need to be explicitly
    reverted back by the application if it no longer wishes for it to be enabled.

@param[in]  u8StopScanOption;
    Setting for enabling or disabling Stopping Scan on first result.
    1 = Enabled, 0 = Disabled (Default)

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tenuM2mScanCh
    tstrM2MScanOption
    tstrM2MStopScanOption
    m2m_wifi_request_scan
    m2m_wifi_set_scan_options
*/
int8_t m2m_wifi_set_stop_scan_on_first(uint8_t u8StopScanOption);

/*!
@ingroup WLANSCAN
@fn \
    int8_t m2m_wifi_set_scan_region(uint16_t ScanRegion);

@brief
    Synchronous API for configuring the regulatory restrictions that may affect the WINC scanning behaviour.

@details
    This function sets a property called the scan region, a parameter that affects the range of
    channels that the WINC may legally scan given a geographic region.

    For 2.4GHz, supported in the current release, the requested scan region cannot exceed the
    maximum number of channels (14).

@param[in]  ScanRegion
    @ref ASIA
    @ref EUROPE
    @ref NORTH_AMERICA

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tenuM2mScanRegion
    m2m_wifi_request_scan
*/
int8_t m2m_wifi_set_scan_region(uint16_t  ScanRegion);

/*!
@ingroup WLANSCAN
@fn \
    int8_t m2m_wifi_request_scan(uint8_t ch);

@brief
    Asynchronous API to request the WINC to scan for networks.

@details
    Scan statuses are delivered to the application via the Wi-Fi event callback (@ref tpfAppWifiCb) in
    three stages. The first step involves the event @ref M2M_WIFI_RESP_SCAN_DONE which, if successful,
    provides the number of detected networks (access points). The application must then read the list
    of access points via multiple calls to the asynchronous @ref m2m_wifi_req_scan_result API. For
    each call to this function, the application will receive (step three) the event
    @ref M2M_WIFI_RESP_SCAN_RESULT.

@param[in]  ch
    RF Channel ID for SCAN operation. It should be set according to @ref tenuM2mScanCh, with a
    value of @ref M2M_WIFI_CH_ALL to scan all channels.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value      otherwise.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at
      initialization. Registration of the callback is done via @ref m2m_wifi_init.
    - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT must be handled in
      the (@ref tpfAppWifiCb) callback.
    - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the
      callback.

@warning
    This API is valid only for STA mode, it may be called regardless of connection state (connected or disconnected states).

@see
    M2M_WIFI_RESP_SCAN_DONE
    M2M_WIFI_RESP_SCAN_RESULT
    tpfAppWifiCb
    tstrM2mWifiscanResult
    tenuM2mScanCh
    m2m_wifi_init
    m2m_wifi_handle_events
    m2m_wifi_req_scan_result

@section WIFIExample6 Example
  The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of
  the events received in response.
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    static uint8_t u8ScanResultIdx = 0;

    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;

            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;

    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult *pstrScanResult = (tstrM2mWifiscanResult*)pvMsg;
            uint8_t                 u8NumFoundAPs   = m2m_wifi_get_num_ap_found();

            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);

            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam param;
    param.pfAppWifiCb = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_request_scan(uint8_t ch);

/*!
@ingroup WLANSCAN
@fn \
    int8_t m2m_wifi_request_scan_passive(uint8_t ch);

@brief
    Similar to @ref m2m_wifi_request_scan but performs passive scanning instead of active scanning.

@param[in]  ch
    RF Channel ID for SCAN operation. It should be set according to @ref tenuM2mScanCh.
    With a value of @ref M2M_WIFI_CH_ALL, means to scan all channels.


@warning
    This function is not allowed in P2P or AP modes. It works only for STA mode (both connected or disconnected states).

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
      is done through passing it to the @ref m2m_wifi_init.
    - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT.
      must be handled in the callback.
    - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the callback.

@see
    M2M_WIFI_RESP_SCAN_DONE
    M2M_WIFI_RESP_SCAN_RESULT
    tpfAppWifiCb
    tstrM2MScanOption
    tstrM2mWifiscanResult
    tenuM2mScanCh
    m2m_wifi_init
    m2m_wifi_request_scan
    m2m_wifi_handle_events
    m2m_wifi_req_scan_result

@return
    The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
*/
int8_t m2m_wifi_request_scan_passive(uint8_t ch);

/*!
@ingroup WLANSCAN
@fn \
    int8_t m2m_wifi_request_scan_ssid_list(uint8_t ch, uint8_t *u8SsidList);

@brief
    Asynchronous wi-fi scan request on the given channel and the hidden scan list.

@details
    The scan status is delivered in the wi-fi event callback and then the application
    is to read the scan results sequentially.
    The number of  APs found (N) is returned in event @ref M2M_WIFI_RESP_SCAN_DONE with the number of found
    APs.
    The application could read the list of APs by calling the function @ref m2m_wifi_req_scan_result N times.

@param[in]  ch
    RF Channel ID for SCAN operation. It should be set according to @ref tenuM2mScanCh.
    With a value of @ref M2M_WIFI_CH_ALL, means to scan all channels.

@param[in]  u8SsidList
    u8SsidList is a buffer containing a list of hidden SSIDs to
    include during the scan. The first byte in the buffer, u8SsidList[0],
    is the number of SSIDs encoded in the string. The number of hidden SSIDs
    cannot exceed @ref MAX_HIDDEN_SITES. All SSIDs are concatenated in the following
    bytes and each SSID is prefixed with a one-byte header containing its length.
    The total number of bytes in u8SsidList buffer, including length byte, cannot
    exceed 133 bytes (MAX_HIDDEN_SITES SSIDs x 32 bytes each, which is max SSID length).
    For instance, encoding the two hidden SSIDs "DEMO_AP" and "TEST"
    results in the following buffer content:

@code
    uint8_t u8SsidList[14];
    u8SsidList[0] = 2; // Number of SSIDs is 2
    u8SsidList[1] = 7; // Length of the string "DEMO_AP" without NULL termination
    memcpy(&u8SsidList[2], "DEMO_AP", 7);  // Bytes index 2-9 containing the string DEMO_AP
    u8SsidList[9] = 4; // Length of the string "TEST" without NULL termination
    memcpy(&u8SsidList[10], "TEST", 4);  // Bytes index 10-13 containing the string TEST
@endcode

@note
    It works with STA/AP mode (connected or disconnected).

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
      is done through passing it to the @ref m2m_wifi_init.
    - The events @ref M2M_WIFI_RESP_SCAN_DONE and @ref M2M_WIFI_RESP_SCAN_RESULT.
      must be handled in the callback.
    - The @ref m2m_wifi_handle_events function MUST be called to receive the responses in the callback.

@see
    M2M_WIFI_RESP_SCAN_DONE
    M2M_WIFI_RESP_SCAN_RESULT
    tpfAppWifiCb
    tstrM2mWifiscanResult
    tenuM2mScanCh
    m2m_wifi_init
    m2m_wifi_handle_events
    m2m_wifi_req_scan_result

@return
    The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.

\section WIFIExample6b Example
  The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of
  the events received in response.
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

static void request_scan_hidden_demo_ap(void);

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    static uint8_t    u8ScanResultIdx = 0;

    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;

            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    request_scan_hidden_demo_ap();
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;
    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8_t                     u8NumFoundAPs = m2m_wifi_get_num_ap_found();

            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);

            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

static void request_scan_hidden_demo_ap(void)
{
    uint8_t list[9];
    char ssid[] = "DEMO_AP";
    uint8 len = (uint8_t)(sizeof(ssid)-1);

    list[0] = 1;
    list[1] = len;
    memcpy(&list[2], ssid, len); // copy 7 bytes
    // Scan all channels
    m2m_wifi_request_scan_ssid_list(M2M_WIFI_CH_ALL, list);
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        request_scan_hidden_demo_ap();
        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_request_scan_ssid_list(uint8_t ch, uint8_t *u8Ssidlist);

/*!
@ingroup WLANSCAN
@fn \
    uint8_t m2m_wifi_get_num_ap_found(void);

@brief
    Synchronous function to retrieve the number of AP's found during the last scan operation.

@details
    This function allows the application to recover the number of access points discovered during
    the most recent scan activity. This is achieved via a global variable in the WINC driver that
    is populated when receiving the @ref M2M_WIFI_RESP_SCAN_DONE event.
    Function to be used in STA mode only.

@see
    m2m_wifi_request_scan
    M2M_WIFI_RESP_SCAN_DONE
    M2M_WIFI_RESP_SCAN_RESULT

@pre
    m2m_wifi_request_scan must be called first to ensure up to date results are available.
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered at initialization. Registering the callback
       is done through passing it to the @ref m2m_wifi_init.
    - The event @ref M2M_WIFI_RESP_SCAN_DONE must be handled in the callback to receive the requested scan information.

@warning
    This function must be called only in the wi-fi callback function when the events
    @ref M2M_WIFI_RESP_SCAN_DONE or @ref M2M_WIFI_RESP_SCAN_RESULT are received.
    Calling this function in any other place will result in undefined/outdated numbers.

@return
    Returns the number of AP's found in the last Scan Request.

@section WIFIExample7 Example
  The code snippet demonstrates an example of how the scan request is called from the application's main function and the handling of
  the events received in response.
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    static uint8_t u8ScanResultIdx = 0;

    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;

            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;
    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8_t                 u8NumFoundAPs = m2m_wifi_get_num_ap_found();

            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);

            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
uint8_t m2m_wifi_get_num_ap_found(void);

/*!
@ingroup WLANSCAN
@fn \
    int8_t m2m_wifi_req_scan_result(uint8_t index);

@brief
    Asynchronous API to request the information of an access point discovered via scanning.

@details
    This function allows the information of any discovered access point to be retrieved. When a
    scan is completed, the application is informed of the number of networks (access points)
    discovered. Calling this function with an index, N, will return the information for the Nth
    access point. The information will be returned to the application via a
    @ref M2M_WIFI_RESP_SCAN_RESULT event, and the response data may be obtained through casting
    the pointer (pvMsg) to @ref tstrM2mWifiscanResult.

@param[in]  index
    Index for the requested result, the index range start from 0 till number of AP's found.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tstrM2mWifiscanResult
    m2m_wifi_get_num_ap_found
    m2m_wifi_request_scan

@pre
    - @ref m2m_wifi_request_scan must be called first to ensure up to date results are available.
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered
    in order to receive scan data after calling this function. Registration of the callback
    is done via the @ref m2m_wifi_init function.
    - The event @ref M2M_WIFI_RESP_SCAN_RESULT must be handled in the callback to receive the
    requested scan information.

@warning
    - This API is valid only for STA mode, it may be called regardless of the connection state (connected or disconnected).
    - Calling this function without first issuing a scan request may lead to stale data being recovered.
    - Application code should refrain from introducing significant delays between issuing the scan
    request and scan result requests.

@section WIFIExample8 Example
    The code snippet demonstrates an example of how the scan request is called from the application's main function and
    the handling of the events received in the response.
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    static uint8_t    u8ScanResultIdx = 0;

    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_SCAN_DONE:
        {
            tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*)pvMsg;

            printf("Num of AP found %d\n",pstrInfo->u8NumofCh);
            if(pstrInfo->s8ScanState == M2M_SUCCESS)
            {
                u8ScanResultIdx = 0;
                if(pstrInfo->u8NumofCh >= 1)
                {
                    m2m_wifi_req_scan_result(u8ScanResultIdx);
                    u8ScanResultIdx ++;
                }
                else
                {
                    printf("No AP Found Rescan\n");
                    m2m_wifi_request_scan(M2M_WIFI_CH_ALL);
                }
            }
            else
            {
                printf("(ERR) Scan fail with error <%d>\n",pstrInfo->s8ScanState);
            }
        }
        break;

    case M2M_WIFI_RESP_SCAN_RESULT:
        {
            tstrM2mWifiscanResult       *pstrScanResult =(tstrM2mWifiscanResult*)pvMsg;
            uint8_t                       u8NumFoundAPs = m2m_wifi_get_num_ap_found();

            printf(">>%02d RI %d SEC %s CH %02d BSSID %02X:%02X:%02X:%02X:%02X:%02X SSID %s\n",
                pstrScanResult->u8index,pstrScanResult->s8rssi,
                pstrScanResult->u8AuthType,
                pstrScanResult->u8ch,
                pstrScanResult->au8BSSID[0], pstrScanResult->au8BSSID[1], pstrScanResult->au8BSSID[2],
                pstrScanResult->au8BSSID[3], pstrScanResult->au8BSSID[4], pstrScanResult->au8BSSID[5],
                pstrScanResult->au8SSID);

            if(u8ScanResultIdx < u8NumFoundAPs)
            {
                // Read the next scan result
                m2m_wifi_req_scan_result(index);
                u8ScanResultIdx ++;
            }
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_request_scan(M2M_WIFI_CH_ALL);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_req_scan_result(uint8_t index);

/*!
@ingroup WLANCONNECT
@fn \
    int8_t m2m_wifi_req_curr_rssi(void);

@brief
    Asynchronous API to request the current Receive Signal Strength (RSSI) of the current connection.

@details
    This function will result in the application receiving the RSSI via a
    @ref M2M_WIFI_RESP_CURRENT_RSSI event.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered
      during initialization. Registration of the callback is done through passing it to @ref m2m_wifi_init
      via the @ref tstrWifiInitParam initialization structure.
    - The event @ref M2M_WIFI_RESP_CURRENT_RSSI must be handled in the callback to receive the requested Rssi information.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@section WIFIExample9 Example
  The code snippet demonstrates how the RSSI request is called in the application's main function and the handling of the event received in the callback.
@code
#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    static uint8_t    u8ScanResultIdx = 0;

    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_CURRENT_RSSI:
        {
            int8_t   *rssi = (int8_t*)pvMsg;
            M2M_INFO("ch rssi %d\n",*rssi);
        }
        break;
    default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        // Scan all channels
        m2m_wifi_req_curr_rssi();

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}
@endcode
*/
int8_t m2m_wifi_req_curr_rssi(void);

/*!
@ingroup WLANCONF
@fn \
    int8_t m2m_wifi_get_otp_mac_address(uint8_t *pu8MacAddr, uint8_t * pu8IsValid);

@brief
    Synchronous API to query the MAC address programmed into the WINC OTP memory.

@details
    This function attempts to read the device's MAC address from the One Time Programmable (OTP)
    memory on the WINC. The presence (yes or no) of a MAC address in the OTP memory and, in the case
    of it being present, its value is returned via RAM pointed to by the input arguments.

    Request the MAC address stored on the One Time Programmable(OTP) memory of the device.
    The function is blocking until the response is received.

@pre
    Prior call to @ref m2m_wifi_init is required before any WIFI/socket function.

@param[out] pu8MacAddr
    Output MAC address buffer 6 bytes in size. Valid only if *pu8Valid=1.

@param[out] pu8IsValid
    A boolean value set by the callee to indicate the validity of pu8MacAddr in OTP. If no MAC has
    been programmed in the OTP the value of this parameter will be zero; otherwise it will be non-zero.

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.

@see
    m2m_wifi_get_mac_address
*/
int8_t m2m_wifi_get_otp_mac_address(uint8_t *pu8MacAddr, uint8_t *pu8IsValid);

/*!
@ingroup WLANCONF
@fn \
    int8_t m2m_wifi_get_mac_address(uint8_t *pu8MacAddr)

@brief
    Synchronous API to retrieve the MAC address currently in use by the device.

@details
    This function obtains the MAC address that is currently in use by the device. If the function
    returns with @ref M2M_SUCCESS then the content of the memory referenced by pu8MacAddr will be
    populated with the 6 byte MAC address; otherwise, that memory will be left unchanged.

@pre
    Prior call to @ref m2m_wifi_init is required before any WIFI/socket function.

@param[out] pu8MacAddr
    Pointer to a buffer in memory containing a 6-byte MAC address (provided function returns @ref M2M_SUCCESS).

@return
    The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise.

@see
    m2m_wifi_get_otp_mac_address
*/
int8_t m2m_wifi_get_mac_address(uint8_t *pu8MacAddr);

/*!
@ingroup WLANPS
@fn \
    int8_t m2m_wifi_set_sleep_mode(uint8_t PsTyp, uint8_t BcastEn);

@brief
    Synchronous API to set the power-save mode of the WINC.

@details
    This is one of the two synchronous power-save setting functions that allow the host MCU application
    to tweak the system power consumption. Such tweaking can be done through one of two ways:
    - 1) Changing the power save mode, to one of the allowed power save modes (see @ref tenuPowerSaveModes). This is done by setting the first parameter.
    - 2) Configuring DTIM monitoring: Configuring beacon monitoring parameters by enabling or disabling the reception of broadcast/multicast data.
         This is done by setting the second parameter.

@param[in]  PsTyp
    Desired power saving mode. Supported types are enumerated in @ref tenuPowerSaveModes.

@param[in]  BcastEn
    Broadcast reception enable flag.
    If set to 1, the WINC will wake for each DTIM beacon to ensure broadcast traffic can be received.
    If set to 0, the WINC will not wakeup at the DTIM beacon, ignoring broadcast traffic, instead it will
    wake every N beacon periods, as per the negotiated Listen Interval.

@warning
    The function called once after initialization.

@return
    The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise.

@see
    tenuPowerSaveModes
    m2m_wifi_get_sleep_mode
    m2m_wifi_set_lsn_int
*/
int8_t m2m_wifi_set_sleep_mode(uint8_t PsTyp, uint8_t BcastEn);

/*!
@ingroup WLANPS
@fn \
    int8_t m2m_wifi_request_sleep(uint32_t u32SlpReqTime);

@brief
    Asynchronous API to place the WINC into sleep mode for a specified period of time.

@details
    Power-save sleep request function, which requests the WINC device to sleep in the currently configured
    power save mode, as set using @ref m2m_wifi_set_sleep_mode, for a specific time as defined by the parameter
    u32SlpReqTime (measured in milliseconds).
    This function should be used when the WINC is running in @ref M2M_PS_MANUAL power save mode only.
    A wake up request is automatically performed by the WINC device when any host driver API function, e.g. Wi-Fi or socket operation is called.

@param[in]  u32SlpReqTime
    Request sleep time in ms.\n
    The best recommended sleep duration is left to be determined by the application.
    Taking into account that if the application sends notifications very rarely,
    sleeping for a long time can be a power-efficient decision.
    In contrast, applications that are sensitive for long periods of absence can experience
    performance degradation in the connection if long sleeping times are used.

@return
    The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise.

@warning
    - This API is currently unsupported on the WINC3400

@see
    tenuPowerSaveModes
    m2m_wifi_set_sleep_mode
*/
int8_t m2m_wifi_request_sleep(uint32_t u32SlpReqTime);

/*!
@ingroup WLANPS
@fn \
    uint8_t m2m_wifi_get_sleep_mode(void);

@brief
    Synchronous API to retrieve the current power save mode of the WINC.

@return
    The current operating power saving mode. The value will be one of those from the enumerated type @ref tenuPowerSaveModes.

@see
    tenuPowerSaveModes
    m2m_wifi_set_sleep_mode
*/
uint8_t m2m_wifi_get_sleep_mode(void);

/*!
@ingroup WLANCONF
@fn \
    int8_t m2m_wifi_set_device_name(uint8_t *pu8DeviceName, uint8_t u8DeviceNameLength);

@brief
    Asynchronous API to set the Wi-Fi Direct "Device Name" of the WINC.

@details
    Sets the WINC device name. The name string is used as a device name in DHCP
    hostname (option 12).
    If a device is not set through this function a default name is assigned.
    The default name is WINC-XX-YY, where XX and YY are the last 2 octets of the OTP
    MAC address. If OTP (eFuse) is programmed, then the default name is WINC-00-00.

@warning
    The function called once after initialization.\n
    Used for DHCP client hostname option (12).\n
    Device name shall contain only characters allowed in valid internet host name as
    defined in RFC 952 and 1123.

@param[in]  pu8DeviceName
    Buffer holding the device name. Device name is a null terminated C string.

@param[in]  u8DeviceNameLength
    Length of the device name. Should not exceed the maximum device name's
    length @ref M2M_DEVICE_NAME_MAX (including null character).

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
*/
int8_t m2m_wifi_set_device_name(uint8_t *pu8DeviceName, uint8_t u8DeviceNameLength);

/*!
@ingroup WLANTIME
@fn \
    int8_t m2m_wifi_configure_sntp(uint8_t *pu8NTPServerName, uint8_t u8NTPServerNameLength, tenuSNTPUseDHCP useDHCP);

@brief
    Configures what NTP server the SNTP client should use.

@details
    Configures what NTP server the SNTP client should use. Only 1 server name can be provided, if the configured server name begins with an asterisk then it will be treated as a server pool.
    The SNTP client can also use the NTP server provided by the DHCP server through option 42.
    By default the NTP server provided by DHCP will be tried first, then the built-in default NTP server (time.nist.gov) will be used.

@param[in]  pu8NTPServerName
    Buffer holding the NTP server name. If the first character is an asterisk (*) then it will be treated as a server pool, where the asterisk will
    be replaced with an incrementing value from 0 to 3 each time a server fails (example: *.pool.ntp.org).

@param[in]  u8NTPServerNameLength
    Length of the NTP server name. Should not exceed the maximum NTP server name length of @ref M2M_NTP_MAX_SERVER_NAME_LENGTH.

@param[in]  useDHCP
    Explicity tell the WINC if it should use the NTP server provided by the DHCP server or not.

@warning
    SNTP should be configured before the connection takes place. If SNTP is configured after the device connects to a
    network, the new configuration can take a minimum of 24h to be applied. However, it can take even longer since it is
    triggered by DHCP renewal.
    Currently there is also a known issue in which if the WINC obtains the NTP server from DHCP and then connects to a
    different network, it will still use the NTP from the previous network.
    Configuring a server name will overwrite the built-in default server until next reboot.

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.
*/
int8_t m2m_wifi_configure_sntp(uint8_t *pu8NTPServerName, uint8_t u8NTPServerNameLength, tenuSNTPUseDHCP useDHCP);

/*!
@ingroup WLANPS
@fn \
    int8_t m2m_wifi_set_lsn_int(tstrM2mLsnInt * pstrM2mLsnInt);

@brief
    Asynchronous API to set Wi-Fi listen interval for power save operation.

@details
    This is one of the two synchronous power-save setting functions that
    allow the host MCU application to tweak the system power consumption. Such tweaking can be done by modifying the
    Wi-Fi listen interval. The listen interval is how many beacon periods the station can sleep before it wakes up to receive data buffered in the AP.
    It is represented in units of AP beacon periods(100ms).

@warning
    The function should be called once after initialization.

@param[in]  pstrM2mLsnInt
    Structure holding the listen interval configuration.

@pre
    The function @ref m2m_wifi_set_sleep_mode shall be called first, to set the power saving mode required.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tstrM2mLsnInt
    m2m_wifi_set_sleep_mode
*/
int8_t m2m_wifi_set_lsn_int(tstrM2mLsnInt *pstrM2mLsnInt);

/**@cond MON_DOC
 */
/*!
@ingroup WLANMON
@fn \
    int8_t m2m_wifi_enable_monitoring_mode(tstrM2MWifiMonitorModeCtrl *, uint8_t *, uint16_t , uint16_t);

@brief
    Asynchronous call to enable Wi-Fi monitoring (promiscuous receive) mode.

@details
    Wi-Fi monitoring mode (Promiscuous mode) enabling function.
    This function enables the monitoring mode, thus allowing two operations to be
    performed:
    1) Transmission of manually configured frames, through using the
        @ref m2m_wifi_send_wlan_pkt function.
    2) Reception of frames based on a defined filtering criteria.

    Enabling monitoring mode allows for reception of all frames that satisfy the filter criteria in the input parameter     and are received on the current wireless channel.
    All packets that meet the filtering criteria are passed to the application layer, to
    be handled by the assigned monitoring callback function.
    The monitoring callback function must be implemented before starting the monitoring mode,
    in-order to handle the packets received.

    A dedicated callback function, @ref tpfAppMonCb, must be registered to handle frames received in
    promiscuous mode. This is done via an instance of a @ref tstrWifiInitParam structure and a call to
    the @ref m2m_wifi_init function.

@param[in]  pstrMtrCtrl
    Pointer to @ref tstrM2MWifiMonitorModeCtrl structure holding the filtering parameters.

@param[in]  pu8PayloadBuffer
    Pointer to a Buffer allocated by the application. The buffer SHALL hold the Data field of
    the WIFI RX Packet (Or a part from it). If it is set to NULL, the WIFI data payload will
    be discarded by the monitoring driver.

@param[in]  u16BufferSize
    The total size of the pu8PayloadBuffer in bytes.

@param[in]  u16DataOffset
    Starting offset in the DATA FIELD of the received WIFI packet. The application may be interested
    in reading specific information from the received packet. It must assign the offset to the starting
    position of it relative to the DATA payload start.\n
    \e Example, \e if \e the \e SSID \e is \e needed \e to \e be \e read \e from \e a \e PROBE \e REQ
    \e packet, \e the \e u16Offset \e MUST \e be \e set \e to \e 0.

@warning
    This mode is available as sniffer ONLY, the WINC cannot be connected in any modes (Station, Access Point or P2P).

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    tstrM2MWifiMonitorModeCtrl
    tstrM2MWifiRxPacketInfo
    tstrWifiInitParam
    tenuM2mScanCh
    m2m_wifi_disable_monitoring_mode
    m2m_wifi_send_wlan_pkt
    m2m_wifi_send_ethernet_pkt

@section WIFIExample10 Example
    The example demonstrates the main function where-by the monitoring enable function is called after
    the initialization of the driver and the packets are handled in the callback function.

@code
#include "m2m_wifi.h"
#include "m2m_types.h"

//Declare receive buffer
uint8_t gmgmt[1600];

//Callback functions
void wifi_cb(uint8_t u8WiFiEvent, void * pvMsg)
{
    ;
}

void wifi_monitoring_cb(tstrM2MWifiRxPacketInfo *pstrWifiRxPacket, uint8_t *pu8Payload, uint16_t u16PayloadSize)
{
    if((NULL != pstrWifiRxPacket) && (0 != u16PayloadSize)) {
        if(MANAGEMENT == pstrWifiRxPacket->u8FrameType) {
            M2M_INFO("***# MGMT PACKET #***\n");
        } else if(DATA_BASICTYPE == pstrWifiRxPacket->u8FrameType) {
            M2M_INFO("***# DATA PACKET #***\n");
        } else if(CONTROL == pstrWifiRxPacket->u8FrameType) {
            M2M_INFO("***# CONTROL PACKET #***\n");
        }
    }
}

int main()
{
    //Register wifi_monitoring_cb
    tstrWifiInitParam param;
    param.pfAppWifiCb = wifi_cb;
    param.pfAppMonCb  = wifi_monitoring_cb;

    nm_bsp_init();

    if(!m2m_wifi_init(&param)) {
        //Enable Monitor Mode with filter to receive all data frames on channel 1
        tstrM2MWifiMonitorModeCtrl  strMonitorCtrl = {0};
        strMonitorCtrl.u8ChannelID      = M2M_WIFI_CH_1;
        strMonitorCtrl.u8FrameType      = DATA_BASICTYPE;
        strMonitorCtrl.u8FrameSubtype   = M2M_WIFI_FRAME_SUB_TYPE_ANY; //Receive any subtype of data frame
        m2m_wifi_enable_monitoring_mode(&strMonitorCtrl, gmgmt, sizeof(gmgmt), 0);

        while(1) {
            m2m_wifi_handle_events(NULL);
        }
    }
    return 0;
}
@endcode
*/
int8_t m2m_wifi_enable_monitoring_mode(tstrM2MWifiMonitorModeCtrl *pstrMtrCtrl, uint8_t *pu8PayloadBuffer,
        uint16_t u16BufferSize, uint16_t u16DataOffset);

/*!
@ingroup WLANMON
@fn \
    int8_t m2m_wifi_disable_monitoring_mode(void);

@brief
    Asynchronous API to disable Wi-Fi monitoring (promiscuous receive) mode.

@details
    Disable Wi-Fi monitoring mode (Promiscuous mode). Expected to be called if the monitoring mode is already enabled,
    but if it was called without enabling it, no negative impact will reside.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_enable_monitoring_mode
 */
int8_t m2m_wifi_disable_monitoring_mode(void);

/*!
@ingroup WLANMON
@fn \
    int8_t m2m_wifi_send_wlan_pkt(uint8_t *, uint16_t, uint16_t);

@brief
    Asynchronous API to queue a raw Wi-Fi packet for transmission by the WINC.

@pre
    Enable Monitoring mode first using @ref m2m_wifi_enable_monitoring_mode

@note
    The application is responsible for the packets.

@warning
    This function is only useful when operating in monitoring mode.

@param[in]  pu8WlanPacket
    Pointer to a buffer holding the whole WIFI frame.

@param[in]  u16WlanHeaderLength
    The size of the WIFI packet header ONLY.

@param[in]  u16WlanPktSize
    The size of the whole packet in bytes.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_enable_monitoring_mode
    m2m_wifi_disable_monitoring_mode
*/
int8_t m2m_wifi_send_wlan_pkt(uint8_t *pu8WlanPacket, uint16_t u16WlanHeaderLength, uint16_t u16WlanPktSize);
/**@endcond*/ //MON_DOC

/*!
@ingroup WLANETH
@fn \
    int8_t m2m_wifi_send_ethernet_pkt(uint8_t* pu8Packet,uint16_t u16PacketSize);

@brief
    Asynchronous API to queue an Ethernet packet for transmission by the WINC.

@details
    Transmit a packet directly in ETHERNET/bypass mode where the TCP/IP stack is disabled
    and the implementation of this packet is left to the application developer.
    The Ethernet packet composition is left to the application developer.

@note
    Packets are the user's responsibility.

@warning
    This function available in ETHERNET/Bypass mode ONLY. Make sure that application defines ETH_MODE.

@param[in]  pu8Packet
    Pointer to a buffer holding the whole Ethernet frame.

@param[in]  u16PacketSize
    The size of the whole packet in bytes.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_enable_mac_mcast
    m2m_wifi_set_receive_buffer
*/
int8_t m2m_wifi_send_ethernet_pkt(uint8_t *pu8Packet, uint16_t u16PacketSize);

/*!
@ingroup WLANTIME
@fn \
    int8_t m2m_wifi_enable_sntp(uint8_t);

@brief
    Asynchronous API to enable or disable the native Simple Network Time Protocol(SNTP) client running on the WINC.

@details
    The SNTP client is enabled by default during chip initialization. This function can be used to
    disable or subsequently re-enable the service.

    The service is capable of synchronizing the WINC system clock to the UTC time from a well-known
    (and trusted) time server, for example "time.nist.gov". By default the SNTP client will update the
    system time once every 24 hours. The ability to track the time accurately is important for various
    applications such as checking expiry of X509 certificates during TLS (Transport Layer Security)
    session establishment.

    It is highly recommended to leave SNTP enabled if there is no alternative source of timing
    information. For systems including an RTC device, SNTP may not be needed and the WINC's time
    may be set using the @ref m2m_wifi_set_system_time function.

@param[in]  bEnable
    Enables or disables the SNTP service
        '0' :disable SNTP
        '1' :enable SNTP

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_set_system_time
 */
int8_t m2m_wifi_enable_sntp(uint8_t bEnable);

/*!
@ingroup WLANTIME
@fn \
    int8_t m2m_wifi_set_system_time(uint32_t);

@brief
    Asynchronous function for setting the system time within the WINC.

@details
    Function for setting the system time in time/date format (@ref uint32_t).
    The @ref tstrSystemTime structure can be used as a reference to the time values that
    should be set and pass its value as @ref uint32_t.

@param[in]  u32UTCSeconds
    Seconds elapsed since January 1, 1900 (NTP Timestamp).

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_enable_sntp
    tstrSystemTime

@note
    If there is an RTC on the host MCU, the SNTP may be disabled and the host may set the system
    time within the firmware using the API @ref m2m_wifi_set_system_time.
 */
int8_t m2m_wifi_set_system_time(uint32_t u32UTCSeconds);

/*!
@ingroup WLANTIME
@fn \
    int8_t m2m_wifi_get_system_time(void);

@brief
    Asynchronous API to obtain the system time in use by the WINC.

@details
    This function will request the WINC to report its current system time to the application. The
    information will arrive at the application via the @ref tpfAppWifiCb and event @ref M2M_WIFI_RESP_GET_SYS_TIME.
    Response time retrieved is parsed into the members defined in the structure @ref tstrSystemTime.

@note
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered
    during initialization. Registration of the callback is done via the @ref m2m_wifi_init API.
    - The event @ref M2M_WIFI_RESP_GET_SYS_TIME must be handled in the callback.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_enable_sntp
    tstrSystemTime
 */
int8_t m2m_wifi_get_system_time(void);

/*!
@ingroup WLANCONF
@fn \
    int8_t m2m_wifi_set_cust_InfoElement(uint8_t*);

@brief
    Asynchronous API to add or remove a user-defined Information Element.

@details
    This function allows the application to provide a custom Information Element to the
    WINC that will be included in all beacon and probe response frames, while in Access Point mode.
    If it is required to delete these IEs, fill the buffer with zeros.

@param[in]  pau8M2mCustInfoElement
    Pointer to Buffer containing the IE to be used. It is the application developer's
    responsibility to ensure on the correctness of the information element's ordering
    passed in.
    If the pointer is null, this removes any current custom IE. If non-null, the pointer
    must reference data in the following format:

@verbatim
    --------------- ---------- ---------- ------------------- -------- -------- ----------- -----------------------
    | Byte[0]       | Byte[1]  | Byte[2]  | Byte[3:length1+2] | ..... | Byte[n] | Byte[n+1] | Byte[n+2:lengthx+2] |
    |---------------|----------|----------|-------------------|-------- --------|-----------|---------------------|
    | #of all Bytes | IE1 ID   | Length1  | Data1(Hex Coded)  | ..... | IEx ID  | Lengthx   | Datax(Hex Coded)    |
    --------------- ---------- ---------- ------------------- -------- -------- ----------- -----------------------
@endverbatim

@warning
    Size of All elements combined must not exceed 255 byte.
    Used in Access Point Mode.

@note
    IEs Format will follow the above format.

@return
     The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_enable_sntp

@section WIFIExample11 Example
   The example demonstrates how the information elements are set using this function.
@code
char elementData[21];
static char state = 0; // To Add, Append, and Delete
if(0 == state) {    //Add 3 IEs
    state = 1;
    //Total Number of Bytes
    elementData[0]=12;
    //First IE
    elementData[1]=200; elementData[2]=1; elementData[3]='A';
    //Second IE
    elementData[4]=201; elementData[5]=2; elementData[6]='B'; elementData[7]='C';
    //Third IE
    elementData[8]=202; elementData[9]=3; elementData[10]='D'; elementData[11]=0; elementData[12]='F';
} else if(1 == state) {
    //Append 2 IEs to others, Notice that we keep old data in array starting with\n
    //element 13 and total number of bytes increased to 20
    state = 2;
    //Total Number of Bytes
    elementData[0]=20;
    //Fourth IE
    elementData[13]=203; elementData[14]=1; elementData[15]='G';
    //Fifth IE
    elementData[16]=204; elementData[17]=3; elementData[18]='X'; elementData[19]=5; elementData[20]='Z';
} else if(2 == state) { //Delete All IEs
    state = 0;
    //Total Number of Bytes
    elementData[0]=0;
}
m2m_wifi_set_cust_InfoElement(elementData);
@endcode
 */
int8_t m2m_wifi_set_cust_InfoElement(uint8_t *pau8M2mCustInfoElement);

/*!
@ingroup WLANPS
@fn \
    int8_t m2m_wifi_set_power_profile(uint8_t u8PwrMode);

@brief
    Change the power profile mode.

@param[in]  u8PwrMode
    Change the WINC power profile to different mode based on the enumeration @ref tenuM2mPwrMode.\n
    Not implemented in WINC3400 firmware.

@warning
    May only be called after initialization, before any connection request, and may not be used to change
    the power mode thereafter.

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.

@see
    tenuM2mPwrMode
    m2m_wifi_init
*/
int8_t m2m_wifi_set_power_profile(uint8_t u8PwrMode);

/*!
@ingroup WLANCONF
@fn \
    int8_t m2m_wifi_set_tx_power(uint8_t u8TxPwrLevel);

@brief
    Set the TX power tenuM2mTxPwrLevel.

@param[in]  u8TxPwrLevel
    Change the TX power based on the enumeration @ref tenuM2mTxPwrLevel.

@pre
    Must be called after the initialization and before any connection request and can't be changed in runtime.

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.

@see
    tenuM2mTxPwrLevel
    m2m_wifi_init
*/
int8_t m2m_wifi_set_tx_power(uint8_t u8TxPwrLevel);

/*!
@ingroup WLANLOG
@fn \
    int8_t m2m_wifi_enable_firmware_logs(uint8_t u8Enable);

@brief
    Enable or Disable logs in run time.

@details
    Enable or Disable logs in run time (Disable Firmware logs will enhance the firmware start-up time and performance).

@param[in]  u8Enable
    Set 1 to enable the logs, 0 for disable.

@pre
    Must be called after initialization through the following function @ref m2m_wifi_init.

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.

@see
    __DISABLE_FIRMWARE_LOGS__ (build option to disable logs from initializations)
    m2m_wifi_init
*/
int8_t m2m_wifi_enable_firmware_logs(uint8_t u8Enable);

/*!
@ingroup WLANCONF
@fn \
    int8_t m2m_wifi_set_battery_voltage(uint16_t u16BattVoltx100);

@brief
    Set the battery voltage to update the firmware calculations.\n
    Not implemented in WINC3400 firmware.

@pre
    Must be called after initialization through the following function @ref m2m_wifi_init.

@param [in] u16BattVoltx100
    Battery voltage multiplied by 100

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.

@see
    m2m_wifi_init
*/
int8_t m2m_wifi_set_battery_voltage(uint16_t u16BattVoltx100);

/*!
@ingroup WLANETH
@fn \
    int8_t m2m_wifi_enable_mac_mcast(uint8_t *pu8MulticastMacAddress, uint8_t u8AddRemove);

@brief
    Asynchronous API to add or remove MAC addresses to the multicast filter.

@details
    This function will configure the WINC to receive/ignore multicast packets from certain
    MAC address groups when operating in bypass mode.
    This function requests the given MAC addresses to be added/removed from the multicast filter.

@param[in]  pu8MulticastMacAddress
    Pointer to MAC address

@param[in]  u8AddRemove
    A flag to add or remove the MAC ADDRESS, based on the following values:
      -  0 : remove MAC address
      -  1 : add MAC address

@note
    Maximum number of MAC addresses that could be added is 8.

@warning
    This function is available in ETHERNET/bypass mode ONLY.
    Make sure that the application defines ETH_MODE.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_set_receive_buffer
    m2m_wifi_send_ethernet_pkt
 */
int8_t m2m_wifi_enable_mac_mcast(uint8_t *pu8MulticastMacAddress, uint8_t u8AddRemove);

/*!
@ingroup WLANETH
@fn \
    int8_t m2m_wifi_set_receive_buffer(void *pvBuffer, uint16_t u16BufferLen);

@brief
    Synchronous function for setting or modifying the receiver buffer's length.

@details
    Synchronous function for setting or modifying the receiver buffer's length.
    In the ETHERNET/bypass mode the application should define a callback of type
    @ref tpfAppEthCb, through which the application handles the received
    ethernet frames. It is through this callback function that the user can
    dynamically modify the length of the currently used receiver buffer.

@param[in]  pvBuffer
    Pointer to Buffer to receive data.
    NULL pointer causes a negative error @ref M2M_ERR_FAIL.

@param[in]  u16BufferLen
    Length of data to be received.  Maximum length of data should not exceed the size defined by TCP/IP
    defined as @ref SOCKET_BUFFER_MAX_LENGTH

@warning
    This function is available in the Ethernet/bypass mode ONLY. Make sure that the application defines ETH_MODE.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

@see
    m2m_wifi_enable_mac_mcast
    m2m_wifi_send_ethernet_pkt
*/
int8_t m2m_wifi_set_receive_buffer(void *pvBuffer, uint16_t u16BufferLen);

/*!
@ingroup WLANCRYPTO
@fn \
    int8_t m2m_wifi_prng_get_random_bytes(uint8_t* pu8PrngBuff,uint16_t u16PrngSize);

@brief
    Asynchronous function for retrieving from the firmware a pseudo-random set of bytes.

@details
    Asynchronous function for retrieving from the firmware a pseudo-random set of bytes as specified in the size passed in as a parameter.
    The registered wifi-cb function retrieves the random bytes through the response @ref M2M_WIFI_RESP_GET_PRNG

@param[in]  pu8PrngBuff
    Pointer to a buffer to receive data.

@param[in]  u16PrngSize
    Request size in bytes

@warning
    Size greater than the maximum specified (@ref M2M_BUFFER_MAX_SIZE - sizeof(tstrPrng))
    causes a negative error @ref M2M_ERR_FAIL.

@return
    The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
*/
int8_t m2m_wifi_prng_get_random_bytes(uint8_t *pu8PrngBuff, uint16_t u16PrngSize);

/*!
@ingroup WLANROAMING
@fn \
    int8_t m2m_wifi_enable_roaming(uint8_t bEnableDhcp);

@brief
    Enable WiFi STA roaming.

@details
    m2m_wifi_enable_roaming enables the firmware to trigger the roaming algorithm/steps on link loss with the current AP.
    If roaming is successful, the @ref M2M_WIFI_RESP_CON_STATE_CHANGED message with state as @ref M2M_WIFI_ROAMED is sent to the host.
    Additionally a @ref M2M_WIFI_REQ_DHCP_CONF message with new DHCP lease details is sent to host (only if bEnableDhcp=1).
    If roaming is unsuccessful, a @ref M2M_WIFI_RESP_CON_STATE_CHANGED message with state as @ref M2M_WIFI_DISCONNECTED is sent to host.

@param[in]  bEnableDhcp
    0 : Disables DHCP client execution after roaming to new AP
    1 : Enables DHCP client execution after roaming to new AP

@pre
    Must be called after the initialization.
    The roaming algorithm/procedure is internal to the firmware.

@return
    The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.

@see
    m2m_wifi_init
*/
int8_t m2m_wifi_enable_roaming(uint8_t bEnableDhcp);

/*!
@ingroup WLANROAMING
@fn \
    int8_t m2m_wifi_disable_roaming(void);

@brief
    Disable WiFi STA roaming.

@pre
    Must be called after the initialization.

@return
    The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.

@see
    m2m_wifi_init
*/
int8_t m2m_wifi_disable_roaming(void);

/*!
@ingroup WLANINIT
@fn \
    uint8_t m2m_wifi_get_state(void);

@brief
    Get the wifi state.

@return
    The function returns the current wifi state (see @ref tenuWifiState for the possible states).

@note
    Check the WINC state. See @ref tenuWifiState for possible states.\n
    @ref WIFI_STATE_INIT state represents WINC initialized but not started, this is a suitable state
    for safe flash access.

@sa
    m2m_wifi_init
    m2m_wifi_download_mode
*/
uint8_t m2m_wifi_get_state(void);

/*!
@ingroup BLEAPI
@fn \
    int8_t m2m_wifi_ble_api_send(const uint8_t* const msg, const uint32_t len);

@brief
    Asynchronous API to send an encapsulated Atmel BLE message over the Wifi Host Interface.

@param[in]  msg
    Pointer to the start of the BLE message to transfer down to the WINC.

@param[in]  len
    The length of the message in octets.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC,
    and a negative value otherwise.
 */
int8_t m2m_wifi_ble_api_send(uint8_t *msg, uint32_t len);

/*!
@ingroup BLEAPI
@fn \
    int8_t m2m_wifi_ble_set_gain_table(uint8_t table_idx);

@brief
    Asynchronous API that notifies the WINC with the Gain Table index from Flash that should use to configure the WiFi and BLE gains.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC,
    and a negative value otherwise.
*/
int8_t m2m_wifi_ble_set_gain_table(uint8_t table_idx);

/*!
@ingroup BLEAPI
@fn \
    int8_t m2m_wifi_req_restrict_ble(void);

@brief
    Asynchronous API to request restricting of BLE functionality by placing the BLE processor in a low power state.
    It is recommended to do this if it is known that BLE functionality will not be used for any significant length of time.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC,
    and a negative value otherwise.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered
    during initialization. Registration of the callback is done via the @ref m2m_wifi_init API.
*/
int8_t m2m_wifi_req_restrict_ble(void);

/*!
@ingroup BLEAPI
@fn \
    int8_t m2m_wifi_req_unrestrict_ble(void);

@brief
    Asynchronous API to request un-restricting of BLE functionality by reverting the BLE processor to full power mode.

@return
    The function returns @ref M2M_SUCCESS if the command has been successfully queued to the WINC,
    and a negative value otherwise.

@pre
    - A Wi-Fi notification callback of type @ref tpfAppWifiCb MUST be implemented and registered
    during initialization. Registration of the callback is done via the @ref m2m_wifi_init API.
*/
int8_t m2m_wifi_req_unrestrict_ble(void);

/** @defgroup VERSION Version
    @brief
        Describes the APIs for reading the version information of the WINC firmware.
    @{
        @defgroup   VERSIONDEF  Defines
        @brief
            Specifies the macros and defines used by the version APIs.

        @defgroup   VERSIONAPI  Functions
        @brief
            Lists the APIs for reading the version information of the WINC firmware.
    @}
 */

/*!
@ingroup VERSIONAPI
@fn \
    int8_t m2m_wifi_get_firmware_version(tstrM2mRev* pstrRev);

@brief
    Synchronous API to obtain the firmware version currently running on the WINC.

@details
    Get the Firmware version info from the active partition, as defined in the structure @ref tstrM2mRev.

@param[out] pstrRev
    Pointer to a variable of type @ref tstrM2mRev, which contains the firmware version parameters.

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.

@pre
    Must be called after initialization through the following function @ref m2m_wifi_init.

@sa
    m2m_wifi_init
*/
int8_t m2m_wifi_get_firmware_version(tstrM2mRev *pstrRev);

/*!
@ingroup VERSIONAPI
@fn \
    int8_t m2m_ota_get_firmware_version(tstrM2mRev *pstrRev);

@brief
    Synchronous API to obtain the firmware version of the WINC image that is stored in the inactive flash partition.
    This is the image that would run on the WINC if @ref m2m_ota_switch_firmware or @ref m2m_ota_rollback were called,
    followed by a reset of the WINC.

@param[out] pstrRev
    Pointer to variable of type @ref tstrM2mRev which contains the ota fw version parameters.

@return
    The function returns @ref M2M_SUCCESS for success and a negative value otherwise.
*/
int8_t m2m_ota_get_firmware_version(tstrM2mRev *pstrRev);

/*!
@fn \
    uint32_t m2m_wifi_get_chipId(void)

@brief
    Synchronous API to obtain the firmware WINC chip ID.

@return
    The function returns chipID > 0 or 0 for failure.
*/
uint32_t m2m_wifi_get_chipId(void);

/*!
@ingroup OTAFUNCTIONS
@fn int8_t m2m_wifi_check_ota_rb(void);

@brief
    Synchronous API to check presence and compatibility of the WINC image that is stored in the inactive flash partition.
    This is the image that would run on the WINC if @ref m2m_ota_switch_firmware or @ref m2m_ota_rollback were called,
    followed by a reset of the WINC.

@return
    The function returns @ref M2M_SUCCESS for compatible image and a negative value otherwise.
*/
int8_t m2m_wifi_check_ota_rb(void);

#ifdef __cplusplus
}
#endif
#endif /* __M2M_WIFI_H__ */