core/ISmmAPI.h
author Scott Ehlert <ds@alliedmods.net>
Thu Dec 10 00:59:50 2009 -0600 (2009-12-10)
changeset 689 4065ba5e9155
parent 552 4b73ffd6e176
child 783 ba8cd35102b1
permissions -rw-r--r--
Rewrote user message caching code to always use IServerGameDLL::GetUserMessageInfo (bug 4117, r=dvander).

Games where the above function can crash are handled by detouring tier0's Error() function and jumping back to our own code. So in theory this should work on all games now.
dvander@513
     1
/*
dvander@371
     2
 * vim: set ts=4 :
dvander@371
     3
 * ======================================================
dvander@371
     4
 * Metamod:Source
ds@523
     5
 * Copyright (C) 2004-2008 AlliedModders LLC and authors.
dvander@371
     6
 * All rights reserved.
dvander@371
     7
 * ======================================================
dvander@371
     8
 *
dvander@371
     9
 * This software is provided 'as-is', without any express or implied warranty.
dvander@371
    10
 * In no event will the authors be held liable for any damages arising from 
dvander@371
    11
 * the use of this software.
dvander@371
    12
 * 
dvander@371
    13
 * Permission is granted to anyone to use this software for any purpose, 
dvander@371
    14
 * including commercial applications, and to alter it and redistribute it 
dvander@371
    15
 * freely, subject to the following restrictions:
dvander@371
    16
 *
dvander@371
    17
 * 1. The origin of this software must not be misrepresented; you must not 
dvander@371
    18
 * claim that you wrote the original software. If you use this software in a 
dvander@371
    19
 * product, an acknowledgment in the product documentation would be 
dvander@371
    20
 * appreciated but is not required.
dvander@371
    21
 * 2. Altered source versions must be plainly marked as such, and must not be
dvander@371
    22
 * misrepresented as being the original software.
dvander@371
    23
 * 3. This notice may not be removed or altered from any source distribution.
dvander@371
    24
 *
dvander@371
    25
 * Version: $Id$
dvander@371
    26
 */
dvander@9
    27
dvander@7
    28
#ifndef _INCLUDE_ISMM_API_H
dvander@7
    29
#define _INCLUDE_ISMM_API_H
dvander@7
    30
dvander@9
    31
/**
dvander@513
    32
 * @brief Core API calls that are provided to plugins.
dvander@9
    33
 * @file ISmmAPI.h
dvander@9
    34
 */
dvander@9
    35
dvander@376
    36
#include <stdarg.h>
dvander@7
    37
#include <interface.h>
dvander@7
    38
#include <eiface.h>
dvander@371
    39
#include <sourcehook.h>
dvander@396
    40
#include <IPluginManager.h>
dvander@396
    41
#include <ISmmPlugin.h>
dvander@405
    42
#include <ISmmPluginExt.h>
dvander@7
    43
dvander@104
    44
#if defined __GNUC__
dvander@104
    45
#if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
dvander@109
    46
#error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
dvander@104
    47
#endif //version check
dvander@104
    48
#endif //__GNUC__
dvander@104
    49
dvander@282
    50
#define	MMIFACE_SOURCEHOOK		"ISourceHook"			/**< ISourceHook Pointer */
dvander@282
    51
#define	MMIFACE_PLMANAGER		"IPluginManager"		/**< SourceMM Plugin Functions */
pavolmarko@457
    52
#define MMIFACE_SH_HOOKMANAUTOGEN	"IHookManagerAutoGen"		/**< SourceHook::IHookManagerAutoGen Pointer */
dvander@371
    53
#define IFACE_MAXNUM			999						/**< Maximum interface version */
dvander@371
    54
dvander@396
    55
namespace SourceMM
dvander@7
    56
{
dvander@396
    57
	class ISmmPlugin;
dvander@396
    58
	class IMetamodListener;
dvander@375
    59
dvander@513
    60
	/**
dvander@513
    61
	 * The core API that Metamod:Source provides to plugins.
dvander@513
    62
	 */
dvander@396
    63
	class ISmmAPI
dvander@396
    64
	{
dvander@396
    65
	public:
dvander@396
    66
		/**
dvander@396
    67
		 * @brief Logs a message through the HL2 log system.
dvander@396
    68
		 * Note: Newlines are appended automatically.
dvander@396
    69
		 *
dvander@396
    70
		 * @param pl			Plugin API pointer (used for tagging message)
dvander@396
    71
		 * @param msg			Formatted string.
dvander@396
    72
		 */
dvander@396
    73
		virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
dvander@396
    74
	
dvander@396
    75
		/**
dvander@396
    76
		 * @brief Returns an interface factory for the HL2 engine.
dvander@396
    77
		 *
dvander@396
    78
		 * @param syn			If syn is true, the synthetic wrapper is returned.  
dvander@396
    79
		 *						If syn is false, the true function is returned.
dvander@396
    80
		 * @return				CreateInterfaceFn function pointer.
dvander@396
    81
		 */
dvander@396
    82
		virtual CreateInterfaceFn GetEngineFactory(bool syn=true) =0;
dvander@244
    83
dvander@396
    84
		/**
dvander@396
    85
		 * @brief Returns an interface factory for the HL2 physics engine.
dvander@396
    86
		 *
dvander@396
    87
		 * @param syn			If syn is true, the synthetic wrapper is returned.  
dvander@396
    88
		 *						If syn is false, the true function is returned.
dvander@396
    89
		 * @return				CreateInterfaceFn function pointer.
dvander@396
    90
		 */
dvander@396
    91
		virtual CreateInterfaceFn GetPhysicsFactory(bool syn=true) =0;
dvander@396
    92
dvander@396
    93
		/**
dvander@396
    94
		 * @brief Returns an interface factory for the HL2 file system.
dvander@396
    95
		 *
dvander@396
    96
		 * @param syn			If syn is true, the synthetic wrapper is returned.  
dvander@396
    97
		 *						If syn is false, the true function is returned.
dvander@396
    98
		 * @return				CreateInterfaceFn function pointer.
dvander@396
    99
		 */
dvander@396
   100
		virtual CreateInterfaceFn GetFileSystemFactory(bool syn=true) =0;
dvander@244
   101
dvander@396
   102
		/**
dvander@396
   103
		 * @brief Returns an interface factory for the GameDLL.
dvander@396
   104
		 *
dvander@396
   105
		 *						If syn is false, the true function is returned.
dvander@396
   106
		 * @return				CreateInterfaceFn function pointer.
dvander@396
   107
		 */
dvander@396
   108
		virtual CreateInterfaceFn GetServerFactory(bool syn=true) =0;
dvander@244
   109
dvander@396
   110
		/**
dvander@396
   111
		 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
dvander@396
   112
		 *
dvander@396
   113
		 * @return				CGlobalVars pointer.
dvander@396
   114
		 */
dvander@396
   115
		virtual CGlobalVars *GetCGlobals() =0;
dvander@244
   116
dvander@396
   117
		/**
dvander@396
   118
		 * @brief Registers a ConCommandBase.
dvander@396
   119
		 *
dvander@396
   120
		 * @param plugin		Parent plugin API pointer.
dvander@396
   121
		 * @param pCommand		ConCommandBase to register.
dvander@396
   122
		 * @return				True if successful, false otherwise.
dvander@396
   123
		 */
dvander@396
   124
		virtual bool RegisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
dvander@244
   125
dvander@396
   126
		/**
dvander@396
   127
		 * @brief Unregisters a ConCommandBase.
dvander@396
   128
		 *
dvander@396
   129
		 * @param plugin		Parent plugin API pointer.
dvander@396
   130
		 * @param pCommand		ConCommandBase to unlink.
dvander@396
   131
		 */
dvander@396
   132
		virtual void UnregisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
dvander@244
   133
	
dvander@396
   134
		/**
dvander@396
   135
		 * @brief Prints an unformatted string to the remote server console.
dvander@396
   136
		 * 
dvander@396
   137
		 * Note: Newlines are not added automatically.
dvander@396
   138
		 *
dvander@396
   139
		 * @param str			Message string.
dvander@396
   140
		 */
dvander@396
   141
		virtual void ConPrint(const char *str) =0;
dvander@244
   142
dvander@396
   143
		/**
dvander@396
   144
		 * @brief Prints a formatted message to the remote server console.  
dvander@396
   145
		 * 
dvander@396
   146
		 * Note: Newlines are not added automatically.
dvander@396
   147
		 *
dvander@396
   148
		 * @param fmt			Formatted message.
dvander@396
   149
		 */
dvander@396
   150
		virtual void ConPrintf(const char *fmt, ...) =0;
dvander@244
   151
dvander@396
   152
		/**
dvander@396
   153
		 * @brief Returns the Metamod Version numbers as major version and 
dvander@396
   154
		 * minor (API) version.  Changes to minor version are guaranteed to be 
dvander@396
   155
		 * backwards compatible.  Changes to major version are not.
dvander@396
   156
		 * 
dvander@396
   157
		 * @param major			Filled with the major API version number.
dvander@396
   158
		 * @param minor			Filled with the minor API version number.
dvander@396
   159
		 * @param plvers		Filled with the current plugin API version number.
dvander@396
   160
		 * @param plmin			Filled with the minimum plugin API version number 
dvander@396
   161
		 * 						supported.
dvander@396
   162
		 */
dvander@396
   163
		virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
dvander@244
   164
	
dvander@396
   165
		/** 
dvander@396
   166
		 * @brief Returns sourcehook API version and implementation version.
dvander@396
   167
		 *
dvander@396
   168
		 * @param shvers		Filled with the SourceHook API version number.
dvander@396
   169
		 * @param shimpl		Filled with the SourceHook implementation number.
dvander@396
   170
		 */
dvander@396
   171
		virtual void GetShVersions(int &shvers, int &shimpl) =0;
dvander@244
   172
	
dvander@396
   173
		/**
dvander@396
   174
		 * @brief Adds a Metamod listener.
dvander@396
   175
		 *
dvander@396
   176
		 * @param plugin		Plugin interface pointer.
dvander@396
   177
		 * @param pListener		Listener interface pointer to add.
dvander@396
   178
		 */
dvander@396
   179
		virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
dvander@244
   180
dvander@396
   181
		/**
dvander@396
   182
		  * @brief Queries the metamod factory
dvander@396
   183
		  *
dvander@396
   184
		  * @param iface		String containing interface name
dvander@396
   185
		  * @param ret			Optional pointer to store return status
dvander@396
   186
		  * @param id			Optional pointer to store id of plugin that 
dvander@396
   187
		  * 					overrode interface, 0 if none
dvander@396
   188
		  * @return				Returned pointer
dvander@396
   189
		  */
dvander@396
   190
		virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
dvander@244
   191
dvander@396
   192
		/**
dvander@396
   193
		 * @brief Given a base interface name, such as ServerGameDLL or 
dvander@396
   194
		 * ServerGameDLL003, reformats the string to increase the number, then 
dvander@396
   195
		 * returns the new number. This is the base function to InterfaceSearch() 
dvander@396
   196
		 * and VInterfaceMatch().
dvander@396
   197
		 * 
dvander@396
   198
		 * @param iface			Input/output interface name.  Must be writable.
dvander@396
   199
		 * @param maxlength		Maximum length of iface buffer.  Must be at least 
dvander@396
   200
		 * 						strlen(iface)+4 chars.
dvander@396
   201
		 * @return				The newly incremented iface version number.
dvander@513
   202
		 * @deprecated			Use InterfaceSearch() or VInterfaceMatch instead.
dvander@396
   203
		 */
dvander@396
   204
		virtual int FormatIface(char iface[], unsigned int maxlength) =0;
dvander@244
   205
dvander@396
   206
		/**
dvander@396
   207
		 * @brief Searches for an interface, eliminating the need to loop 
dvander@396
   208
		 * through FormatIface().
dvander@396
   209
		 * 
dvander@396
   210
		 * @param fn			InterfaceFactory function.
dvander@396
   211
		 * @param iface			Interface string name.
dvander@396
   212
		 * @param max			Maximum version to look up.
dvander@396
   213
		 * @param ret			Last return code from interface factory function.
dvander@396
   214
		 * @return				Interface pointer, or NULL if not found.
dvander@396
   215
		 */
dvander@396
   216
		virtual void *InterfaceSearch(CreateInterfaceFn fn, 
dvander@396
   217
									  const char *iface, 
dvander@396
   218
									  int max, 
dvander@396
   219
									  int *ret) =0;
dvander@166
   220
dvander@396
   221
		/**
dvander@396
   222
		 * @brief Returns the base directory of the game/server, equivalent to 
dvander@396
   223
		 * IVEngineServer::GetGameDir(), except the path is absolute.
dvander@396
   224
		 *
dvander@396
   225
		 * @return				Static pointer to game's absolute basedir.
dvander@396
   226
		 */
dvander@396
   227
		virtual const char *GetBaseDir() =0;
dvander@166
   228
dvander@396
   229
		/**
dvander@396
   230
		 * @brief Formats a file path to the local OS.  
dvander@396
   231
		 *
dvander@396
   232
		 * Does not include any base directories.  Note that all slashes and 
dvander@396
   233
		 * black slashes are reverted to the local OS's expectancy.
dvander@396
   234
		 *
dvander@396
   235
		 * @param buffer		Destination buffer to store path.
dvander@396
   236
		 * @param len			Maximum length of buffer, including null 
dvander@396
   237
		 * 						terminator.
dvander@396
   238
		 * @param fmt			Formatted string.
dvander@407
   239
		 * @param ...			Arguments in the string.
dvander@407
   240
		 * @return				Number of bytes written, not including the null 
dvander@407
   241
		 *						terminator.
dvander@396
   242
		 */
dvander@407
   243
		virtual size_t PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
dvander@244
   244
dvander@396
   245
		/**
dvander@396
   246
		 * @brief Prints text in the specified client's console. Same as 
dvander@396
   247
		 * IVEngineServer::ClientPrintf except that it allows for string 
dvander@396
   248
		 * formatting.
dvander@396
   249
		 *
dvander@396
   250
		 * @param client		Client edict pointer.
dvander@396
   251
		 * @param fmt			Formatted string to print to the client.
dvander@396
   252
		 */
dvander@396
   253
		virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
dvander@244
   254
dvander@396
   255
		/**
dvander@396
   256
		 * @brief Wrapper around InterfaceSearch().  Assumes no maximum.
dvander@396
   257
		 * This is designed to replace the fact that searches only went upwards.
dvander@396
   258
		 * The "V" is intended to convey that this is for Valve formatted 
dvander@396
   259
		 * interface strings.
dvander@396
   260
		 *
dvander@396
   261
		 * @param fn			Interface factory function.
dvander@396
   262
		 * @param iface			Interface string.
dvander@396
   263
		 * @param min			Minimum value to search from.  If zero, searching 
dvander@396
   264
		 *						begins from the first available version regardless 
dvander@396
   265
		 *						of the interface.  Note that this can return 
dvander@396
   266
		 *						interfaces EARLIER than the version specified.  A 
dvander@396
   267
		 *						value of -1 (default) specifies the string version 
dvander@396
   268
		 *						as the minimum.  Any other value specifices the 
dvander@396
   269
		 *						minimum value to search from.
dvander@396
   270
		 * @return				Interface pointer, or NULL if not found.
dvander@396
   271
		 */
dvander@396
   272
		virtual void *VInterfaceMatch(CreateInterfaceFn fn, 
dvander@396
   273
									  const char *iface, 
dvander@396
   274
									  int min=-1) =0;
dvander@282
   275
dvander@396
   276
		/**
dvander@396
   277
		 * @brief Tells SourceMM to add VSP hooking capability to plugins.  
dvander@396
   278
		 *
dvander@396
   279
		 * Since this  potentially uses more resources than it would otherwise, 
dvander@396
   280
		 * plugins have to explicitly enable the feature.  Whether requested or 
dvander@396
   281
		 * not, if it is enabled, all plugins will get a pointer to the VSP 
dvander@396
   282
		 * listener through IMetamodListener.  This will not be called more than 
dvander@396
   283
		 * once for a given plugin; if it is requested more than once, each 
dvander@396
   284
		 * successive call will only give the pointer to plugins which have not 
dvander@396
   285
		 * yet received it.
dvander@396
   286
		 */
dvander@396
   287
		virtual void EnableVSPListener() =0;
dvander@282
   288
dvander@396
   289
		/**
dvander@396
   290
		 * @brief Returns the interface version of the GameDLL's IServerGameDLL 
dvander@396
   291
		 * implementation.
dvander@396
   292
		 *
dvander@396
   293
		 * @return				Interface version of the loaded IServerGameDLL.
dvander@396
   294
		 */
dvander@396
   295
		virtual int GetGameDLLVersion() =0;
ds@287
   296
dvander@396
   297
		/**
dvander@396
   298
		 * @brief Returns the number of user messages in the GameDLL.
dvander@396
   299
		 *
dvander@396
   300
		 * @return				Number of user messages, or -1 if SourceMM has 
dvander@396
   301
		 *						failed to get user message list.
dvander@396
   302
		 */
dvander@396
   303
		virtual int GetUserMessageCount() =0;
ds@287
   304
dvander@396
   305
		/**
dvander@396
   306
		 * @brief Returns the index of the specified user message.
dvander@396
   307
		 *
dvander@396
   308
		 * @param name			User message name.
dvander@396
   309
		 * @param size			Optional pointer to store size of user message.
dvander@396
   310
		 * @return				Message index, or -1 on failure.
dvander@396
   311
		 */
dvander@396
   312
		virtual int FindUserMessage(const char *name, int *size=NULL) =0;
ds@287
   313
dvander@396
   314
		/**
dvander@396
   315
		 * @brief Returns the name of the specified user message.
dvander@396
   316
		 *
dvander@396
   317
		 * @param index			User message index.
dvander@396
   318
		 * @param size			Optional pointer to store size of user message.
dvander@396
   319
		 * @return				Message name, or NULL on failure.
dvander@396
   320
		 */
dvander@396
   321
		virtual const char *GetUserMessage(int index, int *size=NULL) =0;
dvander@371
   322
dvander@396
   323
		/**
dvander@396
   324
		 * @brief Returns the highest interface version of IServerPluginCallbacks 
dvander@396
   325
		 * that the engine supports.  This is useful for games that run on older 
dvander@396
   326
		 * versions of the Source engine, such as The Ship.
dvander@396
   327
		 *
dvander@396
   328
		 * @return				Highest interface version of IServerPluginCallbacks.
dvander@396
   329
		 *						Returns 0 if SourceMM's VSP listener isn't 
dvander@396
   330
		 *						currently enabled.
dvander@513
   331
		 * @deprecated			Use GetVSPInfo() instead.
dvander@396
   332
		 */
dvander@396
   333
		virtual int GetVSPVersion() =0;
dvander@371
   334
dvander@396
   335
		/**
dvander@396
   336
		 * @brief Returns the engine interface that MM:S is using as a backend.
dvander@396
   337
		 *
dvander@396
   338
		 * The values will be one of the SOURCE_ENGINE_* constants from the top
dvander@396
   339
		 * of this file.
dvander@396
   340
	 	 *
dvander@396
   341
	 	 * @return				A SOURCE_ENGINE_* constant value.
dvander@396
   342
		 */
dvander@396
   343
		virtual int GetSourceEngineBuild() =0;
dvander@371
   344
dvander@396
   345
		/**
dvander@396
   346
		 * @brief Returns the VSP listener loaded.  
dvander@396
   347
		 *
dvander@396
   348
		 * This is useful for late-loading plugins which need to decide whether 
dvander@396
   349
		 * to add a listener or not (or need to get the pointer at all).
dvander@396
   350
		 *
dvander@513
   351
		 * @param pVersion		Optional pointer to store the VSP version.
dvander@396
   352
		 * @return				IServerPluginCallbacks pointer, or NULL if an
dvander@396
   353
		 * 						IMetamodListener event has yet to occur for 
dvander@396
   354
		 * 						EnableVSPListener().
dvander@396
   355
		 */
dvander@396
   356
		virtual IServerPluginCallbacks *GetVSPInfo(int *pVersion) =0;
dvander@376
   357
dvander@396
   358
		/**
dvander@396
   359
		 * @brief Formats a string.  This is a platform safe wrapper around 
dvander@396
   360
		 * snprintf/_snprintf.
dvander@396
   361
		 *
dvander@396
   362
		 * @param buffer		Buffer to write to.
dvander@396
   363
		 * @param maxlength		Maximum length of the buffer.
dvander@396
   364
		 * @param format		Format specifiers.
dvander@396
   365
		 * @param ...			Format arguments.
dvander@396
   366
		 * @return				Number of bytes actually written, not including 
dvander@396
   367
		 * 						the null terminator.
dvander@396
   368
		 */
dvander@552
   369
		virtual size_t Format(char *buffer, 
dvander@552
   370
						  	  size_t maxlength,
dvander@552
   371
						  	  const char *format,
dvander@552
   372
						  	  ...) =0;
dvander@376
   373
dvander@513
   374
		/**
dvander@513
   375
		 * @brief Formats a string.  This is a platform safe wrapper around 
dvander@513
   376
		 * vsnprintf/_vsnprintf.
dvander@513
   377
		 *
dvander@513
   378
		 * @param buffer		Buffer to write to.
dvander@513
   379
		 * @param maxlength		Maximum length of the buffer.
dvander@513
   380
		 * @param format		Format specifiers.
dvander@513
   381
		 * @param ap			Format argument list.
dvander@513
   382
		 * @return				Number of bytes actually written, not including the 
dvander@513
   383
		 *						null terminator.
dvander@513
   384
		 */
dvander@513
   385
		virtual size_t FormatArgs(char *buffer,
dvander@513
   386
								  size_t maxlength,
dvander@513
   387
								  const char *format,
dvander@513
   388
								  va_list ap) =0;
dvander@396
   389
	};
dvander@396
   390
}
dvander@7
   391
dvander@396
   392
#if !defined METAMOD_NO_AUTO_NAMESPACE
dvander@396
   393
using namespace SourceMM;
dvander@396
   394
#endif
dvander@138
   395
ds@294
   396
/** 
ds@294
   397
 * Version History
ds@294
   398
 *
ds@294
   399
 * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API.
ds@294
   400
 * 1.1.2 Added API call for generating iface names.
dvander@371
   401
 * 1.2   Added API more helper functions and new SourceHook version.
ds@294
   402
 * 1.2.2 Added API for printing to client console (with string formatting).
dvander@371
   403
 * 1.3   Added new interface search API.
dvander@371
   404
 * 1.4	 Added VSP listener and user message API.
ds@326
   405
 * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks.
dvander@375
   406
 * 1.6.0 Added API for Orange Box.  Broke backwards compatibility.
dvander@124
   407
 */
dvander@124
   408
dvander@7
   409
#endif //_INCLUDE_ISMM_API_H
dvander@371
   410