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