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