#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 equivalent to the SOStartupEx function with timeOut set to SO_STARTUP_TIMEOUT (60,000 milliseconds).
However, the SOStartupEx function can only be used during development; it cannot be used in retail products.
The SOStartup[Ex] function blocks until either preparation for communications are ready or it reaches timeout.
Calls to the SOStartup[Ex] functions also involve actual communication processes, such as host configuration, done by 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 convenience with internal synchronization, the NWC24OpenLib function will return the NWC24_ERR_MUTEX error until this process completes. Note the invocation order when both the SO and NWC24 libraries must be initialized. Also, for the same reason, if completion of the NWC24CloseLib function takes time, the complete initialization of the SO library may be delayed for that amount of time.
Note: The SOStartupEx function is designed for developmental purposes and must not be used in retail products. Make sure this function is not linked in the commercial version of the ROM.
The resulting shorter timeouts might adversely affect the connectivity of network devices.
| 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: Error codes other than those described above might be returned following subsequent library or console firmware updates. To deal with unexpected errors during development, treat all negative return values other than those described above as fatal errors, and either halt program execution or perform similar error handling.
2008/05/19 Revised notes for error codes.
2008/04/01 Prohibited the use of the SOStartupEx function in retail products.
2007/09/20 Described timeouts.
2007/08/22 Described the effect on NWC24OpenLib.
2007/08/07 Added descriptions.
2007/07/13 Added notes about errors.
2007/01/31 Initial version.
CONFIDENTIAL