core/ISmmAPI.h
author Scott Ehlert <ds@alliedmods.net>
Thu Dec 10 00:59:50 2009 -0600 (2009-12-10)
changeset 689 4065ba5e9155
parent 552 4b73ffd6e176
child 783 ba8cd35102b1
permissions -rw-r--r--
Rewrote user message caching code to always use IServerGameDLL::GetUserMessageInfo (bug 4117, r=dvander).

Games where the above function can crash are handled by detouring tier0's Error() function and jumping back to our own code. So in theory this should work on all games now.
     1 /*
     2  * vim: set ts=4 :
     3  * ======================================================
     4  * Metamod:Source
     5  * Copyright (C) 2004-2008 AlliedModders LLC and authors.
     6  * All rights reserved.
     7  * ======================================================
     8  *
     9  * This software is provided 'as-is', without any express or implied warranty.
    10  * In no event will the authors be held liable for any damages arising from 
    11  * the use of this software.
    12  * 
    13  * Permission is granted to anyone to use this software for any purpose, 
    14  * including commercial applications, and to alter it and redistribute it 
    15  * freely, subject to the following restrictions:
    16  *
    17  * 1. The origin of this software must not be misrepresented; you must not 
    18  * claim that you wrote the original software. If you use this software in a 
    19  * product, an acknowledgment in the product documentation would be 
    20  * appreciated but is not required.
    21  * 2. Altered source versions must be plainly marked as such, and must not be
    22  * misrepresented as being the original software.
    23  * 3. This notice may not be removed or altered from any source distribution.
    24  *
    25  * Version: $Id$
    26  */
    27 
    28 #ifndef _INCLUDE_ISMM_API_H
    29 #define _INCLUDE_ISMM_API_H
    30 
    31 /**
    32  * @brief Core API calls that are provided to plugins.
    33  * @file ISmmAPI.h
    34  */
    35 
    36 #include <stdarg.h>
    37 #include <interface.h>
    38 #include <eiface.h>
    39 #include <sourcehook.h>
    40 #include <IPluginManager.h>
    41 #include <ISmmPlugin.h>
    42 #include <ISmmPluginExt.h>
    43 
    44 #if defined __GNUC__
    45 #if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
    46 #error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
    47 #endif //version check
    48 #endif //__GNUC__
    49 
    50 #define	MMIFACE_SOURCEHOOK		"ISourceHook"			/**< ISourceHook Pointer */
    51 #define	MMIFACE_PLMANAGER		"IPluginManager"		/**< SourceMM Plugin Functions */
    52 #define MMIFACE_SH_HOOKMANAUTOGEN	"IHookManagerAutoGen"		/**< SourceHook::IHookManagerAutoGen Pointer */
    53 #define IFACE_MAXNUM			999						/**< Maximum interface version */
    54 
    55 namespace SourceMM
    56 {
    57 	class ISmmPlugin;
    58 	class IMetamodListener;
    59 
    60 	/**
    61 	 * The core API that Metamod:Source provides to plugins.
    62 	 */
    63 	class ISmmAPI
    64 	{
    65 	public:
    66 		/**
    67 		 * @brief Logs a message through the HL2 log system.
    68 		 * Note: Newlines are appended automatically.
    69 		 *
    70 		 * @param pl			Plugin API pointer (used for tagging message)
    71 		 * @param msg			Formatted string.
    72 		 */
    73 		virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
    74 	
    75 		/**
    76 		 * @brief Returns an interface factory for the HL2 engine.
    77 		 *
    78 		 * @param syn			If syn is true, the synthetic wrapper is returned.  
    79 		 *						If syn is false, the true function is returned.
    80 		 * @return				CreateInterfaceFn function pointer.
    81 		 */
    82 		virtual CreateInterfaceFn GetEngineFactory(bool syn=true) =0;
    83 
    84 		/**
    85 		 * @brief Returns an interface factory for the HL2 physics engine.
    86 		 *
    87 		 * @param syn			If syn is true, the synthetic wrapper is returned.  
    88 		 *						If syn is false, the true function is returned.
    89 		 * @return				CreateInterfaceFn function pointer.
    90 		 */
    91 		virtual CreateInterfaceFn GetPhysicsFactory(bool syn=true) =0;
    92 
    93 		/**
    94 		 * @brief Returns an interface factory for the HL2 file system.
    95 		 *
    96 		 * @param syn			If syn is true, the synthetic wrapper is returned.  
    97 		 *						If syn is false, the true function is returned.
    98 		 * @return				CreateInterfaceFn function pointer.
    99 		 */
   100 		virtual CreateInterfaceFn GetFileSystemFactory(bool syn=true) =0;
   101 
   102 		/**
   103 		 * @brief Returns an interface factory for the GameDLL.
   104 		 *
   105 		 *						If syn is false, the true function is returned.
   106 		 * @return				CreateInterfaceFn function pointer.
   107 		 */
   108 		virtual CreateInterfaceFn GetServerFactory(bool syn=true) =0;
   109 
   110 		/**
   111 		 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
   112 		 *
   113 		 * @return				CGlobalVars pointer.
   114 		 */
   115 		virtual CGlobalVars *GetCGlobals() =0;
   116 
   117 		/**
   118 		 * @brief Registers a ConCommandBase.
   119 		 *
   120 		 * @param plugin		Parent plugin API pointer.
   121 		 * @param pCommand		ConCommandBase to register.
   122 		 * @return				True if successful, false otherwise.
   123 		 */
   124 		virtual bool RegisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   125 
   126 		/**
   127 		 * @brief Unregisters a ConCommandBase.
   128 		 *
   129 		 * @param plugin		Parent plugin API pointer.
   130 		 * @param pCommand		ConCommandBase to unlink.
   131 		 */
   132 		virtual void UnregisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   133 	
   134 		/**
   135 		 * @brief Prints an unformatted string to the remote server console.
   136 		 * 
   137 		 * Note: Newlines are not added automatically.
   138 		 *
   139 		 * @param str			Message string.
   140 		 */
   141 		virtual void ConPrint(const char *str) =0;
   142 
   143 		/**
   144 		 * @brief Prints a formatted message to the remote server console.  
   145 		 * 
   146 		 * Note: Newlines are not added automatically.
   147 		 *
   148 		 * @param fmt			Formatted message.
   149 		 */
   150 		virtual void ConPrintf(const char *fmt, ...) =0;
   151 
   152 		/**
   153 		 * @brief Returns the Metamod Version numbers as major version and 
   154 		 * minor (API) version.  Changes to minor version are guaranteed to be 
   155 		 * backwards compatible.  Changes to major version are not.
   156 		 * 
   157 		 * @param major			Filled with the major API version number.
   158 		 * @param minor			Filled with the minor API version number.
   159 		 * @param plvers		Filled with the current plugin API version number.
   160 		 * @param plmin			Filled with the minimum plugin API version number 
   161 		 * 						supported.
   162 		 */
   163 		virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
   164 	
   165 		/** 
   166 		 * @brief Returns sourcehook API version and implementation version.
   167 		 *
   168 		 * @param shvers		Filled with the SourceHook API version number.
   169 		 * @param shimpl		Filled with the SourceHook implementation number.
   170 		 */
   171 		virtual void GetShVersions(int &shvers, int &shimpl) =0;
   172 	
   173 		/**
   174 		 * @brief Adds a Metamod listener.
   175 		 *
   176 		 * @param plugin		Plugin interface pointer.
   177 		 * @param pListener		Listener interface pointer to add.
   178 		 */
   179 		virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
   180 
   181 		/**
   182 		  * @brief Queries the metamod factory
   183 		  *
   184 		  * @param iface		String containing interface name
   185 		  * @param ret			Optional pointer to store return status
   186 		  * @param id			Optional pointer to store id of plugin that 
   187 		  * 					overrode interface, 0 if none
   188 		  * @return				Returned pointer
   189 		  */
   190 		virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
   191 
   192 		/**
   193 		 * @brief Given a base interface name, such as ServerGameDLL or 
   194 		 * ServerGameDLL003, reformats the string to increase the number, then 
   195 		 * returns the new number. This is the base function to InterfaceSearch() 
   196 		 * and VInterfaceMatch().
   197 		 * 
   198 		 * @param iface			Input/output interface name.  Must be writable.
   199 		 * @param maxlength		Maximum length of iface buffer.  Must be at least 
   200 		 * 						strlen(iface)+4 chars.
   201 		 * @return				The newly incremented iface version number.
   202 		 * @deprecated			Use InterfaceSearch() or VInterfaceMatch instead.
   203 		 */
   204 		virtual int FormatIface(char iface[], unsigned int maxlength) =0;
   205 
   206 		/**
   207 		 * @brief Searches for an interface, eliminating the need to loop 
   208 		 * through FormatIface().
   209 		 * 
   210 		 * @param fn			InterfaceFactory function.
   211 		 * @param iface			Interface string name.
   212 		 * @param max			Maximum version to look up.
   213 		 * @param ret			Last return code from interface factory function.
   214 		 * @return				Interface pointer, or NULL if not found.
   215 		 */
   216 		virtual void *InterfaceSearch(CreateInterfaceFn fn, 
   217 									  const char *iface, 
   218 									  int max, 
   219 									  int *ret) =0;
   220 
   221 		/**
   222 		 * @brief Returns the base directory of the game/server, equivalent to 
   223 		 * IVEngineServer::GetGameDir(), except the path is absolute.
   224 		 *
   225 		 * @return				Static pointer to game's absolute basedir.
   226 		 */
   227 		virtual const char *GetBaseDir() =0;
   228 
   229 		/**
   230 		 * @brief Formats a file path to the local OS.  
   231 		 *
   232 		 * Does not include any base directories.  Note that all slashes and 
   233 		 * black slashes are reverted to the local OS's expectancy.
   234 		 *
   235 		 * @param buffer		Destination buffer to store path.
   236 		 * @param len			Maximum length of buffer, including null 
   237 		 * 						terminator.
   238 		 * @param fmt			Formatted string.
   239 		 * @param ...			Arguments in the string.
   240 		 * @return				Number of bytes written, not including the null 
   241 		 *						terminator.
   242 		 */
   243 		virtual size_t PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
   244 
   245 		/**
   246 		 * @brief Prints text in the specified client's console. Same as 
   247 		 * IVEngineServer::ClientPrintf except that it allows for string 
   248 		 * formatting.
   249 		 *
   250 		 * @param client		Client edict pointer.
   251 		 * @param fmt			Formatted string to print to the client.
   252 		 */
   253 		virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
   254 
   255 		/**
   256 		 * @brief Wrapper around InterfaceSearch().  Assumes no maximum.
   257 		 * This is designed to replace the fact that searches only went upwards.
   258 		 * The "V" is intended to convey that this is for Valve formatted 
   259 		 * interface strings.
   260 		 *
   261 		 * @param fn			Interface factory function.
   262 		 * @param iface			Interface string.
   263 		 * @param min			Minimum value to search from.  If zero, searching 
   264 		 *						begins from the first available version regardless 
   265 		 *						of the interface.  Note that this can return 
   266 		 *						interfaces EARLIER than the version specified.  A 
   267 		 *						value of -1 (default) specifies the string version 
   268 		 *						as the minimum.  Any other value specifices the 
   269 		 *						minimum value to search from.
   270 		 * @return				Interface pointer, or NULL if not found.
   271 		 */
   272 		virtual void *VInterfaceMatch(CreateInterfaceFn fn, 
   273 									  const char *iface, 
   274 									  int min=-1) =0;
   275 
   276 		/**
   277 		 * @brief Tells SourceMM to add VSP hooking capability to plugins.  
   278 		 *
   279 		 * Since this  potentially uses more resources than it would otherwise, 
   280 		 * plugins have to explicitly enable the feature.  Whether requested or 
   281 		 * not, if it is enabled, all plugins will get a pointer to the VSP 
   282 		 * listener through IMetamodListener.  This will not be called more than 
   283 		 * once for a given plugin; if it is requested more than once, each 
   284 		 * successive call will only give the pointer to plugins which have not 
   285 		 * yet received it.
   286 		 */
   287 		virtual void EnableVSPListener() =0;
   288 
   289 		/**
   290 		 * @brief Returns the interface version of the GameDLL's IServerGameDLL 
   291 		 * implementation.
   292 		 *
   293 		 * @return				Interface version of the loaded IServerGameDLL.
   294 		 */
   295 		virtual int GetGameDLLVersion() =0;
   296 
   297 		/**
   298 		 * @brief Returns the number of user messages in the GameDLL.
   299 		 *
   300 		 * @return				Number of user messages, or -1 if SourceMM has 
   301 		 *						failed to get user message list.
   302 		 */
   303 		virtual int GetUserMessageCount() =0;
   304 
   305 		/**
   306 		 * @brief Returns the index of the specified user message.
   307 		 *
   308 		 * @param name			User message name.
   309 		 * @param size			Optional pointer to store size of user message.
   310 		 * @return				Message index, or -1 on failure.
   311 		 */
   312 		virtual int FindUserMessage(const char *name, int *size=NULL) =0;
   313 
   314 		/**
   315 		 * @brief Returns the name of the specified user message.
   316 		 *
   317 		 * @param index			User message index.
   318 		 * @param size			Optional pointer to store size of user message.
   319 		 * @return				Message name, or NULL on failure.
   320 		 */
   321 		virtual const char *GetUserMessage(int index, int *size=NULL) =0;
   322 
   323 		/**
   324 		 * @brief Returns the highest interface version of IServerPluginCallbacks 
   325 		 * that the engine supports.  This is useful for games that run on older 
   326 		 * versions of the Source engine, such as The Ship.
   327 		 *
   328 		 * @return				Highest interface version of IServerPluginCallbacks.
   329 		 *						Returns 0 if SourceMM's VSP listener isn't 
   330 		 *						currently enabled.
   331 		 * @deprecated			Use GetVSPInfo() instead.
   332 		 */
   333 		virtual int GetVSPVersion() =0;
   334 
   335 		/**
   336 		 * @brief Returns the engine interface that MM:S is using as a backend.
   337 		 *
   338 		 * The values will be one of the SOURCE_ENGINE_* constants from the top
   339 		 * of this file.
   340 	 	 *
   341 	 	 * @return				A SOURCE_ENGINE_* constant value.
   342 		 */
   343 		virtual int GetSourceEngineBuild() =0;
   344 
   345 		/**
   346 		 * @brief Returns the VSP listener loaded.  
   347 		 *
   348 		 * This is useful for late-loading plugins which need to decide whether 
   349 		 * to add a listener or not (or need to get the pointer at all).
   350 		 *
   351 		 * @param pVersion		Optional pointer to store the VSP version.
   352 		 * @return				IServerPluginCallbacks pointer, or NULL if an
   353 		 * 						IMetamodListener event has yet to occur for 
   354 		 * 						EnableVSPListener().
   355 		 */
   356 		virtual IServerPluginCallbacks *GetVSPInfo(int *pVersion) =0;
   357 
   358 		/**
   359 		 * @brief Formats a string.  This is a platform safe wrapper around 
   360 		 * snprintf/_snprintf.
   361 		 *
   362 		 * @param buffer		Buffer to write to.
   363 		 * @param maxlength		Maximum length of the buffer.
   364 		 * @param format		Format specifiers.
   365 		 * @param ...			Format arguments.
   366 		 * @return				Number of bytes actually written, not including 
   367 		 * 						the null terminator.
   368 		 */
   369 		virtual size_t Format(char *buffer, 
   370 						  	  size_t maxlength,
   371 						  	  const char *format,
   372 						  	  ...) =0;
   373 
   374 		/**
   375 		 * @brief Formats a string.  This is a platform safe wrapper around 
   376 		 * vsnprintf/_vsnprintf.
   377 		 *
   378 		 * @param buffer		Buffer to write to.
   379 		 * @param maxlength		Maximum length of the buffer.
   380 		 * @param format		Format specifiers.
   381 		 * @param ap			Format argument list.
   382 		 * @return				Number of bytes actually written, not including the 
   383 		 *						null terminator.
   384 		 */
   385 		virtual size_t FormatArgs(char *buffer,
   386 								  size_t maxlength,
   387 								  const char *format,
   388 								  va_list ap) =0;
   389 	};
   390 }
   391 
   392 #if !defined METAMOD_NO_AUTO_NAMESPACE
   393 using namespace SourceMM;
   394 #endif
   395 
   396 /** 
   397  * Version History
   398  *
   399  * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API.
   400  * 1.1.2 Added API call for generating iface names.
   401  * 1.2   Added API more helper functions and new SourceHook version.
   402  * 1.2.2 Added API for printing to client console (with string formatting).
   403  * 1.3   Added new interface search API.
   404  * 1.4	 Added VSP listener and user message API.
   405  * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks.
   406  * 1.6.0 Added API for Orange Box.  Broke backwards compatibility.
   407  */
   408 
   409 #endif //_INCLUDE_ISMM_API_H
   410