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