1.1 --- a/sourcemm/ISmmAPI.h Thu Oct 04 19:46:28 2007 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,393 +0,0 @@
1.4 -/**
1.5 - * vim: set ts=4 :
1.6 - * ======================================================
1.7 - * Metamod:Source
1.8 - * Copyright (C) 2004-2007 AlliedModders LLC and authors.
1.9 - * All rights reserved.
1.10 - * ======================================================
1.11 - *
1.12 - * This software is provided 'as-is', without any express or implied warranty.
1.13 - * In no event will the authors be held liable for any damages arising from
1.14 - * the use of this software.
1.15 - *
1.16 - * Permission is granted to anyone to use this software for any purpose,
1.17 - * including commercial applications, and to alter it and redistribute it
1.18 - * freely, subject to the following restrictions:
1.19 - *
1.20 - * 1. The origin of this software must not be misrepresented; you must not
1.21 - * claim that you wrote the original software. If you use this software in a
1.22 - * product, an acknowledgment in the product documentation would be
1.23 - * appreciated but is not required.
1.24 - * 2. Altered source versions must be plainly marked as such, and must not be
1.25 - * misrepresented as being the original software.
1.26 - * 3. This notice may not be removed or altered from any source distribution.
1.27 - *
1.28 - * Version: $Id$
1.29 - */
1.30 -
1.31 -#ifndef _INCLUDE_ISMM_API_H
1.32 -#define _INCLUDE_ISMM_API_H
1.33 -
1.34 -/**
1.35 - * @brief External API interface
1.36 - * @file ISmmAPI.h
1.37 - */
1.38 -
1.39 -#include <interface.h>
1.40 -#include <eiface.h>
1.41 -#include <sourcehook.h>
1.42 -#include "IPluginManager.h"
1.43 -
1.44 -#if defined __GNUC__
1.45 -#if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
1.46 -#error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
1.47 -#endif //version check
1.48 -#endif //__GNUC__
1.49 -
1.50 -class IMetamodListener;
1.51 -class ISmmPluginManager;
1.52 -class ISmmPlugin;
1.53 -
1.54 -#define MMIFACE_SOURCEHOOK "ISourceHook" /**< ISourceHook Pointer */
1.55 -#define MMIFACE_PLMANAGER "IPluginManager" /**< SourceMM Plugin Functions */
1.56 -#define IFACE_MAXNUM 999 /**< Maximum interface version */
1.57 -
1.58 -#define SOURCE_ENGINE_UNKNOWN 0 /**< Could not determine the engine version */
1.59 -#define SOURCE_ENGINE_ORIGINAL 1 /**< Original Source Engine (used by The Ship) */
1.60 -#define SOURCE_ENGINE_EPISODEONE 2 /**< Episode 1 Source Engine (second major SDK) */
1.61 -#define SOURCE_ENGINE_ORANGEBOX 3 /**< Orange Box Source Engine (third major SDK) */
1.62 -
1.63 -class ISmmAPI
1.64 -{
1.65 -public:
1.66 - /**
1.67 - * @brief Logs a message through the HL2 log system.
1.68 - * Note: Newlines are appended automatically.
1.69 - *
1.70 - * @param pl Plugin API pointer (used for tagging message)
1.71 - * @param msg Formatted string.
1.72 - */
1.73 - virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
1.74 -public:
1.75 - /**
1.76 - * @brief Returns an interface factory for the HL2 engine.
1.77 - *
1.78 - * @param syn If syn is true, the synthetic wrapper is returned.
1.79 - * If syn is false, the true function is returned.
1.80 - * @return CreateInterfaceFn function pointer.
1.81 - */
1.82 - virtual CreateInterfaceFn engineFactory(bool syn=true) =0;
1.83 -
1.84 - /**
1.85 - * @brief Returns an interface factory for the HL2 physics engine.
1.86 - *
1.87 - * @param syn If syn is true, the synthetic wrapper is returned.
1.88 - * If syn is false, the true function is returned.
1.89 - * @return CreateInterfaceFn function pointer.
1.90 - */
1.91 - virtual CreateInterfaceFn physicsFactory(bool syn=true) =0;
1.92 -
1.93 - /**
1.94 - * @brief Returns an interface factory for the HL2 file system.
1.95 - *
1.96 - * @param syn If syn is true, the synthetic wrapper is returned.
1.97 - * If syn is false, the true function is returned.
1.98 - * @return CreateInterfaceFn function pointer.
1.99 - */
1.100 - virtual CreateInterfaceFn fileSystemFactory(bool syn=true) =0;
1.101 -
1.102 - /**
1.103 - * @brief Returns an interface factory for the GameDLL.
1.104 - *
1.105 - * @param syn If syn is true, the synthetic wrapper is returned.
1.106 - * If syn is false, the true function is returned.
1.107 - * @return CreateInterfaceFn function pointer.
1.108 - */
1.109 - virtual CreateInterfaceFn serverFactory(bool syn=true) =0;
1.110 -
1.111 - /**
1.112 - * @brief Returns a CGlobalVars pointer from the HL2 Engine.
1.113 - *
1.114 - * @return CGlobalVars pointer.
1.115 - */
1.116 - virtual CGlobalVars *pGlobals() =0;
1.117 -
1.118 - /**
1.119 - * @brief Used with SourceHook, sets teh last meta return value.
1.120 - * Note: Do not call this directly, use the Metamod macros.
1.121 - *
1.122 - * @param res META_RETURN value to set.
1.123 - */
1.124 - virtual void SetLastMetaReturn(META_RES res) =0;
1.125 -
1.126 - /**
1.127 - * @brief Used with SourceHook, returns the last meta return value.
1.128 - * Note: This is only valid inside a hook function.
1.129 - *
1.130 - * @return Last META_RETURN value set by a plugin.
1.131 - */
1.132 - virtual META_RES GetLastMetaReturn() =0;
1.133 -
1.134 -public: // Added in 1.00-RC2 (0:0)
1.135 - /**
1.136 - * @brief Allows access to Metamod's ConCommandBaseAccessor.
1.137 - *
1.138 - * @return Returns IConCommandBaseAccessor pointer.
1.139 - */
1.140 - virtual IConCommandBaseAccessor *GetCvarBaseAccessor() =0;
1.141 -
1.142 - /**
1.143 - * @brief Registers a ConCommandBase.
1.144 - *
1.145 - * @param plugin Parent plugin API pointer.
1.146 - * @param pCommand ConCommandBase to register.
1.147 - * @return True if successful, false otherwise.
1.148 - */
1.149 - virtual bool RegisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
1.150 -
1.151 - /**
1.152 - * @brief Unregisters a ConCommandBase.
1.153 - *
1.154 - * @param plugin Parent plugin API pointer.
1.155 - * @param pCommand ConCommandBase to unlink.
1.156 - */
1.157 - virtual void UnregisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
1.158 -
1.159 - /**
1.160 - * @brief Prints an unformatted string to the remote server console.
1.161 - *
1.162 - * Note: Newlines are not added automatically.
1.163 - *
1.164 - * @param str Message string.
1.165 - */
1.166 - virtual void ConPrint(const char *str) =0;
1.167 -
1.168 - /**
1.169 - * @brief Prints a formatted message to the remote server console.
1.170 - *
1.171 - * Note: Newlines are not added automatically.
1.172 - *
1.173 - * @param fmt Formatted message.
1.174 - */
1.175 - virtual void ConPrintf(const char *fmt, ...) =0;
1.176 -
1.177 -public: // Added in 1.1.0 (1:0)
1.178 - /**
1.179 - * @brief Checks if ConPrint/ConPrintf will mirror to rcon.
1.180 - *
1.181 - * @return True if remote printing available, false otherwise.
1.182 - */
1.183 - virtual bool RemotePrintingAvailable() =0;
1.184 -
1.185 - /**
1.186 - * @brief Returns the Metamod Version numbers as major version and minor (API) version.
1.187 - * Changes to minor version are guaranteed to be backwards compatible.
1.188 - * Changes to major version are not.
1.189 - *
1.190 - * @param major Filled with the major API version number.
1.191 - * @param minor Filled with the minor API version number.
1.192 - * @param plvers Filled with the current plugin API version number.
1.193 - * @param plmin Filled with the minimum plugin API version number supported.
1.194 - */
1.195 - virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
1.196 -
1.197 - /**
1.198 - * @brief Returns sourcehook API version and implementation version.
1.199 - *
1.200 - * @param shvers Filled with the SourceHook API version number.
1.201 - * @param shimpl Filled with the SourceHook implementation number.
1.202 - */
1.203 - virtual void GetShVersions(int &shvers, int &shimpl) =0;
1.204 -
1.205 - /**
1.206 - * @brief Adds a Metamod listener.
1.207 - *
1.208 - * @param plugin Plugin interface pointer.
1.209 - * @param pListener Listener interface pointer to add.
1.210 - */
1.211 - virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
1.212 -
1.213 - /**
1.214 - * @brief Queries the metamod factory
1.215 - *
1.216 - * @param iface String containing interface name
1.217 - * @param ret Optional pointer to store return status
1.218 - * @param id Optional pointer to store id of plugin that overrode interface, 0 if none
1.219 - * @return Returned pointer
1.220 - */
1.221 - virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
1.222 -
1.223 -public: // Added in 1.1.2 (1:1)
1.224 - /**
1.225 - * @brief Given a base interface name, such as ServerGameDLL or ServerGameDLL003,
1.226 - * reformats the string to increase the number, then returns the new number.
1.227 - * This is the base function to InterfaceSearch() and VInterfaceMatch().
1.228 - *
1.229 - * @param iface Input/output interface name. Must be writable.
1.230 - * @param maxlength Maximum length of iface buffer. Must be at least strlen(iface)+4 chars.
1.231 - * @return The newly incremented iface version number.
1.232 - */
1.233 - virtual int FormatIface(char iface[], unsigned int maxlength) =0;
1.234 -
1.235 -public: // Added in 1.2 (1:2)
1.236 - /**
1.237 - * @brief Searches for an interface, eliminating the need to loop through FormatIface().
1.238 - *
1.239 - * @param fn InterfaceFactory function.
1.240 - * @param iface Interface string name.
1.241 - * @param max Maximum version to look up.
1.242 - * @param ret Last return code from interface factory function.
1.243 - * @return Interface pointer, or NULL if not found.
1.244 - */
1.245 - virtual void *InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max, int *ret) =0;
1.246 -
1.247 - /**
1.248 - * @brief Returns the base directory of the game/server, equivalent to
1.249 - * IVEngineServer::GetGameDir(), except the path is absolute.
1.250 - *
1.251 - * @return Static pointer to game's absolute basedir.
1.252 - */
1.253 - virtual const char *GetBaseDir() =0;
1.254 -
1.255 - /**
1.256 - * @brief Formats a file path to the local OS.
1.257 - *
1.258 - * Does not include any base directories. Note that all slashes and black
1.259 - * slashes are reverted to the local OS's expectancy.
1.260 - *
1.261 - * @param buffer Destination buffer to store path.
1.262 - * @param len Maximum length of buffer, including null terminator.
1.263 - * @param fmt Formatted string.
1.264 - */
1.265 - virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
1.266 -
1.267 -public: // Added in 1.2.2 (1:3)
1.268 - /**
1.269 - * @brief Prints text in the specified client's console. Same as
1.270 - * IVEngineServer::ClientPrintf except that it allows for string formatting.
1.271 - *
1.272 - * @param client Client edict pointer.
1.273 - * @param fmt Formatted string to print to the client.
1.274 - */
1.275 - virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
1.276 -
1.277 -public: // Added in 1.3 (1:4)
1.278 - /**
1.279 - * @brief Wrapper around InterfaceSearch(). Assumes no maximum.
1.280 - * This is designed to replace the fact that searches only went upwards.
1.281 - * The "V" is intended to convey that this is for Valve formatted interface strings.
1.282 - *
1.283 - * @param fn Interface factory function.
1.284 - * @param iface Interface string.
1.285 - * @param min Minimum value to search from. If zero, searching
1.286 - * begins from the first available version regardless
1.287 - * of the interface. Note that this can return
1.288 - * interfaces EARLIER than the version specified. A
1.289 - * value of -1 (default) specifies the string version
1.290 - * as the minimum. Any other value specifices the
1.291 - * minimum value to search from.
1.292 - * @return Interface pointer, or NULL if not found.
1.293 - */
1.294 - virtual void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, int min=-1) =0;
1.295 -
1.296 -public: // Added in 1.4 (1:5)
1.297 - /**
1.298 - * @brief Tells SourceMM to add VSP hooking capability to plugins.
1.299 - *
1.300 - * Since this potentially uses more resources than it would otherwise,
1.301 - * plugins have to explicitly enable the feature. Whether requested or
1.302 - * not, if it is enabled, all plugins will get a pointer to the VSP
1.303 - * listener through IMetamodListener. This will not be called more than
1.304 - * once for a given plugin; if it is requested more than once, each
1.305 - * successive call will only give the pointer to plugins which have not
1.306 - * yet received it.
1.307 - */
1.308 - virtual void EnableVSPListener() =0;
1.309 -
1.310 - /**
1.311 - * @brief Returns the interface version of the GameDLL's IServerGameDLL
1.312 - * implementation.
1.313 - *
1.314 - * @return Interface version of the loaded IServerGameDLL.
1.315 - */
1.316 - virtual int GetGameDLLVersion() =0;
1.317 -
1.318 - /**
1.319 - * @brief Returns the number of user messages in the GameDLL.
1.320 - *
1.321 - * @return Number of user messages, or -1 if SourceMM has
1.322 - * failed to get user message list.
1.323 - */
1.324 - virtual int GetUserMessageCount() =0;
1.325 -
1.326 - /**
1.327 - * @brief Returns the index of the specified user message.
1.328 - *
1.329 - * @param name User message name.
1.330 - * @param size Optional pointer to store size of user message.
1.331 - * @return Message index, or -1 on failure.
1.332 - */
1.333 - virtual int FindUserMessage(const char *name, int *size=NULL) =0;
1.334 -
1.335 - /**
1.336 - * @brief Returns the name of the specified user message.
1.337 - *
1.338 - * @param index User message index.
1.339 - * @param size Optional pointer to store size of user message.
1.340 - * @return Message name, or NULL on failure.
1.341 - */
1.342 - virtual const char *GetUserMessage(int index, int *size=NULL) =0;
1.343 -
1.344 -public: // Added in 1.5.0 (1:6)
1.345 - /**
1.346 - * @brief Returns the highest interface version of IServerPluginCallbacks
1.347 - * that the engine supports. This is useful for games that run on older
1.348 - * versions of the Source engine, such as The Ship.
1.349 - *
1.350 - * @return Highest interface version of IServerPluginCallbacks.
1.351 - * Returns 0 if SourceMM's VSP listener isn't currently
1.352 - * enabled.
1.353 - */
1.354 - virtual int GetVSPVersion() =0;
1.355 -
1.356 -public: // Added in 1.6.0 (1:7)
1.357 - /**
1.358 - * @brief Returns the engine interface that MM:S is using as a backend.
1.359 - *
1.360 - * The values will be one of the SOURCE_ENGINE_* constants from the top
1.361 - * of this file.
1.362 - *
1.363 - * @return A SOURCE_ENGINE_* constant value.
1.364 - */
1.365 - virtual int GetSourceEngineBuild() =0;
1.366 -
1.367 - /**
1.368 - * @brief Returns the VSP listener loaded.
1.369 - *
1.370 - * This is useful for late-loading plugins which need to decide whether
1.371 - * to add a listener or not (or need to get the pointer at all).
1.372 - *
1.373 - * @param Optional pointer to store the VSP version.
1.374 - * @return IServerPluginCallbacks pointer, or NULL if an
1.375 - * IMetamodListener event has yet to occur for
1.376 - * EnableVSPListener().
1.377 - */
1.378 - virtual IServerPluginCallbacks *GetVSPInfo(int *pVersion) =0;
1.379 -};
1.380 -
1.381 -
1.382 -/**
1.383 - * Version History
1.384 - *
1.385 - * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API.
1.386 - * 1.1.2 Added API call for generating iface names.
1.387 - * 1.2 Added API more helper functions and new SourceHook version.
1.388 - * 1.2.2 Added API for printing to client console (with string formatting).
1.389 - * 1.3 Added new interface search API.
1.390 - * 1.4 Added VSP listener and user message API.
1.391 - * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks.
1.392 - * 1.6.0 Added API for Orange Box.
1.393 - */
1.394 -
1.395 -#endif //_INCLUDE_ISMM_API_H
1.396 -