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