WCM_ConnectAsync

C Specification


#include <nitroWiFi/wcm.h>

void  WCM_ConnectAsync( void* bssDesc , void* wepDesc , u32 option );
				

Description

An asynchronous function that initiates the sequence to connect to a wireless access point. If the asynchronous process starts normally, the internal state changes from WCM_PHASE_IDLE to WCM_PHASE_IDLE_TO_DCF; when the asynchronous process completes normally, it becomes WCM_PHASE_DCF. This function can only be executed in these internal states. The settings specified as an argument are reflected in the library's internal operation only if the function is called when the internal state is WCM_PHASE_IDLE. When the return value is WCM_RESULT_ACCEPT, the corresponding asynchronous process notification will be generated once and the callback function is called.

Arguments

bssDesc Specifies information about the wireless access point to connect to as pointer to a WMBssDesc structure. For the wireless access point information, use the information provided by the auto-search's asynchronous discovery notification or information obtained with the WCM_PointApList function.
wepDesc Specifies the WEP encryption setting used for connecting to wireless access point as a pointer to a WCMWepDesc structure if NULL, WEP encryption 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 sequence for connection to a wireless access point has already completed, and the internal state was WCM_PHASE_DCF. 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 connect to a wireless access point, 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, the internal state was not WCM_PHASE_IDLE, WCM_PHASE_IDLE_TO_DCF, or WCM_PHASE_DCF, or valid information is not specified for the argument.
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_CONNECT.

WCM_RESULT_SUCCESS Indicates that the asynchronous process succeeded and that the wireless access point was connected normally. The internal state becomes WCM_PHASE_DCF.
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

While connecting to wireless access point and performing communication, one of the following progress notifications may be issued to the callback function specified with WCM_StartupAsync function.
Note that the notification type is the same as that of the asynchronous process result notification for a request to disconnect from wireless access point using the WCM_DisconnectAsync function.

WCM_NOTIFY_DISCONNECT WCM_RESULT_SUCCESS Indicates that the system was disconnected from the wireless access point or that there was no beacon received from the wireless access point for a certain period, resulting in a timeout. The connection with the wireless access point is reset and the internal state returns to WCM_PHASE_IDLE.
WCM_NOTIFY_DISCONNECT WCM_RESULT_FAILURE When disconnected from the wireless access point, the function automatically tries to reset the connection with the wireless access point. This indicates that the function received an error notification during the reset process. The internal state becomes WCM_PHASE_IRREGULAR.
WCM_NOTIFY_DISCONNECT WCM_RESULT_FATAL_ERROR An unrecoverable error occurred while connecting to a wireless access point during communication. Internal state becomes WCM_PHASE_FATAL_ERROR and does not change thereafter.

See Also

WCM_DisconnectAsync, WCM_TerminateAsync, WCM_UpdateOption, WCM_PointApList, WCMWepDesc

Revision History

07/22/2005 Initial version.