1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows"> 8<title>DWC_AddMatchKeyString</title> 9<LINK rel="stylesheet" href="../css/nitro.css" type="text/css"> 10</head> 11 12<body> 13<a name="dwc__match_8h_1a6dc592558f9f69faff4f1911782f3a8"></a> 14<h1 align="left">DWC_AddMatchKeyString</h1> 15<h2>Syntax</h2> 16 17<dl> 18 <dd> 19<CODE>#include <dwc.h></CODE><BR> 20 <BR> 21 <PRE><CODE>u8 <a href=DWC_AddMatchKeyString.html#dwc__match_8h_1a6dc592558f9f69faff4f1911782f3a8>DWC_AddMatchKeyString</a>(u8 keyID, 22 const char *keyString, 23 const char *valueSrc);</CODE></PRE></dd> 24</dl> 25 26<h2>Arguments</h2> 27 28<TABLE border="1" width="100%"> 29 <TBODY> 30 31 <TR> 32<TD width="13%"><EM><STRONG>keyID</STRONG></EM></TD> 33<TD width="87%">Specify 0 when getting a new <CODE>keyID</CODE>.<br>If you specify an additional key ID that is already in use, <CODE>valueSrc</CODE> will be reset if the same <CODE>keyString</CODE> as the one in use is passed; however, nothing will be done if a different <CODE>keyString</CODE> is passed. A maximum of 154 keys can be set with the application.</TD> 34 </TR> 35 36 <TR> 37<TD width="13%"><EM><STRONG>keyString</STRONG></EM></TD> 38<TD width="87%">Pointer to the string that identifies the key.<br>The string is copied and saved within the library.<br>Do not use the same key name with a different key ID.</TD> 39 </TR> 40 41 <TR> 42<TD width="13%"><EM><STRONG>valueSrc</STRONG></EM></TD> 43<TD width="87%">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.</TD> 44 </TR> 45 46 </TBODY> 47</TABLE> 48 49<h2>Return Values</h2> 50 51<p>The key ID for the added key. <CODE>0</CODE> 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. <CODE>0</CODE> is returned even if this function is called before <A href="DWC_InitFriendsMatch.html"><CODE>DWC_InitFriendsMatch</CODE></a>.</p> 52 53<H2>Description</H2> 54<p>Adds a key (of type <CODE>char*</CODE>) used as a matchmaking condition.</p><p>The added key can be used in the matchmaking condition string for the <CODE><A href="DWC_ConnectToAnybodyAsync.html">DWC_ConnectToAnybodyAsync</A></CODE> function or in the player ranking callback function (<CODE><A href="DWCEvalPlayerCallback.html">DWCEvalPlayerCallback</A></CODE>) for the <CODE><A href="DWC_ConnectToAnybodyAsync.html">DWC_ConnectToAnybodyAsync</A></CODE> and <A href="DWC_ConnectToFriendsAsync.html"><CODE>DWC_ConnectToFriendsAsync</CODE></A> functions.</p><p>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.</p><p>While there is no limit to the length of the <CODE>keyString</CODE> or <CODE>valueSrc</CODE> value for calling this function, when the values set for the overall application are used as strings, they must total 2048 or fewer bytes.</p><p>It is no problem if strings of several to dozens of bytes are in <EM><STRONG><CODE>keyString</CODE></STRONG></EM>/<EM><STRONG><CODE>valueSrc</CODE></STRONG></EM>, but do not set any relatively large amounts of data, such as text encoded as binary data.</p><p>You cannot specify an empty string ("") for a key. If an empty string is specified, the <a href=DWC_GetMatchStringValue.html#dwc__match_8h_1d02811d6603b29dc1b7cd6aa75bec05a><CODE>DWC_GetMatchStringValue</CODE></a> function will return the default value.</p><p>Note: Not all strings can be used for key names. Do not use the following key names.</p><p><table border="1"><tr><td><br>country<br></td><td><br>region<br></td><td><br>hostname<br></td><td><br>gamename<br></td><td><br>gamever<br></td><td><br>hostport<br></td><td><br>mapname<br></td><td><br>gametype<br></td><td><br>gamevariant<br></td></tr><tr><td><br>numplayers<br></td><td><br>numteams<br></td><td><br>maxplayers<br></td><td><br>gamemode<br></td><td><br>teamplay<br></td><td><br>fraglimit<br></td><td><br>teamfraglimit<br></td><td><br>timeelapsed<br></td><td><br>timelimit<br></td></tr><tr><td><br>roundtime<br></td><td><br>roundelapsed<br></td><td><br>password<br></td><td><br>groupid<br></td><td><br>player_<br></td><td><br>score_<br></td><td><br>skill_<br></td><td><br>ping_<br></td><td><br>team_<br></td></tr><tr><td><br>deaths_<br></td><td><br>pid_<br></td><td><br>team_t<br></td><td><br>score_t<br></td><td><br>dwc_pid<br></td><td><br>dwc_mtype<br></td><td><br>dwc_mresv<br></td><td><br>dwc_mver<br></td><td><br>dwc_eval<br></td></tr></table></p> 55 56<H2>Revision History</H2> 57<DL> 58 59<DT><para>2.0.1</DT> 60<DD>Added information regarding unavailable key names.</DD> 61 62<DT><para>1.4.21</DT> 63<DD>Made it explicit that the key ID specified is fixed at 0 when getting a new key ID.</DD> 64 65<DT><para>1.4.20</DT> 66<DD>Noted that empty strings cannot be specified.</DD> 67 68<DT><para>1.4.20</DT> 69<DD>Corrected a typo in the maximum number of keys that can be used by the application.</DD> 70 71<DT><para>1.4.20</DT> 72<DD>Corrected a typo in the key ID specified when a new key ID is obtained.</DD> 73 74<DT><para>1.4.20</DT> 75<DD>Added a precaution that identical key names cannot be used.</DD> 76 77</DL> 78<hr><p>CONFIDENTIAL</p></body> 79</html> 80