core-1.4/ISmmAPI.h
changeset 541 35a8cda28485
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/core-1.4/ISmmAPI.h	Fri Nov 14 04:25:40 2008 -0600
     1.3 @@ -0,0 +1,320 @@
     1.4 +/* ======== SourceMM ========
     1.5 +* Copyright (C) 2004-2008 Metamod:Source Development Team
     1.6 +* No warranties of any kind
     1.7 +*
     1.8 +* License: zlib/libpng
     1.9 +*
    1.10 +* Author(s): David "BAILOPAN" Anderson
    1.11 +* ============================
    1.12 +*/
    1.13 +
    1.14 +#ifndef _INCLUDE_ISMM_API_H
    1.15 +#define _INCLUDE_ISMM_API_H
    1.16 +
    1.17 +/**
    1.18 + * @brief External API interface
    1.19 + * @file ISmmAPI.h
    1.20 + */
    1.21 +
    1.22 +#include <interface.h>
    1.23 +#include <eiface.h>
    1.24 +#include <sourcehook/sourcehook.h>
    1.25 +#include "IPluginManager.h"
    1.26 +
    1.27 +#if defined __GNUC__
    1.28 +#if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
    1.29 +#error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
    1.30 +#endif //version check
    1.31 +#endif //__GNUC__
    1.32 +
    1.33 +class IMetamodListener;
    1.34 +class ISmmPluginManager;
    1.35 +class ISmmPlugin;
    1.36 +
    1.37 +#define	MMIFACE_SOURCEHOOK		"ISourceHook"			/**< ISourceHook Pointer */
    1.38 +#define	MMIFACE_PLMANAGER		"IPluginManager"		/**< SourceMM Plugin Functions */
    1.39 +#define IFACE_MAXNUM			999
    1.40 +
    1.41 +class ISmmAPI
    1.42 +{
    1.43 +public:
    1.44 +	/**
    1.45 +	 * @brief Logs a message through the HL2 log system.
    1.46 +	 * Note: Newlines are appended automatically.
    1.47 +	 *
    1.48 +	 * @param pl			Plugin API pointer (used for tagging message)
    1.49 +	 * @param msg			Formatted string.
    1.50 +	 */
    1.51 +	virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
    1.52 +public:
    1.53 +	/**
    1.54 +	 * @brief Returns an interface factory for the HL2 engine.
    1.55 +	 *
    1.56 +	 * @param syn			If syn is true, the synthetic wrapper is returned.  
    1.57 +	 *						If syn is false, the true function is returned.
    1.58 +	 * @return				CreateInterfaceFn function pointer.
    1.59 +	 */
    1.60 +	virtual CreateInterfaceFn engineFactory(bool syn=true) =0;
    1.61 +
    1.62 +	/**
    1.63 +	 * @brief Returns an interface factory for the HL2 physics engine.
    1.64 +	 *
    1.65 +	 * @param syn			If syn is true, the synthetic wrapper is returned.  
    1.66 +	 *						If syn is false, the true function is returned.
    1.67 +	 * @return				CreateInterfaceFn function pointer.
    1.68 +	 */
    1.69 +	virtual CreateInterfaceFn physicsFactory(bool syn=true) =0;
    1.70 +
    1.71 +	/**
    1.72 +	 * @brief Returns an interface factory for the HL2 file system.
    1.73 +	 *
    1.74 +	 * @param syn			If syn is true, the synthetic wrapper is returned.  
    1.75 +	 *						If syn is false, the true function is returned.
    1.76 +	 * @return				CreateInterfaceFn function pointer.
    1.77 +	 */
    1.78 +	virtual CreateInterfaceFn fileSystemFactory(bool syn=true) =0;
    1.79 +
    1.80 +	/**
    1.81 +	 * @brief Returns an interface factory for the GameDLL.
    1.82 +	 *
    1.83 +	 * @param syn			If syn is true, the synthetic wrapper is returned.  
    1.84 +	 *						If syn is false, the true function is returned.
    1.85 +	 * @return				CreateInterfaceFn function pointer.
    1.86 +	 */
    1.87 +	virtual CreateInterfaceFn serverFactory(bool syn=true) =0;
    1.88 +
    1.89 +	/**
    1.90 +	 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
    1.91 +	 *
    1.92 +	 * @return				CGlobalVars pointer.
    1.93 +	 */
    1.94 +	virtual CGlobalVars *pGlobals() =0;
    1.95 +
    1.96 +	/**
    1.97 +	 * @brief Used with SourceHook, sets teh last meta return value.
    1.98 +	 * Note: Do not call this directly, use the Metamod macros.
    1.99 +	 *
   1.100 +	 * @param res			META_RETURN value to set.
   1.101 +	 */
   1.102 +	virtual void SetLastMetaReturn(META_RES res) =0;
   1.103 +
   1.104 +	/**
   1.105 +	 * @brief Used with SourceHook, returns the last meta return value.
   1.106 +	 * Note: This is only valid inside a hook function.
   1.107 +	 *
   1.108 +	 * @return				Last META_RETURN value set by a plugin.
   1.109 +	 */
   1.110 +	virtual META_RES GetLastMetaReturn() =0;
   1.111 +
   1.112 +public:		// Added in 1.00-RC2 (0:0)
   1.113 +	/**
   1.114 +	 * @brief Allows access to Metamod's ConCommandBaseAccessor.
   1.115 +	 *
   1.116 +	 * @return				Returns IConCommandBaseAccessor pointer.
   1.117 +	 */
   1.118 +	virtual IConCommandBaseAccessor *GetCvarBaseAccessor() =0;
   1.119 +
   1.120 +	/**
   1.121 +	 * @brief Registers a ConCommandBase.
   1.122 +	 *
   1.123 +	 * @param plugin		Parent plugin API pointer.
   1.124 +	 * @param pCommand		ConCommandBase to register.
   1.125 +	 * @return				True if successful, false otherwise.  Does not return false yet.
   1.126 +	 */
   1.127 +	virtual bool RegisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   1.128 +
   1.129 +	/**
   1.130 +	 * @brief Unregisters a ConCommandBase.
   1.131 +	 *
   1.132 +	 * @param plugin		Parent plugin API pointer.
   1.133 +	 * @param pCommand		ConCommandBase to unlink.
   1.134 +	 */
   1.135 +	virtual void UnregisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   1.136 +	
   1.137 +	/**
   1.138 +	 * @brief Prints an unformatted string to the remote server console.
   1.139 +	 * Note: Newlines are not added automatically.
   1.140 +	 *
   1.141 +	 * @param str			Message string.
   1.142 +	 */
   1.143 +	virtual void ConPrint(const char *str) =0;
   1.144 +
   1.145 +	/**
   1.146 +	 * @brief Prints a formatted message to the remote server console.  
   1.147 +	 * Note: Newlines are not added automatically.
   1.148 +	 *
   1.149 +	 * @param fmt			Formatted message.
   1.150 +	 */
   1.151 +	virtual void ConPrintf(const char *fmt, ...) =0;
   1.152 +
   1.153 +public:		// Added in 1.1.0 (1:0)
   1.154 +	/**
   1.155 +	 * @brief Checks if ConPrint/ConPrintf will mirror to rcon.
   1.156 +	 *
   1.157 +	 * @return				True if remote printing available, false otherwise.
   1.158 +	 */
   1.159 +	virtual bool RemotePrintingAvailable() =0;
   1.160 +
   1.161 +	/**
   1.162 +	 * @brief Returns the Metamod Version numbers as major version and minor (API) version.
   1.163 +	 * Changes to minor version are guaranteed to be backwards compatible.
   1.164 +	 * Changes to major version are not.
   1.165 +	 * 
   1.166 +	 * @param major			Filled with the major API version number.
   1.167 +	 * @param minor			Filled with the minor API version number.
   1.168 +	 * @param plvers		Filled with the current plugin API version number.
   1.169 +	 * @param plmin			Filled with the minimum plugin API version number supported.
   1.170 +	 */
   1.171 +	virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
   1.172 +	
   1.173 +	/** 
   1.174 +	 * @brief Returns sourcehook API version and implementation version.
   1.175 +	 *
   1.176 +	 * @param shvers		Filled with the SourceHook API version number.
   1.177 +	 * @param shimpl		Filled with the SourceHook implementation number.
   1.178 +	 */
   1.179 +	virtual void GetShVersions(int &shvers, int &shimpl) =0;
   1.180 +	
   1.181 +	/**
   1.182 +	 * @brief Adds a Metamod listener.
   1.183 +	 *
   1.184 +	 * @param plugin		Plugin interface pointer.
   1.185 +	 * @param pListener		Listener interface pointer to add.
   1.186 +	 */
   1.187 +	virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
   1.188 +
   1.189 +	/**
   1.190 +	  * @brief Queries the metamod factory
   1.191 +	  *
   1.192 +	  * @param iface		String containing interface name
   1.193 +	  * @param ret			Optional pointer to store return status
   1.194 +	  * @param id			Optional pointer to store id of plugin that overrode interface, 0 if none
   1.195 +	  * @return				Returned pointer
   1.196 +	  */
   1.197 +	virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
   1.198 +
   1.199 +public:		// Added in 1.1.2 (1:1)
   1.200 +	/**
   1.201 +	 * @brief Given a base interface name, such as ServerGameDLL or ServerGameDLL003, 
   1.202 +	 * reformats the string to increase the number, then returns the new number.
   1.203 +	 * This is the base function to InterfaceSearch() and VInterfaceMatch().
   1.204 +	 * 
   1.205 +	 * @param iface			Input/output interface name.  Must be writable.
   1.206 +	 * @param maxlength		Maximum length of iface buffer.  Must be at least strlen(iface)+4 chars.
   1.207 +	 * @return				The newly incremented iface version number.
   1.208 +	 */
   1.209 +	virtual int FormatIface(char iface[], unsigned int maxlength) =0;
   1.210 +
   1.211 +public:		// Added in 1.2 (1:2)
   1.212 +	/**
   1.213 +	 * @brief Searches for an interface for you.
   1.214 +	 * 
   1.215 +	 * @param fn			InterfaceFactory function.
   1.216 +	 * @param iface			Interface string name.
   1.217 +	 * @param max			Maximum version to look up.
   1.218 +	 * @param ret			Last return code from interface factory function.
   1.219 +	 * @return				Interface pointer, or NULL if not found.
   1.220 +	 */
   1.221 +	virtual void *InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max, int *ret) =0;
   1.222 +
   1.223 +	/**
   1.224 +	 * @brief Returns the base directory of the game/server, equivalent to 
   1.225 +	 *  IVEngineServer::GetGameDir(), except the path is absolute.
   1.226 +	 *
   1.227 +	 * @return				Static pointer to game's absolute basedir.
   1.228 +	 */
   1.229 +	virtual const char *GetBaseDir() =0;
   1.230 +
   1.231 +	/**
   1.232 +	 * @brief Formats a file path to the local OS.  Does not include any base directories.
   1.233 +	 * Note that all slashes and black slashes are reverted to the local OS's expectancy.
   1.234 +	 *
   1.235 +	 * @param buffer		Destination buffer to store path.
   1.236 +	 * @param len			Maximum length of buffer, including null terminator.
   1.237 +	 * @param fmt			Formatted string.
   1.238 +	 */
   1.239 +	virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
   1.240 +
   1.241 +public:		// Added in 1.2.2 (1:3)
   1.242 +	/**
   1.243 +	 * @brief Prints text in the specified client's console. Same as IVEngineServer::ClientPrintf 
   1.244 +	 *  except that it allows for string formatting.
   1.245 +	 *
   1.246 +	 * @param client		Client edict pointer.
   1.247 +	 * @param fmt			Formatted string to print to the client.
   1.248 +	 */
   1.249 +	virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
   1.250 +
   1.251 +public:		// Added in 1.3 (1:4)
   1.252 +	/**
   1.253 +	 * @brief Wrapper around InterfaceSearch().  Assumes no maximum.
   1.254 +	 * This is designed to replace the fact that searches only went upwards.
   1.255 +	 * The "V" is intended to convey that this is for Valve formatted interface strings.
   1.256 +	 *
   1.257 +	 * @param fn			Interface factory function.
   1.258 +	 * @param iface			Interface string.
   1.259 +	 * @param min			Minimum value to search from.  If zero, searching begins from the
   1.260 +	 *                       first available version regardless of the interface.  
   1.261 +	 *                      Note that this can return interfaces EARLIER than the version specified.
   1.262 +	 *                      A value of -1 (default) specifies the string version as the minimum.
   1.263 +	 *                      Any other value specifices the minimum value to search from.
   1.264 +	 * @return				Interface pointer, or NULL if not found.
   1.265 +	 */
   1.266 +	virtual void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, int min=-1) =0;
   1.267 +
   1.268 +public:		// Added in 1.4 (1:5)
   1.269 +	/**
   1.270 +	 * @brief Tells SourceMM to add VSP hooking capability to plugins.  
   1.271 +	 *
   1.272 +	 * Since this  potentially uses more resources than it would otherwise, plugins have to 
   1.273 +	 * explicitly enable the feature.  Whether requested or not, if it is enabled, all plugins 
   1.274 +	 * will get a pointer to the VSP listener through IMetamodListener.
   1.275 +	 */
   1.276 +	virtual void EnableVSPListener() =0;
   1.277 +
   1.278 +	/**
   1.279 +	 * @brief Returns the interface version of the GameDLL's IServerGameDLL implementation.
   1.280 +	 *
   1.281 +	 * @return				Interface version of the loaded IServerGameDLL.
   1.282 +	 */
   1.283 +	virtual int GetGameDLLVersion() =0;
   1.284 +
   1.285 +	/**
   1.286 +	 * @brief Returns the number of user messages in the GameDLL.
   1.287 +	 *
   1.288 +	 * @return				Number of user messages, or -1 if SourceMM has failed to get user message list.
   1.289 +	 */
   1.290 +	virtual int GetUserMessageCount() =0;
   1.291 +
   1.292 +	/**
   1.293 +	 * @brief Returns the index of the specified user message.
   1.294 +	 *
   1.295 +	 * @param name			User message name.
   1.296 +	 * @param size			Optional pointer to store size of user message.
   1.297 +	 * @return				Message index, or -1 on failure.
   1.298 +	 */
   1.299 +	virtual int FindUserMessage(const char *name, int *size=NULL) =0;
   1.300 +
   1.301 +	/**
   1.302 +	 * @brief Returns the name of the specified user message.
   1.303 +	 *
   1.304 +	 * @param index			User message index.
   1.305 +	 * @param size			Optional pointer to store size of user message.
   1.306 +	 * @return				Message name, or NULL on failure.
   1.307 +	 */
   1.308 +	virtual const char *GetUserMessage(int index, int *size=NULL) =0;
   1.309 +};
   1.310 +
   1.311 +
   1.312 +/** 
   1.313 + * Version History
   1.314 + *
   1.315 + * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API.
   1.316 + * 1.1.2 Added API call for generating iface names.
   1.317 + * 1.2   Added API more helper functions and new SourceHook version.
   1.318 + * 1.2.2 Added API for printing to client console (with string formatting).
   1.319 + * 1.3   Added new interface search API.
   1.320 + * 1.4	 Added VSP listener and user message API.
   1.321 + */
   1.322 +
   1.323 +#endif //_INCLUDE_ISMM_API_H