sourcemm/ISmmAPI.h
author Scott Ehlert <ds@alliedmods.net>
Mon Feb 19 13:17:07 2007 +0000 (2007-02-19)
changeset 286 4228d058d7cb
parent 282 7a237e9ea5a1
child 287 0492209c065f
permissions -rw-r--r--
Fixed linux build :o
dvander@9
     1
/* ======== SourceMM ========
dvander@175
     2
* Copyright (C) 2004-2006 Metamod:Source Development Team
dvander@9
     3
* No warranties of any kind
dvander@9
     4
*
dvander@9
     5
* License: zlib/libpng
dvander@9
     6
*
dvander@9
     7
* Author(s): David "BAILOPAN" Anderson
dvander@9
     8
* ============================
dvander@9
     9
*/
dvander@9
    10
dvander@7
    11
#ifndef _INCLUDE_ISMM_API_H
dvander@7
    12
#define _INCLUDE_ISMM_API_H
dvander@7
    13
dvander@9
    14
/**
dvander@9
    15
 * @brief External API interface
dvander@9
    16
 * @file ISmmAPI.h
dvander@9
    17
 */
dvander@9
    18
dvander@7
    19
#include <interface.h>
dvander@7
    20
#include <eiface.h>
dvander@7
    21
#include <sourcehook/sourcehook.h>
dvander@7
    22
#include "IPluginManager.h"
dvander@7
    23
dvander@104
    24
#if defined __GNUC__
dvander@104
    25
#if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
dvander@109
    26
#error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
dvander@104
    27
#endif //version check
dvander@104
    28
#endif //__GNUC__
dvander@104
    29
dvander@138
    30
class IMetamodListener;
dvander@7
    31
class ISmmPluginManager;
dvander@7
    32
class ISmmPlugin;
dvander@7
    33
dvander@282
    34
#define	MMIFACE_SOURCEHOOK		"ISourceHook"			/**< ISourceHook Pointer */
dvander@282
    35
#define	MMIFACE_PLMANAGER		"IPluginManager"		/**< SourceMM Plugin Functions */
dvander@244
    36
#define IFACE_MAXNUM			999
dvander@138
    37
dvander@7
    38
class ISmmAPI
dvander@7
    39
{
dvander@7
    40
public:
dvander@244
    41
	/**
dvander@244
    42
	 * @brief Logs a message through the HL2 log system.
dvander@244
    43
	 * Note: Newlines are appended automatically.
dvander@244
    44
	 *
dvander@244
    45
	 * @param pl			Plugin API pointer (used for tagging message)
dvander@244
    46
	 * @param msg			Formatted string.
dvander@244
    47
	 */
dvander@7
    48
	virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
dvander@7
    49
public:
dvander@244
    50
	/**
dvander@244
    51
	 * @brief Returns an interface factory for the HL2 engine.
dvander@244
    52
	 *
dvander@244
    53
	 * @param syn			If syn is true, the synthetic wrapper is returned.  
dvander@244
    54
	 *						If syn is false, the true function is returned.
dvander@244
    55
	 * @return				CreateInterfaceFn function pointer.
dvander@244
    56
	 */
dvander@7
    57
	virtual CreateInterfaceFn engineFactory(bool syn=true) =0;
dvander@244
    58
dvander@244
    59
	/**
dvander@244
    60
	 * @brief Returns an interface factory for the HL2 physics engine.
dvander@244
    61
	 *
dvander@244
    62
	 * @param syn			If syn is true, the synthetic wrapper is returned.  
dvander@244
    63
	 *						If syn is false, the true function is returned.
dvander@244
    64
	 * @return				CreateInterfaceFn function pointer.
dvander@244
    65
	 */
dvander@7
    66
	virtual CreateInterfaceFn physicsFactory(bool syn=true) =0;
dvander@244
    67
dvander@244
    68
	/**
dvander@244
    69
	 * @brief Returns an interface factory for the HL2 file system.
dvander@244
    70
	 *
dvander@244
    71
	 * @param syn			If syn is true, the synthetic wrapper is returned.  
dvander@244
    72
	 *						If syn is false, the true function is returned.
dvander@244
    73
	 * @return				CreateInterfaceFn function pointer.
dvander@244
    74
	 */
dvander@7
    75
	virtual CreateInterfaceFn fileSystemFactory(bool syn=true) =0;
dvander@244
    76
dvander@244
    77
	/**
dvander@244
    78
	 * @brief Returns an interface factory for the GameDLL.
dvander@244
    79
	 *
dvander@244
    80
	 * @param syn			If syn is true, the synthetic wrapper is returned.  
dvander@244
    81
	 *						If syn is false, the true function is returned.
dvander@244
    82
	 * @return				CreateInterfaceFn function pointer.
dvander@244
    83
	 */
dvander@7
    84
	virtual CreateInterfaceFn serverFactory(bool syn=true) =0;
dvander@244
    85
dvander@244
    86
	/**
dvander@244
    87
	 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
dvander@244
    88
	 *
dvander@244
    89
	 * @return				CGlobalVars pointer.
dvander@244
    90
	 */
dvander@7
    91
	virtual CGlobalVars *pGlobals() =0;
dvander@244
    92
dvander@244
    93
	/**
dvander@244
    94
	 * @brief Used with SourceHook, sets teh last meta return value.
dvander@244
    95
	 * Note: Do not call this directly, use the Metamod macros.
dvander@244
    96
	 *
dvander@244
    97
	 * @param res			META_RETURN value to set.
dvander@244
    98
	 */
dvander@7
    99
	virtual void SetLastMetaReturn(META_RES res) =0;
dvander@244
   100
dvander@244
   101
	/**
dvander@244
   102
	 * @brief Used with SourceHook, returns the last meta return value.
dvander@244
   103
	 * Note: This is only valid inside a hook function.
dvander@244
   104
	 *
dvander@244
   105
	 * @return				Last META_RETURN value set by a plugin.
dvander@244
   106
	 */
dvander@9
   107
	virtual META_RES GetLastMetaReturn() =0;
dvander@244
   108
dvander@124
   109
public:		//Added in 1.00-RC2 (0:0)
dvander@244
   110
	/**
dvander@244
   111
	 * @brief Allows access to Metamod's ConCommandBaseAccessor.
dvander@244
   112
	 *
dvander@244
   113
	 * @return				Returns IConCommandBaseAccessor pointer.
dvander@244
   114
	 */
dvander@64
   115
	virtual IConCommandBaseAccessor *GetCvarBaseAccessor() =0;
dvander@244
   116
dvander@244
   117
	/**
dvander@244
   118
	 * @brief Registers a ConCommandBase.
dvander@244
   119
	 *
dvander@244
   120
	 * @param plugin		Parent plugin API pointer.
dvander@244
   121
	 * @param pCommand		ConCommandBase to register.
dvander@244
   122
	 * @return				True if successful, false otherwise.  Does not return false yet.
dvander@244
   123
	 */
dvander@67
   124
	virtual bool RegisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
dvander@244
   125
dvander@244
   126
	/**
dvander@244
   127
	 * @brief Unregisters a ConCommandBase.
dvander@244
   128
	 *
dvander@244
   129
	 * @param plugin		Parent plugin API pointer.
dvander@244
   130
	 * @param pCommand		ConCommandBase to unlink.
dvander@244
   131
	 */
dvander@67
   132
	virtual void UnregisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
dvander@244
   133
	
dvander@244
   134
	/**
dvander@244
   135
	 * @brief Prints an unformatted string to the remote server console.
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@244
   144
	 * Note: Newlines are not added automatically.
dvander@244
   145
	 *
dvander@244
   146
	 * @param fmt			Formatted message.
dvander@244
   147
	 */
dvander@76
   148
	virtual void ConPrintf(const char *fmt, ...) =0;
dvander@244
   149
dvander@152
   150
public:		//Added in 1.1.0 (1:0)
dvander@244
   151
	/**
dvander@244
   152
	 * @brief Checks if ConPrint/ConPrintf will mirror to rcon.
dvander@244
   153
	 *
dvander@244
   154
	 * @return				True if remote printing available, false otherwise.
dvander@244
   155
	 */
dvander@124
   156
	virtual bool RemotePrintingAvailable() =0;
dvander@244
   157
dvander@244
   158
	/**
dvander@244
   159
	 * @brief Returns the Metamod Version numbers as major version and minor (API) version.
dvander@244
   160
	 * Changes to minor version are guaranteed to be backwards compatible.
dvander@244
   161
	 * Changes to major version are not.
dvander@244
   162
	 * 
dvander@244
   163
	 * @param major			Filled with the major API version number.
dvander@244
   164
	 * @param minor			Filled with the minor API version number.
dvander@244
   165
	 * @param plvers		Filled with the current plugin API version number.
dvander@244
   166
	 * @param plmin			Filled with the minimum plugin API version number supported.
dvander@244
   167
	 */
dvander@124
   168
	virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
dvander@244
   169
	
dvander@244
   170
	/** 
dvander@244
   171
	 * @brief Returns sourcehook API version and implementation version.
dvander@244
   172
	 *
dvander@244
   173
	 * @param shvers		Filled with the SourceHook API version number.
dvander@244
   174
	 * @param shimpl		Filled with the SourceHook implementation number.
dvander@244
   175
	 */
dvander@124
   176
	virtual void GetShVersions(int &shvers, int &shimpl) =0;
dvander@244
   177
	
dvander@244
   178
	/**
dvander@244
   179
	 * @brief Adds a Metamod listener.
dvander@244
   180
	 *
dvander@244
   181
	 * @param plugin		Plugin interface pointer.
dvander@244
   182
	 * @param pListener		Listener interface pointer to add.
dvander@244
   183
	 */
dvander@138
   184
	virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
dvander@244
   185
dvander@139
   186
	/**
dvander@139
   187
	  * @brief Queries the metamod factory
dvander@139
   188
	  *
dvander@244
   189
	  * @param iface		String containing interface name
dvander@244
   190
	  * @param ret			Optional pointer to store return status
dvander@244
   191
	  * @param id			Optional pointer to store id of plugin that overrode interface, 0 if none
dvander@244
   192
	  * @return				Returned pointer
dvander@139
   193
	  */
dvander@139
   194
	virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
dvander@244
   195
dvander@152
   196
public:		//Added in 1.1.2 (1:1)
dvander@152
   197
	/**
dvander@152
   198
	 * @brief Given a base interface name, such as ServerGameDLL or ServerGameDLL003, 
dvander@152
   199
	 * reformats the string to increase the number, then returns the new number.
dvander@244
   200
	 * This is the base function to InterfaceSearch() and VInterfaceMatch().
dvander@244
   201
	 * 
dvander@244
   202
	 * @param iface			Input/output interface name.  Must be writable.
dvander@244
   203
	 * @param maxlength		Maximum length of iface buffer.  Must be at least strlen(iface)+4 chars.
dvander@244
   204
	 * @return				The newly incremented iface version number.
dvander@152
   205
	 */
dvander@152
   206
	virtual int FormatIface(char iface[], unsigned int maxlength) =0;
dvander@244
   207
dvander@166
   208
public:		//Added in 1.2 (1:2)
dvander@166
   209
	/**
dvander@166
   210
	 * @brief Searches for an interface for you.
dvander@244
   211
	 * 
dvander@244
   212
	 * @param fn			InterfaceFactory function.
dvander@244
   213
	 * @param iface			Interface string name.
dvander@244
   214
	 * @param max			Maximum version to look up.
dvander@244
   215
	 * @param ret			Last return code from interface factory function.
dvander@244
   216
	 * @return				Interface pointer, or NULL if not found.
dvander@166
   217
	 */
dvander@166
   218
	virtual void *InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max, int *ret) =0;
dvander@166
   219
dvander@166
   220
	/**
dvander@244
   221
	 * @brief Returns the base directory of the game/server, equivalent to 
dvander@282
   222
	 *  IVEngineServer::GetGameDir(), except the path is absolute.
dvander@244
   223
	 *
dvander@282
   224
	 * @return				Static pointer to game's absolute basedir.
dvander@166
   225
	 */
dvander@166
   226
	virtual const char *GetBaseDir() =0;
dvander@166
   227
dvander@166
   228
	/**
dvander@166
   229
	 * @brief Formats a file path to the local OS.  Does not include any base directories.
dvander@244
   230
	 * Note that all slashes and black slashes are reverted to the local OS's expectancy.
dvander@244
   231
	 *
dvander@244
   232
	 * @param buffer		Destination buffer to store path.
dvander@244
   233
	 * @param len			Maximum length of buffer, including null terminator.
dvander@244
   234
	 * @param fmt			Formatted string.
dvander@166
   235
	 */
dvander@166
   236
	virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
dvander@244
   237
ds@192
   238
public:		// Added in 1.2.2 (1:3)
ds@192
   239
	/**
ds@192
   240
	 * @brief Prints text in the specified client's console. Same as IVEngineServer::ClientPrintf 
ds@192
   241
	 *  except that it allows for string formatting.
dvander@244
   242
	 *
dvander@244
   243
	 * @param client		Client edict pointer.
dvander@244
   244
	 * @param fmt			Formatted string to print to the client.
ds@192
   245
	 */
ds@192
   246
	virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
dvander@244
   247
dvander@244
   248
public:		// Added in 1.3 (1:4)
dvander@244
   249
	/**
dvander@244
   250
	 * @brief Wrapper around InterfaceSearch().  Assumes no maximum.
dvander@244
   251
	 * This is designed to replace the fact that searches only went upwards.
dvander@244
   252
	 * The "V" is intended to convey that this is for Valve formatted interface strings.
dvander@244
   253
	 *
dvander@244
   254
	 * @param fn			Interface factory function.
dvander@244
   255
	 * @param iface			Interface string.
dvander@251
   256
	 * @param min			Minimum value to search from.  If zero, searching begins from the
dvander@251
   257
	 *                       first available version regardless of the interface.  
dvander@251
   258
	 *                      Note that this can return interfaces EARLIER than the version specified.
dvander@251
   259
	 *                      A value of -1 (default) specifies the string version as the minimum.
dvander@251
   260
	 *                      Any other value specifices the minimum value to search from.
dvander@244
   261
	 * @return				Interface pointer, or NULL if not found.
dvander@244
   262
	 */
dvander@251
   263
	virtual void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, int min=-1) =0;
dvander@282
   264
dvander@282
   265
public:		// Added in 1.4 (1:5)
dvander@282
   266
	/**
dvander@282
   267
	 * @brief Tells SourceMM to add VSP hooking capability to plugins.  
dvander@282
   268
	 *
dvander@282
   269
	 * Since this  potentially uses more resources than it would otherwise, plugins have to 
dvander@282
   270
	 * explicitly enable the feature.  Whether requested or not, if it is enabled, all plugins 
dvander@282
   271
	 * will get a pointer to the VSP listener through IMetamodListener.
dvander@282
   272
	 */
dvander@282
   273
	virtual void EnableVSPListener() =0;
dvander@282
   274
dvander@282
   275
	/**
dvander@282
   276
	 * @brief Returns the interface version of the GameDLL's IServerGameDLL implementation.
dvander@282
   277
	 *
dvander@282
   278
	 * @return				Interface version of the loaded IServerGameDLL.
dvander@282
   279
	 */
dvander@282
   280
	virtual int GetGameDLLVersion() =0;
dvander@7
   281
};
dvander@7
   282
dvander@138
   283
dvander@124
   284
/** Version history
dvander@152
   285
 * 1.1.0 bumped API to 1:0.  The breaking changes occured in sourcehook and the plugin API.
dvander@152
   286
 * 1.1.2 added API call for generating iface names.
dvander@167
   287
 * 1.2   added API more helper functions and new SourceHook version.
ds@192
   288
 * 1.2.2 added API for printing to client console (with string formatting)
dvander@244
   289
 * 1.3   added new interface search API
dvander@282
   290
 * 1.4	 added VSP listener API
dvander@124
   291
 */
dvander@124
   292
dvander@7
   293
#endif //_INCLUDE_ISMM_API_H