1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/core-legacy/ISmmAPI.h Fri Nov 14 05:02:00 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