#include <nitroWiFi/wcm.h>
s32 WCM_BeginSearchAsync( void* bssid , void* essid , u32 option );
This is an asynchronous function that initiates the start sequence for wireless access point auto-search. If the asynchronous process starts normally, the internal state changes from WCM_PHASE_IDLE
to WCM_PHASE_IDLE_TO_SEARCH
; when the asynchronous process completes normally, it becomes WCM_PHASE_SEARCH
. This function can only be executed in these internal states. The auto-search setting specified in the argument is updated even if the setting is already configured with this function, and reflected in the internal operation. When the return value is WCM_RESULT_ACCEPT
, the corresponding asynchronous process notification is generated once and the callback function is called.
bssid |
Specifies the BSS-ID of the wireless access point to search for as a pointer to six bytes of data. If NULL or WCM_BSSID_ANY is specified, BSS-ID-based filtering is disabled. |
essid |
Specifies the ESS-ID of the wireless access point to search for as a pointer to a maximum of 32 bytes of data. If NULL or WCM_ESSID_ANY is specified, ESS-ID-based filtering is disabled. |
option |
Specifies 32-bit option update settings in accordance with the option-setting format. For details see the description for WCM_UpdateOption function. |
Returns one of the following process results.
WCM_RESULT_ACCEPT |
Indicates that the request to start the asynchronous sequence was accepted and that the asynchronous process started normally. When the asynchronous process ends, the callback function will be called once. |
WCM_RESULT_PROGRESS |
Indicates that the asynchronous sequence started by this function is already executing and this was a duplicate call. Even with duplicate calls, the asynchronous process completion notification is generated only once. |
WCM_RESULT_SUCCESS |
Indicates that the start sequence for the wireless access point auto-search has already completed, and the internal state was WCM_PHASE_SEARCH . Since the asynchronous process is not started, an asynchronous process completion notification is not generated. |
WCM_RESULT_REJECT |
Indicates that when the function attempted to initiate the sequence to start a wireless access point auto-search, it was not successful in issuing a PXI process request to the ARM7. The internal state remains WCM_PHASE_IDLE and another attempt can be made. |
WCM_RESULT_FAILURE |
Indicates the process failed because the WCM library was not initialized or the internal state was not WCM_PHASE_IDLE , WCM_PHASE_IDLE_TO_SEARCH , or WCM_PHASE_SEARCH , etc. |
WCM_RESULT_FATAL_ERROR |
Indicates that an unrecoverable error has occurred. Internal state becomes WCM_PHASE_FATAL_ERROR and does not change thereafter. |
One of the following asynchronous process results is passed to the callback function specified by WCM_StartupAsync
function. The notification type is always WCM_NOTIFY_BEGIN_SEARCH
.
WCM_RESULT_SUCCESS |
Indicates that the asynchronous process succeeded and wireless access point auto-search began normally. The internal state becomes WCM_PHASE_SEARCH . |
WCM_RESULT_FAILURE |
Indicates that an error notification was received from the WM library during the asynchronous process. The internal state becomes WCM_PHASE_IRREGULAR or returns to WCM_PHASE_IDLE . |
WCM_RESULT_FATAL_ERROR |
Indicates that an unrecoverable error occurred during the asynchronous process. Internal state becomes WCM_PHASE_FATAL_ERROR and does not change thereafter. |
As an intermediate step during the wireless access point auto-search, one of the following progress notifications may be issued to the callback function specified with WCM_StartupAsync
function.
WCM_NOTIFY_FOUND_AP |
WCM_RESULT_SUCCESS |
Issued when a wireless access point is found. Because it is continuously and automatically searching the specified channels, this notification is generated repeatedly when the same wireless access point is found. Information about the wireless access point that was found is indicated in detailed parameter parameter[0] , which is included in the arguments of the callback function, as a pointer to a WMBssDesc type. |
WCM_NOTIFY_FOUND_AP |
WCM_RESULT_FAILURE |
Indicates the reception of an error notification from the WM library during auto-search. Auto-search stops and the internal state becomes WCM_PHASE_IRREGULAR or returns to WCM_PHASE_IDLE . |
WCM_NOTIFY_FOUND_AP |
WCM_RESULT_FATAL_ERROR |
Indicates that an unrecoverable error has occurred during the auto-search process. Auto-search stops and the internal state becomes WCM_PHASE_FATAL_ERROR and does not change thereafter. |
WCM_NOTIFY_SEARCH_AROUND |
WCM_RESULT_SUCCESS |
Issues notification when an automatic search cycle of the specified channels is completed. (It has searched all channels once.) After the cycle is complete, the automatic search continues. Accordingly, this notification is issued repeatedly. This notification is an option setting and it is not issued by default. |
WCM_EndSearchAsync, WCM_SearchAsync, WCM_TerminateAsync, WCM_UpdateOption
07/22/2005 Initial version.