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