WCM_StartupAsync

C Specification


#include <nitroWiFi/wcm.h>

s32   WCM_StartupAsync( WCMConfig* config , WCMNotify notify );
				

Description

An asynchronous function that initiates the start sequence for wireless communication features. If the asynchronous process starts normally, the internal state changes from WCM_PHASE_WAIT to WCM_PHASE_WAIT_TO_IDLE, and if the asynchronous process completes normally, it becomes WCM_PHASE_IDLE. 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_WAIT. The callback function specified with notify is called not only when an asynchronous process completion notification is generated by a call of this function, but also every time an asynchronous process completion notification is generated thereafter. When the return value is WCM_RESULT_ACCEPT, the corresponding asynchronous process notification will be generated once and the callback function is called.

Arguments

config Specifies the pointer to a WCM library internal operation configuration structure of type WCMConfig. The DMA number used internally and operation during wireless access point auto-search can be configured. If NULL is specified, the default configuration values will be used.
notify Designates the callback function called when an asynchronous process notification is generated. If set to NULL, notification will be disabled.
Note that this callback is called from the interrupt handler.

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 startup sequence for the wireless communication feature has already completed, and the internal state was WCM_PHASE_IDLE. Since the asynchronous process is not started, an asynchronous process completion notification is not generated.
WCM_RESULT_FAILURE Indicates the process failed because the WCM library was not initialized or the internal state was not WCM_PHASE_WAIT, WCM_PHASE_WAIT_TO_IDLE, or WCM_PHASE_IDLE. This value is returned also when the function is unsuccessful in issuing a PXI process request to the ARM7. However, because the internal state becomes WCM_PHASE_IRREGULAR, no retries are possible.
WCM_RESULT_WMDISABLE This indicates that the process cannot be executed because the wireless driver is not operating on the ARM7 when the startup of the wireless communications feature was attempted. If the ARM7 component is ichneumon, the wireless driver may have been forcibly stopped by the WVR library.
Also, this value is returned when attempting to execute this process on a Nintendo DS machine that has had wireless communications prohibited.
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 notify. The notification type is always WCM_NOTIFY_STARTUP.

WCM_RESULT_SUCCESS Indicates the asynchronous process has succeeded and the wireless feature started normally. The internal state becomes WCM_PHASE_IDLE.
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.
WCM_RESULT_FAITAL_ERROR Indicates that an unrecoverable error occurred during the asynchronous process. Internal state becomes WCM_PHASE_FATAL_ERROR and does not change thereafter.

See Also

WCM_Init, WCM_CleanupAsync, WCM_TerminateAsync, WCMConfig, WCMNotify

Revision History

2005/09/10 Added description of WCM_RESULT_WMDISABLE.
07/22/2005 Initial version.