#include <dwc.h>
void DWC_InitFriendsMatch(DWCUserData *userdata,
int productID,
const char *secretKey,
int sendBufSize,
int recvBufSize,
DWCFriendData friendList[],
int friendListLen);userdata |
Pointer to the DWCUserData type user data object. |
productID |
Product ID assigned by GameSpy. |
secretKey |
Secret key assigned by GameSpy (C language string). |
sendBufSize |
Size (in bytes) of the send buffer used in peer-to-peer communication. If the value is set to 0, 8 KB is used by default. |
recvBufSize |
Size (in bytes) of the receive buffer used in peer-to-peer communication. If the value is set to 0, 8 KB 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 |
Maximum number of elements in the friends list. The maximum value is 64. |
None.
Initializes the FriendsMatch library, a set of features used for matchmaking and friend management.
Call this function before calling the DWC_LoginAsync function.
Specify the pointer to the DWCUserData structure created with the DWC_CreateUserData function in userdata. Maintain this buffer until DWC_ShutdownFriendsMatch is called.
In addition to the product ID and secret Key specified by this function, the gameName value specified by the DWC_InitForDevelopment and DWC_InitForProduction functions are allocated to each game title. These are the units by which the GameSpy server's allocations take place, and they set the range for matchmaking. In general, the different market versions of a title are assigned the same values for productID, gameName, and secretKey. If you want to perform matchmaking between different game titles, adjust these parameters to match one of the titles. If you do not want to conduct peer matchmaking with friend unspecified between different market regions, you need to use a matchmaking filter. (For more on matchmaking filters, see the DWC_AddMatchKeyString function.) The gameCode setting given to the DWC_CreateUserData function determines whether a friend relationship can be formed. Suppose that players can play with anybody in the world via peer matchmaking with friend unspecified, but you want to restrict friend registrations to within markets. (In other words, you want the range of peer matchmaking with friend specified and server-client matchmaking to be restricted by market.) To accomplish this, set a separate value for each market in the gameCode passed to the DWC_InitForDevelopment and DWC_InitForProduction functions.
The sendBuffSize and recvBuffSize arguments specify the size of buffers to be used for Reliable send/receive between peers. These buffers are allocated by the DWC library after matchmaking is complete. (For information on Reliable transmission, see the DWC_SendReliable function.) A buffer of the specified size is then allocated for each target peer through the memory allocation function passed by the DWC_InitForDevelopment or DWC_InitForProduction function. If a 0 is specified here, the default size of 8 KB is allocated.
Unlike the buffer specified by the DWC_SetRecvBuffer function, the buffers whose sizes are specified here are used internally by the library.
When adjusting these buffer sizes, consider the size of the data exchanged between peers and the frequency of the data exchange and set it so that buffer overflow will not occur. In addition, even if an application does not use reliable communication, a minimum buffer region is required to perform reliable communication when the library establishes peer-to-peer connections. For details, see the Nintendo Wi-Fi Connection TWL-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 to be managed by the application using friendList and friendListLen. The application should save the friend roster along with save data. The friend roster automatically updates within the library. For details about operations performed on the friend roster, see the description of the DWC_CreateFriendKeyToken function. This function is used to create the friend information to be stored in the friend roster. 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.
If you are using the storage feature, you need to specify a provisional friend list with friendList and friendListLen even if the application does not use friend lists. If you do not specify a friend list, the login-completion callback for the data storage server set by the DWC_LoginToStorageServerAsync function will not be generated.
dwccnt and gameName arguments. Note: When using GameSpy, you must specify gameName using either the DWC_InitForDevelopment or DWC_InitForProduction function. dwccnt.For the change log prior to 5.1 PR2, click here.
CONFIDENTIAL