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