DWC_AddMatchKey*

C Specification

#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*) for use as a matchmaking index.

The added key can be used in the matchmaking condition string of the functions DWC_ConnectToAnybodyAsync andDWC_ConnectToFriendsAsync as well as in the player evaluation callback (DWCEvalPlayerCallback).

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

While there is no limit to the length of the keyString/valueSrc value when calling this function once, when the values for the overall application that are set 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.


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 To configure and set a key ID, pass the key ID to this argument.
To get a new keyID, set a value less than DWC_QR2_GAME_KEY_START (such as 0).
If an additional key ID already in use is specified, valueSrc is reset if a keyString the same as the one in use is passed, but nothing will be done if a different keyString is passed.
A maximum of 153 keys can be set with the application.
keyString Pointer to (the character string that identifies) the key name.
The character string is copied and maintained in the library.
valueSrc Pointer to the value/character string that corresponds to the key. When the GameSpy server performs polling, the value or character string corresponding to the key is referenced from this pointer and uploaded to the 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

04/26/2006 Combined DWC_AddMatchKeyInt and DWC_AddMatchKeyString and added a list of index keys that cannot be set
11/14/2005 Added description regarding restrictions on values that can be set
07/22/2005 Initial release.