#include <dwc.h>
BOOL DWC_ConnectToAnybodyAsync(DWCTopologyType topology,
u8 maxEntry,
const char *addFilter,
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. |
maxEntry |
Number of people (including oneself) to request to be in the network. A value from 2 to 32 can be set in this argument. |
addFilter |
String for the matchmaking condition to be added to the game. If no condition is added, NULL is passed. Conditions can be written in standard SQL format. The maximum string length that can be set is 127 characters. In a debug build, the number of characters is checked to see if it exceeds this maximum. The string is copied and maintained in the library. |
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. |
Creates a group by specifying a number of people, without specifying friends. This is known as "connect-to-anybody peer matchmaking" in end-user documents and "peer matchmaking with friend unspecified" in developer documents.
Use the addFilter argument to configure the conditions for the player that is searched for as a matchmaking candidate. The matchmaking condition key(s) used in this filter string must be registered in advance using the DWC_AddMatchKeyInt or DWC_AddMatchKeyString function.
Note that there is no distinction between the development and production servers for friend management and the matchmaking process. When testing matchmaking during the development of a remastered or localized version, matchmaking sometimes occurs with titles that have already been released (even if you initialize DWC using the DWC_InitForDevelopment function).
To avoid this, use a matchmaking filter to prevent peer matchmaking with friend specified between the product and development (debugging) versions. (See the DWC_AddMatchKeyString function for more on matchmaking filters.)
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. The higher a player's evaluation value, the more likely that player will be selected as a matchmaking partner.
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. 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. In addition, once the connection for the new connection client is complete, the matchmaking completion callback is called again. Peer matchmaking with friend unspecified 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.
DWC_InitForDevelopment or the DWC_InitForProduction functions, and not with the DWC_SetAuthServer function. For the change log prior to 5.1 PR2, click here.
CONFIDENTIAL