dvander@371: /** dvander@371: * vim: set ts=4 : dvander@371: * ====================================================== dvander@371: * Metamod:Source dvander@371: * Copyright (C) 2004-2007 AlliedModders LLC and authors. dvander@371: * All rights reserved. dvander@371: * ====================================================== dvander@371: * dvander@371: * This software is provided 'as-is', without any express or implied warranty. dvander@371: * In no event will the authors be held liable for any damages arising from dvander@371: * the use of this software. dvander@371: * dvander@371: * Permission is granted to anyone to use this software for any purpose, dvander@371: * including commercial applications, and to alter it and redistribute it dvander@371: * freely, subject to the following restrictions: dvander@371: * dvander@371: * 1. The origin of this software must not be misrepresented; you must not dvander@371: * claim that you wrote the original software. If you use this software in a dvander@371: * product, an acknowledgment in the product documentation would be dvander@371: * appreciated but is not required. dvander@371: * 2. Altered source versions must be plainly marked as such, and must not be dvander@371: * misrepresented as being the original software. dvander@371: * 3. This notice may not be removed or altered from any source distribution. dvander@371: * dvander@371: * Version: $Id$ dvander@371: */ dvander@9: dvander@7: #ifndef _INCLUDE_ISMM_API_H dvander@7: #define _INCLUDE_ISMM_API_H dvander@7: dvander@9: /** dvander@9: * @brief External API interface dvander@9: * @file ISmmAPI.h dvander@9: */ dvander@9: dvander@376: #include dvander@7: #include dvander@7: #include dvander@371: #include dvander@396: #include dvander@396: #include dvander@405: #include dvander@7: dvander@104: #if defined __GNUC__ dvander@104: #if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3) dvander@109: #error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message." dvander@104: #endif //version check dvander@104: #endif //__GNUC__ dvander@104: dvander@282: #define MMIFACE_SOURCEHOOK "ISourceHook" /**< ISourceHook Pointer */ dvander@282: #define MMIFACE_PLMANAGER "IPluginManager" /**< SourceMM Plugin Functions */ dvander@371: #define IFACE_MAXNUM 999 /**< Maximum interface version */ dvander@371: dvander@396: namespace SourceMM dvander@7: { dvander@396: class ISmmPlugin; dvander@396: class IMetamodListener; dvander@375: dvander@396: class ISmmAPI dvander@396: { dvander@396: public: dvander@396: /** dvander@396: * @brief Logs a message through the HL2 log system. dvander@396: * Note: Newlines are appended automatically. dvander@396: * dvander@396: * @param pl Plugin API pointer (used for tagging message) dvander@396: * @param msg Formatted string. dvander@396: */ dvander@396: virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0; dvander@396: dvander@396: /** dvander@396: * @brief Returns an interface factory for the HL2 engine. dvander@396: * dvander@396: * @param syn If syn is true, the synthetic wrapper is returned. dvander@396: * If syn is false, the true function is returned. dvander@396: * @return CreateInterfaceFn function pointer. dvander@396: */ dvander@396: virtual CreateInterfaceFn GetEngineFactory(bool syn=true) =0; dvander@244: dvander@396: /** dvander@396: * @brief Returns an interface factory for the HL2 physics engine. dvander@396: * dvander@396: * @param syn If syn is true, the synthetic wrapper is returned. dvander@396: * If syn is false, the true function is returned. dvander@396: * @return CreateInterfaceFn function pointer. dvander@396: */ dvander@396: virtual CreateInterfaceFn GetPhysicsFactory(bool syn=true) =0; dvander@396: dvander@396: /** dvander@396: * @brief Returns an interface factory for the HL2 file system. dvander@396: * dvander@396: * @param syn If syn is true, the synthetic wrapper is returned. dvander@396: * If syn is false, the true function is returned. dvander@396: * @return CreateInterfaceFn function pointer. dvander@396: */ dvander@396: virtual CreateInterfaceFn GetFileSystemFactory(bool syn=true) =0; dvander@244: dvander@396: /** dvander@396: * @brief Returns an interface factory for the GameDLL. dvander@396: * dvander@396: * If syn is false, the true function is returned. dvander@396: * @return CreateInterfaceFn function pointer. dvander@396: */ dvander@396: virtual CreateInterfaceFn GetServerFactory(bool syn=true) =0; dvander@244: dvander@396: /** dvander@396: * @brief Returns a CGlobalVars pointer from the HL2 Engine. dvander@396: * dvander@396: * @return CGlobalVars pointer. dvander@396: */ dvander@396: virtual CGlobalVars *GetCGlobals() =0; dvander@244: dvander@396: /** dvander@396: * @brief Registers a ConCommandBase. dvander@396: * dvander@396: * @param plugin Parent plugin API pointer. dvander@396: * @param pCommand ConCommandBase to register. dvander@396: * @return True if successful, false otherwise. dvander@396: */ dvander@396: virtual bool RegisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0; dvander@244: dvander@396: /** dvander@396: * @brief Unregisters a ConCommandBase. dvander@396: * dvander@396: * @param plugin Parent plugin API pointer. dvander@396: * @param pCommand ConCommandBase to unlink. dvander@396: */ dvander@396: virtual void UnregisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0; dvander@244: dvander@396: /** dvander@396: * @brief Prints an unformatted string to the remote server console. dvander@396: * dvander@396: * Note: Newlines are not added automatically. dvander@396: * dvander@396: * @param str Message string. dvander@396: */ dvander@396: virtual void ConPrint(const char *str) =0; dvander@244: dvander@396: /** dvander@396: * @brief Prints a formatted message to the remote server console. dvander@396: * dvander@396: * Note: Newlines are not added automatically. dvander@396: * dvander@396: * @param fmt Formatted message. dvander@396: */ dvander@396: virtual void ConPrintf(const char *fmt, ...) =0; dvander@244: dvander@396: /** dvander@396: * @brief Returns the Metamod Version numbers as major version and dvander@396: * minor (API) version. Changes to minor version are guaranteed to be dvander@396: * backwards compatible. Changes to major version are not. dvander@396: * dvander@396: * @param major Filled with the major API version number. dvander@396: * @param minor Filled with the minor API version number. dvander@396: * @param plvers Filled with the current plugin API version number. dvander@396: * @param plmin Filled with the minimum plugin API version number dvander@396: * supported. dvander@396: */ dvander@396: virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0; dvander@244: dvander@396: /** dvander@396: * @brief Returns sourcehook API version and implementation version. dvander@396: * dvander@396: * @param shvers Filled with the SourceHook API version number. dvander@396: * @param shimpl Filled with the SourceHook implementation number. dvander@396: */ dvander@396: virtual void GetShVersions(int &shvers, int &shimpl) =0; dvander@244: dvander@396: /** dvander@396: * @brief Adds a Metamod listener. dvander@396: * dvander@396: * @param plugin Plugin interface pointer. dvander@396: * @param pListener Listener interface pointer to add. dvander@396: */ dvander@396: virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0; dvander@244: dvander@396: /** dvander@396: * @brief Queries the metamod factory dvander@396: * dvander@396: * @param iface String containing interface name dvander@396: * @param ret Optional pointer to store return status dvander@396: * @param id Optional pointer to store id of plugin that dvander@396: * overrode interface, 0 if none dvander@396: * @return Returned pointer dvander@396: */ dvander@396: virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0; dvander@244: dvander@396: /** dvander@396: * @brief Given a base interface name, such as ServerGameDLL or dvander@396: * ServerGameDLL003, reformats the string to increase the number, then dvander@396: * returns the new number. This is the base function to InterfaceSearch() dvander@396: * and VInterfaceMatch(). dvander@396: * dvander@396: * @param iface Input/output interface name. Must be writable. dvander@396: * @param maxlength Maximum length of iface buffer. Must be at least dvander@396: * strlen(iface)+4 chars. dvander@396: * @return The newly incremented iface version number. dvander@396: */ dvander@396: virtual int FormatIface(char iface[], unsigned int maxlength) =0; dvander@244: dvander@396: /** dvander@396: * @brief Searches for an interface, eliminating the need to loop dvander@396: * through FormatIface(). dvander@396: * dvander@396: * @param fn InterfaceFactory function. dvander@396: * @param iface Interface string name. dvander@396: * @param max Maximum version to look up. dvander@396: * @param ret Last return code from interface factory function. dvander@396: * @return Interface pointer, or NULL if not found. dvander@396: */ dvander@396: virtual void *InterfaceSearch(CreateInterfaceFn fn, dvander@396: const char *iface, dvander@396: int max, dvander@396: int *ret) =0; dvander@166: dvander@396: /** dvander@396: * @brief Returns the base directory of the game/server, equivalent to dvander@396: * IVEngineServer::GetGameDir(), except the path is absolute. dvander@396: * dvander@396: * @return Static pointer to game's absolute basedir. dvander@396: */ dvander@396: virtual const char *GetBaseDir() =0; dvander@166: dvander@396: /** dvander@396: * @brief Formats a file path to the local OS. dvander@396: * dvander@396: * Does not include any base directories. Note that all slashes and dvander@396: * black slashes are reverted to the local OS's expectancy. dvander@396: * dvander@396: * @param buffer Destination buffer to store path. dvander@396: * @param len Maximum length of buffer, including null dvander@396: * terminator. dvander@396: * @param fmt Formatted string. dvander@407: * @param ... Arguments in the string. dvander@407: * @return Number of bytes written, not including the null dvander@407: * terminator. dvander@396: */ dvander@407: virtual size_t PathFormat(char *buffer, size_t len, const char *fmt, ...) =0; dvander@244: dvander@396: /** dvander@396: * @brief Prints text in the specified client's console. Same as dvander@396: * IVEngineServer::ClientPrintf except that it allows for string dvander@396: * formatting. dvander@396: * dvander@396: * @param client Client edict pointer. dvander@396: * @param fmt Formatted string to print to the client. dvander@396: */ dvander@396: virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0; dvander@244: dvander@396: /** dvander@396: * @brief Wrapper around InterfaceSearch(). Assumes no maximum. dvander@396: * This is designed to replace the fact that searches only went upwards. dvander@396: * The "V" is intended to convey that this is for Valve formatted dvander@396: * interface strings. dvander@396: * dvander@396: * @param fn Interface factory function. dvander@396: * @param iface Interface string. dvander@396: * @param min Minimum value to search from. If zero, searching dvander@396: * begins from the first available version regardless dvander@396: * of the interface. Note that this can return dvander@396: * interfaces EARLIER than the version specified. A dvander@396: * value of -1 (default) specifies the string version dvander@396: * as the minimum. Any other value specifices the dvander@396: * minimum value to search from. dvander@396: * @return Interface pointer, or NULL if not found. dvander@396: */ dvander@396: virtual void *VInterfaceMatch(CreateInterfaceFn fn, dvander@396: const char *iface, dvander@396: int min=-1) =0; dvander@282: dvander@396: /** dvander@396: * @brief Tells SourceMM to add VSP hooking capability to plugins. dvander@396: * dvander@396: * Since this potentially uses more resources than it would otherwise, dvander@396: * plugins have to explicitly enable the feature. Whether requested or dvander@396: * not, if it is enabled, all plugins will get a pointer to the VSP dvander@396: * listener through IMetamodListener. This will not be called more than dvander@396: * once for a given plugin; if it is requested more than once, each dvander@396: * successive call will only give the pointer to plugins which have not dvander@396: * yet received it. dvander@396: */ dvander@396: virtual void EnableVSPListener() =0; dvander@282: dvander@396: /** dvander@396: * @brief Returns the interface version of the GameDLL's IServerGameDLL dvander@396: * implementation. dvander@396: * dvander@396: * @return Interface version of the loaded IServerGameDLL. dvander@396: */ dvander@396: virtual int GetGameDLLVersion() =0; ds@287: dvander@396: /** dvander@396: * @brief Returns the number of user messages in the GameDLL. dvander@396: * dvander@396: * @return Number of user messages, or -1 if SourceMM has dvander@396: * failed to get user message list. dvander@396: */ dvander@396: virtual int GetUserMessageCount() =0; ds@287: dvander@396: /** dvander@396: * @brief Returns the index of the specified user message. dvander@396: * dvander@396: * @param name User message name. dvander@396: * @param size Optional pointer to store size of user message. dvander@396: * @return Message index, or -1 on failure. dvander@396: */ dvander@396: virtual int FindUserMessage(const char *name, int *size=NULL) =0; ds@287: dvander@396: /** dvander@396: * @brief Returns the name of the specified user message. dvander@396: * dvander@396: * @param index User message index. dvander@396: * @param size Optional pointer to store size of user message. dvander@396: * @return Message name, or NULL on failure. dvander@396: */ dvander@396: virtual const char *GetUserMessage(int index, int *size=NULL) =0; dvander@371: dvander@396: /** dvander@396: * @brief Returns the highest interface version of IServerPluginCallbacks dvander@396: * that the engine supports. This is useful for games that run on older dvander@396: * versions of the Source engine, such as The Ship. dvander@396: * dvander@396: * @return Highest interface version of IServerPluginCallbacks. dvander@396: * Returns 0 if SourceMM's VSP listener isn't dvander@396: * currently enabled. dvander@396: */ dvander@396: virtual int GetVSPVersion() =0; dvander@371: dvander@396: /** dvander@396: * @brief Returns the engine interface that MM:S is using as a backend. dvander@396: * dvander@396: * The values will be one of the SOURCE_ENGINE_* constants from the top dvander@396: * of this file. dvander@396: * dvander@396: * @return A SOURCE_ENGINE_* constant value. dvander@396: */ dvander@396: virtual int GetSourceEngineBuild() =0; dvander@371: dvander@396: /** dvander@396: * @brief Returns the VSP listener loaded. dvander@396: * dvander@396: * This is useful for late-loading plugins which need to decide whether dvander@396: * to add a listener or not (or need to get the pointer at all). dvander@396: * dvander@396: * @param Optional pointer to store the VSP version. dvander@396: * @return IServerPluginCallbacks pointer, or NULL if an dvander@396: * IMetamodListener event has yet to occur for dvander@396: * EnableVSPListener(). dvander@396: */ dvander@396: virtual IServerPluginCallbacks *GetVSPInfo(int *pVersion) =0; dvander@376: dvander@396: /** dvander@396: * @brief Formats a string. This is a platform safe wrapper around dvander@396: * snprintf/_snprintf. dvander@396: * dvander@396: * @param buffer Buffer to write to. dvander@396: * @param maxlength Maximum length of the buffer. dvander@396: * @param format Format specifiers. dvander@396: * @param ... Format arguments. dvander@396: * @return Number of bytes actually written, not including dvander@396: * the null terminator. dvander@396: */ dvander@376: virtual size_t Format(char *buffer, dvander@396: size_t maxlength, dvander@396: const char *format, dvander@396: ...) =0; dvander@376: dvander@376: /** dvander@376: * @brief Formats a string. This is a platform safe wrapper around dvander@376: * vsnprintf/_vsnprintf. dvander@376: * dvander@376: * @param buffer Buffer to write to. dvander@376: * @param maxlength Maximum length of the buffer. dvander@376: * @param format Format specifiers. dvander@376: * @param ap Format argument list. dvander@376: * @return Number of bytes actually written, not including the dvander@376: * null terminator. dvander@376: */ dvander@376: virtual size_t FormatArgs(char *buffer, dvander@396: size_t maxlength, dvander@396: const char *format, dvander@396: va_list ap) =0; dvander@396: }; dvander@396: } dvander@7: dvander@396: #if !defined METAMOD_NO_AUTO_NAMESPACE dvander@396: using namespace SourceMM; dvander@396: #endif dvander@138: ds@294: /** ds@294: * Version History ds@294: * ds@294: * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API. ds@294: * 1.1.2 Added API call for generating iface names. dvander@371: * 1.2 Added API more helper functions and new SourceHook version. ds@294: * 1.2.2 Added API for printing to client console (with string formatting). dvander@371: * 1.3 Added new interface search API. dvander@371: * 1.4 Added VSP listener and user message API. ds@326: * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks. dvander@375: * 1.6.0 Added API for Orange Box. Broke backwards compatibility. dvander@124: */ dvander@124: dvander@7: #endif //_INCLUDE_ISMM_API_H dvander@371: