DWC_AddMatchKeyString

Syntax

#include <dwc.h>

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

Arguments

keyID	Specify 0 when getting a new `keyID`. If you specify an additional key ID that is already in use, `valueSrc` will be reset if the same `keyString` as the one in use is passed; however, nothing will be done if a different `keyString` is passed. A maximum of 154 keys can be set with the application.
keyString	Pointer to the 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 string is accessed using this pointer and uploaded to the server.

Return Values

The 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. 0 is returned even if this function is called before DWC_InitFriendsMatch.

Description

Adds a key (of type 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.

You cannot specify an empty string ("") for a key. If an empty string is specified, the DWC_GetMatchStringValue function will return the default value.

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

Revision History

2.0.1: Added information regarding unavailable key names.
1.4.21: Made it explicit that the key ID specified is fixed at 0 when getting a new key ID.
1.4.20: Noted that empty strings cannot be specified.
1.4.20: Corrected a typo in the maximum number of keys that can be used by the application.
1.4.20: Corrected a typo in the key ID specified when a new key ID is obtained.
1.4.20: Added a precaution that identical key names cannot be used.

CONFIDENTIAL

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