faluco@654: /** faluco@654: * vim: set ts=4 : faluco@654: * =============================================================== faluco@654: * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. faluco@654: * =============================================================== faluco@654: * faluco@654: * This file is part of the SourceMod/SourcePawn SDK. This file may only be used faluco@654: * or modified under the Terms and Conditions of its License Agreement, which is found faluco@654: * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins faluco@654: * may change at any time. To view the latest information, see: faluco@654: * http://www.sourcemod.net/license.php faluco@654: * faluco@654: * Version: $Id$ faluco@654: */ faluco@654: faluco@654: #if defined _keyvalues_included faluco@654: #endinput faluco@654: #endif faluco@654: #define _keyvalues_included faluco@654: faluco@654: /** faluco@654: * KeyValue data value types faluco@654: */ faluco@654: enum KvDataTypes faluco@654: { faluco@654: KvData_None = 0, /**< Type could not be identified, or no type */ faluco@654: KvData_String, /**< String value */ faluco@654: KvData_Int, /**< Integer value */ faluco@654: KvData_Float, /**< Floating point value */ faluco@654: KvData_Ptr, /**< Pointer value (sometimes called "long") */ faluco@654: KvData_WString, /**< Wide string value */ faluco@654: KvData_Color, /**< Color value */ faluco@654: KvData_UInt64, /**< Large integer value */ faluco@654: /* --- */ faluco@654: KvData_NUMTYPES, faluco@654: }; faluco@654: faluco@654: /** faluco@654: * Creates a new KeyValues structure. The Handle must always be closed. faluco@654: * faluco@654: * @param name Name of the root section. faluco@654: * @param firstKey If non-empty, specifies the first key value. faluco@654: * @param firstValue If firstKey is non-empty, specifies the first key's value. faluco@654: * @return A Handle to a new KeyValues structure. faluco@654: */ dvander@725: native Handle:CreateKeyValues(const String:name[], const String:firstkey[]="", const String:firstValue[]=""); faluco@654: faluco@654: /** faluco@654: * Sets a string value of a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param value String value. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvSetString(Handle:kv, const String:key[], const String:value[]); faluco@654: faluco@654: /** faluco@654: * Sets an integer value of a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param value Value number. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvSetNum(Handle:kv, const String:key[], value); faluco@654: faluco@654: /** faluco@654: * Sets a large integer value of a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param value Large integer value (0=High bits, 1=Low bits) faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ dvander@816: native KvSetUInt64(Handle:kv, const String:key[], const value[2]); faluco@654: faluco@654: /** faluco@654: * Sets a floating point value of a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param value Floating point value. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvSetFloat(Handle:kv, const String:key[], Float:value); faluco@654: faluco@654: /** faluco@654: * Sets a set of color values of a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param r Red value. faluco@654: * @param g Green value. faluco@654: * @param b Blue value. faluco@654: * @param a Alpha value. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvSetColor(Handle:kv, const String:key[], r, g, b, a=0); faluco@654: faluco@654: /** faluco@654: * Retrieves a string value from a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param value Buffer to store key value in. faluco@654: * @param maxlength Maximum length of the value buffer. faluco@654: * @param defvalue Optional default value to use if the key is not found. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvGetString(Handle:kv, const String:key[], String:value[], maxlength, const String:defvalue[]=""); faluco@654: faluco@654: /** faluco@654: * Retrieves an integer value from a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param defvalue Optional default value to use if the key is not found. faluco@654: * @return Integer value of the key. faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvGetNum(Handle:kv, const String:key[], defvalue=0); faluco@654: faluco@654: /** faluco@654: * Retrieves a floating point value from a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param defvalue Optional default value to use if the key is not found. faluco@654: * @return Floating point value of the key. faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native Float:KvGetFloat(Handle:kv, const String:key[], Float:defvalue=0.0); faluco@654: faluco@654: /** faluco@654: * Retrieves a set of color values from a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param r Red value, set by reference. faluco@654: * @param g Green value, set by reference. faluco@654: * @param b Blue value, set by reference. faluco@654: * @param a Alpha value, set by reference. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvGetColor(Handle:kv, const String:key[], &r, &g, &b, &a); faluco@654: faluco@654: /** faluco@654: * Retrieves a large integer value from a KeyValues key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param value Array to represent the large integer. faluco@654: * @param defvalue Optional default value to use if the key is not found. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ dvander@816: native KvGetUInt64(Handle:kv, const String:key[], value[2], defvalue[2]={0,0}); faluco@654: faluco@654: /** faluco@654: * Sets the current position in the KeyValues tree to the given key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Name of the key. faluco@654: * @param create If true, and the key does not exist, it will be created. faluco@654: * @return True if the key exists, false if it does not and was not created. faluco@654: */ faluco@654: native bool:KvJumpToKey(Handle:kv, const String:key[], bool:create=false); faluco@654: faluco@654: /** faluco@654: * Sets the current position in the KeyValues tree to the first sub key. dvander@753: * This native adds to the internal traversal stack. faluco@654: * faluco@654: * @param kv KeyValues Handle. dvander@753: * @param keyOnly If false, non-keys will be traversed (values). faluco@654: * @return True on success, false if there was no first sub key. faluco@654: * @error Invalid Handle. faluco@654: */ dvander@753: native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true); faluco@654: faluco@654: /** faluco@654: * Sets the current position in the KeyValues tree to the next sub key. dvander@753: * This native does NOT add to the internal traversal stack, and thus dvander@753: * KvGoBack() is not needed for each successive call to this function. faluco@654: * faluco@654: * @param kv KeyValues Handle. dvander@753: * @param keyOnly If false, non-keys will be traversed (values). faluco@654: * @return True on success, false if there was no next sub key. faluco@654: * @error Invalid Handle. faluco@654: */ dvander@753: native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true); dvander@753: dvander@753: /** dvander@753: * Saves the current position in the traversal stack onto the traversal dvander@753: * stack. This can be useful if you wish to use KvGotoNextKey() and dvander@753: * have the previous key saved for backwards traversal. dvander@753: * dvander@753: * @param kv KeyValues Handle. dvander@753: * @noreturn dvander@753: * @error Invalid Handle. dvander@753: */ dvander@753: native KvSavePosition(Handle:kv); faluco@654: faluco@654: /** dvander@743: * Removes the given key from the current position. dvander@743: * dvander@743: * @param kv KeyValues Handle. dvander@743: * @param key Name of the key. dvander@743: * @return True on success, false if key did not exist. dvander@743: * @error Invalid Handle. dvander@743: */ dvander@743: native bool:KvDeleteKey(Handle:kv, const String:key[]); dvander@743: dvander@743: /** dvander@753: * Removes the current sub-key and attempts to set the position dvander@753: * to the sub-key after the removed one. If no such sub-key exists, dvander@753: * the position will be the parent key in the traversal stack. dvander@753: * Given the sub-key having position "N" in the traversal stack, the dvander@753: * removal will always take place from position "N-1." dvander@743: * dvander@743: * @param kv KeyValues Handle. dvander@753: * @return 1 if removal succeeded and there was another key. dvander@753: * 0 if the current node was not contained in the dvander@753: * previous node, or no previous node exists. dvander@753: * -1 if removal succeeded and there were no more keys, dvander@753: * thus the state is as if KvGoBack() was called. dvander@743: * @error Invalid Handle. dvander@743: */ dvander@753: native KvDeleteThis(Handle:kv); dvander@743: dvander@743: /** faluco@654: * Jumps back to the previous position. Returns false if there are no faluco@654: * previous positions (i.e., at the root node). This should be called faluco@654: * once for each successful Jump call, in order to return to the top node. dvander@753: * This function pops one node off the internal traversal stack. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @return True on success, false if there is no higher node. faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native bool:KvGoBack(Handle:kv); faluco@654: faluco@654: /** faluco@654: * Sets the position back to the top node, emptying the entire node faluco@654: * traversal history. This can be used instead of looping KvGoBack() faluco@654: * if recursive iteration is not important. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvRewind(Handle:kv); faluco@654: faluco@654: /** faluco@654: * Retrieves the current section name. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param section Buffer to store the section name. faluco@654: * @param maxlength Maximum length of the name buffer. faluco@654: * @return True on success, false on failure. faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native bool:KvGetSectionName(Handle:kv, String:section[], maxlength); faluco@654: faluco@654: /** faluco@654: * Sets the current section name. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param section Section name. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvSetSectionName(Handle:kv, const String:section[]); faluco@654: faluco@654: /** faluco@654: * Returns the data type at a key. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param key Key name. faluco@654: * @return KvDataType value of the key. faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvDataTypes:KvGetDataType(Handle:kv, const String:key[]); faluco@654: faluco@654: /** faluco@654: * Converts a KeyValues tree to a file. The tree is dumped faluco@654: * from the current position. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param file File to dump write to. faluco@654: * @return True on success, false otherwise. faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native bool:KeyValuesToFile(Handle:kv, const String:file[]); faluco@654: faluco@654: /** faluco@654: * Converts a file to a KeyValues tree. The file is read into faluco@654: * the current position of the tree. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param file File to read from. faluco@654: * @return True on success, false otherwise. faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native bool:FileToKeyValues(Handle:kv, const String:file[]); faluco@654: faluco@654: /** faluco@654: * Sets whether or not the KeyValues parser will read escape sequences. faluco@654: * For example, \n would be read as a literal newline. This defaults faluco@654: * to false for new KeyValues structures. faluco@654: * faluco@654: * @param kv KeyValues Handle. faluco@654: * @param useEscapes Whether or not to read escape sequences. faluco@654: * @noreturn faluco@654: * @error Invalid Handle. faluco@654: */ faluco@654: native KvSetEscapeSequences(Handle:kv, bool:useEscapes); dvander@750: dvander@750: /** dvander@750: * Returns the position in the jump stack; I.e. the number of calls dvander@750: * required for KvGoBack to return to the root node. If at the root node, dvander@750: * 0 is returned. dvander@750: * dvander@750: * @param kv KeyValues Handle. dvander@750: * @return Number of non-root nodes in the jump stack. dvander@750: * @error Invalid Handle. dvander@750: */ dvander@750: native KvNodesInStack(Handle:kv);