1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows"> 8<title>DWC_ConnectToGameServerAsync</title> 9<LINK rel="stylesheet" href="../css/nitro.css" type="text/css"> 10</head> 11 12<body> 13<a name="dwc__main_8h_1254f419a2e97ad73074d232c4160cfd2"></a> 14<h1 align="left">DWC_ConnectToGameServerAsync</h1> 15<h2>Syntax</h2> 16 17<dl> 18 <dd> 19<CODE>#include <dwc.h></CODE><BR> 20 <BR> 21 <PRE><CODE>BOOL <a href=DWC_ConnectToGameServerAsync.html#dwc__main_8h_1254f419a2e97ad73074d232c4160cfd2>DWC_ConnectToGameServerAsync</a>(<a href=Macro.html#dwc__match_8h_1c3ba6e33e5dd79e1d13350b71fa22250>DWCTopologyType</a> topology, 22 int serverIndex, 23 <a href=DWCMatchedSCCallback.html#dwc__match_8h_169fa2126df86bf98f54258f5ccab9beb>DWCMatchedSCCallback</a> matchedCallback, 24 void *matchedParam, 25 <a href=DWCNewClientCallback.html#dwc__match_8h_133da3ed06ce23a3dbab8f2e0b9aedc96>DWCNewClientCallback</a> newClientCallback, 26 void *newClientParam, 27 <a href=DWCConnectAttemptCallback.html#dwc__match_8h_11f5ec37975abd1264f03e7d9247c34bf>DWCConnectAttemptCallback</a> attemptCallback, 28 u8 *connectionUserData, 29 void *attemptParam);</CODE></PRE></dd> 30</dl> 31 32<h2>Arguments</h2> 33 34<TABLE border="1" width="100%"> 35 <TBODY> 36 37 <TR> 38<TD width="13%"><EM><STRONG>topology</STRONG></EM></TD> 39<TD width="87%">The connection topology. Specified from inside <a href=Macro.html#dwc__match_8h_1c3ba6e33e5dd79e1d13350b71fa22250><CODE>DWCTopologyType</CODE></a>.</TD> 40 </TR> 41 42 <TR> 43<TD width="13%"><EM><STRONG>serverIndex</STRONG></EM></TD> 44<TD width="87%">Friend roster index on the destination server host.</TD> 45 </TR> 46 47 <TR> 48<TD width="13%"><EM><STRONG>matchedCallback</STRONG></EM></TD> 49<TD width="87%">Pointer to the connection completion callback function. This is called for each person who connects.</TD> 50 </TR> 51 52 <TR> 53<TD width="13%"><EM><STRONG>matchedParam</STRONG></EM></TD> 54<TD width="87%">Parameter for the connection completion callback.</TD> 55 </TR> 56 57 <TR> 58<TD width="13%"><EM><STRONG>newClientCallback</STRONG></EM></TD> 59<TD width="87%">Pointer to the new connection client notification callback function.</TD> 60 </TR> 61 62 <TR> 63<TD width="13%"><EM><STRONG>newClientParam</STRONG></EM></TD> 64<TD width="87%">Parameter for the new connection client notification callback function.</TD> 65 </TR> 66 67 <TR> 68<TD width="13%"><EM><STRONG>attemptCallback</STRONG></EM></TD> 69<TD width="87%">Pointer to the connection acceptance callback function.</TD> 70 </TR> 71 72 <TR> 73<TD width="13%"><EM><STRONG>connectionUserData</STRONG></EM></TD> 74<TD width="87%">Pointer to the local host's own connection acceptance parameter buffer. This must be buffer of length <CODE>u8[<a href=Macro.html#dwc__match_8h_1767334491be60055db279f50c050c695>DWC_CONNECTION_USERDATA_LEN</a>]</CODE>. The buffer’s contents will be copied to the library, so it can be deallocated once this function is called. If NULL is specified, zeros are set for the entire content of the local buffer that is used for determining whether to accept a connection.</TD> 75 </TR> 76 77 <TR> 78<TD width="13%"><EM><STRONG>attemptParam</STRONG></EM></TD> 79<TD width="87%">Parameter for the connection acceptance callback.</TD> 80 </TR> 81 82 </TBODY> 83</TABLE> 84 85<h2>Return Values</h2> 86 87<TABLE border="1" width="100%"> 88 <TBODY> 89 90 <TR> 91<TD width="13%"><EM><STRONG>TRUE</STRONG></EM></TD> 92<TD width="87%">The process starts. The results are indicated via the callback function.</TD> 93 </TR> 94 95 <TR> 96<TD width="13%"><EM><STRONG>FALSE</STRONG></EM></TD> 97<TD width="87%">Not a good state for calling this function.</TD> 98 </TR> 99 100 </TBODY> 101</TABLE> 102 103<H2>Description</H2> 104<p>This function specifies the server host to connect to using the index on the friend roster and then connects there. The server host is the host that waits for connections from client hosts after calling the <A href="DWC_SetupGameServer.html"><CODE>DWC_SetupGameServer</CODE></a> function as part of server-client matchmaking. If the <A href="DWC_ProcessFriendsMatch.html"><CODE>DWC_ProcessFriendsMatch</CODE></a> function is called continuously after calling this function, the matchmaking process will progress. The matchmaking completion callback is called if the matchmaking completes with a success, error, or cancellation.</p><p>A new connection client notification callback is called when at least one client host has already connected to the server host and a new client host arrives to connect to the server host. Once this new client successfully connects, the matchmaking completion callback is called again, as well.</p><p>Depending on the condition of the network connection, the process might be blocked and not return from the function for some time.</p><p>Because there are cases in which <a href=DWCMatchedSCCallback.html#dwc__match_8h_169fa2126df86bf98f54258f5ccab9beb><CODE>DWCMatchedSCCallback</CODE></a> is not called, an appropriate timeout should be established on the application side. The duration of the timeout should be roughly two to three times of what it normally takes to connect.</p> 105 106<H2>Revision History</H2> 107<DL> 108 109<DT><para>2.0.0</DT> 110<DD>Specification change.</DD> 111 112<DT><para>1.4.10</DT> 113<DD>Added a section concerning the details of connecting to the network.</DD> 114 115<DT><para>1.4.16</DT> 116<DD>Added a caution stating that <CODE>DWCMatchedSCCallback</CODE> may not always be called.</DD> 117 118</DL> 119<hr><p>CONFIDENTIAL</p></body> 120</html> 121