DWC_ConnectToGameServerByGroupID

Syntax

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

Arguments

topology The connection topology. Specified as a DWCTopologyType.
groupID The connection group ID.
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 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.

Return Values

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

Description

Tries to reconnect to the server host having the specified group ID. Because the ID of the group that the local host currently belongs to can be obtained using the DWC_GetGroupID function, if the local host saves this ID when it uses matchmaking to connect to someone, as long as that group is accepting client hosts, the local host can reconnect even if the connection is cut.

Note that if the group was formed through friend-specified peer matchmaking or server-client matchmaking and its initial server host has dropped out, it is no longer accepting client hosts. However, if only the server host is left during peer matchmaking with friend specified, it begins reaccepting client hosts.

In addition, because connections made using group IDs do not ask whether the local host has been a member, if the group ID is made public to friends as friend status, the local host could also connect to the group a friend belongs to using this group ID.
However, the following problem arises if the group a host is attempting to join is assumed to be limited to friends.
Usually, when using friend-specified peer matchmaking or server-client matchmaking, only "friends" and "friends of friends" exist within the group, so all communication is between mutual friends. However, if this type of connection by group ID is implemented without any consideration, relationships such as "friend of a friend of a friend" (where communication as mutual friends is impossible) might arise within the same group. To maintain communication between mutual friends, it is necessary to confirm that the friend you are attempting to join is the server host of the group. Use the DWC_IsServerMyself function to check whether the local host is the server host.

If there is a server migration for some reason (such as a bad connection), you sometimes find multiple servers with the same group ID. In this case, a connection is made to the group with the most connected players.

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

Revision History

5.4
Noted that the process might be blocked and not return from the function for some time.
5.3 patch 2
Reworded the note about maintaining communication between mutual friends.

For the change log prior to 5.1 PR2, click here.  


CONFIDENTIAL