dvander@347: /* ======== SourceMM ======== dvander@347: * Copyright (C) 2004-2007 Metamod:Source Development Team dvander@347: * No warranties of any kind dvander@347: * dvander@347: * License: zlib/libpng dvander@347: * dvander@347: * Author(s): David "BAILOPAN" Anderson dvander@347: * ============================ dvander@347: */ dvander@347: dvander@347: #ifndef _INCLUDE_ISMM_API_H dvander@347: #define _INCLUDE_ISMM_API_H dvander@347: dvander@347: /** dvander@347: * @brief External API interface dvander@347: * @file ISmmAPI.h dvander@347: */ dvander@347: dvander@347: #include dvander@347: #include dvander@347: #include dvander@347: #include "IPluginManager.h" dvander@347: dvander@347: #if defined __GNUC__ dvander@347: #if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3) dvander@347: #error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message." dvander@347: #endif //version check dvander@347: #endif //__GNUC__ dvander@347: dvander@347: class IMetamodListener; dvander@347: class ISmmPluginManager; dvander@347: class ISmmPlugin; dvander@347: dvander@347: #define MMIFACE_SOURCEHOOK "ISourceHook" /**< ISourceHook Pointer */ dvander@347: #define MMIFACE_PLMANAGER "IPluginManager" /**< SourceMM Plugin Functions */ dvander@351: #define IFACE_MAXNUM 999 /**< Maximum interface version */ dvander@351: dvander@352: #define SOURCE_ENGINE_UNKNOWN 0 /**< Could not determine the engine version */ dvander@352: #define SOURCE_ENGINE_ORIGINAL 1 /**< Original Source Engine (used by The Ship) */ dvander@352: #define SOURCE_ENGINE_EPISODEONE 2 /**< Episode 1 Source Engine (second major SDK) */ dvander@352: #define SOURCE_ENGINE_ORANGEBOX 3 /**< Orange Box Source Engine (third major SDK) */ dvander@347: dvander@347: class ISmmAPI dvander@347: { dvander@347: public: dvander@347: /** dvander@347: * @brief Logs a message through the HL2 log system. dvander@347: * Note: Newlines are appended automatically. dvander@347: * dvander@347: * @param pl Plugin API pointer (used for tagging message) dvander@347: * @param msg Formatted string. dvander@347: */ dvander@347: virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0; dvander@347: public: dvander@347: /** dvander@347: * @brief Returns an interface factory for the HL2 engine. dvander@347: * dvander@347: * @param syn If syn is true, the synthetic wrapper is returned. dvander@347: * If syn is false, the true function is returned. dvander@347: * @return CreateInterfaceFn function pointer. dvander@347: */ dvander@347: virtual CreateInterfaceFn engineFactory(bool syn=true) =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns an interface factory for the HL2 physics engine. dvander@347: * dvander@347: * @param syn If syn is true, the synthetic wrapper is returned. dvander@347: * If syn is false, the true function is returned. dvander@347: * @return CreateInterfaceFn function pointer. dvander@347: */ dvander@347: virtual CreateInterfaceFn physicsFactory(bool syn=true) =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns an interface factory for the HL2 file system. dvander@347: * dvander@347: * @param syn If syn is true, the synthetic wrapper is returned. dvander@347: * If syn is false, the true function is returned. dvander@347: * @return CreateInterfaceFn function pointer. dvander@347: */ dvander@347: virtual CreateInterfaceFn fileSystemFactory(bool syn=true) =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns an interface factory for the GameDLL. dvander@347: * dvander@347: * @param syn If syn is true, the synthetic wrapper is returned. dvander@347: * If syn is false, the true function is returned. dvander@347: * @return CreateInterfaceFn function pointer. dvander@347: */ dvander@347: virtual CreateInterfaceFn serverFactory(bool syn=true) =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns a CGlobalVars pointer from the HL2 Engine. dvander@347: * dvander@347: * @return CGlobalVars pointer. dvander@347: */ dvander@347: virtual CGlobalVars *pGlobals() =0; dvander@347: dvander@347: /** dvander@347: * @brief Used with SourceHook, sets teh last meta return value. dvander@347: * Note: Do not call this directly, use the Metamod macros. dvander@347: * dvander@347: * @param res META_RETURN value to set. dvander@347: */ dvander@347: virtual void SetLastMetaReturn(META_RES res) =0; dvander@347: dvander@347: /** dvander@347: * @brief Used with SourceHook, returns the last meta return value. dvander@347: * Note: This is only valid inside a hook function. dvander@347: * dvander@347: * @return Last META_RETURN value set by a plugin. dvander@347: */ dvander@347: virtual META_RES GetLastMetaReturn() =0; dvander@347: dvander@347: public: // Added in 1.00-RC2 (0:0) dvander@347: /** dvander@347: * @brief Allows access to Metamod's ConCommandBaseAccessor. dvander@347: * dvander@347: * @return Returns IConCommandBaseAccessor pointer. dvander@347: */ dvander@347: virtual IConCommandBaseAccessor *GetCvarBaseAccessor() =0; dvander@347: dvander@347: /** dvander@347: * @brief Registers a ConCommandBase. dvander@347: * dvander@347: * @param plugin Parent plugin API pointer. dvander@347: * @param pCommand ConCommandBase to register. dvander@351: * @return True if successful, false otherwise. dvander@347: */ dvander@347: virtual bool RegisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0; dvander@347: dvander@347: /** dvander@347: * @brief Unregisters a ConCommandBase. dvander@347: * dvander@347: * @param plugin Parent plugin API pointer. dvander@347: * @param pCommand ConCommandBase to unlink. dvander@347: */ dvander@347: virtual void UnregisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0; dvander@347: dvander@347: /** dvander@347: * @brief Prints an unformatted string to the remote server console. dvander@351: * dvander@347: * Note: Newlines are not added automatically. dvander@347: * dvander@347: * @param str Message string. dvander@347: */ dvander@347: virtual void ConPrint(const char *str) =0; dvander@347: dvander@347: /** dvander@347: * @brief Prints a formatted message to the remote server console. dvander@351: * dvander@347: * Note: Newlines are not added automatically. dvander@347: * dvander@347: * @param fmt Formatted message. dvander@347: */ dvander@347: virtual void ConPrintf(const char *fmt, ...) =0; dvander@347: dvander@347: public: // Added in 1.1.0 (1:0) dvander@347: /** dvander@347: * @brief Checks if ConPrint/ConPrintf will mirror to rcon. dvander@347: * dvander@347: * @return True if remote printing available, false otherwise. dvander@347: */ dvander@347: virtual bool RemotePrintingAvailable() =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns the Metamod Version numbers as major version and minor (API) version. dvander@347: * Changes to minor version are guaranteed to be backwards compatible. dvander@347: * Changes to major version are not. dvander@347: * dvander@347: * @param major Filled with the major API version number. dvander@347: * @param minor Filled with the minor API version number. dvander@347: * @param plvers Filled with the current plugin API version number. dvander@347: * @param plmin Filled with the minimum plugin API version number supported. dvander@347: */ dvander@347: virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns sourcehook API version and implementation version. dvander@347: * dvander@347: * @param shvers Filled with the SourceHook API version number. dvander@347: * @param shimpl Filled with the SourceHook implementation number. dvander@347: */ dvander@347: virtual void GetShVersions(int &shvers, int &shimpl) =0; dvander@347: dvander@347: /** dvander@347: * @brief Adds a Metamod listener. dvander@347: * dvander@347: * @param plugin Plugin interface pointer. dvander@347: * @param pListener Listener interface pointer to add. dvander@347: */ dvander@347: virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0; dvander@347: dvander@347: /** dvander@347: * @brief Queries the metamod factory dvander@347: * dvander@347: * @param iface String containing interface name dvander@347: * @param ret Optional pointer to store return status dvander@347: * @param id Optional pointer to store id of plugin that overrode interface, 0 if none dvander@347: * @return Returned pointer dvander@347: */ dvander@347: virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0; dvander@347: dvander@347: public: // Added in 1.1.2 (1:1) dvander@347: /** dvander@347: * @brief Given a base interface name, such as ServerGameDLL or ServerGameDLL003, dvander@347: * reformats the string to increase the number, then returns the new number. dvander@347: * This is the base function to InterfaceSearch() and VInterfaceMatch(). dvander@347: * dvander@347: * @param iface Input/output interface name. Must be writable. dvander@347: * @param maxlength Maximum length of iface buffer. Must be at least strlen(iface)+4 chars. dvander@347: * @return The newly incremented iface version number. dvander@347: */ dvander@347: virtual int FormatIface(char iface[], unsigned int maxlength) =0; dvander@347: dvander@347: public: // Added in 1.2 (1:2) dvander@347: /** dvander@351: * @brief Searches for an interface, eliminating the need to loop through FormatIface(). dvander@347: * dvander@347: * @param fn InterfaceFactory function. dvander@347: * @param iface Interface string name. dvander@347: * @param max Maximum version to look up. dvander@347: * @param ret Last return code from interface factory function. dvander@347: * @return Interface pointer, or NULL if not found. dvander@347: */ dvander@347: virtual void *InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max, int *ret) =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns the base directory of the game/server, equivalent to dvander@351: * IVEngineServer::GetGameDir(), except the path is absolute. dvander@347: * dvander@347: * @return Static pointer to game's absolute basedir. dvander@347: */ dvander@347: virtual const char *GetBaseDir() =0; dvander@347: dvander@347: /** dvander@351: * @brief Formats a file path to the local OS. dvander@351: * dvander@351: * Does not include any base directories. Note that all slashes and black dvander@351: * slashes are reverted to the local OS's expectancy. dvander@347: * dvander@347: * @param buffer Destination buffer to store path. dvander@347: * @param len Maximum length of buffer, including null terminator. dvander@347: * @param fmt Formatted string. dvander@347: */ dvander@347: virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...) =0; dvander@347: dvander@347: public: // Added in 1.2.2 (1:3) dvander@347: /** dvander@351: * @brief Prints text in the specified client's console. Same as dvander@351: * IVEngineServer::ClientPrintf except that it allows for string formatting. dvander@347: * dvander@347: * @param client Client edict pointer. dvander@347: * @param fmt Formatted string to print to the client. dvander@347: */ dvander@347: virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0; dvander@347: dvander@347: public: // Added in 1.3 (1:4) dvander@347: /** dvander@347: * @brief Wrapper around InterfaceSearch(). Assumes no maximum. dvander@347: * This is designed to replace the fact that searches only went upwards. dvander@347: * The "V" is intended to convey that this is for Valve formatted interface strings. dvander@347: * dvander@347: * @param fn Interface factory function. dvander@347: * @param iface Interface string. dvander@351: * @param min Minimum value to search from. If zero, searching dvander@351: * begins from the first available version regardless dvander@351: * of the interface. Note that this can return dvander@351: * interfaces EARLIER than the version specified. A dvander@351: * value of -1 (default) specifies the string version dvander@351: * as the minimum. Any other value specifices the dvander@351: * minimum value to search from. dvander@347: * @return Interface pointer, or NULL if not found. dvander@347: */ dvander@347: virtual void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, int min=-1) =0; dvander@347: dvander@347: public: // Added in 1.4 (1:5) dvander@347: /** dvander@347: * @brief Tells SourceMM to add VSP hooking capability to plugins. dvander@347: * dvander@351: * Since this potentially uses more resources than it would otherwise, dvander@351: * plugins have to explicitly enable the feature. Whether requested or dvander@351: * not, if it is enabled, all plugins will get a pointer to the VSP dvander@351: * listener through IMetamodListener. This will not be called more than dvander@351: * once for a given plugin; if it is requested more than once, each dvander@351: * successive call will only give the pointer to plugins which have not dvander@351: * yet received it. dvander@347: */ dvander@347: virtual void EnableVSPListener() =0; dvander@347: dvander@347: /** dvander@351: * @brief Returns the interface version of the GameDLL's IServerGameDLL dvander@351: * implementation. dvander@347: * dvander@347: * @return Interface version of the loaded IServerGameDLL. dvander@347: */ dvander@347: virtual int GetGameDLLVersion() =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns the number of user messages in the GameDLL. dvander@347: * dvander@351: * @return Number of user messages, or -1 if SourceMM has dvander@351: * failed to get user message list. dvander@347: */ dvander@347: virtual int GetUserMessageCount() =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns the index of the specified user message. dvander@347: * dvander@347: * @param name User message name. dvander@347: * @param size Optional pointer to store size of user message. dvander@347: * @return Message index, or -1 on failure. dvander@347: */ dvander@347: virtual int FindUserMessage(const char *name, int *size=NULL) =0; dvander@347: dvander@347: /** dvander@347: * @brief Returns the name of the specified user message. dvander@347: * dvander@347: * @param index User message index. dvander@347: * @param size Optional pointer to store size of user message. dvander@347: * @return Message name, or NULL on failure. dvander@347: */ dvander@347: virtual const char *GetUserMessage(int index, int *size=NULL) =0; dvander@351: dvander@348: public: // Added in 1.5.0 (1:6) dvander@348: /** dvander@351: * @brief Returns the highest interface version of IServerPluginCallbacks dvander@351: * that the engine supports. This is useful for games that run on older dvander@351: * versions of the Source engine, such as The Ship. dvander@348: * dvander@348: * @return Highest interface version of IServerPluginCallbacks. dvander@351: * Returns 0 if SourceMM's VSP listener isn't currently dvander@351: * enabled. dvander@348: */ dvander@348: virtual int GetVSPVersion() =0; dvander@351: dvander@351: public: // Added in 1.6.0 (1:7) dvander@351: /** dvander@351: * @brief Returns the engine interface that MM:S is using as a backend. dvander@351: * dvander@351: * The values will be one of the SOURCE_ENGINE_* constants from the top dvander@351: * of this file. dvander@351: * dvander@351: * @return A SOURCE_ENGINE_* constant value. dvander@351: */ dvander@351: virtual int GetSourceEngineBuild() =0; dvander@347: }; dvander@347: dvander@347: dvander@347: /** dvander@347: * Version History dvander@347: * dvander@347: * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API. dvander@347: * 1.1.2 Added API call for generating iface names. dvander@347: * 1.2 Added API more helper functions and new SourceHook version. dvander@347: * 1.2.2 Added API for printing to client console (with string formatting). dvander@347: * 1.3 Added new interface search API. dvander@347: * 1.4 Added VSP listener and user message API. dvander@348: * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks. dvander@351: * 1.6.0 Added API for Orange Box. dvander@347: */ dvander@347: dvander@347: #endif //_INCLUDE_ISMM_API_H dvander@355: