3 * =============================================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _keyvalues_included
36 #define _keyvalues_included
39 * KeyValue data value types
43 KvData_None = 0, /**< Type could not be identified, or no type */
44 KvData_String, /**< String value */
45 KvData_Int, /**< Integer value */
46 KvData_Float, /**< Floating point value */
47 KvData_Ptr, /**< Pointer value (sometimes called "long") */
48 KvData_WString, /**< Wide string value */
49 KvData_Color, /**< Color value */
50 KvData_UInt64, /**< Large integer value */
56 * Creates a new KeyValues structure. The Handle must always be closed.
58 * @param name Name of the root section.
59 * @param firstKey If non-empty, specifies the first key value.
60 * @param firstValue If firstKey is non-empty, specifies the first key's value.
61 * @return A Handle to a new KeyValues structure.
63 native Handle:CreateKeyValues(const String:name[], const String:firstkey[]="", const String:firstValue[]="");
66 * Sets a string value of a KeyValues key.
68 * @param kv KeyValues Handle.
69 * @param key Name of the key, or NULL_STRING.
70 * @param value String value.
72 * @error Invalid Handle.
74 native KvSetString(Handle:kv, const String:key[], const String:value[]);
77 * Sets an integer value of a KeyValues key.
79 * @param kv KeyValues Handle.
80 * @param key Name of the key, or NULL_STRING.
81 * @param value Value number.
83 * @error Invalid Handle.
85 native KvSetNum(Handle:kv, const String:key[], value);
88 * Sets a large integer value of a KeyValues key.
90 * @param kv KeyValues Handle.
91 * @param key Name of the key, or NULL_STRING.
92 * @param value Large integer value (0=High bits, 1=Low bits)
94 * @error Invalid Handle.
96 native KvSetUInt64(Handle:kv, const String:key[], const value[2]);
99 * Sets a floating point value of a KeyValues key.
101 * @param kv KeyValues Handle.
102 * @param key Name of the key, or NULL_STRING.
103 * @param value Floating point value.
105 * @error Invalid Handle.
107 native KvSetFloat(Handle:kv, const String:key[], Float:value);
110 * Sets a set of color values of a KeyValues key.
112 * @param kv KeyValues Handle.
113 * @param key Name of the key, or NULL_STRING.
114 * @param r Red value.
115 * @param g Green value.
116 * @param b Blue value.
117 * @param a Alpha value.
119 * @error Invalid Handle.
121 native KvSetColor(Handle:kv, const String:key[], r, g, b, a=0);
124 * Retrieves a string value from a KeyValues key.
126 * @param kv KeyValues Handle.
127 * @param key Name of the key, or NULL_STRING.
128 * @param value Buffer to store key value in.
129 * @param maxlength Maximum length of the value buffer.
130 * @param defvalue Optional default value to use if the key is not found.
132 * @error Invalid Handle.
134 native KvGetString(Handle:kv, const String:key[], String:value[], maxlength, const String:defvalue[]="");
137 * Retrieves an integer value from a KeyValues key.
139 * @param kv KeyValues Handle.
140 * @param key Name of the key, or NULL_STRING.
141 * @param defvalue Optional default value to use if the key is not found.
142 * @return Integer value of the key.
143 * @error Invalid Handle.
145 native KvGetNum(Handle:kv, const String:key[], defvalue=0);
148 * Retrieves a floating point value from a KeyValues key.
150 * @param kv KeyValues Handle.
151 * @param key Name of the key, or NULL_STRING.
152 * @param defvalue Optional default value to use if the key is not found.
153 * @return Floating point value of the key.
154 * @error Invalid Handle.
156 native Float:KvGetFloat(Handle:kv, const String:key[], Float:defvalue=0.0);
159 * Retrieves a set of color values from a KeyValues key.
161 * @param kv KeyValues Handle.
162 * @param key Name of the key, or NULL_STRING.
163 * @param r Red value, set by reference.
164 * @param g Green value, set by reference.
165 * @param b Blue value, set by reference.
166 * @param a Alpha value, set by reference.
168 * @error Invalid Handle.
170 native KvGetColor(Handle:kv, const String:key[], &r, &g, &b, &a);
173 * Retrieves a large integer value from a KeyValues key.
175 * @param kv KeyValues Handle.
176 * @param key Name of the key, or NULL_STRING.
177 * @param value Array to represent the large integer.
178 * @param defvalue Optional default value to use if the key is not found.
180 * @error Invalid Handle.
182 native KvGetUInt64(Handle:kv, const String:key[], value[2], defvalue[2]={0,0});
185 * Sets the current position in the KeyValues tree to the given key.
187 * @param kv KeyValues Handle.
188 * @param key Name of the key.
189 * @param create If true, and the key does not exist, it will be created.
190 * @return True if the key exists, false if it does not and was not created.
192 native bool:KvJumpToKey(Handle:kv, const String:key[], bool:create=false);
195 * Sets the current position in the KeyValues tree to the first sub key.
196 * This native adds to the internal traversal stack.
198 * @param kv KeyValues Handle.
199 * @param keyOnly If false, non-keys will be traversed (values).
200 * @return True on success, false if there was no first sub key.
201 * @error Invalid Handle.
203 native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true);
206 * Sets the current position in the KeyValues tree to the next sub key.
207 * This native does NOT add to the internal traversal stack, and thus
208 * KvGoBack() is not needed for each successive call to this function.
210 * @param kv KeyValues Handle.
211 * @param keyOnly If false, non-keys will be traversed (values).
212 * @return True on success, false if there was no next sub key.
213 * @error Invalid Handle.
215 native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true);
218 * Saves the current position in the traversal stack onto the traversal
219 * stack. This can be useful if you wish to use KvGotoNextKey() and
220 * have the previous key saved for backwards traversal.
222 * @param kv KeyValues Handle.
224 * @error Invalid Handle.
226 native KvSavePosition(Handle:kv);
229 * Removes the given key from the current position.
231 * @param kv KeyValues Handle.
232 * @param key Name of the key.
233 * @return True on success, false if key did not exist.
234 * @error Invalid Handle.
236 native bool:KvDeleteKey(Handle:kv, const String:key[]);
239 * Removes the current sub-key and attempts to set the position
240 * to the sub-key after the removed one. If no such sub-key exists,
241 * the position will be the parent key in the traversal stack.
242 * Given the sub-key having position "N" in the traversal stack, the
243 * removal will always take place from position "N-1."
245 * @param kv KeyValues Handle.
246 * @return 1 if removal succeeded and there was another key.
247 * 0 if the current node was not contained in the
248 * previous node, or no previous node exists.
249 * -1 if removal succeeded and there were no more keys,
250 * thus the state is as if KvGoBack() was called.
251 * @error Invalid Handle.
253 native KvDeleteThis(Handle:kv);
256 * Jumps back to the previous position. Returns false if there are no
257 * previous positions (i.e., at the root node). This should be called
258 * once for each successful Jump call, in order to return to the top node.
259 * This function pops one node off the internal traversal stack.
261 * @param kv KeyValues Handle.
262 * @return True on success, false if there is no higher node.
263 * @error Invalid Handle.
265 native bool:KvGoBack(Handle:kv);
268 * Sets the position back to the top node, emptying the entire node
269 * traversal history. This can be used instead of looping KvGoBack()
270 * if recursive iteration is not important.
272 * @param kv KeyValues Handle.
274 * @error Invalid Handle.
276 native KvRewind(Handle:kv);
279 * Retrieves the current section name.
281 * @param kv KeyValues Handle.
282 * @param section Buffer to store the section name.
283 * @param maxlength Maximum length of the name buffer.
284 * @return True on success, false on failure.
285 * @error Invalid Handle.
287 native bool:KvGetSectionName(Handle:kv, String:section[], maxlength);
290 * Sets the current section name.
292 * @param kv KeyValues Handle.
293 * @param section Section name.
295 * @error Invalid Handle.
297 native KvSetSectionName(Handle:kv, const String:section[]);
300 * Returns the data type at a key.
302 * @param kv KeyValues Handle.
303 * @param key Key name.
304 * @return KvDataType value of the key.
305 * @error Invalid Handle.
307 native KvDataTypes:KvGetDataType(Handle:kv, const String:key[]);
310 * Converts a KeyValues tree to a file. The tree is dumped
311 * from the current position.
313 * @param kv KeyValues Handle.
314 * @param file File to dump write to.
315 * @return True on success, false otherwise.
316 * @error Invalid Handle.
318 native bool:KeyValuesToFile(Handle:kv, const String:file[]);
321 * Converts a file to a KeyValues tree. The file is read into
322 * the current position of the tree.
324 * @param kv KeyValues Handle.
325 * @param file File to read from.
326 * @return True on success, false otherwise.
327 * @error Invalid Handle.
329 native bool:FileToKeyValues(Handle:kv, const String:file[]);
332 * Sets whether or not the KeyValues parser will read escape sequences.
333 * For example, \n would be read as a literal newline. This defaults
334 * to false for new KeyValues structures.
336 * @param kv KeyValues Handle.
337 * @param useEscapes Whether or not to read escape sequences.
339 * @error Invalid Handle.
341 native KvSetEscapeSequences(Handle:kv, bool:useEscapes);
344 * Returns the position in the jump stack; I.e. the number of calls
345 * required for KvGoBack to return to the root node. If at the root node,
348 * @param kv KeyValues Handle.
349 * @return Number of non-root nodes in the jump stack.
350 * @error Invalid Handle.
352 native KvNodesInStack(Handle:kv);
355 * Makes a new copy of all subkeys in the origin KeyValues to
356 * the destination KeyValues.
357 * NOTE: All KeyValues are processed from the current location not the root one.
359 * @param origin Origin KeyValues Handle.
360 * @param dest Destination KeyValues Handlee.
362 * @error Invalid Handle.
364 native KvCopySubkeys(Handle:origin, Handle:dest);
367 * Finds a KeyValues name by id.
369 * @param kv KeyValues Handle.
370 * @param id KeyValues id.
371 * @param name Buffer to store the name.
372 * @param maxlength Maximum length of the value buffer.
373 * @return True on success, false if id not found.
374 * @error Invalid Handle.
376 native bool:KvFindKeyById(Handle:kv, id, String:name[], maxlength);
379 * Finds a KeyValues id inside a KeyValues tree.
381 * @param kv KeyValues Handle.
382 * @param key Key name.
383 * @param id Id of the found KeyValue.
384 * @return True on success, false if key not found.
385 * @error Invalid Handle.
387 native bool:KvGetNameSymbol(Handle:kv, const String:key[], &id);
