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