DWC_InitFriendsMatch

Syntax

#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 management.

Call this function before calling DWC_LoginAsync.

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.
Unlike the buffer specified by the DWC_SetRecvBuffer function, the buffer whose size is specified here is used internally by the library. 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. In addition, even if an application does not use Reliable communication, a minimum buffer region is required in order to perform Reliable communication when the library establishes peer-to-peer connections. 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. The maximum 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

Revision History

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


CONFIDENTIAL