DWC_AddMatchKey*

Syntax

#include <dwc.h>

u8 DWC_AddMatchKeyInt( u8 keyID,
                       const char* keyString,
                       const int* valueSrc );

u8 DWC_AddMatchKeyString( u8 keyID,
                          const char* keyString,
                          const char* valueSrc );

Description

This function adds a key (of type int or char*) used as a matchmaking condition.

The added key can be used in the matchmaking condition string for the DWC_ConnectToAnybodyAsync function or in the player ranking callback function (DWCEvalPlayerCallback) for the DWC_ConnectToAnybodyAsync and DWC_ConnectToFriendsAsync functions.

All data related to the added key is cleared when the matchmaking completes, so the key must be registered again the next time matchmaking is performed.

While there is no limit to the length of the keyString or valueSrc value for calling this function, when the values set for the overall application are used as strings, they must total 2048 or fewer bytes.

It is no problem if strings of several to dozens of bytes are in keyString/valueSrc, but do not set any relatively large amounts of data, such as text encoded as binary data.

A blank character (" ") cannot be specified in the string corresponding to the key. If a blank character is specified, the default value is returned by the DWC_GetMatchStringValue function.


Note: Not all strings can be used for key names. Do not use the following key names.

country region hostname gamename gamever hostport
mapname gametype gamevariant numplayers numteams maxplayers
gamemode teamplay fraglimit teamfraglimit timeelapsed timelimit
roundtime roundelapsed password groupid player_ score_
skill_ ping_ team_ deaths_ pid_ team_t
score_t dwc_pid dwc_mtype dwc_mresv dwc_mver dwc_eval

Arguments

keyID Be sure to specify 0 if a new key ID is to be obtained.
If a key ID that has already been added is specified, valueSrc is updated as long as the specified keyString is the same as the original, but nothing is done and 0 is returned if it is different.
In addition, the application can set a maximum of 154 keys.
keyString Pointer to the character string that identifies the key.
The string is copied and saved within the library.
Do not use the same key name with a different key ID.
valueSrc Pointer to the value that corresponds to the key. When the GameSpy server performs polling, the value is referenced from this pointer and uploaded to the GameSpy server. The pointer reference destination must be maintained until matchmaking is complete.

Return Values

keyID Key ID for the added key.
0 is returned when the key ID could not be added because of a parameter error or because the upper limit for the configured key setting was exceeded.
Even if this function is called before calling DWC_Init, 0 is returned.

See Also

DWC_GetMatch*Value
DWC_ConnectToAnybodyAsync
DWC_ConnectToFriendsAsync
DWCEvalPlayerCallback

Revision History

2008/04/24 Added a note related to the handling of blank characters when using DWC_GetMatchStringValue
2008/04/15 Clarified that the key ID to be specified when obtaining a new key ID is fixed at 0.
2008/04/15 Added a note about key names.
2008/04/15 Revised the incorrect description of the maximum number of keys that can be used by an application.
2006/04/26 Integrated DWC_AddMatchKeyInt and DWC_AddMatchKeyString
2006/04/26 Added a list of key names that cannot be specified by the application.
2005/11/14 Added a mention of limitations on values to be set.
2005/07/22 Initial version.


CONFIDENTIAL