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