core/ISmmAPI.h
author David Anderson <dvander@alliedmods.net>
Wed Nov 26 00:19:30 2008 -0600 (2008-11-26)
changeset 608 30b546cc4e03
parent 552 4b73ffd6e176
child 783 ba8cd35102b1
permissions -rw-r--r--
Updated changelog, added license headers.
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