1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META http-equiv="Content-Style-Type" content="text/css"> 6<TITLE>SOStartup, SOStartupEx</TITLE> 7<LINK rel="stylesheet" type="text/css" href="../CSS/rex.css"> 8</HEAD> 9<BODY> 10<H1>SOStartup, SOStartupEx</H1> 11 12<H2>Syntax</H2> 13<DL> 14 <DD><PRE><CODE>#include <revolution/so.h></CODE></PRE> 15 <DD><PRE><CODE>int SOStartup ( void ); 16int SOStartupEx( int timeOut );</CODE></PRE> 17</DL> 18 19<H2>Description</H2> 20<P> 21 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 <CODE>SOStartup</CODE>. For details, see the various function references. 22</P> 23<P> 24 The <CODE>SOStartup</CODE> function is equivalent to the <CODE>SOStartupEx</CODE> function with <CODE><strong><em>timeOut</em></strong></CODE> set to <CODE><strong>SO_STARTUP_TIMEOUT</strong></CODE> (60,000 milliseconds).<BR> However, the <CODE>SOStartupEx</CODE> function can only be used during development; it cannot be used in retail products. 25</P> 26<P> 27 The <CODE>SOStartup[Ex]</CODE> function blocks until either preparation for communications are ready or it reaches timeout.<br> Calls to the <CODE>SOStartup[Ex]</CODE> functions also involve actual communication processes, such as host configuration, done by DHCP. The value passed to <CODE><strong><em>timeOut</em></strong></CODE> is the shortest time until timeout. In some cases, the actual duration until the timeout will be longer than the value of <CODE><strong><em>timeOut</em></strong></CODE>. 28</P> 29<P> 30This 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. 31</P> 32<P style="background-color:ffe8ff;padding-top:4px;padding-bottom:4px;padding-left:4px;padding-right:4px;"> 33 <strong>Note: </strong>The system can automatically perform communications independent from the application. But even in this situation, <CODE>SOStartup</CODE> and <CODE>SOCleanup</CODE> 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. 34</P> 35<P style="background-color:ffe8ff;padding-top:4px;padding-bottom:4px;padding-left:4px;padding-right:4px;"> 36 <strong>Note: </strong>For convenience with internal synchronization, the <CODE><A HREF="../nwc24/Misc/NWC24OpenLib.html">NWC24OpenLib</A></CODE> function will return the <CODE>NWC24_ERR_MUTEX</CODE> 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 <CODE><A HREF="../nwc24/Misc/NWC24CloseLib.html">NWC24CloseLib</A></CODE> function takes time, the complete initialization of the SO library may be delayed for that amount of time. 37</P> 38<P style="background-color:ffe8ff;padding-top:4px;padding-bottom:4px;padding-left:4px;padding-right:4px;"> 39 <font color=red><strong>Note:</strong></font> The <font color="red"><CODE>SOStartupEx</CODE> 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.</font><br>The resulting shorter timeouts might adversely affect the connectivity of network devices. 40</P> 41 42<H2>Arguments</H2> 43<TABLE border="1" cellpadding="3" cellspacing="0.1"> 44 <TR> 45 <TH><em>timeOut</em></TH> 46 <TD> 47 Specifies the timeout time in milliseconds for when a transition to communications-ready does not complete. 48 </TD> 49 </TR> 50</TABLE> 51 52<h2>Return Values</h2> 53<TABLE border="1" cellpadding="3" cellspacing="0.1"> 54 <TR> 55 <TH>0</TH> 56 <TD> 57 Process was successful. 58 </TD> 59 </TR> 60 <TR> 61 <TH>SO_EALREADY</TH> 62 <TD> 63 Already transitioned to a communications-ready state via the <CODE>SOStartup[Ex]</CODE> function. 64 </TD> 65 </TR> 66 <TR> 67 <TH>SO_EBUSY</TH> 68 <TD> 69 Because processing that accompanies the state transition of the SO library is in execution, processing cannot be accepted in the current state. 70 </TD> 71 </TR> 72 <TR> 73 <TH>SO_EINVAL</TH> 74 <TD> 75 An invalid state call. Normally does not occur, but is generated when the internal state monitoring in the SO Library is abnormal. 76 </TD> 77 </TR> 78 <TR> 79 <TH>SO_ENETRESET</TH> 80 <TD> 81 The process failed for one of the following reasons: 82 <UL> 83 <li>The SO library has not been initialized with <CODE><a href="SOInit.html">SOInit</a></CODE>. 84 <li>Disconnection in a connected network interface was detected during the transition process. 85 </UL> 86 </TD> 87 </TR> 88 <TR> 89 <TH>SO_ENOENT</TH> 90 <TD> 91 No communications-ready network interface was set. 92 </TD> 93 </TR> 94 <TR> 95 <TH>SO_ENOLINK</TH> 96 <TD> 97 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. 98 </TD> 99 </TR> 100 <TR> 101 <TH>SO_ENXIO</TH> 102 <TD> 103 No network interface device was found. 104 </TD> 105 </TR> 106 <TR> 107 <TH>SO_ETIMEDOUT</TH> 108 <TD> 109 Timed out while waiting for DHCP host configuration to complete. 110 </TD> 111 </TR> 112 <TR> 113 <TH>SO_ERR_DHCP_TIMEOUT</TH> 114 <TD> 115 No response received from the DHCP server during DHCP host configuration. 116 </TD> 117 </TR> 118 <TR> 119 <TH>SO_ERR_DHCP_EXPIRED</TH> 120 <TD> 121 The lease period expired without reconfiguration taking place, after DHCP host configuration completed. 122 </TD> 123 </TR> 124 <TR> 125 <TH>SO_ERR_DHCP_NAK</TH> 126 <TD> 127 Denied by the DHCP server during DHCP host configuration. 128 </TD> 129 </TR> 130 <TR> 131 <TH>SO_ERR_ADDR_COLLISION</TH> 132 <TD> 133 An IP address collision was detected on the network. 134 </TD> 135 </TR> 136 <TR> 137 <TH>SO_ERR_LINK_DOWN</TH> 138 <TD> 139 Disconnection in a connected network interface was detected during the transition process. 140 </TD> 141 </TR> 142 <TR> 143 <TH>SO_ERR_LINK_UP_TIMEOUT</TH> 144 <TD> 145 A timeout occurred before the specified network interface was found. 146 </TD> 147 </TR> 148 <TR> 149 <TH>SO_EFATAL</TH> 150 <TD> 151 One of the following fatal errors occurred: 152 <UL> 153 <li>A call from the exception handler. 154 <li>A fatal error occurred while running the firmware. 155 <li>A timeout occurred while waiting for firmware preparations to complete. 156 </UL> 157 </TD> 158 </TR> 159</TABLE> 160<P style="background-color:ffe8ff;padding-top:4px;padding-bottom:4px;padding-left:4px;padding-right:4px;"> 161 <strong>Note: </strong>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 <CODE><A HREF="../net/NETGetStartupErrorCode.html">NETGetStartupErrorCode</A></CODE>. 162</P> 163 164<P style="background-color:ffe8ff;padding-top:4px;padding-bottom:4px;padding-left:4px;padding-right:4px;"> 165 <strong>Note: </strong>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. 166</P> 167 168<H2>See Also</H2> 169<P> 170 <CODE> 171 <a href="SOCleanup.html">SOCleanup</a><br> 172 <a href="SOInit.html">SOInit</a><br> 173 </CODE> 174</P> 175 176<H2>Revision History</H2> 177<P> 1782008/05/19 Revised notes for error codes. <br>2008/04/01 Prohibited the use of the <CODE>SOStartupEx</CODE> function in retail products. <BR>2007/09/20 Described timeouts. <BR>2007/08/22 Described the effect on <CODE>NWC24OpenLib</CODE>. <BR>2007/08/07 Added descriptions. <BR>2007/07/13 Added notes about errors. <BR>2007/01/31 Initial version. 179</P> 180 181<hr><p>CONFIDENTIAL</p></body> 182</HTML> 183