#include <revolution/so.h>int SOStartup ( void );
int SOStartupEx( int timeOut );
Moves to the state in which Wii can communicate via the Internet. Call this function once before calling the SO library or any function provided by the library. There are exceptions, however; certain functions that do not perform communications processes can be called before the call to SOStartup. For details, see the various function references.
The SOStartup function is the same as the SOStartupEx function for which timeOut has been set to SO_STARTUP_TIMEOUT (60,000 milliseconds).
The SOStartup[Ex] function blocks until either preparation for communications are ready or it reaches timeout.
The SOStartup[Ex] function calls also involve communication processes such as the host configuration and so on for DHCP.
The value passed to timeOut is the shortest time until timeout. In some cases, the actual duration until the timeout will be longer than the value of timeOut.
This function may block for a long period of time before it finishes processing. Consequently, we recommend that when you call this function you prepare a separate thread from other processing, such as rendering.
Note: The system can automatically perform communications independent from the application. But even in this situation, SOStartup and SOCleanup must be called in accordance with the application's processes, and in some cases the process will end in less time that is normally required.
Note: For the sake of convenience for internal synchronization, NWC24OpenLib will return an NWC24_ERR_MUTEX error until this process completes. Be cautious about the invocation order when both the SO library and the NWC24 library must be initialized.
Note: Shorter timeouts might adversely affect the connectivity of network devices. Unless there is a special reason, use the recommended value for timeouts for the SOStartup function.
| timeOut | Specifies the timeout time in milliseconds for when a transition to communications-ready does not complete. |
|---|
| 0 | Process was successful. |
|---|---|
| SO_EALREADY |
Already transitioned to a communications-ready state via the SOStartup[Ex] function.
|
| SO_EBUSY | Because processing that accompanies the state transition of the SO library is in execution, processing cannot be accepted in the current state. |
| SO_EINVAL | An invalid state call. Normally does not occur, but is generated when the internal state monitoring in the SO Library is abnormal. |
| SO_ENETRESET |
The process failed for one of the following reasons:
|
| SO_ENOENT | No communications-ready network interface was set. |
| SO_ENOLINK | SO Library process cannot take place because a network interface cannot currently be used. Can occur for physical reasons, such as an unplugged LAN cable, or for software reasons, such as exclusive control of the network interface. |
| SO_ENXIO | No network interface device was found. |
| SO_ETIMEDOUT | Timed out while waiting for DHCP host configuration to complete. |
| SO_ERR_DHCP_TIMEOUT | No response received from the DHCP server during DHCP host configuration. |
| SO_ERR_DHCP_EXPIRED | The lease period expired without reconfiguration taking place, after DHCP host configuration completed. |
| SO_ERR_DHCP_NAK | Denied by the DHCP server during DHCP host configuration. |
| SO_ERR_ADDR_COLLISION | An IP address collision was detected on the network. |
| SO_ERR_LINK_DOWN | Disconnection in a connected network interface was detected during the transition process. |
| SO_ERR_LINK_UP_TIMEOUT | A timeout occurred before the specified network interface was found. |
| SO_EFATAL |
One of the following fatal errors occurred:
|
Note: As a general rule, if this function returns an error you will need to inform the user that the application has failed to connect to the network. If the Programming Guideline for the upper-level library you are using has rules for displaying the error messages, you should take appropriate action to follow those rules. If you will be displaying the five (or six) digit error code for user support, get the code using NETGetStartupErrorCode.
Note: Errors may be added as the library is updated. Handle all negative return values as general errors.
2007/09/20 Added the explanation about timeouts.
2007/08/22 Added text about the impact on NWC24OpenLib.
2007/08/07 Added Description section.
2007/07/13 Added warning about errors.
2007/01/31 Initial version.
CONFIDENTIAL