1.1 --- a/sourcemm/ISmmAPI.h Sun Nov 25 01:22:41 2007 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,405 +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 <stdarg.h>
1.40 -#include <interface.h>
1.41 -#include <eiface.h>
1.42 -#include <sourcehook.h>
1.43 -#include <IPluginManager.h>
1.44 -#include <ISmmPlugin.h>
1.45 -#include <ISmmPluginExt.h>
1.46 -
1.47 -#if defined __GNUC__
1.48 -#if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
1.49 -#error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
1.50 -#endif //version check
1.51 -#endif //__GNUC__
1.52 -
1.53 -#define MMIFACE_SOURCEHOOK "ISourceHook" /**< ISourceHook Pointer */
1.54 -#define MMIFACE_PLMANAGER "IPluginManager" /**< SourceMM Plugin Functions */
1.55 -#define MMIFACE_SH_HOOKMANAUTOGEN "IHookManagerAutoGen" /**< SourceHook::IHookManagerAutoGen Pointer */
1.56 -#define IFACE_MAXNUM 999 /**< Maximum interface version */
1.57 -
1.58 -namespace SourceMM
1.59 -{
1.60 - class ISmmPlugin;
1.61 - class IMetamodListener;
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 -
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 GetEngineFactory(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 GetPhysicsFactory(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 GetFileSystemFactory(bool syn=true) =0;
1.101 -
1.102 - /**
1.103 - * @brief Returns an interface factory for the GameDLL.
1.104 - *
1.105 - * If syn is false, the true function is returned.
1.106 - * @return CreateInterfaceFn function pointer.
1.107 - */
1.108 - virtual CreateInterfaceFn GetServerFactory(bool syn=true) =0;
1.109 -
1.110 - /**
1.111 - * @brief Returns a CGlobalVars pointer from the HL2 Engine.
1.112 - *
1.113 - * @return CGlobalVars pointer.
1.114 - */
1.115 - virtual CGlobalVars *GetCGlobals() =0;
1.116 -
1.117 - /**
1.118 - * @brief Registers a ConCommandBase.
1.119 - *
1.120 - * @param plugin Parent plugin API pointer.
1.121 - * @param pCommand ConCommandBase to register.
1.122 - * @return True if successful, false otherwise.
1.123 - */
1.124 - virtual bool RegisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
1.125 -
1.126 - /**
1.127 - * @brief Unregisters a ConCommandBase.
1.128 - *
1.129 - * @param plugin Parent plugin API pointer.
1.130 - * @param pCommand ConCommandBase to unlink.
1.131 - */
1.132 - virtual void UnregisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
1.133 -
1.134 - /**
1.135 - * @brief Prints an unformatted string to the remote server console.
1.136 - *
1.137 - * Note: Newlines are not added automatically.
1.138 - *
1.139 - * @param str Message string.
1.140 - */
1.141 - virtual void ConPrint(const char *str) =0;
1.142 -
1.143 - /**
1.144 - * @brief Prints a formatted message to the remote server console.
1.145 - *
1.146 - * Note: Newlines are not added automatically.
1.147 - *
1.148 - * @param fmt Formatted message.
1.149 - */
1.150 - virtual void ConPrintf(const char *fmt, ...) =0;
1.151 -
1.152 - /**
1.153 - * @brief Returns the Metamod Version numbers as major version and
1.154 - * minor (API) version. Changes to minor version are guaranteed to be
1.155 - * backwards compatible. Changes to major version are not.
1.156 - *
1.157 - * @param major Filled with the major API version number.
1.158 - * @param minor Filled with the minor API version number.
1.159 - * @param plvers Filled with the current plugin API version number.
1.160 - * @param plmin Filled with the minimum plugin API version number
1.161 - * supported.
1.162 - */
1.163 - virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
1.164 -
1.165 - /**
1.166 - * @brief Returns sourcehook API version and implementation version.
1.167 - *
1.168 - * @param shvers Filled with the SourceHook API version number.
1.169 - * @param shimpl Filled with the SourceHook implementation number.
1.170 - */
1.171 - virtual void GetShVersions(int &shvers, int &shimpl) =0;
1.172 -
1.173 - /**
1.174 - * @brief Adds a Metamod listener.
1.175 - *
1.176 - * @param plugin Plugin interface pointer.
1.177 - * @param pListener Listener interface pointer to add.
1.178 - */
1.179 - virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
1.180 -
1.181 - /**
1.182 - * @brief Queries the metamod factory
1.183 - *
1.184 - * @param iface String containing interface name
1.185 - * @param ret Optional pointer to store return status
1.186 - * @param id Optional pointer to store id of plugin that
1.187 - * overrode interface, 0 if none
1.188 - * @return Returned pointer
1.189 - */
1.190 - virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
1.191 -
1.192 - /**
1.193 - * @brief Given a base interface name, such as ServerGameDLL or
1.194 - * ServerGameDLL003, reformats the string to increase the number, then
1.195 - * returns the new number. This is the base function to InterfaceSearch()
1.196 - * and VInterfaceMatch().
1.197 - *
1.198 - * @param iface Input/output interface name. Must be writable.
1.199 - * @param maxlength Maximum length of iface buffer. Must be at least
1.200 - * strlen(iface)+4 chars.
1.201 - * @return The newly incremented iface version number.
1.202 - */
1.203 - virtual int FormatIface(char iface[], unsigned int maxlength) =0;
1.204 -
1.205 - /**
1.206 - * @brief Searches for an interface, eliminating the need to loop
1.207 - * through FormatIface().
1.208 - *
1.209 - * @param fn InterfaceFactory function.
1.210 - * @param iface Interface string name.
1.211 - * @param max Maximum version to look up.
1.212 - * @param ret Last return code from interface factory function.
1.213 - * @return Interface pointer, or NULL if not found.
1.214 - */
1.215 - virtual void *InterfaceSearch(CreateInterfaceFn fn,
1.216 - const char *iface,
1.217 - int max,
1.218 - int *ret) =0;
1.219 -
1.220 - /**
1.221 - * @brief Returns the base directory of the game/server, equivalent to
1.222 - * IVEngineServer::GetGameDir(), except the path is absolute.
1.223 - *
1.224 - * @return Static pointer to game's absolute basedir.
1.225 - */
1.226 - virtual const char *GetBaseDir() =0;
1.227 -
1.228 - /**
1.229 - * @brief Formats a file path to the local OS.
1.230 - *
1.231 - * Does not include any base directories. Note that all slashes and
1.232 - * black slashes are reverted to the local OS's expectancy.
1.233 - *
1.234 - * @param buffer Destination buffer to store path.
1.235 - * @param len Maximum length of buffer, including null
1.236 - * terminator.
1.237 - * @param fmt Formatted string.
1.238 - * @param ... Arguments in the string.
1.239 - * @return Number of bytes written, not including the null
1.240 - * terminator.
1.241 - */
1.242 - virtual size_t PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
1.243 -
1.244 - /**
1.245 - * @brief Prints text in the specified client's console. Same as
1.246 - * IVEngineServer::ClientPrintf except that it allows for string
1.247 - * formatting.
1.248 - *
1.249 - * @param client Client edict pointer.
1.250 - * @param fmt Formatted string to print to the client.
1.251 - */
1.252 - virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
1.253 -
1.254 - /**
1.255 - * @brief Wrapper around InterfaceSearch(). Assumes no maximum.
1.256 - * This is designed to replace the fact that searches only went upwards.
1.257 - * The "V" is intended to convey that this is for Valve formatted
1.258 - * interface strings.
1.259 - *
1.260 - * @param fn Interface factory function.
1.261 - * @param iface Interface string.
1.262 - * @param min Minimum value to search from. If zero, searching
1.263 - * begins from the first available version regardless
1.264 - * of the interface. Note that this can return
1.265 - * interfaces EARLIER than the version specified. A
1.266 - * value of -1 (default) specifies the string version
1.267 - * as the minimum. Any other value specifices the
1.268 - * minimum value to search from.
1.269 - * @return Interface pointer, or NULL if not found.
1.270 - */
1.271 - virtual void *VInterfaceMatch(CreateInterfaceFn fn,
1.272 - const char *iface,
1.273 - int min=-1) =0;
1.274 -
1.275 - /**
1.276 - * @brief Tells SourceMM to add VSP hooking capability to plugins.
1.277 - *
1.278 - * Since this potentially uses more resources than it would otherwise,
1.279 - * plugins have to explicitly enable the feature. Whether requested or
1.280 - * not, if it is enabled, all plugins will get a pointer to the VSP
1.281 - * listener through IMetamodListener. This will not be called more than
1.282 - * once for a given plugin; if it is requested more than once, each
1.283 - * successive call will only give the pointer to plugins which have not
1.284 - * yet received it.
1.285 - */
1.286 - virtual void EnableVSPListener() =0;
1.287 -
1.288 - /**
1.289 - * @brief Returns the interface version of the GameDLL's IServerGameDLL
1.290 - * implementation.
1.291 - *
1.292 - * @return Interface version of the loaded IServerGameDLL.
1.293 - */
1.294 - virtual int GetGameDLLVersion() =0;
1.295 -
1.296 - /**
1.297 - * @brief Returns the number of user messages in the GameDLL.
1.298 - *
1.299 - * @return Number of user messages, or -1 if SourceMM has
1.300 - * failed to get user message list.
1.301 - */
1.302 - virtual int GetUserMessageCount() =0;
1.303 -
1.304 - /**
1.305 - * @brief Returns the index of the specified user message.
1.306 - *
1.307 - * @param name User message name.
1.308 - * @param size Optional pointer to store size of user message.
1.309 - * @return Message index, or -1 on failure.
1.310 - */
1.311 - virtual int FindUserMessage(const char *name, int *size=NULL) =0;
1.312 -
1.313 - /**
1.314 - * @brief Returns the name of the specified user message.
1.315 - *
1.316 - * @param index User message index.
1.317 - * @param size Optional pointer to store size of user message.
1.318 - * @return Message name, or NULL on failure.
1.319 - */
1.320 - virtual const char *GetUserMessage(int index, int *size=NULL) =0;
1.321 -
1.322 - /**
1.323 - * @brief Returns the highest interface version of IServerPluginCallbacks
1.324 - * that the engine supports. This is useful for games that run on older
1.325 - * versions of the Source engine, such as The Ship.
1.326 - *
1.327 - * @return Highest interface version of IServerPluginCallbacks.
1.328 - * Returns 0 if SourceMM's VSP listener isn't
1.329 - * currently enabled.
1.330 - */
1.331 - virtual int GetVSPVersion() =0;
1.332 -
1.333 - /**
1.334 - * @brief Returns the engine interface that MM:S is using as a backend.
1.335 - *
1.336 - * The values will be one of the SOURCE_ENGINE_* constants from the top
1.337 - * of this file.
1.338 - *
1.339 - * @return A SOURCE_ENGINE_* constant value.
1.340 - */
1.341 - virtual int GetSourceEngineBuild() =0;
1.342 -
1.343 - /**
1.344 - * @brief Returns the VSP listener loaded.
1.345 - *
1.346 - * This is useful for late-loading plugins which need to decide whether
1.347 - * to add a listener or not (or need to get the pointer at all).
1.348 - *
1.349 - * @param Optional pointer to store the VSP version.
1.350 - * @return IServerPluginCallbacks pointer, or NULL if an
1.351 - * IMetamodListener event has yet to occur for
1.352 - * EnableVSPListener().
1.353 - */
1.354 - virtual IServerPluginCallbacks *GetVSPInfo(int *pVersion) =0;
1.355 -
1.356 - /**
1.357 - * @brief Formats a string. This is a platform safe wrapper around
1.358 - * snprintf/_snprintf.
1.359 - *
1.360 - * @param buffer Buffer to write to.
1.361 - * @param maxlength Maximum length of the buffer.
1.362 - * @param format Format specifiers.
1.363 - * @param ... Format arguments.
1.364 - * @return Number of bytes actually written, not including
1.365 - * the null terminator.
1.366 - */
1.367 - virtual size_t Format(char *buffer,
1.368 - size_t maxlength,
1.369 - const char *format,
1.370 - ...) =0;
1.371 -
1.372 - /**
1.373 - * @brief Formats a string. This is a platform safe wrapper around
1.374 - * vsnprintf/_vsnprintf.
1.375 - *
1.376 - * @param buffer Buffer to write to.
1.377 - * @param maxlength Maximum length of the buffer.
1.378 - * @param format Format specifiers.
1.379 - * @param ap Format argument list.
1.380 - * @return Number of bytes actually written, not including the
1.381 - * null terminator.
1.382 - */
1.383 - virtual size_t FormatArgs(char *buffer,
1.384 - size_t maxlength,
1.385 - const char *format,
1.386 - va_list ap) =0;
1.387 - };
1.388 -}
1.389 -
1.390 -#if !defined METAMOD_NO_AUTO_NAMESPACE
1.391 -using namespace SourceMM;
1.392 -#endif
1.393 -
1.394 -/**
1.395 - * Version History
1.396 - *
1.397 - * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API.
1.398 - * 1.1.2 Added API call for generating iface names.
1.399 - * 1.2 Added API more helper functions and new SourceHook version.
1.400 - * 1.2.2 Added API for printing to client console (with string formatting).
1.401 - * 1.3 Added new interface search API.
1.402 - * 1.4 Added VSP listener and user message API.
1.403 - * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks.
1.404 - * 1.6.0 Added API for Orange Box. Broke backwards compatibility.
1.405 - */
1.406 -
1.407 -#endif //_INCLUDE_ISMM_API_H
1.408 -