1.1 --- a/plugins/include/keyvalues.inc Fri Jul 11 06:51:21 2008 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,429 +0,0 @@
1.4 -/**
1.5 - * vim: set ts=4 :
1.6 - * =============================================================================
1.7 - * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
1.8 - * =============================================================================
1.9 - *
1.10 - * This file is part of the SourceMod/SourcePawn SDK.
1.11 - *
1.12 - * This program is free software; you can redistribute it and/or modify it under
1.13 - * the terms of the GNU General Public License, version 3.0, as published by the
1.14 - * Free Software Foundation.
1.15 - *
1.16 - * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 - * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 - * details.
1.20 - *
1.21 - * You should have received a copy of the GNU General Public License along with
1.22 - * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 - *
1.24 - * As a special exception, AlliedModders LLC gives you permission to link the
1.25 - * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 - * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 - * by the Valve Corporation. You must obey the GNU General Public License in
1.28 - * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 - * this exception to all derivative works. AlliedModders LLC defines further
1.30 - * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 - * or <http://www.sourcemod.net/license.php>.
1.32 - *
1.33 - * Version: $Id$
1.34 - */
1.35 -
1.36 -#if defined _keyvalues_included
1.37 - #endinput
1.38 -#endif
1.39 -#define _keyvalues_included
1.40 -
1.41 -/**
1.42 - * KeyValue data value types
1.43 - */
1.44 -enum KvDataTypes
1.45 -{
1.46 - KvData_None = 0, /**< Type could not be identified, or no type */
1.47 - KvData_String, /**< String value */
1.48 - KvData_Int, /**< Integer value */
1.49 - KvData_Float, /**< Floating point value */
1.50 - KvData_Ptr, /**< Pointer value (sometimes called "long") */
1.51 - KvData_WString, /**< Wide string value */
1.52 - KvData_Color, /**< Color value */
1.53 - KvData_UInt64, /**< Large integer value */
1.54 - /* --- */
1.55 - KvData_NUMTYPES,
1.56 -};
1.57 -
1.58 -/**
1.59 - * Creates a new KeyValues structure. The Handle must always be closed.
1.60 - *
1.61 - * @param name Name of the root section.
1.62 - * @param firstKey If non-empty, specifies the first key value.
1.63 - * @param firstValue If firstKey is non-empty, specifies the first key's value.
1.64 - * @return A Handle to a new KeyValues structure.
1.65 - */
1.66 -native Handle:CreateKeyValues(const String:name[], const String:firstkey[]="", const String:firstValue[]="");
1.67 -
1.68 -/**
1.69 - * Sets a string value of a KeyValues key.
1.70 - *
1.71 - * @param kv KeyValues Handle.
1.72 - * @param key Name of the key, or NULL_STRING.
1.73 - * @param value String value.
1.74 - * @noreturn
1.75 - * @error Invalid Handle.
1.76 - */
1.77 -native KvSetString(Handle:kv, const String:key[], const String:value[]);
1.78 -
1.79 -/**
1.80 - * Sets an integer value of a KeyValues key.
1.81 - *
1.82 - * @param kv KeyValues Handle.
1.83 - * @param key Name of the key, or NULL_STRING.
1.84 - * @param value Value number.
1.85 - * @noreturn
1.86 - * @error Invalid Handle.
1.87 - */
1.88 -native KvSetNum(Handle:kv, const String:key[], value);
1.89 -
1.90 -/**
1.91 - * Sets a large integer value of a KeyValues key.
1.92 - *
1.93 - * @param kv KeyValues Handle.
1.94 - * @param key Name of the key, or NULL_STRING.
1.95 - * @param value Large integer value (0=High bits, 1=Low bits)
1.96 - * @noreturn
1.97 - * @error Invalid Handle.
1.98 - */
1.99 -native KvSetUInt64(Handle:kv, const String:key[], const value[2]);
1.100 -
1.101 -/**
1.102 - * Sets a floating point value of a KeyValues key.
1.103 - *
1.104 - * @param kv KeyValues Handle.
1.105 - * @param key Name of the key, or NULL_STRING.
1.106 - * @param value Floating point value.
1.107 - * @noreturn
1.108 - * @error Invalid Handle.
1.109 - */
1.110 -native KvSetFloat(Handle:kv, const String:key[], Float:value);
1.111 -
1.112 -/**
1.113 - * Sets a set of color values of a KeyValues key.
1.114 - *
1.115 - * @param kv KeyValues Handle.
1.116 - * @param key Name of the key, or NULL_STRING.
1.117 - * @param r Red value.
1.118 - * @param g Green value.
1.119 - * @param b Blue value.
1.120 - * @param a Alpha value.
1.121 - * @noreturn
1.122 - * @error Invalid Handle.
1.123 - */
1.124 -native KvSetColor(Handle:kv, const String:key[], r, g, b, a=0);
1.125 -
1.126 -/**
1.127 - * Sets a vector value of a KeyValues key.
1.128 - *
1.129 - * @param kv KeyValues Handle.
1.130 - * @param key Name of the key, or NULL_STRING.
1.131 - * @param vec Vector value.
1.132 - * @noreturn
1.133 - * @error Invalid Handle.
1.134 - */
1.135 -native KvSetVector(Handle:kv, const String:key[], const Float:vec[3]);
1.136 -
1.137 -/**
1.138 - * Retrieves a string value from a KeyValues key.
1.139 - *
1.140 - * @param kv KeyValues Handle.
1.141 - * @param key Name of the key, or NULL_STRING.
1.142 - * @param value Buffer to store key value in.
1.143 - * @param maxlength Maximum length of the value buffer.
1.144 - * @param defvalue Optional default value to use if the key is not found.
1.145 - * @noreturn
1.146 - * @error Invalid Handle.
1.147 - */
1.148 -native KvGetString(Handle:kv, const String:key[], String:value[], maxlength, const String:defvalue[]="");
1.149 -
1.150 -/**
1.151 - * Retrieves an integer value from a KeyValues key.
1.152 - *
1.153 - * @param kv KeyValues Handle.
1.154 - * @param key Name of the key, or NULL_STRING.
1.155 - * @param defvalue Optional default value to use if the key is not found.
1.156 - * @return Integer value of the key.
1.157 - * @error Invalid Handle.
1.158 - */
1.159 -native KvGetNum(Handle:kv, const String:key[], defvalue=0);
1.160 -
1.161 -/**
1.162 - * Retrieves a floating point value from a KeyValues key.
1.163 - *
1.164 - * @param kv KeyValues Handle.
1.165 - * @param key Name of the key, or NULL_STRING.
1.166 - * @param defvalue Optional default value to use if the key is not found.
1.167 - * @return Floating point value of the key.
1.168 - * @error Invalid Handle.
1.169 - */
1.170 -native Float:KvGetFloat(Handle:kv, const String:key[], Float:defvalue=0.0);
1.171 -
1.172 -/**
1.173 - * Retrieves a set of color values from a KeyValues key.
1.174 - *
1.175 - * @param kv KeyValues Handle.
1.176 - * @param key Name of the key, or NULL_STRING.
1.177 - * @param r Red value, set by reference.
1.178 - * @param g Green value, set by reference.
1.179 - * @param b Blue value, set by reference.
1.180 - * @param a Alpha value, set by reference.
1.181 - * @noreturn
1.182 - * @error Invalid Handle.
1.183 - */
1.184 -native KvGetColor(Handle:kv, const String:key[], &r, &g, &b, &a);
1.185 -
1.186 -/**
1.187 - * Retrieves a large integer value from a KeyValues key.
1.188 - *
1.189 - * @param kv KeyValues Handle.
1.190 - * @param key Name of the key, or NULL_STRING.
1.191 - * @param value Array to represent the large integer.
1.192 - * @param defvalue Optional default value to use if the key is not found.
1.193 - * @noreturn
1.194 - * @error Invalid Handle.
1.195 - */
1.196 -native KvGetUInt64(Handle:kv, const String:key[], value[2], defvalue[2]={0,0});
1.197 -
1.198 -/**
1.199 - * Retrieves a vector value from a KeyValues key.
1.200 - *
1.201 - * @param kv KeyValues Handle.
1.202 - * @param key Name of the key, or NULL_STRING.
1.203 - * @param vec Destination vector to store the value in.
1.204 - * @param defvalue Optional default value to use if the key is not found.
1.205 - * @noreturn
1.206 - * @error Invalid Handle.
1.207 - */
1.208 -native KvGetVector(Handle:kv, const String:key[], Float:vec[3], const Float:defvalue[3]={0.0, 0.0, 0.0});
1.209 -
1.210 -/**
1.211 - * Sets the current position in the KeyValues tree to the given key.
1.212 - *
1.213 - * @param kv KeyValues Handle.
1.214 - * @param key Name of the key.
1.215 - * @param create If true, and the key does not exist, it will be created.
1.216 - * @return True if the key exists, false if it does not and was not created.
1.217 - */
1.218 -native bool:KvJumpToKey(Handle:kv, const String:key[], bool:create=false);
1.219 -
1.220 -/**
1.221 - * Sets the current position in the KeyValues tree to the given key.
1.222 - *
1.223 - * @param kv KeyValues Handle.
1.224 - * @param id KeyValues id.
1.225 - * @return True if the key exists, false if it does not.
1.226 - */
1.227 -native bool:KvJumpToKeySymbol(Handle:kv, id);
1.228 -
1.229 -/**
1.230 - * Sets the current position in the KeyValues tree to the first sub key.
1.231 - * This native adds to the internal traversal stack.
1.232 - *
1.233 - * @param kv KeyValues Handle.
1.234 - * @param keyOnly If false, non-keys will be traversed (values).
1.235 - * @return True on success, false if there was no first sub key.
1.236 - * @error Invalid Handle.
1.237 - */
1.238 -native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true);
1.239 -
1.240 -/**
1.241 - * Sets the current position in the KeyValues tree to the next sub key.
1.242 - * This native does NOT add to the internal traversal stack, and thus
1.243 - * KvGoBack() is not needed for each successive call to this function.
1.244 - *
1.245 - * @param kv KeyValues Handle.
1.246 - * @param keyOnly If false, non-keys will be traversed (values).
1.247 - * @return True on success, false if there was no next sub key.
1.248 - * @error Invalid Handle.
1.249 - */
1.250 -native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true);
1.251 -
1.252 -/**
1.253 - * Saves the current position in the traversal stack onto the traversal
1.254 - * stack. This can be useful if you wish to use KvGotoNextKey() and
1.255 - * have the previous key saved for backwards traversal.
1.256 - *
1.257 - * @param kv KeyValues Handle.
1.258 - * @noreturn
1.259 - * @error Invalid Handle.
1.260 - */
1.261 -native KvSavePosition(Handle:kv);
1.262 -
1.263 -/**
1.264 - * Removes the given key from the current position.
1.265 - *
1.266 - * @param kv KeyValues Handle.
1.267 - * @param key Name of the key.
1.268 - * @return True on success, false if key did not exist.
1.269 - * @error Invalid Handle.
1.270 - */
1.271 -native bool:KvDeleteKey(Handle:kv, const String:key[]);
1.272 -
1.273 -/**
1.274 - * Removes the current sub-key and attempts to set the position
1.275 - * to the sub-key after the removed one. If no such sub-key exists,
1.276 - * the position will be the parent key in the traversal stack.
1.277 - * Given the sub-key having position "N" in the traversal stack, the
1.278 - * removal will always take place from position "N-1."
1.279 - *
1.280 - * @param kv KeyValues Handle.
1.281 - * @return 1 if removal succeeded and there was another key.
1.282 - * 0 if the current node was not contained in the
1.283 - * previous node, or no previous node exists.
1.284 - * -1 if removal succeeded and there were no more keys,
1.285 - * thus the state is as if KvGoBack() was called.
1.286 - * @error Invalid Handle.
1.287 - */
1.288 -native KvDeleteThis(Handle:kv);
1.289 -
1.290 -/**
1.291 - * Jumps back to the previous position. Returns false if there are no
1.292 - * previous positions (i.e., at the root node). This should be called
1.293 - * once for each successful Jump call, in order to return to the top node.
1.294 - * This function pops one node off the internal traversal stack.
1.295 - *
1.296 - * @param kv KeyValues Handle.
1.297 - * @return True on success, false if there is no higher node.
1.298 - * @error Invalid Handle.
1.299 - */
1.300 -native bool:KvGoBack(Handle:kv);
1.301 -
1.302 -/**
1.303 - * Sets the position back to the top node, emptying the entire node
1.304 - * traversal history. This can be used instead of looping KvGoBack()
1.305 - * if recursive iteration is not important.
1.306 - *
1.307 - * @param kv KeyValues Handle.
1.308 - * @noreturn
1.309 - * @error Invalid Handle.
1.310 - */
1.311 -native KvRewind(Handle:kv);
1.312 -
1.313 -/**
1.314 - * Retrieves the current section name.
1.315 - *
1.316 - * @param kv KeyValues Handle.
1.317 - * @param section Buffer to store the section name.
1.318 - * @param maxlength Maximum length of the name buffer.
1.319 - * @return True on success, false on failure.
1.320 - * @error Invalid Handle.
1.321 - */
1.322 -native bool:KvGetSectionName(Handle:kv, String:section[], maxlength);
1.323 -
1.324 -/**
1.325 - * Sets the current section name.
1.326 - *
1.327 - * @param kv KeyValues Handle.
1.328 - * @param section Section name.
1.329 - * @noreturn
1.330 - * @error Invalid Handle.
1.331 - */
1.332 -native KvSetSectionName(Handle:kv, const String:section[]);
1.333 -
1.334 -/**
1.335 - * Returns the data type at a key.
1.336 - *
1.337 - * @param kv KeyValues Handle.
1.338 - * @param key Key name.
1.339 - * @return KvDataType value of the key.
1.340 - * @error Invalid Handle.
1.341 - */
1.342 -native KvDataTypes:KvGetDataType(Handle:kv, const String:key[]);
1.343 -
1.344 -/**
1.345 - * Converts a KeyValues tree to a file. The tree is dumped
1.346 - * from the current position.
1.347 - *
1.348 - * @param kv KeyValues Handle.
1.349 - * @param file File to dump write to.
1.350 - * @return True on success, false otherwise.
1.351 - * @error Invalid Handle.
1.352 - */
1.353 -native bool:KeyValuesToFile(Handle:kv, const String:file[]);
1.354 -
1.355 -/**
1.356 - * Converts a file to a KeyValues tree. The file is read into
1.357 - * the current position of the tree.
1.358 - *
1.359 - * @param kv KeyValues Handle.
1.360 - * @param file File to read from.
1.361 - * @return True on success, false otherwise.
1.362 - * @error Invalid Handle.
1.363 - */
1.364 -native bool:FileToKeyValues(Handle:kv, const String:file[]);
1.365 -
1.366 -/**
1.367 - * Sets whether or not the KeyValues parser will read escape sequences.
1.368 - * For example, \n would be read as a literal newline. This defaults
1.369 - * to false for new KeyValues structures.
1.370 - *
1.371 - * @param kv KeyValues Handle.
1.372 - * @param useEscapes Whether or not to read escape sequences.
1.373 - * @noreturn
1.374 - * @error Invalid Handle.
1.375 - */
1.376 -native KvSetEscapeSequences(Handle:kv, bool:useEscapes);
1.377 -
1.378 -/**
1.379 - * Returns the position in the jump stack; I.e. the number of calls
1.380 - * required for KvGoBack to return to the root node. If at the root node,
1.381 - * 0 is returned.
1.382 - *
1.383 - * @param kv KeyValues Handle.
1.384 - * @return Number of non-root nodes in the jump stack.
1.385 - * @error Invalid Handle.
1.386 - */
1.387 -native KvNodesInStack(Handle:kv);
1.388 -
1.389 -/**
1.390 - * Makes a new copy of all subkeys in the origin KeyValues to
1.391 - * the destination KeyValues.
1.392 - * NOTE: All KeyValues are processed from the current location not the root one.
1.393 - *
1.394 - * @param origin Origin KeyValues Handle.
1.395 - * @param dest Destination KeyValues Handlee.
1.396 - * @noreturn
1.397 - * @error Invalid Handle.
1.398 - */
1.399 -native KvCopySubkeys(Handle:origin, Handle:dest);
1.400 -
1.401 -/**
1.402 - * Finds a KeyValues name by id.
1.403 - *
1.404 - * @param kv KeyValues Handle.
1.405 - * @param id KeyValues id.
1.406 - * @param name Buffer to store the name.
1.407 - * @param maxlength Maximum length of the value buffer.
1.408 - * @return True on success, false if id not found.
1.409 - * @error Invalid Handle.
1.410 - */
1.411 -native bool:KvFindKeyById(Handle:kv, id, String:name[], maxlength);
1.412 -
1.413 -/**
1.414 - * Finds a KeyValues id inside a KeyValues tree.
1.415 - *
1.416 - * @param kv KeyValues Handle.
1.417 - * @param key Key name.
1.418 - * @param id Id of the found KeyValue.
1.419 - * @return True on success, false if key not found.
1.420 - * @error Invalid Handle.
1.421 - */
1.422 -native bool:KvGetNameSymbol(Handle:kv, const String:key[], &id);
1.423 -
1.424 -/**
1.425 - * Retrieves the current section id.
1.426 - *
1.427 - * @param kv KeyValues Handle.
1.428 - * @param id Id of the current section.
1.429 - * @return True on success, false on failure.
1.430 - * @error Invalid Handle.
1.431 - */
1.432 -native bool:KvGetSectionSymbol(Handle:kv, &id);
