core/ISmmAPI.h
changeset 539 db914129ae01
parent 523 6f1630519b81
child 552 4b73ffd6e176
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/core/ISmmAPI.h	Fri Nov 14 04:04:02 2008 -0600
     1.3 @@ -0,0 +1,410 @@
     1.4 +/*
     1.5 + * vim: set ts=4 :
     1.6 + * ======================================================
     1.7 + * Metamod:Source
     1.8 + * Copyright (C) 2004-2008 AlliedModders LLC and authors.
     1.9 + * All rights reserved.
    1.10 + * ======================================================
    1.11 + *
    1.12 + * This software is provided 'as-is', without any express or implied warranty.
    1.13 + * In no event will the authors be held liable for any damages arising from 
    1.14 + * the use of this software.
    1.15 + * 
    1.16 + * Permission is granted to anyone to use this software for any purpose, 
    1.17 + * including commercial applications, and to alter it and redistribute it 
    1.18 + * freely, subject to the following restrictions:
    1.19 + *
    1.20 + * 1. The origin of this software must not be misrepresented; you must not 
    1.21 + * claim that you wrote the original software. If you use this software in a 
    1.22 + * product, an acknowledgment in the product documentation would be 
    1.23 + * appreciated but is not required.
    1.24 + * 2. Altered source versions must be plainly marked as such, and must not be
    1.25 + * misrepresented as being the original software.
    1.26 + * 3. This notice may not be removed or altered from any source distribution.
    1.27 + *
    1.28 + * Version: $Id$
    1.29 + */
    1.30 +
    1.31 +#ifndef _INCLUDE_ISMM_API_H
    1.32 +#define _INCLUDE_ISMM_API_H
    1.33 +
    1.34 +/**
    1.35 + * @brief Core API calls that are provided to plugins.
    1.36 + * @file ISmmAPI.h
    1.37 + */
    1.38 +
    1.39 +#include <stdarg.h>
    1.40 +#include <interface.h>
    1.41 +#include <eiface.h>
    1.42 +#include <sourcehook.h>
    1.43 +#include <IPluginManager.h>
    1.44 +#include <ISmmPlugin.h>
    1.45 +#include <ISmmPluginExt.h>
    1.46 +
    1.47 +#if defined __GNUC__
    1.48 +#if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
    1.49 +#error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
    1.50 +#endif //version check
    1.51 +#endif //__GNUC__
    1.52 +
    1.53 +#define	MMIFACE_SOURCEHOOK		"ISourceHook"			/**< ISourceHook Pointer */
    1.54 +#define	MMIFACE_PLMANAGER		"IPluginManager"		/**< SourceMM Plugin Functions */
    1.55 +#define MMIFACE_SH_HOOKMANAUTOGEN	"IHookManagerAutoGen"		/**< SourceHook::IHookManagerAutoGen Pointer */
    1.56 +#define IFACE_MAXNUM			999						/**< Maximum interface version */
    1.57 +
    1.58 +namespace SourceMM
    1.59 +{
    1.60 +	class ISmmPlugin;
    1.61 +	class IMetamodListener;
    1.62 +
    1.63 +	/**
    1.64 +	 * The core API that Metamod:Source provides to plugins.
    1.65 +	 */
    1.66 +	class ISmmAPI
    1.67 +	{
    1.68 +	public:
    1.69 +		/**
    1.70 +		 * @brief Logs a message through the HL2 log system.
    1.71 +		 * Note: Newlines are appended automatically.
    1.72 +		 *
    1.73 +		 * @param pl			Plugin API pointer (used for tagging message)
    1.74 +		 * @param msg			Formatted string.
    1.75 +		 */
    1.76 +		virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
    1.77 +	
    1.78 +		/**
    1.79 +		 * @brief Returns an interface factory for the HL2 engine.
    1.80 +		 *
    1.81 +		 * @param syn			If syn is true, the synthetic wrapper is returned.  
    1.82 +		 *						If syn is false, the true function is returned.
    1.83 +		 * @return				CreateInterfaceFn function pointer.
    1.84 +		 */
    1.85 +		virtual CreateInterfaceFn GetEngineFactory(bool syn=true) =0;
    1.86 +
    1.87 +		/**
    1.88 +		 * @brief Returns an interface factory for the HL2 physics engine.
    1.89 +		 *
    1.90 +		 * @param syn			If syn is true, the synthetic wrapper is returned.  
    1.91 +		 *						If syn is false, the true function is returned.
    1.92 +		 * @return				CreateInterfaceFn function pointer.
    1.93 +		 */
    1.94 +		virtual CreateInterfaceFn GetPhysicsFactory(bool syn=true) =0;
    1.95 +
    1.96 +		/**
    1.97 +		 * @brief Returns an interface factory for the HL2 file system.
    1.98 +		 *
    1.99 +		 * @param syn			If syn is true, the synthetic wrapper is returned.  
   1.100 +		 *						If syn is false, the true function is returned.
   1.101 +		 * @return				CreateInterfaceFn function pointer.
   1.102 +		 */
   1.103 +		virtual CreateInterfaceFn GetFileSystemFactory(bool syn=true) =0;
   1.104 +
   1.105 +		/**
   1.106 +		 * @brief Returns an interface factory for the GameDLL.
   1.107 +		 *
   1.108 +		 *						If syn is false, the true function is returned.
   1.109 +		 * @return				CreateInterfaceFn function pointer.
   1.110 +		 */
   1.111 +		virtual CreateInterfaceFn GetServerFactory(bool syn=true) =0;
   1.112 +
   1.113 +		/**
   1.114 +		 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
   1.115 +		 *
   1.116 +		 * @return				CGlobalVars pointer.
   1.117 +		 */
   1.118 +		virtual CGlobalVars *GetCGlobals() =0;
   1.119 +
   1.120 +		/**
   1.121 +		 * @brief Registers a ConCommandBase.
   1.122 +		 *
   1.123 +		 * @param plugin		Parent plugin API pointer.
   1.124 +		 * @param pCommand		ConCommandBase to register.
   1.125 +		 * @return				True if successful, false otherwise.
   1.126 +		 */
   1.127 +		virtual bool RegisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   1.128 +
   1.129 +		/**
   1.130 +		 * @brief Unregisters a ConCommandBase.
   1.131 +		 *
   1.132 +		 * @param plugin		Parent plugin API pointer.
   1.133 +		 * @param pCommand		ConCommandBase to unlink.
   1.134 +		 */
   1.135 +		virtual void UnregisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   1.136 +	
   1.137 +		/**
   1.138 +		 * @brief Prints an unformatted string to the remote server console.
   1.139 +		 * 
   1.140 +		 * Note: Newlines are not added automatically.
   1.141 +		 *
   1.142 +		 * @param str			Message string.
   1.143 +		 */
   1.144 +		virtual void ConPrint(const char *str) =0;
   1.145 +
   1.146 +		/**
   1.147 +		 * @brief Prints a formatted message to the remote server console.  
   1.148 +		 * 
   1.149 +		 * Note: Newlines are not added automatically.
   1.150 +		 *
   1.151 +		 * @param fmt			Formatted message.
   1.152 +		 */
   1.153 +		virtual void ConPrintf(const char *fmt, ...) =0;
   1.154 +
   1.155 +		/**
   1.156 +		 * @brief Returns the Metamod Version numbers as major version and 
   1.157 +		 * minor (API) version.  Changes to minor version are guaranteed to be 
   1.158 +		 * backwards compatible.  Changes to major version are not.
   1.159 +		 * 
   1.160 +		 * @param major			Filled with the major API version number.
   1.161 +		 * @param minor			Filled with the minor API version number.
   1.162 +		 * @param plvers		Filled with the current plugin API version number.
   1.163 +		 * @param plmin			Filled with the minimum plugin API version number 
   1.164 +		 * 						supported.
   1.165 +		 */
   1.166 +		virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
   1.167 +	
   1.168 +		/** 
   1.169 +		 * @brief Returns sourcehook API version and implementation version.
   1.170 +		 *
   1.171 +		 * @param shvers		Filled with the SourceHook API version number.
   1.172 +		 * @param shimpl		Filled with the SourceHook implementation number.
   1.173 +		 */
   1.174 +		virtual void GetShVersions(int &shvers, int &shimpl) =0;
   1.175 +	
   1.176 +		/**
   1.177 +		 * @brief Adds a Metamod listener.
   1.178 +		 *
   1.179 +		 * @param plugin		Plugin interface pointer.
   1.180 +		 * @param pListener		Listener interface pointer to add.
   1.181 +		 */
   1.182 +		virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
   1.183 +
   1.184 +		/**
   1.185 +		  * @brief Queries the metamod factory
   1.186 +		  *
   1.187 +		  * @param iface		String containing interface name
   1.188 +		  * @param ret			Optional pointer to store return status
   1.189 +		  * @param id			Optional pointer to store id of plugin that 
   1.190 +		  * 					overrode interface, 0 if none
   1.191 +		  * @return				Returned pointer
   1.192 +		  */
   1.193 +		virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
   1.194 +
   1.195 +		/**
   1.196 +		 * @brief Given a base interface name, such as ServerGameDLL or 
   1.197 +		 * ServerGameDLL003, reformats the string to increase the number, then 
   1.198 +		 * returns the new number. This is the base function to InterfaceSearch() 
   1.199 +		 * and VInterfaceMatch().
   1.200 +		 * 
   1.201 +		 * @param iface			Input/output interface name.  Must be writable.
   1.202 +		 * @param maxlength		Maximum length of iface buffer.  Must be at least 
   1.203 +		 * 						strlen(iface)+4 chars.
   1.204 +		 * @return				The newly incremented iface version number.
   1.205 +		 * @deprecated			Use InterfaceSearch() or VInterfaceMatch instead.
   1.206 +		 */
   1.207 +		virtual int FormatIface(char iface[], unsigned int maxlength) =0;
   1.208 +
   1.209 +		/**
   1.210 +		 * @brief Searches for an interface, eliminating the need to loop 
   1.211 +		 * through FormatIface().
   1.212 +		 * 
   1.213 +		 * @param fn			InterfaceFactory function.
   1.214 +		 * @param iface			Interface string name.
   1.215 +		 * @param max			Maximum version to look up.
   1.216 +		 * @param ret			Last return code from interface factory function.
   1.217 +		 * @return				Interface pointer, or NULL if not found.
   1.218 +		 */
   1.219 +		virtual void *InterfaceSearch(CreateInterfaceFn fn, 
   1.220 +									  const char *iface, 
   1.221 +									  int max, 
   1.222 +									  int *ret) =0;
   1.223 +
   1.224 +		/**
   1.225 +		 * @brief Returns the base directory of the game/server, equivalent to 
   1.226 +		 * IVEngineServer::GetGameDir(), except the path is absolute.
   1.227 +		 *
   1.228 +		 * @return				Static pointer to game's absolute basedir.
   1.229 +		 */
   1.230 +		virtual const char *GetBaseDir() =0;
   1.231 +
   1.232 +		/**
   1.233 +		 * @brief Formats a file path to the local OS.  
   1.234 +		 *
   1.235 +		 * Does not include any base directories.  Note that all slashes and 
   1.236 +		 * black slashes are reverted to the local OS's expectancy.
   1.237 +		 *
   1.238 +		 * @param buffer		Destination buffer to store path.
   1.239 +		 * @param len			Maximum length of buffer, including null 
   1.240 +		 * 						terminator.
   1.241 +		 * @param fmt			Formatted string.
   1.242 +		 * @param ...			Arguments in the string.
   1.243 +		 * @return				Number of bytes written, not including the null 
   1.244 +		 *						terminator.
   1.245 +		 */
   1.246 +		virtual size_t PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
   1.247 +
   1.248 +		/**
   1.249 +		 * @brief Prints text in the specified client's console. Same as 
   1.250 +		 * IVEngineServer::ClientPrintf except that it allows for string 
   1.251 +		 * formatting.
   1.252 +		 *
   1.253 +		 * @param client		Client edict pointer.
   1.254 +		 * @param fmt			Formatted string to print to the client.
   1.255 +		 */
   1.256 +		virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
   1.257 +
   1.258 +		/**
   1.259 +		 * @brief Wrapper around InterfaceSearch().  Assumes no maximum.
   1.260 +		 * This is designed to replace the fact that searches only went upwards.
   1.261 +		 * The "V" is intended to convey that this is for Valve formatted 
   1.262 +		 * interface strings.
   1.263 +		 *
   1.264 +		 * @param fn			Interface factory function.
   1.265 +		 * @param iface			Interface string.
   1.266 +		 * @param min			Minimum value to search from.  If zero, searching 
   1.267 +		 *						begins from the first available version regardless 
   1.268 +		 *						of the interface.  Note that this can return 
   1.269 +		 *						interfaces EARLIER than the version specified.  A 
   1.270 +		 *						value of -1 (default) specifies the string version 
   1.271 +		 *						as the minimum.  Any other value specifices the 
   1.272 +		 *						minimum value to search from.
   1.273 +		 * @return				Interface pointer, or NULL if not found.
   1.274 +		 */
   1.275 +		virtual void *VInterfaceMatch(CreateInterfaceFn fn, 
   1.276 +									  const char *iface, 
   1.277 +									  int min=-1) =0;
   1.278 +
   1.279 +		/**
   1.280 +		 * @brief Tells SourceMM to add VSP hooking capability to plugins.  
   1.281 +		 *
   1.282 +		 * Since this  potentially uses more resources than it would otherwise, 
   1.283 +		 * plugins have to explicitly enable the feature.  Whether requested or 
   1.284 +		 * not, if it is enabled, all plugins will get a pointer to the VSP 
   1.285 +		 * listener through IMetamodListener.  This will not be called more than 
   1.286 +		 * once for a given plugin; if it is requested more than once, each 
   1.287 +		 * successive call will only give the pointer to plugins which have not 
   1.288 +		 * yet received it.
   1.289 +		 */
   1.290 +		virtual void EnableVSPListener() =0;
   1.291 +
   1.292 +		/**
   1.293 +		 * @brief Returns the interface version of the GameDLL's IServerGameDLL 
   1.294 +		 * implementation.
   1.295 +		 *
   1.296 +		 * @return				Interface version of the loaded IServerGameDLL.
   1.297 +		 */
   1.298 +		virtual int GetGameDLLVersion() =0;
   1.299 +
   1.300 +		/**
   1.301 +		 * @brief Returns the number of user messages in the GameDLL.
   1.302 +		 *
   1.303 +		 * @return				Number of user messages, or -1 if SourceMM has 
   1.304 +		 *						failed to get user message list.
   1.305 +		 */
   1.306 +		virtual int GetUserMessageCount() =0;
   1.307 +
   1.308 +		/**
   1.309 +		 * @brief Returns the index of the specified user message.
   1.310 +		 *
   1.311 +		 * @param name			User message name.
   1.312 +		 * @param size			Optional pointer to store size of user message.
   1.313 +		 * @return				Message index, or -1 on failure.
   1.314 +		 */
   1.315 +		virtual int FindUserMessage(const char *name, int *size=NULL) =0;
   1.316 +
   1.317 +		/**
   1.318 +		 * @brief Returns the name of the specified user message.
   1.319 +		 *
   1.320 +		 * @param index			User message index.
   1.321 +		 * @param size			Optional pointer to store size of user message.
   1.322 +		 * @return				Message name, or NULL on failure.
   1.323 +		 */
   1.324 +		virtual const char *GetUserMessage(int index, int *size=NULL) =0;
   1.325 +
   1.326 +		/**
   1.327 +		 * @brief Returns the highest interface version of IServerPluginCallbacks 
   1.328 +		 * that the engine supports.  This is useful for games that run on older 
   1.329 +		 * versions of the Source engine, such as The Ship.
   1.330 +		 *
   1.331 +		 * @return				Highest interface version of IServerPluginCallbacks.
   1.332 +		 *						Returns 0 if SourceMM's VSP listener isn't 
   1.333 +		 *						currently enabled.
   1.334 +		 * @deprecated			Use GetVSPInfo() instead.
   1.335 +		 */
   1.336 +		virtual int GetVSPVersion() =0;
   1.337 +
   1.338 +		/**
   1.339 +		 * @brief Returns the engine interface that MM:S is using as a backend.
   1.340 +		 *
   1.341 +		 * The values will be one of the SOURCE_ENGINE_* constants from the top
   1.342 +		 * of this file.
   1.343 +	 	 *
   1.344 +	 	 * @return				A SOURCE_ENGINE_* constant value.
   1.345 +		 */
   1.346 +		virtual int GetSourceEngineBuild() =0;
   1.347 +
   1.348 +		/**
   1.349 +		 * @brief Returns the VSP listener loaded.  
   1.350 +		 *
   1.351 +		 * This is useful for late-loading plugins which need to decide whether 
   1.352 +		 * to add a listener or not (or need to get the pointer at all).
   1.353 +		 *
   1.354 +		 * @param pVersion		Optional pointer to store the VSP version.
   1.355 +		 * @return				IServerPluginCallbacks pointer, or NULL if an
   1.356 +		 * 						IMetamodListener event has yet to occur for 
   1.357 +		 * 						EnableVSPListener().
   1.358 +		 */
   1.359 +		virtual IServerPluginCallbacks *GetVSPInfo(int *pVersion) =0;
   1.360 +
   1.361 +		/**
   1.362 +		 * @brief Formats a string.  This is a platform safe wrapper around 
   1.363 +		 * snprintf/_snprintf.
   1.364 +		 *
   1.365 +		 * @param buffer		Buffer to write to.
   1.366 +		 * @param maxlength		Maximum length of the buffer.
   1.367 +		 * @param format		Format specifiers.
   1.368 +		 * @param ...			Format arguments.
   1.369 +		 * @return				Number of bytes actually written, not including 
   1.370 +		 * 						the null terminator.
   1.371 +		 */
   1.372 +	virtual size_t Format(char *buffer, 
   1.373 +						  size_t maxlength,
   1.374 +						  const char *format,
   1.375 +						  ...) =0;
   1.376 +
   1.377 +		/**
   1.378 +		 * @brief Formats a string.  This is a platform safe wrapper around 
   1.379 +		 * vsnprintf/_vsnprintf.
   1.380 +		 *
   1.381 +		 * @param buffer		Buffer to write to.
   1.382 +		 * @param maxlength		Maximum length of the buffer.
   1.383 +		 * @param format		Format specifiers.
   1.384 +		 * @param ap			Format argument list.
   1.385 +		 * @return				Number of bytes actually written, not including the 
   1.386 +		 *						null terminator.
   1.387 +		 */
   1.388 +		virtual size_t FormatArgs(char *buffer,
   1.389 +								  size_t maxlength,
   1.390 +								  const char *format,
   1.391 +								  va_list ap) =0;
   1.392 +	};
   1.393 +}
   1.394 +
   1.395 +#if !defined METAMOD_NO_AUTO_NAMESPACE
   1.396 +using namespace SourceMM;
   1.397 +#endif
   1.398 +
   1.399 +/** 
   1.400 + * Version History
   1.401 + *
   1.402 + * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API.
   1.403 + * 1.1.2 Added API call for generating iface names.
   1.404 + * 1.2   Added API more helper functions and new SourceHook version.
   1.405 + * 1.2.2 Added API for printing to client console (with string formatting).
   1.406 + * 1.3   Added new interface search API.
   1.407 + * 1.4	 Added VSP listener and user message API.
   1.408 + * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks.
   1.409 + * 1.6.0 Added API for Orange Box.  Broke backwards compatibility.
   1.410 + */
   1.411 +
   1.412 +#endif //_INCLUDE_ISMM_API_H
   1.413 +