00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 * 00029 * Version: $Id$ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_ 00033 #define _INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_ 00034 00035 /** 00036 * @file ISourceMod.h 00037 * @brief Defines miscellaneous helper functions useful to extensions. 00038 */ 00039 00040 #include <IHandleSys.h> 00041 #include <sp_vm_api.h> 00042 #include <IDataPack.h> 00043 #include <time.h> 00044 00045 #define SMINTERFACE_SOURCEMOD_NAME "ISourceMod" 00046 #define SMINTERFACE_SOURCEMOD_VERSION 7 00047 00048 /** 00049 * @brief Forward declaration of the KeyValues class. 00050 */ 00051 class KeyValues; 00052 00053 namespace SourceMod 00054 { 00055 /** 00056 * @brief Describes various ways of formatting a base path. 00057 */ 00058 enum PathType 00059 { 00060 Path_None = 0, /**< No base path */ 00061 Path_Game, /**< Base path is absolute mod folder */ 00062 Path_SM, /**< Base path is absolute to SourceMod */ 00063 Path_SM_Rel, /**< Base path is relative to SourceMod */ 00064 }; 00065 00066 /** 00067 * @brief Called when a game frame is fired. 00068 * 00069 * @param simulating Whether or not the game is ticking. 00070 */ 00071 typedef void (*GAME_FRAME_HOOK)(bool simulating); 00072 00073 /** 00074 * @brief Contains miscellaneous helper functions. 00075 */ 00076 class ISourceMod : public SMInterface 00077 { 00078 public: 00079 virtual const char *GetInterfaceName() 00080 { 00081 return SMINTERFACE_SOURCEMOD_NAME; 00082 } 00083 virtual unsigned int GetInterfaceVersion() 00084 { 00085 return SMINTERFACE_SOURCEMOD_VERSION; 00086 } 00087 public: 00088 /** 00089 * @brief Returns the full path to the game directory. 00090 * 00091 * @return A string containing the full game path. 00092 */ 00093 virtual const char *GetGamePath() const =0; 00094 00095 /** 00096 * @brief Returns the full path to the SourceMod directory. 00097 * 00098 * @return A string containing the full SourceMod path. 00099 */ 00100 virtual const char *GetSourceModPath() const =0; 00101 00102 /** 00103 * @brief Builds a platform path for a specific target base path. 00104 * 00105 * If the path starts with the string "file://" and the PathType is 00106 * not relative, then the "file://" portion is stripped off, and the 00107 * rest of the path is used without any modification (except for 00108 * correcting slashes). This can be used to override the path 00109 * builder to supply alternate absolute paths. Examples: 00110 * 00111 * file://C:/Temp/file.txt 00112 * file:///tmp/file.txt 00113 * 00114 * @param type Type of path to use as a base. 00115 * @param buffer Buffer to write to. 00116 * @param maxlength Size of buffer. 00117 * @param format Format string. 00118 * @param ... Format arguments. 00119 * @return Number of bytes written. 00120 */ 00121 virtual size_t BuildPath(PathType type, char *buffer, size_t maxlength, const char *format, ...) =0; 00122 00123 /** 00124 * @brief Logs a message to the SourceMod logs. 00125 * 00126 * @param pExt Extension calling this function. 00127 * @param format Message format. 00128 * @param ... Message format parameters. 00129 */ 00130 virtual void LogMessage(IExtension *pExt, const char *format, ...) =0; 00131 00132 /** 00133 * @brief Logs a message to the SourceMod error logs. 00134 * 00135 * @param pExt Extension calling this function. 00136 * @param format Message format. 00137 * @param ... Message format parameters. 00138 */ 00139 virtual void LogError(IExtension *pExt, const char *format, ...) =0; 00140 00141 /** 00142 * @brief Formats a string from a native. 00143 * 00144 * @param buffer Buffer to store message. 00145 * @param maxlength Maximum length of buffer (including null terminator). 00146 * @param pContext Pointer to the plugin's context. 00147 * @param params Parameter array that was passed to the native. 00148 * @param param Parameter index where format string and variable arguments begin. 00149 * Note: parameter indexes start at 1. 00150 * @return Number of bytes written, not including the null terminator. 00151 */ 00152 virtual size_t FormatString(char *buffer, 00153 size_t maxlength, 00154 SourcePawn::IPluginContext *pContext, 00155 const cell_t *params, 00156 unsigned int param) =0; 00157 00158 /** 00159 * @brief Creates a data pack object. 00160 * 00161 * @return A new IDataPack object. 00162 */ 00163 virtual IDataPack *CreateDataPack() =0; 00164 00165 /** 00166 * @brief Releases a data pack's resources so it can be re-used. 00167 * 00168 * @param pack An IDataPack object to release. 00169 */ 00170 virtual void FreeDataPack(IDataPack *pack) =0; 00171 00172 /** 00173 * @brief Not implemented, do not use. 00174 * 00175 * @param readonly Ignored 00176 * @return 0 00177 */ 00178 virtual HandleType_t GetDataPackHandleType(bool readonly=false) =0; 00179 00180 /** 00181 * @brief Retrieves a KeyValues pointer from a handle. 00182 * 00183 * @param hndl Handle_t from which to retrieve contents. 00184 * @param err Optional address to store a possible handle error. 00185 * @param root If true it will return the root KeyValues pointer for the whole structure. 00186 * 00187 * @return The KeyValues pointer, or NULL for any error encountered. 00188 */ 00189 virtual KeyValues *ReadKeyValuesHandle(Handle_t hndl, HandleError *err=NULL, bool root=false) =0; 00190 00191 /** 00192 * @brief Returns the name of the game directory. 00193 * 00194 * @return A string containing the name of the game directory. 00195 */ 00196 virtual const char *GetGameFolderName() const =0; 00197 00198 /** 00199 * @brief Returns the scripting engine interface. 00200 * 00201 * @return A pointer to the scripting engine interface. 00202 */ 00203 virtual SourcePawn::ISourcePawnEngine *GetScriptingEngine() =0; 00204 00205 /** 00206 * @brief Deprecated, do not use. 00207 * 00208 * @return NULL. 00209 */ 00210 virtual SourcePawn::IVirtualMachine *GetScriptingVM() =0; 00211 00212 /** 00213 * @brief Returns the adjusted server time. 00214 * 00215 * @return Adjusted server time. 00216 */ 00217 virtual time_t GetAdjustedTime() =0; 00218 00219 /** 00220 * @brief Sets the global client SourceMod will use for assisted 00221 * translations (that is, %t). 00222 * 00223 * @param index Client index. 00224 * @deprecated Use ITranslator::GetGlobalTarget() instead. 00225 * @return Old global client value. 00226 */ 00227 virtual unsigned int SetGlobalTarget(unsigned int index) =0; 00228 00229 /** 00230 * @brief Returns the global client SourceMod is currently using 00231 * for assisted translations (that is, %t). 00232 * 00233 * @deprecated Use ITranslator::GetGlobalTarget() instead. 00234 * @return Global client value. 00235 */ 00236 virtual unsigned int GetGlobalTarget() const =0; 00237 00238 /** 00239 * @brief Adds a function to be called each game frame. 00240 * 00241 * @param hook Hook function. 00242 */ 00243 virtual void AddGameFrameHook(GAME_FRAME_HOOK hook) =0; 00244 00245 /** 00246 * @brief Removes one game frame hook matching the given function. 00247 * 00248 * @param hook Hook function. 00249 */ 00250 virtual void RemoveGameFrameHook(GAME_FRAME_HOOK hook) =0; 00251 }; 00252 } 00253 00254 #endif //_INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_
1.5.1