dvander@2168: /**
dvander@2168: * vim: set ts=4 :
dvander@2168: * =============================================================================
dvander@2168: * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
dvander@2168: * =============================================================================
dvander@2168: *
dvander@2168: * This file is part of the SourceMod/SourcePawn SDK.
dvander@2168: *
dvander@2168: * This program is free software; you can redistribute it and/or modify it under
dvander@2168: * the terms of the GNU General Public License, version 3.0, as published by the
dvander@2168: * Free Software Foundation.
dvander@2168: *
dvander@2168: * This program is distributed in the hope that it will be useful, but WITHOUT
dvander@2168: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
dvander@2168: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
dvander@2168: * details.
dvander@2168: *
dvander@2168: * You should have received a copy of the GNU General Public License along with
dvander@2168: * this program. If not, see .
dvander@2168: *
dvander@2168: * As a special exception, AlliedModders LLC gives you permission to link the
dvander@2168: * code of this program (as well as its derivative works) to "Half-Life 2," the
dvander@2168: * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
dvander@2168: * by the Valve Corporation. You must obey the GNU General Public License in
dvander@2168: * all respects for all other code used. Additionally, AlliedModders LLC grants
dvander@2168: * this exception to all derivative works. AlliedModders LLC defines further
dvander@2168: * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
dvander@2168: * or .
dvander@2168: *
dvander@2168: * Version: $Id$
dvander@2168: */
dvander@2168:
dvander@2168: #if defined _keyvalues_included
dvander@2168: #endinput
dvander@2168: #endif
dvander@2168: #define _keyvalues_included
dvander@2168:
dvander@2168: /**
dvander@2168: * KeyValue data value types
dvander@2168: */
dvander@2168: enum KvDataTypes
dvander@2168: {
dvander@2168: KvData_None = 0, /**< Type could not be identified, or no type */
dvander@2168: KvData_String, /**< String value */
dvander@2168: KvData_Int, /**< Integer value */
dvander@2168: KvData_Float, /**< Floating point value */
dvander@2168: KvData_Ptr, /**< Pointer value (sometimes called "long") */
dvander@2168: KvData_WString, /**< Wide string value */
dvander@2168: KvData_Color, /**< Color value */
dvander@2168: KvData_UInt64, /**< Large integer value */
dvander@2168: /* --- */
dvander@2168: KvData_NUMTYPES,
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * Creates a new KeyValues structure. The Handle must always be closed.
dvander@2168: *
dvander@2168: * @param name Name of the root section.
dvander@2168: * @param firstKey If non-empty, specifies the first key value.
dvander@2168: * @param firstValue If firstKey is non-empty, specifies the first key's value.
dvander@2168: * @return A Handle to a new KeyValues structure.
dvander@2168: */
dvander@2168: native Handle:CreateKeyValues(const String:name[], const String:firstkey[]="", const String:firstValue[]="");
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets a string value of a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param value String value.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSetString(Handle:kv, const String:key[], const String:value[]);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets an integer value of a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param value Value number.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSetNum(Handle:kv, const String:key[], value);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets a large integer value of a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param value Large integer value (0=High bits, 1=Low bits)
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSetUInt64(Handle:kv, const String:key[], const value[2]);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets a floating point value of a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param value Floating point value.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSetFloat(Handle:kv, const String:key[], Float:value);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets a set of color values of a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param r Red value.
dvander@2168: * @param g Green value.
dvander@2168: * @param b Blue value.
dvander@2168: * @param a Alpha value.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSetColor(Handle:kv, const String:key[], r, g, b, a=0);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets a vector value of a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param vec Vector value.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSetVector(Handle:kv, const String:key[], const Float:vec[3]);
dvander@2168:
dvander@2168: /**
dvander@2168: * Retrieves a string value from a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param value Buffer to store key value in.
dvander@2168: * @param maxlength Maximum length of the value buffer.
dvander@2168: * @param defvalue Optional default value to use if the key is not found.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvGetString(Handle:kv, const String:key[], String:value[], maxlength, const String:defvalue[]="");
dvander@2168:
dvander@2168: /**
dvander@2168: * Retrieves an integer value from a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param defvalue Optional default value to use if the key is not found.
dvander@2168: * @return Integer value of the key.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvGetNum(Handle:kv, const String:key[], defvalue=0);
dvander@2168:
dvander@2168: /**
dvander@2168: * Retrieves a floating point value from a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param defvalue Optional default value to use if the key is not found.
dvander@2168: * @return Floating point value of the key.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native Float:KvGetFloat(Handle:kv, const String:key[], Float:defvalue=0.0);
dvander@2168:
dvander@2168: /**
dvander@2168: * Retrieves a set of color values from a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param r Red value, set by reference.
dvander@2168: * @param g Green value, set by reference.
dvander@2168: * @param b Blue value, set by reference.
dvander@2168: * @param a Alpha value, set by reference.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvGetColor(Handle:kv, const String:key[], &r, &g, &b, &a);
dvander@2168:
dvander@2168: /**
dvander@2168: * Retrieves a large integer value from a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param value Array to represent the large integer.
dvander@2168: * @param defvalue Optional default value to use if the key is not found.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvGetUInt64(Handle:kv, const String:key[], value[2], defvalue[2]={0,0});
dvander@2168:
dvander@2168: /**
dvander@2168: * Retrieves a vector value from a KeyValues key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key, or NULL_STRING.
dvander@2168: * @param vec Destination vector to store the value in.
dvander@2168: * @param defvalue Optional default value to use if the key is not found.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvGetVector(Handle:kv, const String:key[], Float:vec[3], const Float:defvalue[3]={0.0, 0.0, 0.0});
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets the current position in the KeyValues tree to the given key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key.
dvander@2168: * @param create If true, and the key does not exist, it will be created.
dvander@2168: * @return True if the key exists, false if it does not and was not created.
dvander@2168: */
dvander@2168: native bool:KvJumpToKey(Handle:kv, const String:key[], bool:create=false);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets the current position in the KeyValues tree to the given key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param id KeyValues id.
dvander@2168: * @return True if the key exists, false if it does not.
dvander@2168: */
dvander@2168: native bool:KvJumpToKeySymbol(Handle:kv, id);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets the current position in the KeyValues tree to the first sub key.
dvander@2168: * This native adds to the internal traversal stack.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param keyOnly If false, non-keys will be traversed (values).
dvander@2168: * @return True on success, false if there was no first sub key.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets the current position in the KeyValues tree to the next sub key.
dvander@2168: * This native does NOT add to the internal traversal stack, and thus
dvander@2168: * KvGoBack() is not needed for each successive call to this function.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param keyOnly If false, non-keys will be traversed (values).
dvander@2168: * @return True on success, false if there was no next sub key.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true);
dvander@2168:
dvander@2168: /**
dvander@2168: * Saves the current position in the traversal stack onto the traversal
dvander@2168: * stack. This can be useful if you wish to use KvGotoNextKey() and
dvander@2168: * have the previous key saved for backwards traversal.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSavePosition(Handle:kv);
dvander@2168:
dvander@2168: /**
dvander@2168: * Removes the given key from the current position.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Name of the key.
dvander@2168: * @return True on success, false if key did not exist.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KvDeleteKey(Handle:kv, const String:key[]);
dvander@2168:
dvander@2168: /**
dvander@2168: * Removes the current sub-key and attempts to set the position
dvander@2168: * to the sub-key after the removed one. If no such sub-key exists,
dvander@2168: * the position will be the parent key in the traversal stack.
dvander@2168: * Given the sub-key having position "N" in the traversal stack, the
dvander@2168: * removal will always take place from position "N-1."
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @return 1 if removal succeeded and there was another key.
dvander@2168: * 0 if the current node was not contained in the
dvander@2168: * previous node, or no previous node exists.
dvander@2168: * -1 if removal succeeded and there were no more keys,
dvander@2168: * thus the state is as if KvGoBack() was called.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvDeleteThis(Handle:kv);
dvander@2168:
dvander@2168: /**
dvander@2168: * Jumps back to the previous position. Returns false if there are no
dvander@2168: * previous positions (i.e., at the root node). This should be called
dvander@2168: * once for each successful Jump call, in order to return to the top node.
dvander@2168: * This function pops one node off the internal traversal stack.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @return True on success, false if there is no higher node.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KvGoBack(Handle:kv);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets the position back to the top node, emptying the entire node
dvander@2168: * traversal history. This can be used instead of looping KvGoBack()
dvander@2168: * if recursive iteration is not important.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvRewind(Handle:kv);
dvander@2168:
dvander@2168: /**
dvander@2168: * Retrieves the current section name.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param section Buffer to store the section name.
dvander@2168: * @param maxlength Maximum length of the name buffer.
dvander@2168: * @return True on success, false on failure.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KvGetSectionName(Handle:kv, String:section[], maxlength);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets the current section name.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param section Section name.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSetSectionName(Handle:kv, const String:section[]);
dvander@2168:
dvander@2168: /**
dvander@2168: * Returns the data type at a key.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Key name.
dvander@2168: * @return KvDataType value of the key.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvDataTypes:KvGetDataType(Handle:kv, const String:key[]);
dvander@2168:
dvander@2168: /**
dvander@2168: * Converts a KeyValues tree to a file. The tree is dumped
dvander@2168: * from the current position.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param file File to dump write to.
dvander@2168: * @return True on success, false otherwise.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KeyValuesToFile(Handle:kv, const String:file[]);
dvander@2168:
dvander@2168: /**
dvander@2168: * Converts a file to a KeyValues tree. The file is read into
dvander@2168: * the current position of the tree.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param file File to read from.
dvander@2168: * @return True on success, false otherwise.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:FileToKeyValues(Handle:kv, const String:file[]);
dvander@2168:
dvander@2168: /**
dvander@2168: * Sets whether or not the KeyValues parser will read escape sequences.
dvander@2168: * For example, \n would be read as a literal newline. This defaults
dvander@2168: * to false for new KeyValues structures.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param useEscapes Whether or not to read escape sequences.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvSetEscapeSequences(Handle:kv, bool:useEscapes);
dvander@2168:
dvander@2168: /**
dvander@2168: * Returns the position in the jump stack; I.e. the number of calls
dvander@2168: * required for KvGoBack to return to the root node. If at the root node,
dvander@2168: * 0 is returned.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @return Number of non-root nodes in the jump stack.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvNodesInStack(Handle:kv);
dvander@2168:
dvander@2168: /**
dvander@2168: * Makes a new copy of all subkeys in the origin KeyValues to
dvander@2168: * the destination KeyValues.
dvander@2168: * NOTE: All KeyValues are processed from the current location not the root one.
dvander@2168: *
dvander@2168: * @param origin Origin KeyValues Handle.
dvander@2168: * @param dest Destination KeyValues Handlee.
dvander@2168: * @noreturn
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native KvCopySubkeys(Handle:origin, Handle:dest);
dvander@2168:
dvander@2168: /**
dvander@2168: * Finds a KeyValues name by id.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param id KeyValues id.
dvander@2168: * @param name Buffer to store the name.
dvander@2168: * @param maxlength Maximum length of the value buffer.
dvander@2168: * @return True on success, false if id not found.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KvFindKeyById(Handle:kv, id, String:name[], maxlength);
dvander@2168:
dvander@2168: /**
dvander@2168: * Finds a KeyValues id inside a KeyValues tree.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param key Key name.
dvander@2168: * @param id Id of the found KeyValue.
dvander@2168: * @return True on success, false if key not found.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KvGetNameSymbol(Handle:kv, const String:key[], &id);
dvander@2168:
dvander@2168: /**
dvander@2168: * Retrieves the current section id.
dvander@2168: *
dvander@2168: * @param kv KeyValues Handle.
dvander@2168: * @param id Id of the current section.
dvander@2168: * @return True on success, false on failure.
dvander@2168: * @error Invalid Handle.
dvander@2168: */
dvander@2168: native bool:KvGetSectionSymbol(Handle:kv, &id);