Home - sourcemod-central - file revision - public/ISourceMod.h@e877885fac80 Mercurial
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
public/ISourceMod.h
author David Anderson <dvander@alliedmods.net>
Wed Feb 25 20:24:56 2009 -0500 (2009-02-25)
changeset 2612 e877885fac80
parent 2289 44045ead61cd
child 2555 ce70871a404b
permissions -rw-r--r--
Bumped all versions. 
     1 /**
     2  * vim: set ts=4 :
     3  * =============================================================================
     4  * SourceMod
     5  * Copyright (C) 2004-2008 AlliedModders LLC.  All rights reserved.
     6  * =============================================================================
     7  *
     8  * This program is free software; you can redistribute it and/or modify it under
     9  * the terms of the GNU General Public License, version 3.0, as published by the
    10  * Free Software Foundation.
    11  * 
    12  * This program is distributed in the hope that it will be useful, but WITHOUT
    13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    14  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
    15  * details.
    16  *
    17  * You should have received a copy of the GNU General Public License along with
    18  * this program.  If not, see <http://www.gnu.org/licenses/>.
    19  *
    20  * As a special exception, AlliedModders LLC gives you permission to link the
    21  * code of this program (as well as its derivative works) to "Half-Life 2," the
    22  * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
    23  * by the Valve Corporation.  You must obey the GNU General Public License in
    24  * all respects for all other code used.  Additionally, AlliedModders LLC grants
    25  * this exception to all derivative works.  AlliedModders LLC defines further
    26  * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
    27  * or <http://www.sourcemod.net/license.php>.
    28  *
    29  * Version: $Id$
    30  */
    31 
    32 #ifndef _INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_
    33 #define _INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_
    34 
    35 /**
    36  * @file ISourceMod.h
    37  * @brief Defines miscellaneous helper functions useful to extensions.
    38  */
    39 
    40 #include <IHandleSys.h>
    41 #include <sp_vm_api.h>
    42 #include <IDataPack.h>
    43 #include <time.h>
    44 
    45 #define SMINTERFACE_SOURCEMOD_NAME		"ISourceMod"
    46 #define SMINTERFACE_SOURCEMOD_VERSION	7
    47 
    48 /**
    49 * @brief Forward declaration of the KeyValues class.
    50 */
    51 class KeyValues;
    52 
    53 namespace SourceMod
    54 {
    55 	/**
    56 	 * @brief Describes various ways of formatting a base path.
    57 	 */
    58 	enum PathType
    59 	{
    60 		Path_None = 0,			/**< No base path */
    61 		Path_Game,				/**< Base path is absolute mod folder */
    62 		Path_SM,				/**< Base path is absolute to SourceMod */
    63 		Path_SM_Rel,			/**< Base path is relative to SourceMod */
    64 	};
    65 
    66 	/**
    67 	 * @brief Called when a game frame is fired.
    68 	 *
    69 	 * @param simulating		Whether or not the game is ticking.
    70 	 */
    71 	typedef void (*GAME_FRAME_HOOK)(bool simulating);
    72 
    73 	/**
    74 	 * @brief Contains miscellaneous helper functions.
    75 	 */
    76 	class ISourceMod : public SMInterface
    77 	{
    78 	public:
    79 		virtual const char *GetInterfaceName()
    80 		{
    81 			return SMINTERFACE_SOURCEMOD_NAME;
    82 		}
    83 		virtual unsigned int GetInterfaceVersion()
    84 		{
    85 			return SMINTERFACE_SOURCEMOD_VERSION;
    86 		}
    87 	public:
    88 		/**
    89 		 * @brief Returns the full path to the game directory.
    90 		 *
    91 		 * @return			A string containing the full game path.
    92 		 */
    93 		virtual const char *GetGamePath() const =0;
    94 
    95 		/**
    96 		 * @brief Returns the full path to the SourceMod directory.
    97 		 *
    98 		 * @return			A string containing the full SourceMod path.
    99 		 */
   100 		virtual const char *GetSourceModPath() const =0;
   101 
   102 		/**
   103 		 * @brief Builds a platform path for a specific target base path.
   104 		 *
   105 		 * If the path starts with the string "file://" and the PathType is 
   106 		 * not relative, then the "file://" portion is stripped off, and the 
   107 		 * rest of the path is used without any modification (except for 
   108 		 * correcting slashes).  This can be used to override the path 
   109 		 * builder to supply alternate absolute paths.  Examples:
   110 		 *
   111 		 * file://C:/Temp/file.txt
   112 		 * file:///tmp/file.txt
   113 		 *
   114 		 * @param type		Type of path to use as a base.
   115 		 * @param buffer	Buffer to write to.
   116 		 * @param maxlength	Size of buffer.
   117 		 * @param format	Format string.
   118 		 * @param ...		Format arguments.
   119 		 * @return			Number of bytes written.
   120 		 */
   121 		virtual size_t BuildPath(PathType type, char *buffer, size_t maxlength, const char *format, ...) =0;
   122 
   123 		/**
   124 		 * @brief Logs a message to the SourceMod logs.
   125 		 *
   126 		 * @param pExt		Extension calling this function.
   127 		 * @param format	Message format.
   128 		 * @param ...		Message format parameters.
   129 		 */
   130 		virtual void LogMessage(IExtension *pExt, const char *format, ...) =0;
   131 
   132 		/**
   133 		 * @brief Logs a message to the SourceMod error logs.
   134 		 *
   135 		 * @param pExt		Extension calling this function.
   136 		 * @param format	Message format.
   137 		 * @param ...		Message format parameters.
   138 		 */
   139 		virtual void LogError(IExtension *pExt, const char *format, ...) =0;
   140 
   141 		/**
   142 		 * @brief Formats a string from a native.
   143 		 *
   144 		 * @param buffer		Buffer to store message.
   145 		 * @param maxlength		Maximum length of buffer (including null terminator).
   146 		 * @param pContext		Pointer to the plugin's context.
   147 		 * @param params		Parameter array that was passed to the native.
   148 		 * @param param			Parameter index where format string and variable arguments begin.
   149 		 *						Note: parameter indexes start at 1.
   150 		 * @return				Number of bytes written, not including the null terminator.
   151 		 */
   152 		virtual size_t FormatString(char *buffer, 
   153 									size_t maxlength, 
   154 									SourcePawn::IPluginContext *pContext,
   155 									const cell_t *params,
   156 									unsigned int param) =0;
   157 
   158 		/**
   159 		 * @brief Creates a data pack object.
   160 		 *
   161 		 * @return			A new IDataPack object.
   162 		 */
   163 		virtual IDataPack *CreateDataPack() =0;
   164 
   165 		/**
   166 		 * @brief Releases a data pack's resources so it can be re-used.
   167 		 *
   168 		 * @param pack		An IDataPack object to release.
   169 		 */
   170 		virtual void FreeDataPack(IDataPack *pack) =0;
   171 
   172 		/**
   173 		 * @brief Not implemented, do not use.
   174 		 *
   175 		 * @param readonly	Ignored
   176 		 * @return			0
   177 		 */
   178 		virtual HandleType_t GetDataPackHandleType(bool readonly=false) =0;
   179 
   180 		/**
   181 		 * @brief Retrieves a KeyValues pointer from a handle.
   182 		 *
   183 		 * @param hndl		Handle_t from which to retrieve contents.
   184 		 * @param err		Optional address to store a possible handle error.
   185 		 * @param root		If true it will return the root KeyValues pointer for the whole structure.
   186 		 *
   187 		 * @return			The KeyValues pointer, or NULL for any error encountered.
   188 		 */
   189 		virtual KeyValues *ReadKeyValuesHandle(Handle_t hndl, HandleError *err=NULL, bool root=false) =0;
   190 
   191 		/**
   192 		 * @brief Returns the name of the game directory.
   193 		 *
   194 		 * @return			A string containing the name of the game directory.
   195 		 */
   196 		virtual const char *GetGameFolderName() const =0;
   197 
   198 		/**
   199 		 * @brief Returns the scripting engine interface.
   200 		 *
   201 		 * @return			A pointer to the scripting engine interface.
   202 		 */
   203 		virtual SourcePawn::ISourcePawnEngine *GetScriptingEngine() =0;
   204 
   205 		/**
   206 		 * @brief Deprecated, do not use.
   207 		 *
   208 		 * @return			NULL.
   209 		 */
   210 		virtual SourcePawn::IVirtualMachine *GetScriptingVM() =0;
   211 
   212 		/**
   213 		 * @brief Returns the adjusted server time.
   214 		 *
   215 		 * @return			Adjusted server time.
   216 		 */
   217 		virtual time_t GetAdjustedTime() =0;
   218 
   219 		/**
   220 		 * @brief Sets the global client SourceMod will use for assisted 
   221 		 * translations (that is, %t).
   222 		 *
   223 		 * @param index		Client index.
   224 		 * @deprecated		Use ITranslator::GetGlobalTarget() instead.
   225 		 * @return			Old global client value.
   226 		 */
   227 		virtual unsigned int SetGlobalTarget(unsigned int index) =0;
   228 
   229 		/**
   230 		 * @brief Returns the global client SourceMod is currently using 
   231 		 * for assisted translations (that is, %t).
   232 		 *
   233 		 * @deprecated		Use ITranslator::GetGlobalTarget() instead.
   234 		 * @return			Global client value.
   235 		 */
   236 		virtual unsigned int GetGlobalTarget() const =0;
   237 
   238 		/**
   239 		 * @brief Adds a function to be called each game frame.
   240 		 *
   241 		 * @param hook		Hook function.
   242 		 */
   243 		virtual void AddGameFrameHook(GAME_FRAME_HOOK hook) =0;
   244 
   245 		/**
   246 		 * @brief Removes one game frame hook matching the given function.
   247 		 *
   248 		 * @param hook		Hook function.
   249 		 */
   250 		virtual void RemoveGameFrameHook(GAME_FRAME_HOOK hook) =0;
   251 	};
   252 }
   253 
   254 #endif //_INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_
sourcemod-central
Feed