Home - sourcemod-central - file revision - plugins/include/keyvalues.inc@a9e6cd2953f2 Mercurial
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
plugins/include/keyvalues.inc
author Scott Ehlert <ds@alliedmods.net>
Fri Aug 10 09:16:58 2007 +0000 (2007-08-10)
changeset 1301 a9e6cd2953f2
parent 1000 aefbd36eaf91
child 1330 ab94316bb52b
permissions -rw-r--r--
Added replicate and notify parameters to ResetConVar() - these were already available for SetConVarX() 
     1 /**
     2  * vim: set ts=4 :
     3  * ===============================================================
     4  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
     5  * ===============================================================
     6  *
     7  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
     8  * or modified under the Terms and Conditions of its License Agreement, which is found 
     9  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
    10  * may change at any time.  To view the latest information, see:
    11  *   http://www.sourcemod.net/license.php
    12  *
    13  * Version: $Id$
    14  */
    15  
    16 #if defined _keyvalues_included
    17  #endinput
    18 #endif
    19 #define _keyvalues_included
    20 
    21 /**
    22  * KeyValue data value types
    23  */
    24 enum KvDataTypes
    25 {
    26 	KvData_None = 0,	/**< Type could not be identified, or no type */
    27 	KvData_String,		/**< String value */
    28 	KvData_Int,			/**< Integer value */
    29 	KvData_Float,		/**< Floating point value */
    30 	KvData_Ptr,			/**< Pointer value (sometimes called "long") */
    31 	KvData_WString,		/**< Wide string value */
    32 	KvData_Color,		/**< Color value */
    33 	KvData_UInt64,		/**< Large integer value */
    34 	/* --- */
    35 	KvData_NUMTYPES, 
    36 };
    37 
    38 /**
    39  * Creates a new KeyValues structure.  The Handle must always be closed.
    40  *
    41  * @param name			Name of the root section.
    42  * @param firstKey		If non-empty, specifies the first key value.
    43  * @param firstValue	If firstKey is non-empty, specifies the first key's value.
    44  * @return				A Handle to a new KeyValues structure.
    45  */
    46 native Handle:CreateKeyValues(const String:name[], const String:firstkey[]="", const String:firstValue[]="");
    47 
    48 /** 
    49  * Sets a string value of a KeyValues key.
    50  *
    51  * @param kv			KeyValues Handle.
    52  * @param key			Name of the key, or NULL_STRING.
    53  * @param value			String value.
    54  * @noreturn
    55  * @error				Invalid Handle.
    56  */
    57 native KvSetString(Handle:kv, const String:key[], const String:value[]);
    58 
    59 /** 
    60  * Sets an integer value of a KeyValues key.
    61  *
    62  * @param kv			KeyValues Handle.
    63  * @param key			Name of the key, or NULL_STRING.
    64  * @param value			Value number.
    65  * @noreturn
    66  * @error				Invalid Handle.
    67  */
    68 native KvSetNum(Handle:kv, const String:key[], value);
    69 
    70 /** 
    71  * Sets a large integer value of a KeyValues key.
    72  *
    73  * @param kv			KeyValues Handle.
    74  * @param key			Name of the key, or NULL_STRING.
    75  * @param value			Large integer value (0=High bits, 1=Low bits)
    76  * @noreturn
    77  * @error				Invalid Handle.
    78  */
    79 native KvSetUInt64(Handle:kv, const String:key[], const value[2]);
    80 
    81 /** 
    82  * Sets a floating point value of a KeyValues key.
    83  *
    84  * @param kv			KeyValues Handle.
    85  * @param key			Name of the key, or NULL_STRING.
    86  * @param value			Floating point value.
    87  * @noreturn
    88  * @error				Invalid Handle.
    89  */
    90 native KvSetFloat(Handle:kv, const String:key[], Float:value);
    91 
    92 /** 
    93  * Sets a set of color values of a KeyValues key.
    94  *
    95  * @param kv			KeyValues Handle.
    96  * @param key			Name of the key, or NULL_STRING.
    97  * @param r				Red value.
    98  * @param g				Green value.
    99  * @param b				Blue value.
   100  * @param a				Alpha value.
   101  * @noreturn
   102  * @error				Invalid Handle.
   103  */
   104 native KvSetColor(Handle:kv, const String:key[], r, g, b, a=0);
   105 
   106 /** 
   107  * Retrieves a string value from a KeyValues key.
   108  *
   109  * @param kv			KeyValues Handle.
   110  * @param key			Name of the key, or NULL_STRING.
   111  * @param value			Buffer to store key value in.
   112  * @param maxlength		Maximum length of the value buffer.
   113  * @param defvalue		Optional default value to use if the key is not found.
   114  * @noreturn
   115  * @error				Invalid Handle.
   116  */
   117 native KvGetString(Handle:kv, const String:key[], String:value[], maxlength, const String:defvalue[]="");
   118 
   119 /** 
   120  * Retrieves an integer value from a KeyValues key.
   121  *
   122  * @param kv			KeyValues Handle.
   123  * @param key			Name of the key, or NULL_STRING.
   124  * @param defvalue		Optional default value to use if the key is not found.
   125  * @return				Integer value of the key.
   126  * @error				Invalid Handle.
   127  */
   128 native KvGetNum(Handle:kv, const String:key[], defvalue=0);
   129 
   130 /** 
   131  * Retrieves a floating point value from a KeyValues key.
   132  *
   133  * @param kv			KeyValues Handle.
   134  * @param key			Name of the key, or NULL_STRING.
   135  * @param defvalue		Optional default value to use if the key is not found.
   136  * @return				Floating point value of the key.
   137  * @error				Invalid Handle.
   138  */
   139 native Float:KvGetFloat(Handle:kv, const String:key[], Float:defvalue=0.0);
   140 
   141 /** 
   142  * Retrieves a set of color values from a KeyValues key.
   143  *
   144  * @param kv			KeyValues Handle.
   145  * @param key			Name of the key, or NULL_STRING.
   146  * @param r				Red value, set by reference.
   147  * @param g				Green value, set by reference. 
   148  * @param b				Blue value, set by reference. 
   149  * @param a				Alpha value, set by reference. 
   150  * @noreturn
   151  * @error				Invalid Handle.
   152  */
   153 native KvGetColor(Handle:kv, const String:key[], &r, &g, &b, &a);
   154 
   155 /** 
   156  * Retrieves a large integer value from a KeyValues key.
   157  *
   158  * @param kv			KeyValues Handle.
   159  * @param key			Name of the key, or NULL_STRING.
   160  * @param value			Array to represent the large integer.
   161  * @param defvalue		Optional default value to use if the key is not found.
   162  * @noreturn
   163  * @error				Invalid Handle.
   164  */
   165 native KvGetUInt64(Handle:kv, const String:key[], value[2], defvalue[2]={0,0});
   166 
   167 /**
   168  * Sets the current position in the KeyValues tree to the given key.
   169  *
   170  * @param kv			KeyValues Handle.
   171  * @param key			Name of the key.
   172  * @param create		If true, and the key does not exist, it will be created.
   173  * @return				True if the key exists, false if it does not and was not created.
   174  */
   175 native bool:KvJumpToKey(Handle:kv, const String:key[], bool:create=false);
   176 
   177 /**
   178  * Sets the current position in the KeyValues tree to the first sub key.
   179  * This native adds to the internal traversal stack.
   180  *
   181  * @param kv			KeyValues Handle.
   182  * @param keyOnly		If false, non-keys will be traversed (values).
   183  * @return				True on success, false if there was no first sub key.
   184  * @error				Invalid Handle.
   185  */
   186 native bool:KvGotoFirstSubKey(Handle:kv, bool:keyOnly=true);
   187 
   188 /**
   189  * Sets the current position in the KeyValues tree to the next sub key.
   190  * This native does NOT add to the internal traversal stack, and thus
   191  * KvGoBack() is not needed for each successive call to this function.
   192  *
   193  * @param kv			KeyValues Handle.
   194  * @param keyOnly		If false, non-keys will be traversed (values).
   195  * @return				True on success, false if there was no next sub key.
   196  * @error				Invalid Handle.
   197  */
   198 native bool:KvGotoNextKey(Handle:kv, bool:keyOnly=true);
   199 
   200 /**
   201  * Saves the current position in the traversal stack onto the traversal
   202  * stack.  This can be useful if you wish to use KvGotoNextKey() and 
   203  * have the previous key saved for backwards traversal.
   204  *
   205  * @param kv			KeyValues Handle.
   206  * @noreturn
   207  * @error				Invalid Handle.
   208  */
   209 native KvSavePosition(Handle:kv);
   210 
   211 /**
   212  * Removes the given key from the current position.
   213  *
   214  * @param kv			KeyValues Handle.
   215  * @param key			Name of the key.
   216  * @return				True on success, false if key did not exist.
   217  * @error				Invalid Handle.
   218  */
   219 native bool:KvDeleteKey(Handle:kv, const String:key[]);
   220 
   221 /**
   222  * Removes the current sub-key and attempts to set the position
   223  * to the sub-key after the removed one.  If no such sub-key exists,
   224  * the position will be the parent key in the traversal stack.
   225  * Given the sub-key having position "N" in the traversal stack, the 
   226  * removal will always take place from position "N-1."
   227  *
   228  * @param kv			KeyValues Handle.
   229  * @return				1 if removal succeeded and there was another key.
   230  *						0 if the current node was not contained in the
   231  *						  previous node, or no previous node exists.
   232  *						-1 if removal succeeded and there were no more keys,
   233  *						  thus the state is as if KvGoBack() was called.
   234  * @error				Invalid Handle.
   235  */
   236 native KvDeleteThis(Handle:kv);
   237 
   238 /**
   239  * Jumps back to the previous position.  Returns false if there are no
   240  * previous positions (i.e., at the root node).  This should be called
   241  * once for each successful Jump call, in order to return to the top node.
   242  * This function pops one node off the internal traversal stack.
   243  *
   244  * @param kv			KeyValues Handle.
   245  * @return				True on success, false if there is no higher node.
   246  * @error				Invalid Handle.
   247  */
   248 native bool:KvGoBack(Handle:kv);
   249 
   250 /**
   251  * Sets the position back to the top node, emptying the entire node 
   252  * traversal history.  This can be used instead of looping KvGoBack()
   253  * if recursive iteration is not important.
   254  *
   255  * @param kv			KeyValues Handle.
   256  * @noreturn
   257  * @error				Invalid Handle.
   258  */
   259 native KvRewind(Handle:kv);
   260 
   261 /**
   262  * Retrieves the current section name.
   263  * 
   264  * @param kv			KeyValues Handle.
   265  * @param section		Buffer to store the section name.
   266  * @param maxlength		Maximum length of the name buffer.
   267  * @return				True on success, false on failure.
   268  * @error				Invalid Handle.
   269  */
   270 native bool:KvGetSectionName(Handle:kv, String:section[], maxlength);
   271 
   272 /**
   273  * Sets the current section name.
   274  * 
   275  * @param kv			KeyValues Handle.
   276  * @param section		Section name.
   277  * @noreturn
   278  * @error				Invalid Handle.
   279  */
   280 native KvSetSectionName(Handle:kv, const String:section[]);
   281 
   282 /**
   283  * Returns the data type at a key.
   284  *
   285  * @param kv			KeyValues Handle.
   286  * @param key			Key name.
   287  * @return				KvDataType value of the key.
   288  * @error				Invalid Handle.
   289  */
   290 native KvDataTypes:KvGetDataType(Handle:kv, const String:key[]);
   291 
   292 /**
   293  * Converts a KeyValues tree to a file.  The tree is dumped
   294  * from the current position.
   295  *
   296  * @param kv			KeyValues Handle.
   297  * @param file			File to dump write to.
   298  * @return				True on success, false otherwise.
   299  * @error				Invalid Handle.
   300  */
   301 native bool:KeyValuesToFile(Handle:kv, const String:file[]);
   302 
   303 /**
   304  * Converts a file to a KeyValues tree.  The file is read into
   305  * the current position of the tree.
   306  *
   307  * @param kv			KeyValues Handle.
   308  * @param file			File to read from.
   309  * @return				True on success, false otherwise.
   310  * @error				Invalid Handle.
   311  */
   312 native bool:FileToKeyValues(Handle:kv, const String:file[]);
   313 
   314 /**
   315  * Sets whether or not the KeyValues parser will read escape sequences.
   316  * For example, \n would be read as a literal newline.  This defaults
   317  * to false for new KeyValues structures.
   318  *
   319  * @param kv			KeyValues Handle.
   320  * @param useEscapes	Whether or not to read escape sequences.
   321  * @noreturn
   322  * @error				Invalid Handle.
   323  */
   324 native KvSetEscapeSequences(Handle:kv, bool:useEscapes);
   325 
   326 /**
   327  * Returns the position in the jump stack; I.e. the number of calls
   328  * required for KvGoBack to return to the root node.  If at the root node,
   329  * 0 is returned.
   330  *
   331  * @param kv			KeyValues Handle.
   332  * @return				Number of non-root nodes in the jump stack.
   333  * @error				Invalid Handle.
   334  */
   335 native KvNodesInStack(Handle:kv);
sourcemod-central
Feed