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