1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/public/ISourceMod.h Sun Mar 30 07:00:22 2008 +0000
1.3 @@ -0,0 +1,252 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * =============================================================================
1.7 + * SourceMod
1.8 + * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved.
1.9 + * =============================================================================
1.10 + *
1.11 + * This program is free software; you can redistribute it and/or modify it under
1.12 + * the terms of the GNU General Public License, version 3.0, as published by the
1.13 + * Free Software Foundation.
1.14 + *
1.15 + * This program is distributed in the hope that it will be useful, but WITHOUT
1.16 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.17 + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.18 + * details.
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License along with
1.21 + * this program. If not, see <http://www.gnu.org/licenses/>.
1.22 + *
1.23 + * As a special exception, AlliedModders LLC gives you permission to link the
1.24 + * code of this program (as well as its derivative works) to "Half-Life 2," the
1.25 + * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.26 + * by the Valve Corporation. You must obey the GNU General Public License in
1.27 + * all respects for all other code used. Additionally, AlliedModders LLC grants
1.28 + * this exception to all derivative works. AlliedModders LLC defines further
1.29 + * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.30 + * or <http://www.sourcemod.net/license.php>.
1.31 + *
1.32 + * Version: $Id$
1.33 + */
1.34 +
1.35 +#ifndef _INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_
1.36 +#define _INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_
1.37 +
1.38 +/**
1.39 + * @file ISourceMod.h
1.40 + * @brief Defines miscellaneous helper functions useful to extensions.
1.41 + */
1.42 +
1.43 +#include <IHandleSys.h>
1.44 +#include <sp_vm_api.h>
1.45 +#include <IDataPack.h>
1.46 +#include <time.h>
1.47 +
1.48 +#define SMINTERFACE_SOURCEMOD_NAME "ISourceMod"
1.49 +#define SMINTERFACE_SOURCEMOD_VERSION 7
1.50 +
1.51 +/**
1.52 +* @brief Forward declaration of the KeyValues class.
1.53 +*/
1.54 +class KeyValues;
1.55 +
1.56 +namespace SourceMod
1.57 +{
1.58 + /**
1.59 + * @brief Describes various ways of formatting a base path.
1.60 + */
1.61 + enum PathType
1.62 + {
1.63 + Path_None = 0, /**< No base path */
1.64 + Path_Game, /**< Base path is absolute mod folder */
1.65 + Path_SM, /**< Base path is absolute to SourceMod */
1.66 + Path_SM_Rel, /**< Base path is relative to SourceMod */
1.67 + };
1.68 +
1.69 + /**
1.70 + * @brief Called when a game frame is fired.
1.71 + *
1.72 + * @param simulating Whether or not the game is ticking.
1.73 + */
1.74 + typedef void (*GAME_FRAME_HOOK)(bool simulating);
1.75 +
1.76 + /**
1.77 + * @brief Contains miscellaneous helper functions.
1.78 + */
1.79 + class ISourceMod : public SMInterface
1.80 + {
1.81 + public:
1.82 + virtual const char *GetInterfaceName()
1.83 + {
1.84 + return SMINTERFACE_SOURCEMOD_NAME;
1.85 + }
1.86 + virtual unsigned int GetInterfaceVersion()
1.87 + {
1.88 + return SMINTERFACE_SOURCEMOD_VERSION;
1.89 + }
1.90 + public:
1.91 + /**
1.92 + * @brief Returns the full path to the game directory.
1.93 + *
1.94 + * @return A string containing the full game path.
1.95 + */
1.96 + virtual const char *GetGamePath() const =0;
1.97 +
1.98 + /**
1.99 + * @brief Returns the full path to the SourceMod directory.
1.100 + *
1.101 + * @return A string containing the full SourceMod path.
1.102 + */
1.103 + virtual const char *GetSourceModPath() const =0;
1.104 +
1.105 + /**
1.106 + * @brief Builds a platform path for a specific target base path.
1.107 + *
1.108 + * If the path starts with the string "file://" and the PathType is
1.109 + * not relative, then the "file://" portion is stripped off, and the
1.110 + * rest of the path is used without any modification (except for
1.111 + * correcting slashes). This can be used to override the path
1.112 + * builder to supply alternate absolute paths. Examples:
1.113 + *
1.114 + * file://C:/Temp/file.txt
1.115 + * file:///tmp/file.txt
1.116 + *
1.117 + * @param type Type of path to use as a base.
1.118 + * @param buffer Buffer to write to.
1.119 + * @param maxlength Size of buffer.
1.120 + * @param format Format string.
1.121 + * @param ... Format arguments.
1.122 + * @return Number of bytes written.
1.123 + */
1.124 + virtual size_t BuildPath(PathType type, char *buffer, size_t maxlength, const char *format, ...) =0;
1.125 +
1.126 + /**
1.127 + * @brief Logs a message to the SourceMod logs.
1.128 + *
1.129 + * @param pExt Extension calling this function.
1.130 + * @param format Message format.
1.131 + * @param ... Message format parameters.
1.132 + */
1.133 + virtual void LogMessage(IExtension *pExt, const char *format, ...) =0;
1.134 +
1.135 + /**
1.136 + * @brief Logs a message to the SourceMod error logs.
1.137 + *
1.138 + * @param pExt Extension calling this function.
1.139 + * @param format Message format.
1.140 + * @param ... Message format parameters.
1.141 + */
1.142 + virtual void LogError(IExtension *pExt, const char *format, ...) =0;
1.143 +
1.144 + /**
1.145 + * @brief Formats a string from a native.
1.146 + *
1.147 + * @param buffer Buffer to store message.
1.148 + * @param maxlength Maximum length of buffer (including null terminator).
1.149 + * @param pContext Pointer to the plugin's context.
1.150 + * @param params Parameter array that was passed to the native.
1.151 + * @param param Parameter index where format string and variable arguments begin.
1.152 + * Note: parameter indexes start at 1.
1.153 + * @return Number of bytes written, not including the null terminator.
1.154 + */
1.155 + virtual size_t FormatString(char *buffer,
1.156 + size_t maxlength,
1.157 + SourcePawn::IPluginContext *pContext,
1.158 + const cell_t *params,
1.159 + unsigned int param) =0;
1.160 +
1.161 + /**
1.162 + * @brief Creates a data pack object.
1.163 + *
1.164 + * @return A new IDataPack object.
1.165 + */
1.166 + virtual IDataPack *CreateDataPack() =0;
1.167 +
1.168 + /**
1.169 + * @brief Releases a data pack's resources so it can be re-used.
1.170 + *
1.171 + * @param pack An IDataPack object to release.
1.172 + */
1.173 + virtual void FreeDataPack(IDataPack *pack) =0;
1.174 +
1.175 + /**
1.176 + * @brief Not implemented, do not use.
1.177 + *
1.178 + * @param readonly Ignored
1.179 + * @return 0
1.180 + */
1.181 + virtual HandleType_t GetDataPackHandleType(bool readonly=false) =0;
1.182 +
1.183 + /**
1.184 + * @brief Retrieves a KeyValues pointer from a handle.
1.185 + *
1.186 + * @param hndl Handle_t from which to retrieve contents.
1.187 + * @param err Optional address to store a possible handle error.
1.188 + * @param root If true it will return the root KeyValues pointer for the whole structure.
1.189 + *
1.190 + * @return The KeyValues pointer, or NULL for any error encountered.
1.191 + */
1.192 + virtual KeyValues *ReadKeyValuesHandle(Handle_t hndl, HandleError *err=NULL, bool root=false) =0;
1.193 +
1.194 + /**
1.195 + * @brief Returns the name of the game directory.
1.196 + *
1.197 + * @return A string containing the name of the game directory.
1.198 + */
1.199 + virtual const char *GetGameFolderName() const =0;
1.200 +
1.201 + /**
1.202 + * @brief Returns the scripting engine interface.
1.203 + *
1.204 + * @return A pointer to the scripting engine interface.
1.205 + */
1.206 + virtual SourcePawn::ISourcePawnEngine *GetScriptingEngine() =0;
1.207 +
1.208 + /**
1.209 + * @brief Returns the JIT interface.
1.210 + *
1.211 + * @return A pointer to the JIT interface.
1.212 + */
1.213 + virtual SourcePawn::IVirtualMachine *GetScriptingVM() =0;
1.214 +
1.215 + /**
1.216 + * @brief Returns the adjusted server time.
1.217 + *
1.218 + * @return Adjusted server time.
1.219 + */
1.220 + virtual time_t GetAdjustedTime() =0;
1.221 +
1.222 + /**
1.223 + * @brief Sets the global client SourceMod will use for assisted
1.224 + * translations (that is, %t).
1.225 + *
1.226 + * @param index Client index.
1.227 + * @return Old global client value.
1.228 + */
1.229 + virtual unsigned int SetGlobalTarget(unsigned int index) =0;
1.230 +
1.231 + /**
1.232 + * @brief Returns the global client SourceMod is currently using
1.233 + * for assisted translations (that is, %t).
1.234 + *
1.235 + * @return Global client value.
1.236 + */
1.237 + virtual unsigned int GetGlobalTarget() const =0;
1.238 +
1.239 + /**
1.240 + * @brief Adds a function to be called each game frame.
1.241 + *
1.242 + * @param hook Hook function.
1.243 + */
1.244 + virtual void AddGameFrameHook(GAME_FRAME_HOOK hook) =0;
1.245 +
1.246 + /**
1.247 + * @brief Removes one game frame hook matching the given function.
1.248 + *
1.249 + * @param hook Hook function.
1.250 + */
1.251 + virtual void RemoveGameFrameHook(GAME_FRAME_HOOK hook) =0;
1.252 + };
1.253 +}
1.254 +
1.255 +#endif //_INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_
