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