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_ConnectToFriendsAsync</title> 9<LINK rel="stylesheet" href="../css/nitro.css" type="text/css"> 10</head> 11 12<body> 13<a name="dwc__main_8h_1dcb8be27412df5c9d5e0d9b9d035079b"></a> 14<h1 align="left">DWC_ConnectToFriendsAsync</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_ConnectToFriendsAsync.html#dwc__main_8h_1dcb8be27412df5c9d5e0d9b9d035079b>DWC_ConnectToFriendsAsync</a>(<a href=Macro.html#dwc__match_8h_1c3ba6e33e5dd79e1d13350b71fa22250>DWCTopologyType</a> topology, 22 const u8 friendIdxList[], 23 int friendIdxListLen, 24 u8 maxEntry, 25 <a href=DWCMatchedSCCallback.html#dwc__match_8h_169fa2126df86bf98f54258f5ccab9beb>DWCMatchedSCCallback</a> matchedCallback, 26 void *matchedParam, 27 <a href=DWCNewClientCallback.html#dwc__match_8h_133da3ed06ce23a3dbab8f2e0b9aedc96>DWCNewClientCallback</a> newClientCallback, 28 void *newClientParam, 29 <a href=DWCEvalPlayerCallback.html#dwc__match_8h_1546369b77983a0a5e7b8609d236ba937>DWCEvalPlayerCallback</a> evalCallback, 30 void *evalParam, 31 <a href=DWCConnectAttemptCallback.html#dwc__match_8h_11f5ec37975abd1264f03e7d9247c34bf>DWCConnectAttemptCallback</a> attemptCallback, 32 u8 *connectionUserData, 33 void *attemptParam);</CODE></PRE></dd> 34</dl> 35 36<h2>Arguments</h2> 37 38<TABLE border="1" width="100%"> 39 <TBODY> 40 41 <TR> 42<TD width="13%"><EM><STRONG>topology</STRONG></EM></TD> 43<TD width="87%">The connection topology. Specified from inside <a href=Macro.html#dwc__match_8h_1c3ba6e33e5dd79e1d13350b71fa22250><CODE>DWCTopologyType</CODE></a>.</TD> 44 </TR> 45 46 <TR> 47<TD width="13%"><EM><STRONG>friendIdxList</STRONG></EM></TD> 48<TD width="87%">Pointer to the friend index list used for requesting connections. If NULL, the entire friend roster becomes the connection request target.</TD> 49 </TR> 50 51 <TR> 52<TD width="13%"><EM><STRONG>friendIdxListLen</STRONG></EM></TD> 53<TD width="87%">Length of the friend index list used for requesting connections. The maximum value is 64, just like the length of the friend roster.</TD> 54 </TR> 55 56 <TR> 57<TD width="13%"><EM><STRONG>maxEntry</STRONG></EM></TD> 58<TD width="87%">Number of people (including oneself) to make up the requested network. A value from 2 to 32 can be set in this argument.</TD> 59 </TR> 60 61 <TR> 62<TD width="13%"><EM><STRONG>matchedCallback</STRONG></EM></TD> 63<TD width="87%">Pointer to the connection completion callback function. This is called for each person who connects.</TD> 64 </TR> 65 66 <TR> 67<TD width="13%"><EM><STRONG>matchedParam</STRONG></EM></TD> 68<TD width="87%">Parameter for the connection completion callback.</TD> 69 </TR> 70 71 <TR> 72<TD width="13%"><EM><STRONG>newClientCallback</STRONG></EM></TD> 73<TD width="87%">Pointer to the new connection client notification callback function.</TD> 74 </TR> 75 76 <TR> 77<TD width="13%"><EM><STRONG>newClientParam</STRONG></EM></TD> 78<TD width="87%">Parameter for the new connection client notification callback function.</TD> 79 </TR> 80 81 <TR> 82<TD width="13%"><EM><STRONG>evalCallback</STRONG></EM></TD> 83<TD width="87%">Pointer to the player evaluation callback function.</TD> 84 </TR> 85 86 <TR> 87<TD width="13%"><EM><STRONG>evalParam</STRONG></EM></TD> 88<TD width="87%">Parameter for the player evaluation callback.</TD> 89 </TR> 90 91 <TR> 92<TD width="13%"><EM><STRONG>attemptCallback</STRONG></EM></TD> 93<TD width="87%">Pointer to the connection acceptance callback function.</TD> 94 </TR> 95 96 <TR> 97<TD width="13%"><EM><STRONG>connectionUserData</STRONG></EM></TD> 98<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> 99 </TR> 100 101 <TR> 102<TD width="13%"><EM><STRONG>attemptParam</STRONG></EM></TD> 103<TD width="87%">Parameter for the connection acceptance callback.</TD> 104 </TR> 105 106 </TBODY> 107</TABLE> 108 109<h2>Return Values</h2> 110 111<TABLE border="1" width="100%"> 112 <TBODY> 113 114 <TR> 115<TD width="13%"><EM><STRONG>TRUE</STRONG></EM></TD> 116<TD width="87%">The process starts. The results are indicated via the callback function.</TD> 117 </TR> 118 119 <TR> 120<TD width="13%"><EM><STRONG>FALSE</STRONG></EM></TD> 121<TD width="87%">Not a good state for calling this function.</TD> 122 </TR> 123 124 </TBODY> 125</TABLE> 126 127<H2>Description</H2> 128<p>This function specifies friends and connects to them, creating a group. This is known as peer matchmaking by specifying friends.</p><p>The argument <CODE>friendIdxList</CODE> specifies a pointer to the array of indices collected from inside the friend roster of the friend with whom matchmaking is intended. If <CODE>NULL</CODE> is specified in the index list, all friends in the friend roster are candidates for matchmaking. The friend roster that is referenced during peer matchmaking with friends specified is specified with the <A href="DWC_InitFriendsMatch.html"><CODE>DWC_InitFriendsMatch</CODE></a> function.</p><p>If the argument <CODE>evalCallback</CODE> is specified, the designated evaluation callback function is called each time a matchmaking candidate player is found. The matchmaking condition key can be referenced by using the <CODE><A href="DWC_GetMatchIntValue.html">DWC_GetMatchIntValue</A></CODE> or <CODE><A href="DWC_GetMatchStringValue.html">DWC_GetMatchStringValue</A></CODE> function inside the evaluation callback function. Be sure to evaluate the player based on that value and return the evaluation value as the return value. Players with an evaluation value of 0 or less are excluded from matchmaking.</p><p>When connecting to specified friends through peer matchmaking, exactly one person at a time is found as a candidate player. If the evaluation value is greater than 0, matchmaking begins. If the value is 0 or lower, no matchmaking takes place.</p><p>After this function is called, matchmaking proceeds as long as the <a href=DWC_ProcessFriendsMatch.html#dwc__main_8h_1c7b64bfd61e6c336a1d382fb6d1ea2d8><CODE>DWC_ProcessFriendsMatch</CODE></a> function continues to be called. The matchmaking completion callback is called if matchmaking with the first server host results in success, error, or cancel status. The new connection client notification callback is called when a new client arrives to connect to the server host after the local host has connected to the server host. In addition, once the connection for the new connection client is complete, the matchmaking completion callback is called again. Friend-specified peer matchmaking automatically determines whether the local host is a server or client.</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>Although matchmaking will not be performed with a peer with a different connection topology, note the following points. The evaluation callback is called when the <a href=DWCEvalPlayerCallback.html#dwc__match_8h_1546369b77983a0a5e7b8609d236ba937><CODE>DWCEvalPlayerCallback</CODE></a> parameter has been set for the <a href=DWC_ConnectToAnybodyAsync.html#dwc__main_8h_10c4e2a60e98dfa82a16b5e896d3a2203><CODE>DWC_ConnectToAnybodyAsync</CODE></a>/<a href=DWC_ConnectToFriendsAsync.html#dwc__main_8h_1dcb8be27412df5c9d5e0d9b9d035079b><CODE>DWC_ConnectToFriendsAsync</CODE></a> functions, even if the peer has a different connection topology. Because the evaluation callback has no way of knowing the connection topology of the peer, there is no method that can be used within the evaluation callback to exclude such peers.</p><p>If a peer selected for connection in the evaluation callback's filtering results actually has a different connection topology, matchmaking cannot be performed with that peer. This behavior repeats until a peer can be found with which matchmaking is possible. When using the <a href=DWC_ConnectToAnybodyAsync.html#dwc__main_8h_10c4e2a60e98dfa82a16b5e896d3a2203><CODE>DWC_ConnectToAnybodyAsync</CODE></a> or <a href=DWC_ConnectToFriendsAsync.html#dwc__main_8h_1dcb8be27412df5c9d5e0d9b9d035079b><CODE>DWC_ConnectToFriendsAsync</CODE></a> functions, be sure to establish conditions for forming groups other than connection topology and then, within those groups, make sure the connection topology is uniform.</p> 129 130<H2>Revision History</H2> 131<DL> 132 133<DT><para>2.0.0</DT> 134<DD>Specification change.</DD> 135 136<DT><para>1.4.10</DT> 137<DD>Added a section concerning the details of connecting to the network.</DD> 138 139</DL> 140<hr><p>CONFIDENTIAL</p></body> 141</html> 142