m2m_wifi_request_scan

Asynchronous wi-fi scan request on the given channel.

Asynchronous wi-fi scan request on the given channel, and scan for hidden APs with the given ssid.

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 M2M_WIFI_RESP_SCAN_DONE with the number of found APs. The application could read the list of APs by calling the function m2m_wifi_req_scan_result N times.

Functions
NMI_API sint8	m2m_wifi_request_scan (uint8 ch)
	Asynchronous API to request the WINC IC to scan for networks. More...
NMI_API sint8	m2m_wifi_request_scan_ssid (uint8 ch, char *pcssid)

NMI_API sint8 m2m_wifi_request_scan

(

uint8

ch

)

Asynchronous API to request the WINC IC to scan for networks.

Asynchronous API to request the WINC to scan for networks.

Parameters

[in]

ch

RF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh. With a value of M2M_WIFI_CH_ALL(255)), means to scan all channels.

Precondition

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

See Also

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

Returns

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

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.

#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
    static uint8    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                       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);
        }
    }
}

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.

Parameters

[in]

ch

RF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh, with a value of M2M_WIFI_CH_ALL to scan all channels.

Returns

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

Precondition

• A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at initialization. Registration of the callback is done via m2m_wifi_init.
• The events M2M_WIFI_RESP_SCAN_DONE and M2M_WIFI_RESP_SCAN_RESULT must be handled in the (tpfAppWifiCb) callback.
• The 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 Also

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

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.

#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
    static uint8    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                       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);
        }
    }
}

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.

Parameters

[in]

ch

RF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh, with a value of M2M_WIFI_CH_ALL to scan all channels.

Returns

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

Precondition

• A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at initialization. Registration of the callback is done via m2m_wifi_init.
• The events M2M_WIFI_RESP_SCAN_DONE and M2M_WIFI_RESP_SCAN_RESULT must be handled in the (tpfAppWifiCb) callback.
• The 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 Also

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

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.

#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
    static uint8 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                 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);
        }
    }
}

NMI_API sint8 m2m_wifi_request_scan_ssid	(	uint8	ch,
		char *	pcssid
	)

Parameters

[in]

ch

RF Channel ID for SCAN operation. It should be set according to tenuM2mScanCh. With a value of M2M_WIFI_CH_ALL(255)), means to scan all channels.

pcssid Null terminated string holding SSID to include in probe requests to scan for hidden AP having the same SSID

Warning

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

Precondition

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

See Also

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

Returns

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

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.

References tstrM2MScan::au8SSID, gu8scanInProgress, hif_send(), M2M_ERR, M2M_ERR_SCAN_IN_PROGRESS, m2m_memcpy(), m2m_memset(), M2M_REQ_GRP_WIFI, m2m_strlen(), M2M_SUCCESS, M2M_WIFI_REQ_SCAN, NULL, and tstrM2MScan::u8ChNum.

Referenced by os_m2m_wifi_request_scan_ssid_imp().