ds@1114: /**
ds@1114:  * vim: set ts=4 :
ds@1114:  * ===============================================================
ds@1114:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
ds@1114:  * ===============================================================
ds@1114:  *
ds@1114:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
ds@1114:  * or modified under the Terms and Conditions of its License Agreement, which is found 
ds@1114:  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
ds@1114:  * may change at any time.  To view the latest information, see:
ds@1114:  *   http://www.sourcemod.net/license.php
ds@1114:  *
ds@1114:  * Version: $Id$
ds@1114:  */
ds@1114: 
ds@1114: #if defined _sdktools_stringtables_included
ds@1114:   #endinput
ds@1114: #endif
ds@1114: #define _sdktools_stringtables_included
ds@1114: 
ds@1114: #define INVALID_STRING_TABLE -1		/**< An invalid string table index */
ds@1114: #define INVALID_STRING_INDEX -1		/**< An invalid string index in a table */
ds@1114: 
ds@1114: /**
ds@1114:  * Searches for a string table.
ds@1114:  *
ds@1114:  * @param name			Name of string table to find.
ds@1114:  * @return				A string table index number if found, INVALID_STRING_TABLE otherwise.
ds@1114:  */
ds@1114: native FindStringTable(const String:name[]);
ds@1114: 
ds@1114: /**
ds@1114:  * Returns the number of string tables that currently exist.
ds@1114:  *
ds@1114:  * @return				Number of string tables that currently exist.
ds@1114:  */
ds@1114: native GetNumStringTables();
ds@1114: 
ds@1114: /**
ds@1114:  * Returns the number of strings that currently exist in a given string table.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @return				Number of strings that currently exist.
ds@1114:  * @error				Invalid string table index.
ds@1114:  */
ds@1114: native GetStringTableNumStrings(tableidx);
ds@1114: 
ds@1114: /**
ds@1114:  * Returns the maximum number of strings that are allowed in a given string table.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @return				Maximum number of strings allowed.
ds@1114:  * @error				Invalid string table index.
ds@1114:  */
ds@1114: native GetStringTableMaxStrings(tableidx);
ds@1114: 
ds@1114: /**
ds@1114:  * Retrieves the name of a string table.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @param name			Buffer to store the name of the string table.
ds@1114:  * @param maxlength		Maximum length of string buffer.
ds@1114:  * @return				Number of bytes written to the buffer (UTF-8 safe).
ds@1114:  * @error				Invalid string table index.
ds@1114:  */
ds@1114: native GetStringTableName(tableidx, String:name[], maxlength);
ds@1114: 
ds@1114: /**
ds@1114:  * Searches for the index of a given string in a string table.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @param string		String to find.
ds@1114:  * @return				String index if found, INVALID_STRING_INDEX otherwise.
ds@1114:  * @error				Invalid string table index.
ds@1114:  */
ds@1114: native FindStringIndex(tableidx, const String:str[]);
ds@1114: 
ds@1114: /**
ds@1114:  * Retrieves the string at a given index of a string table.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @param stringidx		A string index.
ds@1114:  * @param name			Buffer to store the string value.
ds@1114:  * @param maxlength		Maximum length of string buffer.
ds@1114:  * @return				Number of bytes written to the buffer (UTF-8 safe).
ds@1114:  * @error				Invalid string table index or string index.
ds@1114:  */
ds@1114: native ReadStringTable(tableidx, stringIdx, String:str[], maxlength);
ds@1114: 
ds@1114: /**
ds@1114:  * Returns the length of the user data associated with a given string index.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @param stringidx		A string index.
ds@1114:  * @return				Length of user data. This will be 0 if there is no user data.
ds@1114:  * @error				Invalid string table index or string index.
ds@1114:  */
ds@1114: native GetStringTableDataLength(tableidx, stringidx);
ds@1114: 
ds@1114: /**
ds@1114:  * Retrieves the user data associated with a given string index.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @param stringidx		A string index.
ds@1114:  * @param userdata		Buffer to store the user data. This will be set to "" if there is no user data.
ds@1114:  * @param maxlength		Maximum length of string buffer.
ds@1114:  * @return				Number of bytes written to the buffer (UTF-8 safe).
ds@1114:  * @error				Invalid string table index or string index.
ds@1114:  */
ds@1114: native GetStringTableData(tableidx, stringIdx, String:userdata[], maxlength);
ds@1114: 
ds@1114: /**
ds@1114:  * Sets the user data associated with a given string index.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @param stringidx		A string index.
ds@1114:  * @param userdata		User data string that will be set.
ds@1114:  * @param length		Length of user data string. This should include the null terminator.
ds@1114:  * @return				Number of bytes written to the buffer (UTF-8 safe).
ds@1114:  * @error				Invalid string table index or string index.
ds@1114:  */
ds@1114: native SetStringTableData(tableidx, stringIdx, const String:userdata[], length);
ds@1114: 
ds@1114: /**
ds@1114:  * Adds a string to a given string table.
ds@1114:  *
ds@1114:  * @param tableidx		A string table index.
ds@1114:  * @param string		String to add.
ds@1114:  * @param userdata		An optional user data string.
ds@1114:  * @param length		Length of user data string. This should include the null terminator.
ds@1114:  *						If set to -1, then user data will be not be altered if the specified string
ds@1114:  *						already exists in the string table.
ds@1114:  */
ds@1114: native AddToStringTable(tableidx, const String:str[], const String:userdata[]="", length=-1);
ds@1114: 
ds@1114: /**
ds@1114:  * Locks or unlocks the network string tables.
ds@1114:  *
ds@1114:  * @param lock			Determines whether network string tables should be locked.
ds@1114:  *						True means the tables should be locked for writing; false means unlocked.
ds@1114:  * @return				Previous lock state.
ds@1114:  */
ds@1114: native bool:LockStringTables(bool:lock);
ds@1114: 
ds@1114: /**
ds@1114:  * Adds a file to the downloadables network string table.
ds@1114:  * This forces a client to download the file if they do not already have it.
ds@1114:  *
ds@1114:  * @param filename		File that will be added to downloadables table.
ds@1114:  */
ds@1115: stock AddFileToDownloadsTable(const String:filename[])
ds@1114: {
ds@1114: 	static table = INVALID_STRING_TABLE;
ds@1114: 	
ds@1114: 	if (table == INVALID_STRING_TABLE)
ds@1114: 	{
ds@1114: 		table = FindStringTable("downloadables");
ds@1114: 	}
ds@1114: 	
ds@1114: 	new bool:save = LockStringTables(false);
ds@1114: 	AddToStringTable(table, filename);
ds@1114: 	LockStringTables(save);
ds@1114: }