core/ISmmPlugin.h
author Scott Ehlert <ds@alliedmods.net>
Mon Nov 17 00:57:17 2008 -0600 (2008-11-17)
changeset 557 0a8ad2b12708
parent 539 db914129ae01
child 783 ba8cd35102b1
permissions -rw-r--r--
Added Windows support for loader, core, and core-legacy
     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_PLUGIN_H
    29 #define _INCLUDE_ISMM_PLUGIN_H
    30 
    31 /**
    32  * @brief Plugin API interface.
    33  * @file ISmmPlugin.h These are callbacks that plugins can implement without hooks.
    34  * The pure-virtual ISmmPlugin callbacks must be implemented for the load to load.
    35  */
    36 
    37 #include <interface.h>
    38 #include <sourcehook.h>
    39 #include <IPluginManager.h>
    40 #include <ISmmAPI.h>
    41 #include <ISmmPluginExt.h>
    42 
    43 namespace SourceMM
    44 {
    45 	class ISmmAPI;
    46 
    47 	/**
    48 	 * @brief Callbacks that a plugin must expose.
    49 	 */
    50 	class ISmmPlugin
    51 	{
    52 	public:
    53 		/**
    54 		 * @brief Called to request the plugin's API version.
    55 		 *
    56 		 * This is the first callback invoked, and always remains at the top 
    57 		 * of the virtual table.  
    58 		 *
    59 		 * @return			Plugin API version.
    60 		 */
    61 		virtual int GetApiVersion() 
    62 		{ 
    63 			return METAMOD_PLAPI_VERSION; 
    64 		}
    65 
    66 		/**
    67 		 * @brief Virtual destructor so GCC doesn't complain.
    68 		 */
    69 		virtual ~ISmmPlugin()
    70 		{
    71 		}
    72 
    73 	public:
    74 		/**
    75 		 * @brief Called on plugin load.
    76 		 *
    77 		 * This is called as DLLInit() executes - after the parameters are 
    78 		 * known, but before the original GameDLL function is called.  
    79 		 * Therefore, you cannot hook it, but you don't need to - Load() is 
    80 		 * basically your hook.  You can override factories before the engine 
    81 		 * and gamedll exchange them.  However, take care to note that if your 
    82 		 * plugin is unloaded, and the gamedll/engine have cached an interface 
    83 		 * you've passed, something will definitely crash.  Be careful.
    84 		 *
    85 		 * @param id		Internal id of plugin.  Saved globally by PLUGIN_SAVEVARS()
    86 		 * @param ismm		External API for SourceMM.  Saved globally by PLUGIN_SAVEVARS()
    87 		 * @param error		Error message buffer
    88 		 * @param maxlength	Size of error message buffer
    89 		 * @param late		Set to true if your plugin was loaded late (not at server load).
    90 		 * @return			True if successful, return false to reject the load.
    91 		 */
    92 		virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
    93 
    94 		/**
    95 		 * @brief Called when all plugins have been loaded.  
    96 		 *
    97 		 * This is called after DLLInit(), and thus the mod has been mostly initialized. 
    98 		 * It is also safe to assume that all other (automatically loaded) plugins are now 
    99 		 * ready to start interacting, because they are all loaded.
   100 		 */
   101 		virtual void AllPluginsLoaded()
   102 		{
   103 		}
   104 
   105 		/**
   106 		 * @brief Called when your plugin is "queried".  
   107 		 * 
   108 		 * This is useful for rejecting a loaded state.  For example, if your 
   109 		 * plugin wants to stop operating, it can simply return false and copy 
   110 		 * an error message.  This will notify other plugins or MM:S of 
   111 		 * something bad that happened.  MM:S will not cache the return state, 
   112 		 * so if you return false,  your plugin will not actually be paused or 
   113 		 * unloaded.  This callback will be called when:
   114 		 *  - Another plugin requests it
   115 		 *  - Someone types "meta list", it will show up as "REFUSED"
   116 		 *  - When Metamod need to re-check the plugin's status
   117 		 *  - If the plugin does something like overload a factory, Metamod 
   118 		 *    will make sure the Query() returns true before calling it.
   119 		 *  Also note that this query will only override Metamod when the 
   120 		 *  plugin is running and not paused.
   121 		 *
   122 		 * @param error		Buffer for error message, or NULL if none.
   123 		 * @param maxlen	Maximum length of error buffer.
   124 		 * @return			Status code - true for okay, false for badness.
   125 		 */
   126 		virtual bool QueryRunning(char *error, size_t maxlen)
   127 		{
   128 			return true;
   129 		}
   130 
   131 		/** 
   132 		 * @brief Called on plugin unload.  You can return false if you know 
   133 		 * your plugin is not capable of restoring critical states it modifies.
   134 		 *
   135 		 * @param error		Error message buffer
   136 		 * @param maxlen	Size of error message buffer
   137 		 * @return			True on success, return false to request no unload.
   138 		 */
   139 		virtual bool Unload(char *error, size_t maxlen)
   140 		{
   141 			return true;
   142 		}
   143 
   144 		/** 
   145 		 * @brief Called on plugin pause.
   146 		 *
   147 		 * @param	error Error message buffer
   148 		 * @param	maxlen Size of error message buffer
   149 		 * @return	True on success, return false to request no pause.
   150 		 */
   151 		virtual bool Pause(char *error, size_t maxlen)
   152 		{
   153 			return true;
   154 		}
   155 
   156 		/** 
   157 		 * @brief Called on plugin unpause.
   158 		 *
   159 		 * @param	error Error message buffer
   160 		 * @param	maxlen Size of error message buffer
   161 		 * @return	True on success, return false to request no unpause.
   162 		 */
   163 		virtual bool Unpause(char *error, size_t maxlen)
   164 		{
   165 			return true;
   166 		}
   167 	public:
   168 		/** @brief Return author as string */
   169 		virtual const char *GetAuthor() =0;
   170 	
   171 		/** @brief Return plugin name as string */
   172 		virtual const char *GetName() =0;
   173 	
   174 		/** @brief Return a description as string */
   175 		virtual const char *GetDescription() =0;
   176 	
   177 		/** @brief Return a URL as string */
   178 		virtual const char *GetURL() =0;
   179 	
   180 		/** @brief Return quick license code as string */
   181 		virtual const char *GetLicense() =0;
   182 	
   183 		/** @brief Return version as string */
   184 		virtual const char *GetVersion() =0;
   185 	
   186 		/** @brief Return author as string */
   187 		virtual const char *GetDate() =0;
   188 	
   189 		/** @brief Return author as string */
   190 		virtual const char *GetLogTag() =0;
   191 	};
   192 
   193 	/**
   194 	 * @brief Various events that Metamod can fire.
   195 	 */
   196 	class IMetamodListener
   197 	{
   198 	public:
   199 		/**
   200 		 * @brief Called when a plugin is loaded.
   201 		 *
   202 		 * @param id		Id of the plugin.
   203 		 */
   204 		virtual void OnPluginLoad(PluginId id)
   205 		{
   206 		}
   207 
   208 		/**
   209 		 * @brief Called when a plugin is unloaded.
   210 		 *
   211 		 * @param id		Id of the plugin.
   212 		 */
   213 		virtual void OnPluginUnload(PluginId id)
   214 		{
   215 		}
   216 	
   217 		/**
   218 		 * @brief Called when a plugin is paused.
   219 		 *
   220 		 * @param id		Id of the plugin.
   221 		 */
   222 		virtual void OnPluginPause(PluginId id)
   223 		{
   224 		}
   225 	
   226 		/**
   227 		 * @brief Called when a plugin is unpaused.
   228 		 *
   229 		 * @param id		Id of the plugin.
   230 		 */
   231 		virtual void OnPluginUnpause(PluginId id)
   232 		{
   233 		}
   234 	
   235 		/**
   236 		 * @brief Called when the level is loaded (after GameInit, before 
   237 		 * ServerActivate).
   238 		 *
   239 		 * To override this, hook IServerGameDLL::LevelInit().
   240 		 *
   241 		 * @param pMapName		Name of the map.
   242 		 * @param pMapEntities	Lump string of the map entities, in KeyValues
   243 		 * 						format.
   244 		 * @param pOldLevel		Unknown.
   245 		 * @param pLandmarkName	Unknown.
   246 		 * @param loadGame		Unknown.
   247 		 * @param background	Unknown.
   248 		 */
   249 		virtual void OnLevelInit(char const *pMapName, 
   250 								 char const *pMapEntities, 
   251 								 char const *pOldLevel, 
   252 								 char const *pLandmarkName, 
   253 								 bool loadGame, 
   254 								 bool background) 
   255 		{ 
   256 		}
   257 
   258 		/**
   259 		 * @brief Called when the level is shut down.  May be called more than 
   260 		 * once.
   261 		 */
   262 		virtual void OnLevelShutdown()
   263 		{
   264 		}
   265 
   266 		/**
   267 		 * @brief Called when engineFactory() is used through Metamod:Source's 
   268 		 * wrapper.  This can be used to provide interfaces to other plugins or
   269 		 * the GameDLL.
   270 		 *
   271 		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   272 		 *
   273 		 * @param iface			Interface string.
   274 		 * @param ret			Optional pointer to store return code.
   275 		 * @return				Generic pointer to the interface, or NULL if 
   276 		 * 						not found.
   277 		 */
   278 		virtual void *OnEngineQuery(const char *iface, int *ret)
   279 		{
   280 			if (ret)
   281 			{
   282 				*ret = IFACE_FAILED;
   283 			}
   284 
   285 			return NULL; 
   286 		}
   287 
   288 		/**
   289 		 * @brief Called when the physics factory is used through 
   290 		 * Metamod:Source's wrapper. This can be used to provide interfaces to 
   291 		 * other plugins.
   292 		 *
   293 		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   294 		 *
   295 		 * @param iface			Interface string.
   296 		 * @param ret			Optional pointer to store return code.
   297 		 * @return				Generic pointer to the interface, or NULL if 
   298 		 * 						not found.
   299 		 */
   300 		virtual void *OnPhysicsQuery(const char *iface, int *ret)
   301 		{
   302 			if (ret)
   303 			{
   304 				*ret = IFACE_FAILED;
   305 			}
   306 	
   307 			return NULL; 
   308 		}
   309 
   310 		/**
   311 		 * @brief Called when the filesystem factory is used through 
   312 		 * Metamod:Source's wrapper.  This can be used to provide interfaces to 
   313 		 * other plugins.
   314 		 *
   315 		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   316 		 *
   317 		 * @param iface			Interface string.
   318 		 * @param ret			Optional pointer to store return code.
   319 		 * @return				Generic pointer to the interface, or NULL if not 
   320 		 * 						found.
   321 		 */
   322 		virtual void *OnFileSystemQuery(const char *iface, int *ret)
   323 		{
   324 			if (ret)
   325 			{
   326 				*ret = IFACE_FAILED;
   327 			}
   328 			
   329 			return NULL; 
   330 		}
   331 
   332 		/**
   333 		 * @brief Called when the server DLL's factory is used through 
   334 		 * Metamod:Source's wrapper.  This can be used to provide interfaces to 
   335 		 * other plugins.
   336 		 *
   337 		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   338 		 *
   339 		 * @param iface			Interface string.
   340 		 * @param ret			Optional pointer to store return code.
   341 		 * @return				Generic pointer to the interface, or NULL if not 
   342 		 * 						found.
   343 		 */
   344 		virtual void *OnGameDLLQuery(const char *iface, int *ret)
   345 		{
   346 			if (ret)
   347 			{
   348 				*ret = IFACE_FAILED;
   349 			}
   350 	
   351 			return NULL; 
   352 		}
   353 
   354 		/**
   355 		 * @brief Called when Metamod's own factory is invoked.  
   356 		 * This can be used to provide interfaces to other plugins.
   357 		 *
   358 		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   359 		 *
   360 		 * @param iface			Interface string.
   361 		 * @param ret			Optional pointer to store return code.
   362 		 * @return				Generic pointer to the interface, or NULL if not 
   363 		 * 						found.
   364 		 */
   365 		virtual void *OnMetamodQuery(const char *iface, int *ret)
   366 		{
   367 			if (ret)
   368 			{
   369 				*ret = IFACE_FAILED;
   370 			}
   371 	
   372 			return NULL; 	
   373 		}
   374 
   375 		/**
   376 		 * @brief Called when Metamod:Source acquires a valid 
   377 		 * IServerPluginCallbacks pointer to be used for hooking by plugins.
   378 		 *
   379 		 * This will only be called after a call to ISmmAPI::EnableVSPListener().
   380 		 * If called before GameInit, this callback will occur before LevelInit.
   381 		 * Otherwise, it will be called on the first call after that.
   382 		 *
   383 		 * This callback is provided to all plugins regardless of which (or how 
   384 		 * many) called EnableVSPListener(), but only if at least one did in 
   385 		 * fact enable it, and only once for all plugins.  That is, a late 
   386 		 * loading plugin should use ISmmAPI::GetVSPInfo() before relying on 
   387 		 * this callback.
   388 		 *
   389 		 * This callback is never called if Metamod:Source is in VSP mode.  
   390 		 * If in VSP mode, a VSP instance is automatically and always available 
   391 		 * via ISmmAPI::GetVSPInfo(), which should be called anyway (to handle 
   392 		 * late loading cases).
   393 		 *
   394 		 * @param iface			Interface pointer.  If NULL, then the VSP 
   395 		 * 						listening construct failed to initialize and 
   396 		 * 						is not available.
   397 		 */
   398 		virtual void OnVSPListening(IServerPluginCallbacks *iface) 
   399 		{ 
   400 		}
   401 
   402 		/**
   403 		 * @brief Called when Metamod:Source is about to remove a concommand or 
   404 		 * convar.  This can also be called if ISmmAPI::UnregisterConCmdBase is 
   405 		 * used by a plugin.
   406 		 *
   407 		 * @param id			Id of the plugin that created the concommand or 
   408 		 * 						convar.
   409 		 * @param pCommand		Pointer to concommand or convar that is being 
   410 		 * 						removed.
   411 		 */
   412 		virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
   413 		{
   414 		}
   415 	};
   416 }
   417 
   418 #if !defined METAMOD_NO_AUTO_NAMESPACE
   419 using namespace SourceMM;
   420 #endif
   421 
   422 #define PL_EXPOSURE		CreateInterface
   423 #define PL_EXPOSURE_C	"CreateInterface"
   424 
   425 /**
   426  * @brief Exposes the plugin to the MM:S loader.
   427  *
   428  * @param name		Deprecated - should be a variable name (like name).
   429  * @param var		Name of the variable that contains the singleton.
   430  *					This macro automatically takes the address of it, so 
   431  * 					you should not pass a pointer to your plugin's 
   432  *					singleton.
   433  */
   434 #define PLUGIN_EXPOSE(name, var) \
   435 	ISmmAPI *g_SMAPI = NULL; \
   436 	ISmmPlugin *g_PLAPI = NULL; \
   437 	PluginId g_PLID = (PluginId)0; \
   438 	SourceHook::ISourceHook *g_SHPtr = NULL; \
   439 	SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
   440 		if (name && !strcmp(name, METAMOD_PLAPI_NAME)) { \
   441 			return static_cast<void *>(&var); \
   442 		} \
   443 		return NULL; \
   444 	}
   445 
   446 
   447 /**
   448  * @brief This should be in one of your header files, if you wish 
   449  * to use values like g_SHPtr in other files.
   450  */
   451 #define PLUGIN_GLOBALVARS()	\
   452 	extern SourceHook::ISourceHook *g_SHPtr; \
   453 	extern ISmmAPI *g_SMAPI; \
   454 	extern ISmmPlugin *g_PLAPI; \
   455 	extern PluginId g_PLID; 
   456 
   457 /**
   458  * @brief This should be the first line in your Load callback.
   459  */
   460 #define PLUGIN_SAVEVARS() \
   461 	g_SMAPI = ismm; \
   462 	g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
   463 	g_PLAPI = static_cast<ISmmPlugin *>(this); \
   464 	g_PLID = id;
   465 
   466 #define META_LOG				g_SMAPI->LogMsg
   467 #define META_REGCMD(name)		g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command)
   468 #define META_REGCVAR(var)		g_SMAPI->RegisterConCommandBase(g_PLAPI, var)
   469 #define META_UNREGCMD(name)		g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command)
   470 #define META_UNREGCVAR(var)		g_SMAPI->UnregisterConCommandBase(g_PLAPI, var)
   471 #define	META_CONPRINT			g_SMAPI->ConPrint
   472 #define META_CONPRINTF			g_SMAPI->ConPrintf
   473 
   474 /* Probably should use this up above someday */
   475 #define CONCMD_VARNAME(name) name##_command
   476 
   477 #if !defined SMM_API
   478 #if defined __WIN32__ || defined _WIN32 || defined WIN32
   479 	#define SMM_API extern "C" __declspec(dllexport)
   480 #elif defined __GNUC__
   481 	#if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
   482 		#define SMM_API extern "C" __attribute__ ((visibility("default")))	
   483 	#else
   484 		#define SMM_API	extern "C" 
   485 	#endif	
   486 #endif
   487 #endif //!defined SMM_API
   488 
   489 /**
   490  * @brief Macro for automatically getting a current or newer Valve interface.
   491  *
   492  * @param v_factory		Factory method to use from ISmmAPI (such as engineFactory).
   493  * @param v_var			Variable name to store into.
   494  * @param v_type		Interface type (do not include the pointer/asterisk).
   495  * @param v_name		Interface name.
   496  */
   497 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
   498 	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
   499 	if (!v_var) \
   500 	{ \
   501 		if (error && maxlen) \
   502 		{ \
   503 			ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
   504 		} \
   505 		return false; \
   506 	}
   507 
   508  /**
   509   * @brief Same as GET_V_IFACE, except searches for any.
   510   *
   511   * @param v_factory	Factory method to use from ISmmAPI (such as engineFactory).
   512   * @param v_var		Variable name to store into.
   513   * @param v_type		Interface type (do not include the pointer/asterisk).
   514   * @param v_name		Interface name.
   515   */
   516 #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
   517 	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
   518 	if (!v_var) \
   519 	{ \
   520 		if (error && maxlen) \
   521 		{ \
   522 			ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
   523 		} \
   524 		return false; \
   525 	}
   526 
   527 #endif //_INCLUDE_ISMM_PLUGIN_H
   528