DWC_ConnectToGameServerAsync

Syntax

#include <dwc.h>
BOOL DWC_ConnectToGameServerAsync(DWCTopologyType topology,
                                  int serverIndex,
                                  DWCMatchedSCCallback matchedCallback,
                                  void *matchedParam,
                                  DWCNewClientCallback newClientCallback,
                                  void *newClientParam,
                                  DWCConnectAttemptCallback attemptCallback,
                                  u8 *connectionUserData,
                                  void *attemptParam);

Arguments

topology The connection topology. Specified as a DWCTopologyType.
serverIndex Friend roster index on the destination server host.
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.
attemptCallback This is left for compatibility. Specify NULL.
connectionUserData Pointer to own connection-acceptance parameter buffer. It must be a buffer of length u8[DWC_CONNECTION_USERDATA_LEN].
attemptParam This is left for compatibility. Specify NULL.

Return Values

TRUE Processing begins. The results are indicated via the callback function.
FALSE Not a good state for calling this function.

Description

Specifies a server host by its index on the friend roster and then connects to it. The server host is the host that waits for connections from client hosts after calling the DWC_SetupGameServer function as part of server-client matchmaking. If the DWC_ProcessFriendsMatch function is called continuously after calling this function, the matchmaking process progresses. The matchmaking completion callback is called if the matchmaking completes with a success, error, or cancellation.

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.

Depending on the condition of the network connection, the process might be blocked and not return from the function for some time.

Because there are cases in which DWCMatchedSCCallback 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.

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.

Revision History

For the changelog prior to 5.1 PR2, click here.


CONFIDENTIAL