00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2010 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 13 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 Function type for FrameAction callbacks. 00075 * 00076 * @param data User data pointer. 00077 */ 00078 typedef void (*FRAMEACTION)(void *data); 00079 00080 /** 00081 * @brief Contains miscellaneous helper functions. 00082 */ 00083 class ISourceMod : public SMInterface 00084 { 00085 public: 00086 virtual const char *GetInterfaceName() 00087 { 00088 return SMINTERFACE_SOURCEMOD_NAME; 00089 } 00090 virtual unsigned int GetInterfaceVersion() 00091 { 00092 return SMINTERFACE_SOURCEMOD_VERSION; 00093 } 00094 public: 00095 /** 00096 * @brief Returns the full path to the game directory. 00097 * 00098 * @return A string containing the full game path. 00099 */ 00100 virtual const char *GetGamePath() const =0; 00101 00102 /** 00103 * @brief Returns the full path to the SourceMod directory. 00104 * 00105 * @return A string containing the full SourceMod path. 00106 */ 00107 virtual const char *GetSourceModPath() const =0; 00108 00109 /** 00110 * @brief Builds a platform path for a specific target base path. 00111 * 00112 * If the path starts with the string "file://" and the PathType is 00113 * not relative, then the "file://" portion is stripped off, and the 00114 * rest of the path is used without any modification (except for 00115 * correcting slashes). This can be used to override the path 00116 * builder to supply alternate absolute paths. Examples: 00117 * 00118 * file://C:/Temp/file.txt 00119 * file:///tmp/file.txt 00120 * 00121 * @param type Type of path to use as a base. 00122 * @param buffer Buffer to write to. 00123 * @param maxlength Size of buffer. 00124 * @param format Format string. 00125 * @param ... Format arguments. 00126 * @return Number of bytes written. 00127 */ 00128 virtual size_t BuildPath(PathType type, char *buffer, size_t maxlength, const char *format, ...) =0; 00129 00130 /** 00131 * @brief Logs a message to the SourceMod logs. 00132 * 00133 * @param pExt Extension calling this function. 00134 * @param format Message format. 00135 * @param ... Message format parameters. 00136 */ 00137 virtual void LogMessage(IExtension *pExt, const char *format, ...) =0; 00138 00139 /** 00140 * @brief Logs a message to the SourceMod error logs. 00141 * 00142 * @param pExt Extension calling this function. 00143 * @param format Message format. 00144 * @param ... Message format parameters. 00145 */ 00146 virtual void LogError(IExtension *pExt, const char *format, ...) =0; 00147 00148 /** 00149 * @brief Formats a string from a native. 00150 * 00151 * @param buffer Buffer to store message. 00152 * @param maxlength Maximum length of buffer (including null terminator). 00153 * @param pContext Pointer to the plugin's context. 00154 * @param params Parameter array that was passed to the native. 00155 * @param param Parameter index where format string and variable arguments begin. 00156 * Note: parameter indexes start at 1. 00157 * @return Number of bytes written, not including the null terminator. 00158 */ 00159 virtual size_t FormatString(char *buffer, 00160 size_t maxlength, 00161 SourcePawn::IPluginContext *pContext, 00162 const cell_t *params, 00163 unsigned int param) =0; 00164 00165 /** 00166 * @brief Creates a data pack object. 00167 * 00168 * @return A new IDataPack object. 00169 */ 00170 virtual IDataPack *CreateDataPack() =0; 00171 00172 /** 00173 * @brief Releases a data pack's resources so it can be re-used. 00174 * 00175 * @param pack An IDataPack object to release. 00176 */ 00177 virtual void FreeDataPack(IDataPack *pack) =0; 00178 00179 /** 00180 * @brief Not implemented, do not use. 00181 * 00182 * @param readonly Ignored 00183 * @return 0 00184 */ 00185 virtual HandleType_t GetDataPackHandleType(bool readonly=false) =0; 00186 00187 /** 00188 * @brief Retrieves a KeyValues pointer from a handle. 00189 * 00190 * @param hndl Handle_t from which to retrieve contents. 00191 * @param err Optional address to store a possible handle error. 00192 * @param root If true it will return the root KeyValues pointer for the whole structure. 00193 * 00194 * @return The KeyValues pointer, or NULL for any error encountered. 00195 */ 00196 virtual KeyValues *ReadKeyValuesHandle(Handle_t hndl, HandleError *err=NULL, bool root=false) =0; 00197 00198 /** 00199 * @brief Returns the name of the game directory. 00200 * 00201 * @return A string containing the name of the game directory. 00202 */ 00203 virtual const char *GetGameFolderName() const =0; 00204 00205 /** 00206 * @brief Returns the scripting engine interface. 00207 * 00208 * @return A pointer to the scripting engine interface. 00209 */ 00210 virtual SourcePawn::ISourcePawnEngine *GetScriptingEngine() =0; 00211 00212 /** 00213 * @brief Deprecated, do not use. 00214 * 00215 * @return NULL. 00216 */ 00217 virtual SourcePawn::IVirtualMachine *GetScriptingVM() =0; 00218 00219 /** 00220 * @brief Returns the adjusted server time. 00221 * 00222 * @return Adjusted server time. 00223 */ 00224 virtual time_t GetAdjustedTime() =0; 00225 00226 /** 00227 * @brief Sets the global client SourceMod will use for assisted 00228 * translations (that is, %t). 00229 * 00230 * @param index Client index. 00231 * @deprecated Use ITranslator::GetGlobalTarget() instead. 00232 * @return Old global client value. 00233 */ 00234 virtual unsigned int SetGlobalTarget(unsigned int index) =0; 00235 00236 /** 00237 * @brief Returns the global client SourceMod is currently using 00238 * for assisted translations (that is, %t). 00239 * 00240 * @deprecated Use ITranslator::GetGlobalTarget() instead. 00241 * @return Global client value. 00242 */ 00243 virtual unsigned int GetGlobalTarget() const =0; 00244 00245 /** 00246 * @brief Adds a function to be called each game frame. 00247 * 00248 * @param hook Hook function. 00249 */ 00250 virtual void AddGameFrameHook(GAME_FRAME_HOOK hook) =0; 00251 00252 /** 00253 * @brief Removes one game frame hook matching the given function. 00254 * 00255 * @param hook Hook function. 00256 */ 00257 virtual void RemoveGameFrameHook(GAME_FRAME_HOOK hook) =0; 00258 00259 /** 00260 * @brief Platform-safe wrapper around snprintf(). 00261 * 00262 * @param buffer String buffer. 00263 * @param maxlength Maximum length of buffer. 00264 * @param fmt Format specifier string. 00265 * @param ... Format arguments. 00266 * @return Number of bytes (not including null terminator) written. 00267 */ 00268 virtual size_t Format(char *buffer, size_t maxlength, const char *fmt, ...) = 0; 00269 00270 /** 00271 * @brief Platform-safe wrapper around vsnprintf(). 00272 * 00273 * @param buffer String buffer. 00274 * @param maxlength Maximum length of buffer. 00275 * @param fmt Format specifier string. 00276 * @param ap Format arguments. 00277 * @return Number of bytes (not including null terminator) written. 00278 */ 00279 virtual size_t FormatArgs(char *buffer, size_t maxlength, const char *fmt, va_list ap) = 0; 00280 00281 /** 00282 * @brief Adds an action to be executed on the next available frame. 00283 * 00284 * This function is thread safe. 00285 * 00286 * @param fn Function to execute. 00287 * @param data Data to pass to function. 00288 */ 00289 virtual void AddFrameAction(FRAMEACTION fn, void *data) = 0; 00290 00291 /** 00292 * @brief Retrieves a core.cfg configuration value. 00293 * 00294 * @param key Core.cfg key phrase. 00295 * @return Value string, or NULL on failure. 00296 * The string will be destroyed on core.cfg reparses. 00297 */ 00298 virtual const char *GetCoreConfigValue(const char *key) = 0; 00299 00300 /** 00301 * @brief Returns SourceMod's Metamod:Source plugin ID. 00302 * 00303 * @return Metamod:Source PluginId. 00304 */ 00305 virtual int GetPluginId() = 0; 00306 00307 00308 /** 00309 * @brief Returns SourceHook's API version. 00310 * 00311 * @return SourceHook API version number. 00312 */ 00313 virtual int GetShApiVersion() = 0; 00314 00315 /** 00316 * @brief Returns whether or not a map is currently running. 00317 * 00318 * @return True if a map is currently running, otherwise false. 00319 */ 00320 virtual bool IsMapRunning() = 0; 00321 }; 00322 } 00323 00324 #endif //_INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_
1.7.1