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