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