From 2113dc8ad4d067ddb56b34a13d195267a5adc000 Mon Sep 17 00:00:00 2001 From: David Anderson Date: Mon, 18 Feb 2008 23:11:25 +0000 Subject: [PATCH] made the headers a bit more doxygen friendly --HG-- extra : convert_revision : svn%3Ac2935e3e-5518-0410-8daf-afa5dab7d4e3/trunk%40659 --- sourcemm/IPluginManager.h | 50 ++++--- sourcemm/ISmmAPI.h | 41 ++--- sourcemm/ISmmPlugin.h | 24 ++- sourcemm/ISmmPluginExt.h | 307 +++++++++++++++++++------------------- sourcemm/svn_version.h | 8 +- 5 files changed, 228 insertions(+), 202 deletions(-) diff --git a/sourcemm/IPluginManager.h b/sourcemm/IPluginManager.h index 0e245de..be4089d 100644 --- a/sourcemm/IPluginManager.h +++ b/sourcemm/IPluginManager.h @@ -1,4 +1,4 @@ -/** +/* * vim: set ts=4 : * ====================================================== * Metamod:Source @@ -60,6 +60,9 @@ namespace SourceMM Pl_Running=0, }; + /** + * @brief Programmatic management of the "loaded plugin" list. + */ class ISmmPluginManager { public: @@ -68,51 +71,50 @@ namespace SourceMM * then the plugin is considered to be "hot" - it might refuse its own load later! * Also, a hot plugin might not have an error message. * - * @param file String containing file name - * @param source Specifies who loaded the plugin - * @param status Status of the plugin - * @param ismm Pointer to Smm API - * @param error String buffer for error messages - * @param maxlen Maximum length of buffer - * @return Id of plugin + * @param file String containing file name. + * @param source Specifies who loaded the plugin. + * @param already Whether or not the plugin was already loaded. + * @param error String buffer for error messages. + * @param maxlen Maximum length of buffer. + * @return Id of plugin. */ virtual PluginId Load(const char *file, PluginId source, bool &already, char *error, size_t maxlen) =0; /** - * @brief Unloads a plugin + * @brief Unloads a plugin. * - * @param id Id of plugin - * @param error String buffer for error messages - * @param maxlen Maximum length of buffer - * @return True on success, false otherwise + * @param id Id of plugin + * @param force True to forcefully unload, false to let plugin opt-out. + * @param error String buffer for error messages + * @param maxlen Maximum length of buffer + * @return True on success, false otherwise */ virtual bool Unload(PluginId id, bool force, char *error, size_t maxlen) =0; /** * @brief Pauses a plugin * - * @param id Id of plugin - * @param error String buffer for error messages - * @param maxlen Maximum length of buffer - * @return True on success, false otherwise + * @param id Id of plugin + * @param error String buffer for error messages + * @param maxlen Maximum length of buffer + * @return True on success, false otherwise */ virtual bool Pause(PluginId id, char *error, size_t maxlen) =0; /** * @brief Unpauses a plugin * - * @param id Id of plugin - * @param force If true, forces the plugin to unload - * @param error String buffer for error messages - * @param maxlen Maximum length of buffer - * @return True on success, false otherwise + * @param id Id of plugin + * @param error String buffer for error messages + * @param maxlen Maximum length of buffer + * @return True on success, false otherwise */ virtual bool Unpause(PluginId id, char *error, size_t maxlen) =0; /** * @brief Unloads all plugins forcefully * - * @return True on success, false otherwise + * @return True on success, false otherwise */ virtual bool UnloadAll() =0; @@ -132,7 +134,7 @@ namespace SourceMM * * @param id Id of plugin * @param error Message buffer - * @param maxlen Size of error buffer + * @param maxlength Size of error buffer * @return Status value */ virtual bool QueryRunning(PluginId id, char *error, size_t maxlength) =0; diff --git a/sourcemm/ISmmAPI.h b/sourcemm/ISmmAPI.h index b405579..893d9a1 100644 --- a/sourcemm/ISmmAPI.h +++ b/sourcemm/ISmmAPI.h @@ -1,4 +1,4 @@ -/** +/* * vim: set ts=4 : * ====================================================== * Metamod:Source @@ -29,7 +29,7 @@ #define _INCLUDE_ISMM_API_H /** - * @brief External API interface + * @brief Core API calls that are provided to plugins. * @file ISmmAPI.h */ @@ -57,6 +57,9 @@ namespace SourceMM class ISmmPlugin; class IMetamodListener; + /** + * The core API that Metamod:Source provides to plugins. + */ class ISmmAPI { public: @@ -196,6 +199,7 @@ namespace SourceMM * @param maxlength Maximum length of iface buffer. Must be at least * strlen(iface)+4 chars. * @return The newly incremented iface version number. + * @deprecated Use InterfaceSearch() or VInterfaceMatch instead. */ virtual int FormatIface(char iface[], unsigned int maxlength) =0; @@ -324,6 +328,7 @@ namespace SourceMM * @return Highest interface version of IServerPluginCallbacks. * Returns 0 if SourceMM's VSP listener isn't * currently enabled. + * @deprecated Use GetVSPInfo() instead. */ virtual int GetVSPVersion() =0; @@ -343,7 +348,7 @@ namespace SourceMM * This is useful for late-loading plugins which need to decide whether * to add a listener or not (or need to get the pointer at all). * - * @param Optional pointer to store the VSP version. + * @param pVersion Optional pointer to store the VSP version. * @return IServerPluginCallbacks pointer, or NULL if an * IMetamodListener event has yet to occur for * EnableVSPListener(). @@ -366,21 +371,21 @@ namespace SourceMM const char *format, ...) =0; - /** - * @brief Formats a string. This is a platform safe wrapper around - * vsnprintf/_vsnprintf. - * - * @param buffer Buffer to write to. - * @param maxlength Maximum length of the buffer. - * @param format Format specifiers. - * @param ap Format argument list. - * @return Number of bytes actually written, not including the - * null terminator. - */ - virtual size_t FormatArgs(char *buffer, - size_t maxlength, - const char *format, - va_list ap) =0; + /** + * @brief Formats a string. This is a platform safe wrapper around + * vsnprintf/_vsnprintf. + * + * @param buffer Buffer to write to. + * @param maxlength Maximum length of the buffer. + * @param format Format specifiers. + * @param ap Format argument list. + * @return Number of bytes actually written, not including the + * null terminator. + */ + virtual size_t FormatArgs(char *buffer, + size_t maxlength, + const char *format, + va_list ap) =0; }; } diff --git a/sourcemm/ISmmPlugin.h b/sourcemm/ISmmPlugin.h index d80982b..bb0a99c 100644 --- a/sourcemm/ISmmPlugin.h +++ b/sourcemm/ISmmPlugin.h @@ -1,4 +1,4 @@ -/** +/* * vim: set ts=4 : * ====================================================== * Metamod:Source @@ -29,8 +29,9 @@ #define _INCLUDE_ISMM_PLUGIN_H /** - * @brief Plugin API interface - * @file ISmmPlugin.h + * @brief Plugin API interface. + * @file ISmmPlugin.h These are callbacks that plugins can implement without hooks. + * The pure-virtual ISmmPlugin callbacks must be implemented for the load to load. */ #include @@ -421,6 +422,15 @@ using namespace SourceMM; #define PL_EXPOSURE CreateInterface #define PL_EXPOSURE_C "CreateInterface" +/** + * @brief Exposes the plugin to the MM:S loader. + * + * @param name Deprecated - should be a variable name (like name). + * @param var Name of the variable that contains the singleton. + * This macro automatically takes the address of it, so + * you should not pass a pointer to your plugin's + * singleton. + */ #define PLUGIN_EXPOSE(name, var) \ ISmmAPI *g_SMAPI = NULL; \ ISmmPlugin *g_PLAPI = NULL; \ @@ -433,12 +443,20 @@ using namespace SourceMM; return NULL; \ } + +/** + * @brief This should be in one of your header files, if you wish + * to use values like g_SHPtr in other files. + */ #define PLUGIN_GLOBALVARS() \ extern SourceHook::ISourceHook *g_SHPtr; \ extern ISmmAPI *g_SMAPI; \ extern ISmmPlugin *g_PLAPI; \ extern PluginId g_PLID; +/** + * @brief This should be the first line in your Load callback. + */ #define PLUGIN_SAVEVARS() \ g_SMAPI = ismm; \ g_SHPtr = static_cast(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \ diff --git a/sourcemm/ISmmPluginExt.h b/sourcemm/ISmmPluginExt.h index 8af00e4..a41ed59 100644 --- a/sourcemm/ISmmPluginExt.h +++ b/sourcemm/ISmmPluginExt.h @@ -1,156 +1,157 @@ -/** - * vim: set ts=4 : - * ====================================================== - * Metamod:Source - * Copyright (C) 2004-2007 AlliedModders LLC and authors. - * All rights reserved. - * ====================================================== - * - * This software is provided 'as-is', without any express or implied warranty. - * In no event will the authors be held liable for any damages arising from - * the use of this software. - * - * Permission is granted to anyone to use this software for any purpose, - * including commercial applications, and to alter it and redistribute it - * freely, subject to the following restrictions: - * - * 1. The origin of this software must not be misrepresented; you must not - * claim that you wrote the original software. If you use this software in a - * product, an acknowledgment in the product documentation would be - * appreciated but is not required. - * 2. Altered source versions must be plainly marked as such, and must not be - * misrepresented as being the original software. - * 3. This notice may not be removed or altered from any source distribution. - * - * Version: $Id$ - */ - -#ifndef _INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_ -#define _INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_ - -#include - -/** - * @file ISmmPluginExt.h Definitions for extended plugin exposure syntax. - * @brief Provides an alternate method for loading plugins, without needing to - * include the default headers and all their Half-Life baggage. - */ - -#define SOURCE_ENGINE_UNKNOWN 0 /**< Could not determine the engine version */ -#define SOURCE_ENGINE_ORIGINAL 1 /**< Original Source Engine (used by The Ship) */ -#define SOURCE_ENGINE_EPISODEONE 2 /**< Episode 1 Source Engine (second major SDK) */ -#define SOURCE_ENGINE_ORANGEBOX 3 /**< Orange Box Source Engine (third major SDK) */ - -#define METAMOD_PLAPI_VERSION 14 /**< Version of this header file */ -#define METAMOD_PLAPI_NAME "ISmmPlugin" /**< Name of the plugin interface */ - -namespace SourceMM -{ - class ISmmPlugin; - class ISmmAPI; - +/* + * vim: set ts=4 : + * ====================================================== + * Metamod:Source + * Copyright (C) 2004-2007 AlliedModders LLC and authors. + * All rights reserved. + * ====================================================== + * + * This software is provided 'as-is', without any express or implied warranty. + * In no event will the authors be held liable for any damages arising from + * the use of this software. + * + * Permission is granted to anyone to use this software for any purpose, + * including commercial applications, and to alter it and redistribute it + * freely, subject to the following restrictions: + * + * 1. The origin of this software must not be misrepresented; you must not + * claim that you wrote the original software. If you use this software in a + * product, an acknowledgment in the product documentation would be + * appreciated but is not required. + * 2. Altered source versions must be plainly marked as such, and must not be + * misrepresented as being the original software. + * 3. This notice may not be removed or altered from any source distribution. + * + * Version: $Id$ + */ + +#ifndef _INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_ +#define _INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_ + +#include + +/** + * @file ISmmPluginExt.h Provides an alternate method for loading plugins, + * without needing to include the default headers and all their Half-Life baggage. + * + * @brief Definitions for extended plugin loading. + */ + +#define SOURCE_ENGINE_UNKNOWN 0 /**< Could not determine the engine version */ +#define SOURCE_ENGINE_ORIGINAL 1 /**< Original Source Engine (used by The Ship) */ +#define SOURCE_ENGINE_EPISODEONE 2 /**< Episode 1 Source Engine (second major SDK) */ +#define SOURCE_ENGINE_ORANGEBOX 3 /**< Orange Box Source Engine (third major SDK) */ + +#define METAMOD_PLAPI_VERSION 14 /**< Version of this header file */ +#define METAMOD_PLAPI_NAME "ISmmPlugin" /**< Name of the plugin interface */ + +namespace SourceMM +{ + class ISmmPlugin; + class ISmmAPI; + /** * @brief Used to uniquely identify plugins. */ - typedef int PluginId; - - #define METAMOD_FAIL_API_V1 7 /**< Minimum API version to detect for V1 */ - #define METAMOD_FAIL_API_V2 14 /**< Minimum API version to detect for V2 */ - - /** - * Use this to instantiate a plugin that will always fail. - * This class definition works against major API versions 1 and 2. - */ - class ISmmFailPlugin - { - public: - /** - * @brief You must return METAMOD_FAIL_API_V1 or METAMOD_FAIL_API_V2 here, - * depending on which Metamod:Source version you detected. - */ - virtual int GetApiVersion() = 0; - - /** - * @brief Do not change. - */ - virtual ~ISmmFailPlugin() - { - } - - /** - * @brief Return false here -- fill in the error buffer appropriately. - * - * Do not ever return true. If you do, MM:S will crash because the class layout is - * incomplete against ISmmPlugin. - * - * @param id Ignore. - * @param ismm Ignore. - * @param error Error buffer (must be filled). - * @param maxlength Maximum size of error buffer. - * @param late Ignore. - * @return Must return false. - */ - virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0; - }; -} - -typedef SourceMM::ISmmPlugin METAMOD_PLUGIN; - -/** - * @brief Contains version information. - */ -struct MetamodVersionInfo -{ - int api_major; /**< ISmmAPI major version */ - int api_minor; /**< ISmmAPI minor version */ - int sh_iface; /**< SourceHook interface version */ - int sh_impl; /**< SourceHook implementation version */ - int pl_min; /**< Plugin API minimum version */ - int pl_max; /**< Plugin API maximum version */ - int source_engine; /**< Source Engine version (SOURCE_* constants) */ -}; - -/** - * @brief Contains information about loading a plugin. - */ -struct MetamodLoaderInfo -{ - const char *pl_file; /**< File path to the plugin being loaded. */ - const char *pl_path; /**< Folder path containing the plugin. */ -}; - -/** - * @brief If a function of this type is exposed as "CreateInterface_MMS", then - * Metamod:Source will attempt to call this function before calling - * CreateInterface. If this function returns a valid ISmmPlugin pointer, then - * CreateInterface will not be called. - * - * This is useful for implementing a mini-loader plugin for multiple versions. - * - * @param mvi MetamodVersionInfo structure. - * @param mli MetamodLoaderInfo structure. - * @return ISmmAPI pointer, or NULL if none. - */ -typedef METAMOD_PLUGIN *(*METAMOD_FN_LOAD)(const MetamodVersionInfo *mvi, - const MetamodLoaderInfo *mli); - -/** - * @brief If a function of this type is exposed as "UnloadInterface_MMS", then - * Metamod:Source will attempt to call this function after calling - * ISmmAPI::Unload(), and before closing the library. This lets loader plugins - * clean up before exiting. - * - * Note: This function will be ignored unless CreateInterfce_MMS was exposed. - * It may be called even if ISmmAPI::Unload() could not be called. - */ -typedef void (*METAMOD_FN_UNLOAD)(); - -/** - * @brief Original type of load function. CreateInterfaceFn from Valve. - * - * Plugins will expose this as "CreateInterface". - */ -typedef void *(*METAMOD_FN_ORIG_LOAD)(const char *, int *); - -#endif //INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_ - + typedef int PluginId; + + #define METAMOD_FAIL_API_V1 7 /**< Minimum API version to detect for V1 */ + #define METAMOD_FAIL_API_V2 14 /**< Minimum API version to detect for V2 */ + + /** + * Use this to instantiate a plugin that will always fail. + * This class definition works against major API versions 1 and 2. + */ + class ISmmFailPlugin + { + public: + /** + * @brief You must return METAMOD_FAIL_API_V1 or METAMOD_FAIL_API_V2 here, + * depending on which Metamod:Source version you detected. + */ + virtual int GetApiVersion() = 0; + + /** + * @brief Do not change. + */ + virtual ~ISmmFailPlugin() + { + } + + /** + * @brief Return false here -- fill in the error buffer appropriately. + * + * Do not ever return true. If you do, MM:S will crash because the class layout is + * incomplete against ISmmPlugin. + * + * @param id Ignore. + * @param ismm Ignore. + * @param error Error buffer (must be filled). + * @param maxlength Maximum size of error buffer. + * @param late Ignore. + * @return Must return false. + */ + virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0; + }; +} + +typedef SourceMM::ISmmPlugin METAMOD_PLUGIN; + +/** + * @brief Contains version information. + */ +struct MetamodVersionInfo +{ + int api_major; /**< ISmmAPI major version */ + int api_minor; /**< ISmmAPI minor version */ + int sh_iface; /**< SourceHook interface version */ + int sh_impl; /**< SourceHook implementation version */ + int pl_min; /**< Plugin API minimum version */ + int pl_max; /**< Plugin API maximum version */ + int source_engine; /**< Source Engine version (SOURCE_* constants) */ +}; + +/** + * @brief Contains information about loading a plugin. + */ +struct MetamodLoaderInfo +{ + const char *pl_file; /**< File path to the plugin being loaded. */ + const char *pl_path; /**< Folder path containing the plugin. */ +}; + +/** + * @brief If a function of this type is exposed as "CreateInterface_MMS", then + * Metamod:Source will attempt to call this function before calling + * CreateInterface. If this function returns a valid ISmmPlugin pointer, then + * CreateInterface will not be called. + * + * This is useful for implementing a mini-loader plugin for multiple versions. + * + * @param mvi MetamodVersionInfo structure. + * @param mli MetamodLoaderInfo structure. + * @return ISmmAPI pointer, or NULL if none. + */ +typedef METAMOD_PLUGIN *(*METAMOD_FN_LOAD)(const MetamodVersionInfo *mvi, + const MetamodLoaderInfo *mli); + +/** + * @brief If a function of this type is exposed as "UnloadInterface_MMS", then + * Metamod:Source will attempt to call this function after calling + * ISmmAPI::Unload(), and before closing the library. This lets loader plugins + * clean up before exiting. + * + * Note: This function will be ignored unless CreateInterfce_MMS was exposed. + * It may be called even if ISmmAPI::Unload() could not be called. + */ +typedef void (*METAMOD_FN_UNLOAD)(); + +/** + * @brief Original type of load function. CreateInterfaceFn from Valve. + * + * Plugins will expose this as "CreateInterface". + */ +typedef void *(*METAMOD_FN_ORIG_LOAD)(const char *, int *); + +#endif //INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_ + diff --git a/sourcemm/svn_version.h b/sourcemm/svn_version.h index 4bb5713..1d4d72d 100644 --- a/sourcemm/svn_version.h +++ b/sourcemm/svn_version.h @@ -5,9 +5,9 @@ #define SVN_PRODUCT_VERSION "1.6.0" -#define SVN_REVISION 653 -#define SVN_REVISION_STRING "653" -#define SVN_FILE_VERSION 1,6,0,653 -#define SVN_FILE_VERSION_STRING "1.6.0.653" +#define SVN_REVISION 655 +#define SVN_REVISION_STRING "655" +#define SVN_FILE_VERSION 1,6,0,655 +#define SVN_FILE_VERSION_STRING "1.6.0.655" #endif //_INCLUDE_SVN_VERSION_H_