DWC_InitFriendsMatch

C Specification

#include <dwc.h>

void DWC_InitFriendsMatch( DWCFriendsMatchControl* dwccnt,
                           DWCUserData* userdata,
                           int productID,
                           const char* gameName,
                           const char* secretKey,
                           int sendBufSize,
                           int recvBufSize,
                           DWCFriendData friendList[],
                           int friendListLen );

Description

Initializes the FriendsMatch Library (function group) used for matchmaking and friend managment.

Call this function before calling the DWC_LoginAsync function.

The dwccnt buffer is used to control the FriendsMatch Library. Using the application, allocate a buffer large enough for the DWCFriendsMatchControl structure, and maintain that buffer until DWC_ShutdownFriendsMatch is called.

Specify the pointer to the DWCUserData structure created with DWC_CreateUserData in userdata. Maintain this buffer until DWC_ShutdownFriendsMatch is called.

productID, gameName, and secretKey are assigned separately for each game title to create a communication group. These communication groups are used to assign GameSpy servers and to configure the ranges for matchmaking and friend relationship creation. If you want to configure the ranges within the same game type or game title based on the market region (for example, so that Japanese and North American game versions cannot communicate), be sure to use a namespace that can be created using the DWC_CreateUserData function.

The DWC library allocates sendBuffSize and recvBuffSize after matchmaking has completed, and designates a buffer size for reliable network communications between DS units. A buffer of the same size will then be allocated for each connection-destination DS using the memory allocation function passed by the DWC_SetMemFunc function. If a 0 is specified here, the default of 8 kilobytes is allocated.
This function specifies the size of the buffer that will be used internally by the library. This buffer is different from the buffer specified by DWC_SetRecvBuffer. When adjusting buffer size, set it so that the size of the data exchanged between DS units and the frequency the data exchange does not cause the buffer to overflow. A region of at least some minimal size is required because Reliable communications are used to establish the peer-to-peer connection even if the application is not set to use Reliable communications. For details, see the Nintendo Wi-Fi Connection NITRO-DWC Programming Manual.
When the send/receive buffer size is reduced, it is possible to make adjustments so that the buffer does not overflow by using the DWC_SetSendSplitMax function to reduce the maximum size of the send data.

Specify the friend roster the application is supposed to manage in friendList and friendListLen. The application should back up the friend roster on the DS card. The friend roster automatically updates within the library. For details about friend roster processing, see the descriptions for the DWC_CreateExchangeToken / DWC_CreateFriendKeyToken functions that create friend information for storage in the friend roster. Furthermore, because the friend roster uses the passed buffer without making a copy in the library, keep the entity in the application until the DWC_ShutdownFriendsMatch function is called.

Arguments

dwccnt Pointer to the FriendsMatch Library control object.
userdata Pointer to the type DWCUserData user data object.
productID The product ID assigned by GameSpy.
gameName The game name assigned by GameSpy (C language string).
secretKey The secret key assigned by GameSpy (C language string).
sendBufSize The size of the send buffer used in network communications between DS consoles. If the value is set to 0, 8 Kbytes is used by default.
recvBufSize The size of the receive buffer used in network communications between DS consoles. If the value is set to 0, 8 Kbytes is used by default.
friendList Pointer to a friend roster for which an array with the maximum number of elements was allocated (NULL if unused).
friendListLen The maximum number of elements in the friends list. Max value is 64.

Return Values

None.

See Also

DWC_SetMemFunc, DWC_ProcessFriendsMatch , DWC_ShutdownFriendsMatch , DWC_CreateUserData, DWC_LoginAsync, DWC_CreateExchangeToken, DWC_CreateFriendKeyToken, DWC_SendReliable, DWC_SetSendSplitMax, DWC_SetRecvBuffer

Revision History

06/05/2006 Added explanations about the arguments sendBufSize and recvBufSize
01/31/2006 Set up a link to the FriendsMatch Library, and deleted the explanation of terminology
01/18/2006 Added a description that the maximum value of the friendListLen argument is 64
12/16/2005 Revisions
10/26/2005 Revisions
07/22/2005 Initial version