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>C Specification</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 the same as the <CODE>SOStartupEx</CODE> function for which <CODE><strong><em>timeOut</em></strong></CODE> has been set to <CODE><strong>SO_STARTUP_TIMEOUT</strong></CODE> (60,000 milliseconds). 25</P> 26<P> 27 The <CODE>SOStartup[Ex]</CODE> function blocks until either preparation for communications are ready or it reaches timeout.<br>The <CODE>SOStartup[Ex]</CODE> function calls also involve communication processes such as the host configuration and so on for DHCP. <br>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 the sake of convenience for internal synchronization, <CODE><A HREF="../nwc24/Misc/NWC24OpenLib.html">NWC24OpenLib</A></CODE> will return an <CODE>NWC24_ERR_MUTEX</CODE> error until this process completes. Be cautious about the invocation order when both the SO library and the NWC24 library must be initialized. 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>: Shorter timeouts might adversely affect the connectivity of network devices. Unless there is a special reason, use the recommended value for timeouts for the <CODE>SOStartup</CODE> function. 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>Errors may be added as the library is updated. Handle all negative return values as general errors. 166</P> 167 168<H2>See Also</H2> 169<P> 170 <CODE><a href="SOCleanup.html">SOCleanup</a><br> <a href="SOInit.html">SOInit</a><br></CODE> 171</P> 172 173<H2>Revision History</H2> 174<P> 1752007/09/20 Added the explanation about timeouts.<BR>2007/08/22 Added text about the impact on <CODE>NWC24OpenLib</CODE>.<BR>2007/08/07 Added Description section.<BR>2007/07/13 Added warning about errors.<BR>2007/01/31 Initial version. 176</P> 177 178<hr><p>CONFIDENTIAL</p></body> 179</HTML> 180