#include <dwc.h>
BOOL DWC_ConnectToFriendsAsync(DWCTopologyType topology,
const u8 friendIdxList[],
int friendIdxListLen,
u8 maxEntry,
DWCMatchedSCCallback matchedCallback,
void *matchedParam,
DWCNewClientCallback newClientCallback,
void *newClientParam,
DWCEvalPlayerCallback evalCallback,
void *evalParam,
DWCConnectAttemptCallback attemptCallback,
u8 *connectionUserData,
void *attemptParam);topology |
The connection topology. Specified as a DWCTopologyType. |
friendIdxList |
Pointer to the friend index list used for requesting connections. If NULL, the entire friend roster becomes the connection request target. |
friendIdxListLen |
Length of the friend index list used for requesting connections. The maximum value is 64, just like the length of the friend roster. |
maxEntry |
Number of people (including oneself) to make up the requested network. A value from 2 to 32 can be set in this argument. |
matchedCallback |
Pointer to the connection complete callback function. This is called for each person connected. |
matchedParam |
Parameter for the connection-complete callback. |
newClientCallback |
Pointer to the new connection client notification callback function. |
newClientParam |
Parameter for the new connection client notification callback function. |
evalCallback |
Pointer to the player evaluation callback function. |
evalParam |
Parameter for the player evaluation callback. |
attemptCallback |
Pointer to the connection-acceptance callback function. |
connectionUserData |
Pointer to own connection-acceptance parameter buffer. It must be a buffer of length u8[DWC_CONNECTION_USERDATA_LEN]. The buffer's contents are 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. |
attemptParam |
Parameter for the connection-acceptance callback. |
TRUE |
Processing begins. The results are indicated via the callback function. |
FALSE |
Not a good state for calling this function. |
Specifies friends and connects to them, creating a group. This is known as peer matchmaking by specifying friends.
The argument friendIdxList specifies a pointer to the array of indices collected in the friend roster of the friend with whom matchmaking is intended. If NULL is specified in the index list, all friends in the friends roster are candidates for matchmaking. The friend roster that is referenced during friend-specified peer matchmaking is specified by the DWC_InitFriendsMatch function.
If the argument evalCallback is specified, the designated evaluation callback function is called each time a matchmaking candidate player is found. The matchmaking condition keys can be referenced by using the DWC_GetMatchIntValue or DWC_GetMatchStringValue 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.
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.
After this function is called, matchmaking proceeds as long as the DWC_ProcessFriendsMatch 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.
Depending on the condition of the network connection, the process might be blocked and not return from the function for some time.
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 DWCEvalPlayerCallback parameter has been set for the DWC_ConnectToAnybodyAsync and DWC_ConnectToFriendsAsync 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 in the evaluation callback to exclude such peers.
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 DWC_ConnectToAnybodyAsync or DWC_ConnectToFriendsAsync function, be sure to establish conditions for forming groups other than by connection topology and then, within those groups, make sure the connection topology is uniform.
Server migration occurs when a server host disconnects when the connection topology is full mesh or hybrid. Server migration does not occur with the star connection topology. With a hybrid connection, only those hosts directly connected to the new server host can connect to the new server host, and all other hosts are disconnected. Once server migration has occurred even once, new client hosts can no longer join that group. However, when using friend-specified peer matchmaking, if the only member of the group after server migration occurs is the local host itself, the group resumes accepting new client hosts.
For the change log prior to 5.1 PR2, click here.
CONFIDENTIAL