/**

  * vim: set ts=4 :

  * =============================================================================

  * SourceMod

  * Copyright (C) 2004-2008 AlliedModders LLC.  All rights reserved.

  * =============================================================================

  *

  * This program is free software; you can redistribute it and/or modify it under

  * the terms of the GNU General Public License, version 3.0, as published by the

  * Free Software Foundation.

  * 

  * This program is distributed in the hope that it will be useful, but WITHOUT

  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more

  * details.

  *

  * You should have received a copy of the GNU General Public License along with

  * this program.  If not, see <http://www.gnu.org/licenses/>.

  *

  * As a special exception, AlliedModders LLC gives you permission to link the

  * code of this program (as well as its derivative works) to "Half-Life 2," the

  * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software

  * by the Valve Corporation.  You must obey the GNU General Public License in

  * all respects for all other code used.  Additionally, AlliedModders LLC grants

  * this exception to all derivative works.  AlliedModders LLC defines further

  * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),

  * or <http://www.sourcemod.net/license.php>.

  *

  * Version: $Id$

  */

 #ifndef _INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_

 #define _INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_

 #include <IShareSys.h>

 #define SMINTERFACE_TRANSLATOR_NAME		"ITranslator"

 #define SMINTERFACE_TRANSLATOR_VERSION	1

 /**

  * @file ITranslator.h

  * @brief Defines interfaces related to translation files.

  */

 namespace SourceMod

 {

 	/**

 	 * @brief SourceMod hardcodes the English language (default) to ID 0.

 	 * This cannot be changed and languages.cfg should never have it as anything 

 	 * other than the first index.

 	 */

 	#define SOURCEMOD_LANGUAGE_ENGLISH			0

 	/**

 	 * @brief For %T formats, specifies that the language should be that of the 

 	 * server and not a specific client.

 	 */

 	#define SOURCEMOD_SERVER_LANGUAGE			0

 	/**

 	 * @brief Translation error codes.

 	 */

 	enum TransError

 	{

 		Trans_Okay = 0,					/**< Translation succeeded. */

 		Trans_BadLanguage = 1,			/**< Bad language ID. */

 		Trans_BadPhrase = 2,			/**< Phrase not found. */

 		Trans_BadPhraseLanguage = 3,	/**< Phrase not found in the given language. */

 		Trans_BadPhraseFile = 4,		/**< Phrase file was unreadable. */

 	};

 	/**

 	 * @brief Contains information about a translation phrase.

 	 */

 	struct Translation

 	{

 		const char *szPhrase;		/**< Translated phrase. */

 		unsigned int fmt_count;		/**< Number of format parameters. */

 		int *fmt_order;				/**< Array of size fmt_count where each 

 										 element is the numerical order of 

 										 parameter insertion, starting from 

 										 0.

 										 */

 	};

 	/**

 	 * @brief Represents a phrase file from SourceMod's "translations" folder.

 	 */

 	class IPhraseFile

 	{

 	public:

 		/**

 		 * @brief Attempts to find a translation phrase in a phrase file.

 		 *

 		 * @param szPhrase			String containing the phrase name.

 		 * @param lang_id			Language ID.

 		 * @param pTrans			Buffer to store translation info.

 		 * @return					Translation error code indicating success 

 		 *							(pTrans is filled) or failure (pTrans 

 		 *							contents is undefined).

 		 */

 		virtual TransError GetTranslation(

 			const char *szPhrase, 

 			unsigned int lang_id, 

 			Translation *pTrans) =0;

 		/**

 		 * @brief Returns the file name of this translation file.

 		 *

 		 * @return					File name.

 		 */

 		virtual const char *GetFilename() =0;

 	};

 	/**

 	 * Represents a collection of phrase files.

 	 */

 	class IPhraseCollection

 	{

 	public:

 		/**

 		 * @brief Adds a phrase file to the collection, using a cached one 

 		 * if already found.  The return value is provided for informational 

 		 * purposes and does not need to be saved.  The life time of the 

 		 * return pointer is equal to the life time of the collection.

 		 *

 		 * This function will internally ignore dupliate additions but still 

 		 * return a valid pointer.

 		 *

 		 * @param filename			File name, without the ".txt" extension, of 

 		 *							the phrase file in the translations folder.

 		 * @return					An IPhraseFile pointer, even if the file does 

 		 *							not exist.

 		 */

 		virtual IPhraseFile *AddPhraseFile(const char *filename) =0;

 		/**

 		 * @brief Returns the number of contained phrase files.

 		 *

 		 * @return					Number of contained phrase files.

 		 */

 		virtual unsigned int GetFileCount() =0;

 		/**

 		 * @brief Returns the pointer to a contained phrase file.

 		 *

 		 * @param file				File index, from 0 to GetFileCount()-1.

 		 * @return					IPhraseFile pointer, or NULL if out of 

 		 *							range.

 		 */

 		virtual IPhraseFile *GetFile(unsigned int file) =0;

 		/**

 		 * @brief Destroys the phrase collection, freeing all internal 

 		 * resources and invalidating the object.

 		 */

 		virtual void Destroy() =0;

 		/**

 		 * @brief Attempts a translation across a given language.  All 

 		 * contained files are searched for an appropriate match; the 

 		 * first valid match is returned.

 		 *

 		 * @param key				String containing the phrase name.

 		 * @param langid			Language ID to translate to.

 		 * @param pTrans			Translation buffer.

 		 * @return					Translation error code; on success, 

 		 *							pTrans is valid.  On failure, the 

 		 *							contents of pTrans is undefined.

 		 */

 		virtual TransError FindTranslation(

 			const char *key,

 			unsigned int langid,

 			Translation *pTrans) =0;

 		/**

 		 * @brief Formats a phrase given a parameter stack.  The parameter 

 		 * stack size must exactly match the expected parameter count.  If 

 		 * this count is too small or too large, the format fails.

 		 *

 		 * @param buffer			Buffer to store formatted text.

 		 * @param maxlength			Maximum length of the buffer.

 		 * @param format			String containing format information.  

 		 *							This is equivalent to SourceMod's Format() 

 		 *							native, and sub-translations are acceptable. 

 		 * @param params			An array of pointers to each parameter. 

 		 *							Integer parameters must have a pointer to the integer.

 		 *							Float parameters must have a pointer to a float.

 		 *							String parameters must be a string pointer.

 		 *							Char parameters must be a pointer to a char.

 		 *							Translation parameters fill multiple indexes in the 

 		 *							array.  For %T translations, the expected stack is:

 		 *							[phrase string pointer] [int target id pointer] [...] 

 		 *							Where [...] is the required parameters for the translation,  

 		 *							in the order expected by the phrase, not the phrase's 

 		 *							translation.  For example, say the format is:

 		 *							"%d %T" and the phrase's format is {1:s,2:f}, then the 

 		 *							parameter stack should be:

 		 *							int *, const char *, int *, const char *, float *

 		 *							The %t modifier is the same except the target id pointer 

 		 *							would be removed:

 		 *							int *, const char *, const char *, float *

 		 * @param numparams			Number of parameters in the params array.

 		 * @param pOutLength		Optional pointer filled with output length on success.

 		 * @param pFailPhrase		Optional pointer; on failure, is filled with NULL if the 

 		 *							failure was not due to a failed translation phrase.  

 		 *							Otherwise, it is filled with the given phrase name pointer 

 		 *							from the parameter stack.  Undefined on success.

 		 * @return					True on success.  False if the parameter stack was not 

 		 *							exactly the right length, or if a translation phrase 

 		 *							could not be found.

 		 */

 		virtual bool FormatString(

 			char *buffer,

 			size_t maxlength,

 			const char *format,

 			void **params,

 			unsigned int numparams,

 			size_t *pOutLength,

 			const char **pFailPhrase) =0;

 	};

 	/**

 	 * @brief Provides functions for translation.

 	 */

 	 class ITranslator : public SMInterface

 	{

 	public:

 		virtual const char *GetInterfaceName() =0;

 		virtual unsigned int GetInterfaceVersion() =0;

 	public:

 		/**

 		 * @brief Creates a new phrase collection object.

 		 *

 		 * @return			A new phrase collection object, which must be 

 		 *					destroyed via IPhraseCollection::Destroy() when 

 		 *					no longer needed.

 		 */

 		virtual IPhraseCollection *CreatePhraseCollection() =0;

 		/**

 		 * @brief Returns the server language.

 		 *

 		 * @return			Server language index.

 		 */

 		virtual unsigned int GetServerLanguage() =0;

 		/**

 		 * @brief Returns a client's language.

 		 *

 		 * @param client	Client index.

 		 * @return			Client language index, or server's if client's is 

 		 *					not known.

 		 */

 		virtual unsigned int GetClientLanguage(int client) =0;

 		/**

 		 * @brief Sets the global client SourceMod will use for assisted 

 		 * translations (that is, %t).

 		 *

 		 * @param index		Client index (0 for server).

 		 * @return			Old global client value.

 		 */

 		virtual int SetGlobalTarget(int index) =0;

 		/**

 		 * @brief Returns the global client SourceMod is currently using 

 		 * for assisted translations (that is, %t).

 		 *

 		 * @return			Global client index (0 for server).

 		 */

 		virtual int GetGlobalTarget() const =0;

 		/**

 		 * @brief Formats a phrase given a parameter stack.  The parameter 

 		 * stack size must exactly match the expected parameter count.  If 

 		 * this count is too small or too large, the format fails.

 		 *

 		 * Note: This is the same as IPhraseCollection::FormatString(), except 

 		 * that the IPhraseCollection parameter is explicit instead of implicit.

 		 *

 		 * @param buffer			Buffer to store formatted text.

 		 * @param maxlength			Maximum length of the buffer.

 		 * @param format			String containing format information.  

 		 *							This is equivalent to SourceMod's Format() 

 		 *							native, and sub-translations are acceptable. 

 		 * @param pPhrases			Optional phrase collection pointer to search for 

 		 *							phrases.

 		 * @param params			An array of pointers to each parameter. 

 		 *							Integer parameters must have a pointer to the integer.

 		 *							Float parameters must have a pointer to a float.

 		 *							String parameters must be a string pointer.

 		 *							Char parameters must be a pointer to a char.

 		 *							Translation parameters fill multiple indexes in the 

 		 *							array.  For %T translations, the expected stack is:

 		 *							[phrase string pointer] [int target id pointer] [...] 

 		 *							Where [...] is the required parameters for the translation,  

 		 *							in the order expected by the phrase, not the phrase's 

 		 *							translation.  For example, say the format is:

 		 *							"%d %T" and the phrase's format is {1:s,2:f}, then the 

 		 *							parameter stack should be:

 		 *							int *, const char *, int *, const char *, float *

 		 *							The %t modifier is the same except the target id pointer 

 		 *							would be removed:

 		 *							int *, const char *, const char *, float *

 		 * @param numparams			Number of parameters in the params array.

 		 * @param pOutLength		Optional pointer filled with output length on success.

 		 * @param pFailPhrase		Optional pointer; on failure, is filled with NULL if the 

 		 *							failure was not due to a failed translation phrase.  

 		 *							Otherwise, it is filled with the given phrase name pointer 

 		 *							from the parameter stack.  Undefined on success.

 		 * @return					True on success.  False if the parameter stack was not 

 		 *							exactly the right length, or if a translation phrase 

 		 *							could not be found.

 		 */

 		virtual bool FormatString(

 			char *buffer,

 			size_t maxlength,

 			const char *format,

 			IPhraseCollection *pPhrases,

 			void **params,

 			unsigned int numparams,

 			size_t *pOutLength,

 			const char **pFailPhrase) =0;

 	};

 }

 #endif //_INCLUDE_SOURCEMOD_TRANSLATOR_INTERFACE_H_