WCM_BeginSearchAsync

C Specification


#include <nitroWiFi/wcm.h>

s32   WCM_BeginSearchAsync(  void* bssid , void* essid , u32 option );
				

Description

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.

Arguments

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.

Return Values

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.

Asynchronous Process Results

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.

Asynchronous Notification

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.

See Also

WCM_EndSearchAsync, WCM_SearchAsync, WCM_TerminateAsync, WCM_UpdateOption

Revision History

07/22/2005 Initial version.