diff --git a/core/msvc8/sourcemod_mm.vcproj b/core/msvc8/sourcemod_mm.vcproj index a6bfccfa..9095ead3 100644 --- a/core/msvc8/sourcemod_mm.vcproj +++ b/core/msvc8/sourcemod_mm.vcproj @@ -381,6 +381,10 @@ RelativePath="..\..\public\ITextParsers.h" > + + #include +/** + * @file IExtensionSys.h + * @brief Defines the interface for loading/unloading/managing extensions. + */ + namespace SourceMod { class IExtensionInterface; - typedef void * ITERATOR; + typedef void * ITERATOR; /**< Generic pointer for dependency iterators */ /** - * @brief Encapsulates an IExtension. + * @brief Encapsulates an IExtensionInterface and its dependencies. */ class IExtension { @@ -78,6 +97,9 @@ namespace SourceMod virtual bool IsRunning(char *error, size_t maxlength) =0; }; + /** + * @brief Version code of the IExtensionInterface API itself. + */ #define SMINTERFACE_EXTENSIONAPI_VERSION 1 /** @@ -86,6 +108,7 @@ namespace SourceMod class IExtensionInterface { public: + /** Returns the interface API version */ virtual unsigned int GetExtensionVersion() { return SMINTERFACE_EXTENSIONAPI_VERSION; @@ -172,12 +195,18 @@ namespace SourceMod #define SMINTERFACE_EXTENSIONMANAGER_NAME "IExtensionManager" #define SMINTERFACE_EXTENSIONMANAGER_VERSION 1 + /** + * @brief Not currently used. + */ enum ExtensionLifetime { ExtLifetime_Forever, //Extension will never be unloaded automatically ExtLifetime_Map, //Extension will be unloaded at the end of the map }; + /** + * @brief Manages the loading/unloading of extensions. + */ class IExtensionManager : public SMInterface { public: diff --git a/public/IForwardSys.h b/public/IForwardSys.h index bd023adc..05608fef 100644 --- a/public/IForwardSys.h +++ b/public/IForwardSys.h @@ -1,6 +1,32 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_FORWARDINTERFACE_H_ #define _INCLUDE_SOURCEMOD_FORWARDINTERFACE_H_ +/** + * @file IForwardSys.h + * @brief Defines the interface for managing collections ("forwards") of plugin calls. + * + * The Forward System is responsible for managing automated collections of IPluginFunctions. + * It thus provides wrappers to calling many functions at once. There are two types of such + * wrappers: Managed and Unmanaged. Confusingly, these terms refer to whether the user manages + * the forwards, not Core. Managed forwards are completely managed by the user, and are custom + * editable collections. Unmanaged forwards are the opposite, and will only work on a single global + * function name in all plugins. + */ + #include #include #include @@ -10,31 +36,40 @@ using namespace SourcePawn; #define SMINTERFACE_FORWARDMANAGER_NAME "IForwardManager" #define SMINTERFACE_FORWARDMANAGER_VERSION 1 -/** +/* * There is some very important documentation at the bottom of this file. * Readers interested in knowing more about the forward system, scrolling down is a must! */ namespace SourceMod { + /** + * @brief Defines the event hook result types plugins can return. + */ enum ResultType { - Pl_Continue = 0, /* No result */ - Pl_Handled = 1, /* Result was handled, stop at the end */ - Pl_Stop = 2, /* Result was handled, stop now */ + Pl_Continue = 0, /**< No result */ + Pl_Handled = 1, /**< Result was handled, stop at the end */ + Pl_Stop = 2, /**< Result was handled, stop now */ }; + /** + * @brief Defines how a forward iterates through plugin functions. + */ enum ExecType { - ET_Ignore = 0, /* Ignore all return values, return 0 */ - ET_Single = 1, /* Only return the last exec, ignore all others */ - ET_Event = 2, /* Acts as an event with the ResultTypes above, no mid-Stops allowed, returns highest */ - ET_Hook = 3, /* Acts as a hook with the ResultTypes above, mid-Stops allowed, returns highest */ - ET_Custom = 4, /* Ignored or handled by an IForwardFilter */ + ET_Ignore = 0, /**< Ignore all return values, return 0 */ + ET_Single = 1, /**< Only return the last exec, ignore all others */ + ET_Event = 2, /**< Acts as an event with the ResultTypes above, no mid-Stops allowed, returns highest */ + ET_Hook = 3, /**< Acts as a hook with the ResultTypes above, mid-Stops allowed, returns highest */ + ET_Custom = 4, /**< Ignored or handled by an IForwardFilter */ }; class IForward; + /** + * @brief Allows interception of how the Forward System executes functions. + */ class IForwardFilter { public: @@ -89,18 +124,16 @@ namespace SourceMod }; /** - * @brief Abstracts multiple function calling. + * @brief Unmanaged Forward, abstracts calling multiple functions as "forwards," or collections of functions. * - * NOTE: Parameters should be pushed in forward order, unlike - * the virtual machine/IPluginContext order. - * NOTE: Some functions are repeated in here because their - * documentation differs from their IPluginFunction equivalents. - * Missing are the Push functions, whose only doc change is that - * they throw SP_ERROR_PARAM on type mismatches. + * Parameters should be pushed in forward order, unlike the virtual machine/IPluginContext order. + * Some functions are repeated in here because their documentation differs from their IPluginFunction equivalents. + * Missing are the Push functions, whose only doc change is that they throw SP_ERROR_PARAM on type mismatches. */ class IForward : public ICallable { public: + /** Virtual Destructor */ virtual ~IForward() { } @@ -151,7 +184,9 @@ namespace SourceMod int flags=0) =0; }; - + /** + * @brief Managed Forward, same as IForward, except the collection can be modified. + */ class IChangeableForward : public IForward { public: @@ -189,7 +224,7 @@ namespace SourceMod * NOTE: If used during a call, function is temporarily queued until calls are over. * * @param ctx Context to use as a look-up. - * @param funcid Function id to add. + * @param index Function id to add. * @return True on success, otherwise false. */ virtual bool AddFunction(IPluginContext *ctx, funcid_t index) =0; @@ -203,18 +238,24 @@ namespace SourceMod #define SP_PARAMTYPE_ARRAY (4<<1)|SP_PARAMFLAG_BYREF #define SP_PARAMTYPE_VARARG (5<<1) + /** + * @brief Describes the various ways to pass parameters to plugins. + */ enum ParamType { - Param_Any = SP_PARAMTYPE_ANY, - Param_Cell = SP_PARAMTYPE_CELL, - Param_Float = SP_PARAMTYPE_FLOAT, - Param_String = SP_PARAMTYPE_STRING, - Param_Array = SP_PARAMTYPE_ARRAY, - Param_VarArgs = SP_PARAMTYPE_VARARG, - Param_CellByRef = SP_PARAMTYPE_CELL|SP_PARAMFLAG_BYREF, - Param_FloatByRef = SP_PARAMTYPE_FLOAT|SP_PARAMFLAG_BYREF, + Param_Any = SP_PARAMTYPE_ANY, /**< Any data type can be pushed */ + Param_Cell = SP_PARAMTYPE_CELL, /**< Only basic cells can be pushed */ + Param_Float = SP_PARAMTYPE_FLOAT, /**< Only floats can be pushed */ + Param_String = SP_PARAMTYPE_STRING, /**< Only strings can be pushed */ + Param_Array = SP_PARAMTYPE_ARRAY, /**< Only arrays can be pushed */ + Param_VarArgs = SP_PARAMTYPE_VARARG, /**< Same as "..." in plugins, anything can be pushed, but it will always be byref */ + Param_CellByRef = SP_PARAMTYPE_CELL|SP_PARAMFLAG_BYREF, /**< Only a cell by reference can be pushed */ + Param_FloatByRef = SP_PARAMTYPE_FLOAT|SP_PARAMFLAG_BYREF, /**< Only a float by reference can be pushed */ }; + /** + * @brief Provides functions for creating/destroying managed and unmanaged forwards. + */ class IForwardManager : public SMInterface { public: @@ -287,7 +328,7 @@ namespace SourceMod }; }; -/** +/* * In the AMX Mod X model of forwarding, each forward contained a list of pairs, each pair containing * a function ID and an AMX structure. The forward structure itself did very little but hold parameter types. * An execution call worked like this: diff --git a/public/IHandleSys.h b/public/IHandleSys.h index ba56bb43..e9631892 100644 --- a/public/IHandleSys.h +++ b/public/IHandleSys.h @@ -1,24 +1,63 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_ #define _INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_ +/** + * @file IHandleSys.h + * @brief Defines the interface for creating, reading, and removing Handles. + * + * The Handle system abstracts generic pointers into typed objects represented by + * 32bit codes. This is extremely useful for verifying data integrity and cross-platform + * support in SourcePawn scripts. When a Plugin unloads, all its Handles are freed, ensuring + * that no memory leaks are present, They have reference counts and thus can be duplicated, + * or cloned, and are safe to pass between Plugins even if one is unloaded. + * + * Handles are created with a given type (custom types may be created). They can have + * per-Identity permissions for deletion, reading, and cloning. They also support generic + * operations. For example, deleting a Handle will call that type's destructor on the generic + * pointer, making cleanup easier for users and eliminating memory leaks. + */ + #include #include #define SMINTERFACE_HANDLESYSTEM_NAME "IHandleSys" #define SMINTERFACE_HANDLESYSTEM_VERSION 1 +/** Specifies no Identity */ #define DEFAULT_IDENTITY NULL +/** Specifies no Type. This is invalid for everything but reading a Handle. */ +#define NO_HANDLE_TYPE 0 +/** Specifies an invalid/NULL Handle */ +#define BAD_HANDLE 0 namespace SourceMod { /** - * Both of these types have invalid values of '0' for error checking. + * @brief Represents a Handle Type ID. */ typedef unsigned int HandleType_t; + + /** + * @brief Represents a Handle ID. + */ typedef unsigned int Handle_t; - /** + /* * About type checking: * Types can be inherited - a Parent type ("Supertype") can have child types. * When accessing handles, type checking is done. This table shows how this is resolved: @@ -31,88 +70,100 @@ namespace SourceMod * Child Child Success */ + /** + * @brief Lists the possible handle error codes. + */ enum HandleError { - HandleError_None = 0, /* No error */ - HandleError_Changed, /* The handle has been freed and reassigned */ - HandleError_Type, /* The handle has a different type registered */ - HandleError_Freed, /* The handle has been freed */ - HandleError_Index, /* generic internal indexing error */ - HandleError_Access, /* No access permitted to free this handle */ - HandleError_Limit, /* The limited number of handles has been reached */ - HandleError_Identity, /* The identity token was not usable */ - HandleError_Owner, /* Owners do not match for this operation */ - HandleError_Version, /* Unrecognized security structure version */ - HandleError_Parameter, /* An invalid parameter was passed */ - HandleError_NoInherit, /* This type cannot be inherited */ + HandleError_None = 0, /**< No error */ + HandleError_Changed, /**< The handle has been freed and reassigned */ + HandleError_Type, /**< The handle has a different type registered */ + HandleError_Freed, /**< The handle has been freed */ + HandleError_Index, /**< generic internal indexing error */ + HandleError_Access, /**< No access permitted to free this handle */ + HandleError_Limit, /**< The limited number of handles has been reached */ + HandleError_Identity, /**< The identity token was not usable */ + HandleError_Owner, /**< Owners do not match for this operation */ + HandleError_Version, /**< Unrecognized security structure version */ + HandleError_Parameter, /**< An invalid parameter was passed */ + HandleError_NoInherit, /**< This type cannot be inherited */ }; /** - * Access rights specific to a type + * @brief Lists access rights specific to a type. */ enum HTypeAccessRight { - HTypeAccess_Create = 0, /* Handles of this type can be created (DEFAULT=false) */ - HTypeAccess_Inherit, /* Sub-types can inherit this type (DEFAULT=false) */ + HTypeAccess_Create = 0, /**< Handles of this type can be created (DEFAULT=false) */ + HTypeAccess_Inherit, /**< Sub-types can inherit this type (DEFAULT=false) */ /* -------------- */ - HTypeAccess_TOTAL, /* Total number of type access rights */ + HTypeAccess_TOTAL, /**< Total number of type access rights */ }; /** - * Access rights specific to a Handle. These rights are exclusive. - * For example, you do not need "read" access to delete or clone. + * @brief Lists access rights specific to a Handle. + * + * These rights are exclusive. For example, you do not need "read" access to delete or clone. */ enum HandleAccessRight { - HandleAccess_Read, /* Can be read (DEFAULT=ident only) */ - HandleAccess_Delete, /* Can be deleted (DEFAULT=owner only) */ - HandleAccess_Clone, /* Can be cloned (DEFAULT=any) */ + HandleAccess_Read, /**< Can be read (DEFAULT=ident only) */ + HandleAccess_Delete, /**< Can be deleted (DEFAULT=owner only) */ + HandleAccess_Clone, /**< Can be cloned (DEFAULT=any) */ /* ------------- */ - HandleAccess_TOTAL, /* Total number of access rights */ + HandleAccess_TOTAL, /**< Total number of access rights */ }; - #define HANDLE_RESTRICT_IDENTITY (1<<0) /* Access is restricted to the identity */ - #define HANDLE_RESTRICT_OWNER (1<<1) /* Access is restricted to the owner */ + /** Access is restricted to the identity */ + #define HANDLE_RESTRICT_IDENTITY (1<<0) + /** Access is restricted to the owner */ + #define HANDLE_RESTRICT_OWNER (1<<1) /** - * This is used to define per-type access rights. + * @brief This is used to define per-type access rights. */ struct TypeAccess { + /** Constructor */ TypeAccess() { hsVersion = SMINTERFACE_HANDLESYSTEM_VERSION; } - unsigned int hsVersion; - IdentityToken_t *ident; - bool access[HTypeAccess_TOTAL]; + unsigned int hsVersion; /**< Handle API version */ + IdentityToken_t *ident; /**< Identity owning this type */ + bool access[HTypeAccess_TOTAL]; /**< Access array */ }; /** - * This is used to define per-Handle access rights. + * @brief This is used to define per-Handle access rights. */ struct HandleAccess { + /** Constructor */ HandleAccess() { hsVersion = SMINTERFACE_HANDLESYSTEM_VERSION; } - unsigned int hsVersion; - unsigned int access[HandleAccess_TOTAL]; + unsigned int hsVersion; /**< Handle API version */ + unsigned int access[HandleAccess_TOTAL]; /**< Access array */ }; /** - * This pair of tokens is used for identification. + * @brief This pair of tokens is used for identification. */ struct HandleSecurity { - IdentityToken_t *pOwner; /* Owner of the Handle */ - IdentityToken_t *pIdentity; /* Owner of the Type */ + IdentityToken_t *pOwner; /**< Owner of the Handle */ + IdentityToken_t *pIdentity; /**< Owner of the Type */ }; + /** + * @brief Hooks type-specific Handle operations. + */ class IHandleTypeDispatch { public: + /** Returns the Handle API version */ virtual unsigned int GetDispatchVersion() { return SMINTERFACE_HANDLESYSTEM_VERSION; @@ -124,6 +175,9 @@ namespace SourceMod virtual void OnHandleDestroy(HandleType_t type, void *object) =0; }; + /** + * @brief Provides functions for managing Handles. + */ class IHandleSys : public SMInterface { public: @@ -202,7 +256,7 @@ namespace SourceMod * NOTE: This function will decrement the internal reference counter. It will * only perform any further action if the counter hits 0. * - * @param type Handle_t identifier to destroy. + * @param handle Handle_t identifier to destroy. * @param pSecurity Security information struct (may be NULL). * @return A HandleError error code. */ diff --git a/public/ILibrarySys.h b/public/ILibrarySys.h index 000668d6..a8bafacf 100644 --- a/public/ILibrarySys.h +++ b/public/ILibrarySys.h @@ -1,6 +1,25 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_LIBRARY_INTERFACE_SYS_H_ #define _INCLUDE_SOURCEMOD_LIBRARY_INTERFACE_SYS_H_ +/** + * @file ILibrarySys.h + * @brief Defines platform-dependent operations, such as opening libraries and files. + */ + #include namespace SourceMod @@ -11,9 +30,9 @@ namespace SourceMod class ILibrary { public: + /** Virtual destructor (calls CloseLibrary) */ virtual ~ILibrary() { - /* Calling delete will call CloseLibrary! */ }; public: /** @@ -36,6 +55,7 @@ namespace SourceMod class IDirectory { public: + /** Virtual destructor */ virtual ~IDirectory() { } diff --git a/public/IPluginSys.h b/public/IPluginSys.h index 589b788f..6f4846fb 100644 --- a/public/IPluginSys.h +++ b/public/IPluginSys.h @@ -1,12 +1,32 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_ #define _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_ +/** + * @file IPluginSys.h + * @brief Defines the interface for the Plugin System, which manages loaded plugins. + */ + #include #include #define SMINTERFACE_PLUGINSYSTEM_NAME "IPluginManager" #define SMINTERFACE_PLUGINSYSTEM_VERSION 1 +/** Context user slot 3 is used Core for holding an IPluginContext pointer. */ #define SM_CONTEXTVAR_USER 3 namespace SourceMod @@ -14,35 +34,33 @@ namespace SourceMod class IPlugin; /** - * @brief Encapsulates plugin public information. + * @brief Encapsulates plugin public information exposed through "myinfo." */ typedef struct sm_plugininfo_s { - const char *name; - const char *author; - const char *description; - const char *version; - const char *url; + const char *name; /**< Plugin name */ + const char *author; /**< Plugin author */ + const char *description; /**< Plugin description */ + const char *version; /**< Plugin version string */ + const char *url; /**< Plugin URL */ } sm_plugininfo_t; /** * @brief Describes the usability status of a plugin. - * Note: The status "Loaded" and "Created" are only reachable - * during map load. */ enum PluginStatus { - Plugin_Running=0, /* Plugin is running */ + Plugin_Running=0, /**< Plugin is running */ /* All states below are unexecutable */ - Plugin_Paused, /* Plugin is loaded but paused */ - Plugin_Error, /* Plugin is loaded but errored/locked */ + Plugin_Paused, /**< Plugin is loaded but paused */ + Plugin_Error, /**< Plugin is loaded but errored/locked */ /* All states below do not have all natives */ - Plugin_Loaded, /* Plugin has passed loading and can be finalized */ - Plugin_Failed, /* Plugin has a fatal failure */ - Plugin_Created, /* Plugin is created but not initialized */ - Plugin_Uncompiled, /* Plugin is not yet compiled by the JIT */ - Plugin_BadLoad, /* Plugin failed to load */ + Plugin_Loaded, /**< Plugin has passed loading and can be finalized */ + Plugin_Failed, /**< Plugin has a fatal failure */ + Plugin_Created, /**< Plugin is created but not initialized */ + Plugin_Uncompiled, /**< Plugin is not yet compiled by the JIT */ + Plugin_BadLoad, /**< Plugin failed to load */ }; @@ -51,10 +69,10 @@ namespace SourceMod */ enum PluginType { - PluginType_Private, /* Plugin is privately managed and receives no forwards */ - PluginType_MapUpdated, /* Plugin will never be unloaded unless for updates on mapchange */ - PluginType_MapOnly, /* Plugin will be removed at mapchange */ - PluginType_Global, /* Plugin will never be unloaded or updated */ + PluginType_Private, /**< Plugin is privately managed and receives no forwards */ + PluginType_MapUpdated, /**< Plugin will never be unloaded unless for updates on mapchange */ + PluginType_MapOnly, /**< Plugin will be removed at mapchange */ + PluginType_Global, /**< Plugin will never be unloaded or updated */ }; /** @@ -63,6 +81,7 @@ namespace SourceMod class IPlugin { public: + /** Virtual destructor */ virtual ~IPlugin() { } @@ -140,6 +159,7 @@ namespace SourceMod class IPluginIterator { public: + /** Virtual destructor */ virtual ~IPluginIterator() { }; diff --git a/public/IRootConsoleMenu.h b/public/IRootConsoleMenu.h index fc389b5a..01b5d4f3 100644 --- a/public/IRootConsoleMenu.h +++ b/public/IRootConsoleMenu.h @@ -1,11 +1,29 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_ROOT_CONSOLE_MENU_H_ #define _INCLUDE_SOURCEMOD_ROOT_CONSOLE_MENU_H_ /** - * @brief Note: This interface is not exposed. - * The reason should be obvious: we do not want users touching the "root" console menu. - * If we exposed this, every little plugin would be dropping down a silly set of user commands, - * whereas this menu is explicitly provided for stuff that only Core itself is capable of managing. + * @file IRootConsoleMenu.h + * @brief Defines the interface for adding options to the "sm" console command. + * + * This interface is not yet exported. It will be eventually. The initial reason should + * be obvious: we do not want users actually touching it. If we exposed this, every little + * plugin would be dropping down a silly set of user commands, and exploiting/cluttering the menu. + * Since this menu is explicitly provided for stuff that only Core itself is capable of managing, + * we won't expose it until a legitimate reason comes up. */ namespace SourceMod @@ -80,8 +98,8 @@ namespace SourceMod * N being the length of the command name. This is subject to change in case we * account for Valve's font choices. * - * @param option String containing the command option. - * @param description String containing the command description. + * @param cmd String containing the command option. + * @param text String containing the command description. */ virtual void DrawGenericOption(const char *cmd, const char *text) =0; }; diff --git a/public/IShareSys.h b/public/IShareSys.h index ab8f4525..528e4233 100644 --- a/public/IShareSys.h +++ b/public/IShareSys.h @@ -1,16 +1,42 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_IFACE_SHARE_SYS_H_ #define _INCLUDE_SOURCEMOD_IFACE_SHARE_SYS_H_ +/** + * @file IShareSys.h + * @brief Defines the Share System, responsible for shared resources and dependencies. + * + * The Share System also manages the Identity_t data type, although this is internally + * implemented with the Handle System. + */ + #include -#define NO_IDENTITY 0 namespace SourceMod { class IExtension; struct IdentityToken_t; + + /** Forward declaration from IHandleSys.h */ typedef unsigned int HandleType_t; + + /** Forward declaration from IHandleSys.h */ typedef HandleType_t IdentityType_t; + /** * @brief Defines the base functionality required by a shared interface. */ @@ -79,7 +105,7 @@ namespace SourceMod * NOTE: Adding natives currently does not bind them to any loaded plugins. * You must manually bind late natives. * - * @param token Identity token of parent object. + * @param myself Identity token of parent object. * @param natives Array of natives to add. The last entry must have NULL members. */ virtual void AddNatives(IExtension *myself, const sp_nativeinfo_t *natives) =0; diff --git a/public/ISourceMod.h b/public/ISourceMod.h index 43ec9cd5..bfdf4897 100644 --- a/public/ISourceMod.h +++ b/public/ISourceMod.h @@ -1,6 +1,25 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_ #define _INCLUDE_SOURCEMOD_MAIN_HELPER_INTERFACE_H_ +/** + * @file ISourceMod.h + * @brief Defines miscellanious helper functions useful to extensions. + */ + #include #include @@ -9,14 +28,20 @@ namespace SourceMod { + /** + * @brief Describes various ways of formatting a base path. + */ enum PathType { - Path_None = 0, - Path_Game, - Path_SM, - Path_SM_Rel, + Path_None = 0, /**< No base path */ + Path_Game, /**< Base path is absolute mod folder */ + Path_SM, /**< Base path is absolute to SourceMod */ + Path_SM_Rel, /**< Base path is relative to SourceMod */ }; + /** + * @brief Contains miscellanious helper functions. + */ class ISourceMod : public SMInterface { public: @@ -58,6 +83,7 @@ namespace SourceMod /** * @brief Logs a message to the SourceMod logs. * + * @param pExt Extension calling this function. * @param format Message format. * @param ... Message format parameters. */ @@ -66,6 +92,7 @@ namespace SourceMod /** * @brief Logs a message to the SourceMod error logs. * + * @param pExt Extension calling this function. * @param format Message format. * @param ... Message format parameters. */ diff --git a/public/ITextParsers.h b/public/ITextParsers.h index cae293a1..d7723cd9 100644 --- a/public/ITextParsers.h +++ b/public/ITextParsers.h @@ -1,6 +1,25 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_TEXTPARSERS_INTERFACE_H_ #define _INCLUDE_SOURCEMOD_TEXTPARSERS_INTERFACE_H_ +/** + * @file ITextParsers.h + * @brief Defines various text/file parsing functions, as well as UTF-8 support code. + */ + #include namespace SourceMod @@ -43,6 +62,10 @@ namespace SourceMod * maintain * products */ + + /** + * @brief Contains parse events for INI files. + */ class ITextListener_INI { public: @@ -74,7 +97,7 @@ namespace SourceMod * @param invalid_tokens Whether or not the key contained invalid tokens. * @param equal_token There was an '=' sign present (in case the value is missing). * @param quotes Whether value was enclosed in quotes. - * @param curtoken Contains the token index of the start of the value string. + * @param curtok Contains the token index of the start of the value string. * This can be changed when returning false. * @return True to keep parsing, false otherwise. */ @@ -95,7 +118,7 @@ namespace SourceMod * @param curtok Pointer to optionally store failed position in string. * @return True to keep parsing, false otherwise. */ - virtual bool ReadINI_RawLine(const char *line, unsigned int *cutok) + virtual bool ReadINI_RawLine(const char *line, unsigned int *curtok) { return true; } @@ -140,29 +163,38 @@ namespace SourceMod * // * / * */ + /** + * @brief Lists actions to take when an SMC parse hook is done. + */ enum SMCParseResult { - SMCParse_Continue, //continue parsing - SMCParse_Halt, //stop parsing here - SMCParse_HaltFail //stop parsing and return failure + SMCParse_Continue, /**< Continue parsing */ + SMCParse_Halt, /**< Stop parsing here */ + SMCParse_HaltFail /**< Stop parsing and return SMCParseError_Custom */ }; + /** + * @brief Lists error codes possible from parsing an SMC file. + */ enum SMCParseError { - SMCParse_Okay = 0, //no error - SMCParse_StreamOpen, //stream failed to open - SMCParse_StreamError, //the stream died... somehow - SMCParse_Custom, //a custom handler threw an error - SMCParse_InvalidSection1, //a section was declared without quotes, and had extra tokens - SMCParse_InvalidSection2, //a section was declared without any header - SMCParse_InvalidSection3, //a section ending was declared with too many unknown tokens - SMCParse_InvalidSection4, //a section ending has no matching beginning - SMCParse_InvalidSection5, //a section beginning has no matching ending - SMCParse_InvalidTokens, //there were too many unidentifiable strings on one line - SMCParse_TokenOverflow, //the token buffer overflowed - SMCParse_InvalidProperty1, //a property was declared outside of any section + SMCParse_Okay = 0, /**< No error */ + SMCParse_StreamOpen, /**< Stream failed to open */ + SMCParse_StreamError, /**< The stream died... somehow */ + SMCParse_Custom, /**< A custom handler threw an error */ + SMCParse_InvalidSection1, /**< A section was declared without quotes, and had extra tokens */ + SMCParse_InvalidSection2, /**< A section was declared without any header */ + SMCParse_InvalidSection3, /**< A section ending was declared with too many unknown tokens */ + SMCParse_InvalidSection4, /**< A section ending has no matching beginning */ + SMCParse_InvalidSection5, /**< A section beginning has no matching ending */ + SMCParse_InvalidTokens, /**< There were too many unidentifiable strings on one line */ + SMCParse_TokenOverflow, /**< The token buffer overflowed */ + SMCParse_InvalidProperty1, /**< A property was declared outside of any section */ }; + /** + * @brief Describes the events available for reading an SMC stream. + */ class ITextListener_SMC { public: @@ -250,6 +282,9 @@ namespace SourceMod #define SMINTERFACE_TEXTPARSERS_NAME "ITextParsers" #define SMINTERFACE_TEXTPARSERS_VERSION 1 + /** + * @brief Contains various text stream parsing functions. + */ class ITextParsers : public SMInterface { public: diff --git a/public/doxygen/SourceMod.doxyfile b/public/doxygen/SourceMod.doxyfile new file mode 100644 index 00000000..857703d9 --- /dev/null +++ b/public/doxygen/SourceMod.doxyfile @@ -0,0 +1,262 @@ +# Doxyfile 1.5.1-p1 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = "SourceMod SDK" +PROJECT_NUMBER = 376 +OUTPUT_DIRECTORY = c:\temp\sm-dox +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +USE_WINDOWS_ENCODING = YES +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = r:\sourcemod\ +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 10 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +BUILTIN_STL_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = NO +SORT_BRIEF_DOCS = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = r:\sourcemod\trunk\public +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.d \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.idl \ + *.odl \ + *.cs \ + *.php \ + *.php3 \ + *.inc \ + *.m \ + *.mm \ + *.dox \ + *.py +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = NO +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = NO +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = YES +CHM_FILE = SourceMod-SDK.chm +HHC_LOCATION = C:/temp/sm-dox/html/index.hhc +GENERATE_CHI = NO +BINARY_TOC = YES +TOC_EXPAND = YES +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = YES +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = NO +USE_PDFLATEX = NO +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = SOURCEMOD_BUILD \ + SMEXT_CONF_METAMOD +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = YES +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = "C:/Program Files/ATT/Graphviz/bin" +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 1024 +MAX_DOT_GRAPH_HEIGHT = 1024 +MAX_DOT_GRAPH_DEPTH = 1000 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = YES diff --git a/public/extensions/IThreader.h b/public/extensions/IThreader.h index 90e401fe..6e934010 100644 --- a/public/extensions/IThreader.h +++ b/public/extensions/IThreader.h @@ -1,6 +1,25 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_THREADER_H #define _INCLUDE_SOURCEMOD_THREADER_H +/** + * @file IThreader.h + * @brief Contains platform independent routines for threading. + */ + #include #define SMINTERFACE_THREADER_NAME "IThreader" @@ -15,13 +34,14 @@ namespace SourceMod { Thread_Default = 0, /** - * Auto-release handle on finish + * @brief Auto-release handle on finish + * * You are not guaranteed the handle for this is valid after * calling MakeThread(), so never use it until OnTerminate is called. */ Thread_AutoRelease = 1, /** - * Thread is created "suspended", meaning it is inactive until unpaused. + * @brief Thread is created "suspended", meaning it is inactive until unpaused. */ Thread_CreateSuspended = 2, }; @@ -53,13 +73,14 @@ namespace SourceMod */ struct ThreadParams { + /** Constructor */ ThreadParams() : flags(Thread_Default), prio(ThreadPrio_Normal) { }; - ThreadFlags flags; - ThreadPriority prio; + ThreadFlags flags; /**< Flags to set on the thread */ + ThreadPriority prio; /**< Priority to set on the thread */ }; class IThreadCreator; @@ -70,6 +91,7 @@ namespace SourceMod class IThreadHandle { public: + /** Virtual destructor */ virtual ~IThreadHandle() { }; public: /** @@ -94,7 +116,7 @@ namespace SourceMod /** * @brief Returns the thread states. * - * @param ptparmas Pointer to a ThreadParams buffer. + * @param ptparams Pointer to a ThreadParams buffer. */ virtual void GetParams(ThreadParams *ptparams) =0; @@ -135,6 +157,7 @@ namespace SourceMod class IThread { public: + /** Virtual destructor */ virtual ~IThread() { }; public: /** @@ -145,8 +168,7 @@ namespace SourceMod virtual void RunThread(IThreadHandle *pHandle) =0; /** - * @param Called when the thread terminates. - * Note: This occurs inside the thread as well. + * @brief Called when the thread terminates. This occurs inside the thread as well. * * @param pHandle Pointer to the thread's handle. * @param cancel True if the thread did not finish, false otherwise. @@ -161,6 +183,7 @@ namespace SourceMod class IThreadCreator { public: + /** Virtual Destructor */ virtual ~IThreadCreator() { }; public: /** @@ -204,6 +227,7 @@ namespace SourceMod class IMutex { public: + /** Virtual Destructor */ virtual ~IMutex() { }; public: /** @@ -235,6 +259,7 @@ namespace SourceMod class IEventSignal { public: + /** Virtual Destructor */ virtual ~IEventSignal() { }; public: /** @@ -271,6 +296,7 @@ namespace SourceMod class IThreadWorker : public IThreadCreator { public: + /** Virtual Destructor */ virtual ~IThreadWorker() { }; diff --git a/public/sample_ext/extension.cpp b/public/sample_ext/extension.cpp index 9065e47d..dcdc0211 100644 --- a/public/sample_ext/extension.cpp +++ b/public/sample_ext/extension.cpp @@ -1,5 +1,10 @@ #include "extension.h" -Sample g_Sample; +/** + * @file extension.cpp + * @brief Implement extension code here. + */ + +Sample g_Sample; /**< Global singleton for your extension's main interface */ SMEXT_LINK(&g_Sample); diff --git a/public/sample_ext/extension.h b/public/sample_ext/extension.h index 7d0fc767..cd40740e 100644 --- a/public/sample_ext/extension.h +++ b/public/sample_ext/extension.h @@ -1,8 +1,15 @@ #ifndef _INCLUDE_SOURCEMOD_EXTENSION_PROPER_H_ #define _INCLUDE_SOURCEMOD_EXTENSION_PROPER_H_ +/** + * @file extension.h + * @brief Sample extension code header. + */ + + #include "smsdk_ext.h" + /** * @brief Sample implementation of the SDK Extension. * Note: Uncomment one of the pre-defined virtual functions in order to use it. diff --git a/public/sample_ext/smsdk_config.h b/public/sample_ext/smsdk_config.h index 488dedf1..80cf4b6a 100644 --- a/public/sample_ext/smsdk_config.h +++ b/public/sample_ext/smsdk_config.h @@ -1,6 +1,11 @@ #ifndef _INCLUDE_SOURCEMOD_EXTENSION_CONFIG_H_ #define _INCLUDE_SOURCEMOD_EXTENSION_CONFIG_H_ +/** + * @file smsdk_config.h + * @brief Contains macros for configuring basic extension information. + */ + /* Basic information exposed publically */ #define SMEXT_CONF_NAME "Sample Extension" #define SMEXT_CONF_DESCRIPTION "Sample extension to help developers" diff --git a/public/sample_ext/smsdk_ext.cpp b/public/sample_ext/smsdk_ext.cpp index 0dfcd408..493cf7f3 100644 --- a/public/sample_ext/smsdk_ext.cpp +++ b/public/sample_ext/smsdk_ext.cpp @@ -1,13 +1,33 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #include #include #include "smsdk_ext.h" -IShareSys *g_pShareSys = NULL; -IExtension *myself = NULL; -IHandleSys *g_pHandleSys = NULL; -ISourceMod *g_pSM = NULL; -IForwardManager *g_pForwards = NULL; +/** + * @file smsdk_ext.cpp + * @brief Contains wrappers for making Extensions easier to write. + */ +IShareSys *g_pShareSys = NULL; /**< Share system */ +IExtension *myself = NULL; /**< Ourself */ +IHandleSys *g_pHandleSys = NULL; /**< Handle system */ +ISourceMod *g_pSM = NULL; /**< SourceMod helpers */ +IForwardManager *g_pForwards = NULL; /**< Forward system */ + +/** Exports the main interface */ PLATFORM_EXTERN_C IExtensionInterface *GetSMExtAPI() { return g_pExtensionIface; @@ -139,14 +159,15 @@ void SDKExtension::SDK_OnAllLoaded() #if defined SMEXT_CONF_METAMOD -PluginId g_PLID = 0; -ISmmPlugin *g_PLAPI = NULL; -SourceHook::ISourceHook *g_SHPtr = NULL; -ISmmAPI *g_SMAPI = NULL; +PluginId g_PLID = 0; /**< Metamod plugin ID */ +ISmmPlugin *g_PLAPI = NULL; /**< Metamod plugin API */ +SourceHook::ISourceHook *g_SHPtr = NULL; /**< SourceHook pointer */ +ISmmAPI *g_SMAPI = NULL; /**< SourceMM API pointer */ -IVEngineServer *engine = NULL; -IServerGameDLL *gamedll = NULL; +IVEngineServer *engine = NULL; /**< IVEngineServer pointer */ +IServerGameDLL *gamedll = NULL; /**< IServerGameDLL pointer */ +/** Exposes the extension to Metamod */ SMM_API void *PL_EXPOSURE(const char *name, int *code) { if (name && !strcmp(name, PLAPI_NAME)) diff --git a/public/sample_ext/smsdk_ext.h b/public/sample_ext/smsdk_ext.h index 16d931bc..85c70011 100644 --- a/public/sample_ext/smsdk_ext.h +++ b/public/sample_ext/smsdk_ext.h @@ -1,6 +1,25 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_EXTENSION_BASESDK_H_ #define _INCLUDE_SOURCEMOD_EXTENSION_BASESDK_H_ +/** + * @file smsdk_ext.h + * @brief Contains wrappers for making Extensions easier to write. + */ + #include "smsdk_config.h" #include #include @@ -24,6 +43,7 @@ class SDKExtension : public IExtensionInterface { public: + /** Constructor */ SDKExtension(); public: /** @@ -88,28 +108,56 @@ public: //IExtensionInterface virtual bool OnExtensionLoad(IExtension *me, IShareSys *sys, char *error, size_t err_max, bool late); virtual void OnExtensionUnload(); virtual void OnExtensionsAllLoaded(); + + /** Returns whether or not this is a Metamod-based extension */ virtual bool IsMetamodExtension(); + + /** + * @brief Called when the pause state changes. + * + * @param state True if being paused, false if being unpaused. + */ virtual void OnExtensionPauseChange(bool state); + + /** Returns name */ virtual const char *GetExtensionName(); + /** Returns URL */ virtual const char *GetExtensionURL(); + /** Returns log tag */ virtual const char *GetExtensionTag(); + /** Returns author */ virtual const char *GetExtensionAuthor(); + /** Returns version string */ virtual const char *GetExtensionVerString(); + /** Returns description string */ virtual const char *GetExtensionDescription(); + /** Returns date string */ virtual const char *GetExtensionDateString(); #if defined SMEXT_CONF_METAMOD public: //ISmmPlugin + /** Called when the extension is attached to Metamod. */ virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late); + /** Returns the author to MM */ virtual const char *GetAuthor(); + /** Returns the name to MM */ virtual const char *GetName(); + /** Returns the description to MM */ virtual const char *GetDescription(); + /** Returns the URL to MM */ virtual const char *GetURL(); + /** Returns the license to MM */ virtual const char *GetLicense(); + /** Returns the version string to MM */ virtual const char *GetVersion(); + /** Returns the date string to MM */ virtual const char *GetDate(); + /** Returns the logtag to MM */ virtual const char *GetLogTag(); + /** Called on unload */ virtual bool Unload(char *error, size_t maxlen); + /** Called on pause */ virtual bool Pause(char *error, size_t maxlen); + /** Called on unpause */ virtual bool Unpause(char *error, size_t maxlen); private: bool m_SourceMMLoaded; @@ -132,7 +180,9 @@ extern IVEngineServer *engine; extern IServerGameDLL *gamedll; #endif +/** Creates a SourceMod interface macro pair */ #define SM_MKIFACE(name) SMINTERFACE_##name##_NAME, SMINTERFACE_##name##_VERSION +/** Automates retrieving SourceMod interfaces */ #define SM_GET_IFACE(prefix,addr) \ if (!g_pShareSys->RequestInterface(SM_MKIFACE(prefix), myself, (SMInterface **)&addr)) { \ if (error) { \ diff --git a/public/sm_platform.h b/public/sm_platform.h index 8f672d37..062b08c8 100644 --- a/public/sm_platform.h +++ b/public/sm_platform.h @@ -1,8 +1,23 @@ +/** + * =============================================================== + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. + * =============================================================== + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEMOD_PLATFORM_H_ #define _INCLUDE_SOURCEMOD_PLATFORM_H_ /** - * @file Contains platform-specific macros for abstraction. + * @file sm_platform.h + * @brief Contains platform-specific macros for abstraction. */ #if defined WIN32 || defined WIN64 diff --git a/public/sourcepawn/sp_file_headers.h b/public/sourcepawn/sp_file_headers.h index d3f41e7e..5f925bb2 100644 --- a/public/sourcepawn/sp_file_headers.h +++ b/public/sourcepawn/sp_file_headers.h @@ -1,26 +1,46 @@ +/** + * ================================================================ + * SourcePawn (C)2004-2007 AlliedModders LLC. All rights reserved. + * ================================================================ + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SPFILE_HEADERS_H #define _INCLUDE_SPFILE_HEADERS_H +/** + * @file sp_file_headers.h + * @brief Defines the structure present in a SourcePawn compiled binary. + * + * Note: These structures should be 1-byte packed to match the file format. + */ + #include #if defined __GNUC__ || defined HAVE_STDINT_ #include #else #if !defined HAVE_STDINT_H - typedef unsigned __int64 uint64_t; - typedef __int64 int64_t; - typedef unsigned __int32 uint32_t; - typedef __int32 int32_t; - typedef unsigned __int16 uint16_t; - typedef __int16 int16_t; - typedef unsigned __int8 uint8_t; - typedef __int8 int8_t; + typedef unsigned __int64 uint64_t; /**< 64bit unsigned integer */ + typedef __int64 int64_t; /**< 64bit signed integer */ + typedef unsigned __int32 uint32_t; /**< 32bit unsigned integer */ + typedef __int32 int32_t; /**< 32bit signed integer */ + typedef unsigned __int16 uint16_t; /**< 16bit unsigned integer */ + typedef __int16 int16_t; /**< 16bit signed integer */ + typedef unsigned __int8 uint8_t; /**< 8bit unsigned integer */ + typedef __int8 int8_t; /**< 8bit signed integer */ #define HAVE_STDINT_H #endif #endif -#define SPFILE_MAGIC 0x53504646 /* Source Pawn File Format (SPFF) */ -//#define SPFILE_VERSION 0x0100 -#define SPFILE_VERSION 0x0101 /* Uncompressed bytecode */ +#define SPFILE_MAGIC 0x53504646 /**< Source Pawn File Format (SPFF) */ +#define SPFILE_VERSION 0x0101 /**< Uncompressed bytecode */ //:TODO: better compiler/nix support #if defined __linux__ @@ -30,78 +50,92 @@ #pragma pack(1) /* structures must be packed (byte-aligned) */ #endif -#define SPFILE_COMPRESSION_NONE 0 -#define SPFILE_COMPRESSION_GZ 1 +#define SPFILE_COMPRESSION_NONE 0 /**< No compression in file */ +#define SPFILE_COMPRESSION_GZ 1 /**< GZ compression */ +/** + * @brief File section header format. + */ typedef struct sp_file_section_s { - uint32_t nameoffs; /* rel offset into global string table */ - uint32_t dataoffs; - uint32_t size; + uint32_t nameoffs; /**< Relative offset into global string table */ + uint32_t dataoffs; /**< Offset into the data section of the file */ + uint32_t size; /**< Size of the section's entry in the data section */ } sp_file_section_t; /** - * If compression is 0, then - * disksize may be 0 to mean that - * only the imagesize is needed. + * @brief File header format. If compression is 0, then disksize may be 0 + * to mean that only the imagesize is needed. */ typedef struct sp_file_hdr_s { - uint32_t magic; /* magic number */ - uint16_t version; /* version code */ - uint8_t compression;/* compression algorithm */ - uint32_t disksize; /* size on disk */ - uint32_t imagesize; /* size in memory */ - uint8_t sections; /* number of sections */ - uint32_t stringtab; /* offset to string table */ - uint32_t dataoffs; /* offset to file proper (any compression starts here) */ + uint32_t magic; /**< Magic number */ + uint16_t version; /**< Version code */ + uint8_t compression;/**< Compression algorithm */ + uint32_t disksize; /**< Size on disk */ + uint32_t imagesize; /**< Size in memory */ + uint8_t sections; /**< Number of sections */ + uint32_t stringtab; /**< Offset to string table */ + uint32_t dataoffs; /**< Offset to file proper (any compression starts here) */ } sp_file_hdr_t; -#define SP_FLAG_DEBUG (1<<0) +#define SP_FLAG_DEBUG (1<<0) /**< Debug information is present in the file */ -/* section is ".code" */ +/** + * @brief File-encoded format of the ".code" section. + */ typedef struct sp_file_code_s { - uint32_t codesize; /* codesize in bytes */ - uint8_t cellsize; /* cellsize in bytes */ - uint8_t codeversion; /* version of opcodes supported */ - uint16_t flags; /* flags */ - uint32_t main; /* address to "main" if any */ - uint32_t code; /* rel offset to code */ + uint32_t codesize; /**< Codesize in bytes */ + uint8_t cellsize; /**< Cellsize in bytes */ + uint8_t codeversion; /**< Version of opcodes supported */ + uint16_t flags; /**< Flags */ + uint32_t main; /**< Address to "main," if any */ + uint32_t code; /**< Relative offset to code */ } sp_file_code_t; -/* section is .data */ +/** + * @brief File-encoded format of the ".data" section. + */ typedef struct sp_file_data_s { - uint32_t datasize; /* size of data section in memory */ - uint32_t memsize; /* total mem required (includes data) */ - uint32_t data; /* file offset to data (helper) */ + uint32_t datasize; /**< Size of data section in memory */ + uint32_t memsize; /**< Total mem required (includes data) */ + uint32_t data; /**< File offset to data (helper) */ } sp_file_data_t; -/* section is .publics */ +/** + * @brief File-encoded format of the ".publics" section. + */ typedef struct sp_file_publics_s { - uint32_t address; /* address rel to code section */ - uint32_t name; /* index into nametable */ + uint32_t address; /**< Address relative to code section */ + uint32_t name; /**< Index into nametable */ } sp_file_publics_t; -/* section is .natives */ +/** + * @brief File-encoded format of the ".natives" section. + */ typedef struct sp_file_natives_s { - uint32_t name; /* name of native at index */ + uint32_t name; /**< Index into nametable */ } sp_file_natives_t; -/* section is .libraries */ +/** + * @brief File-encoded format of the ".libraries" section (UNUSED). + */ typedef struct sp_file_libraries_s { - uint32_t name; /* index into nametable */ + uint32_t name; /**< Index into nametable */ } sp_file_libraries_t; -/* section is .pubvars */ +/** + * @brief File-encoded format of the ".pubvars" section. + */ typedef struct sp_file_pubvars_s { - uint32_t address; /* address rel to dat section */ - uint32_t name; /* index into nametable */ + uint32_t address; /**< Address relative to the DAT section */ + uint32_t name; /**< Index into nametable */ } sp_file_pubvars_t; #if defined __linux__ @@ -110,54 +144,66 @@ typedef struct sp_file_pubvars_s #pragma pack(pop) /* reset previous packing */ #endif +/** + * @brief File-encoded debug information table. + */ typedef struct sp_fdbg_info_s { - uint32_t num_files; /* number of files */ - uint32_t num_lines; /* number of lines */ - uint32_t num_syms; /* number of symbols */ - uint32_t num_arrays; /* number of symbols which are arrays */ + uint32_t num_files; /**< number of files */ + uint32_t num_lines; /**< number of lines */ + uint32_t num_syms; /**< number of symbols */ + uint32_t num_arrays; /**< number of symbols which are arrays */ } sp_fdbg_info_t; /** - * Debug information structures + * @brief File-encoded debug file table. */ typedef struct sp_fdbg_file_s { - uint32_t addr; /* address into code */ - uint32_t name; /* offset into debug nametable */ + uint32_t addr; /**< Address into code */ + uint32_t name; /**< Offset into debug nametable */ } sp_fdbg_file_t; +/** + * @brief File-encoded debug line table. + */ typedef struct sp_fdbg_line_s { - uint32_t addr; /* address into code */ - uint32_t line; /* line number */ + uint32_t addr; /**< Address into code */ + uint32_t line; /**< Line number */ } sp_fdbg_line_t; -#define SP_SYM_VARIABLE 1 /* cell that has an address and that can be fetched directly (lvalue) */ -#define SP_SYM_REFERENCE 2 /* VARIABLE, but must be dereferenced */ -#define SP_SYM_ARRAY 3 -#define SP_SYM_REFARRAY 4 /* an array passed by reference (i.e. a pointer) */ -#define SP_SYM_FUNCTION 9 +#define SP_SYM_VARIABLE 1 /**< Cell that has an address and that can be fetched directly (lvalue) */ +#define SP_SYM_REFERENCE 2 /**< VARIABLE, but must be dereferenced */ +#define SP_SYM_ARRAY 3 /**< Symbol is an array */ +#define SP_SYM_REFARRAY 4 /**< An array passed by reference (i.e. a pointer) */ +#define SP_SYM_FUNCTION 9 /**< Symbol is a function */ +/** + * @brief File-encoded debug symbol information. + */ typedef struct sp_fdbg_symbol_s { - int32_t addr; /* address rel to DAT or stack frame */ - int16_t tagid; /* tag id */ - uint32_t codestart; /* start scope validity in code */ - uint32_t codeend; /* end scope validity in code */ - uint8_t ident; /* variable type */ - uint8_t vclass; /* scope class (local vs global) */ - uint16_t dimcount; /* dimension count (for arrays) */ - uint32_t name; /* offset into debug nametable */ + int32_t addr; /**< Address rel to DAT or stack frame */ + int16_t tagid; /**< Tag id */ + uint32_t codestart; /**< Start scope validity in code */ + uint32_t codeend; /**< End scope validity in code */ + uint8_t ident; /**< Variable type */ + uint8_t vclass; /**< Scope class (local vs global) */ + uint16_t dimcount; /**< Dimension count (for arrays) */ + uint32_t name; /**< Offset into debug nametable */ } sp_fdbg_symbol_t; +/** + * @brief File-encoded debug symbol array dimension info. + */ typedef struct sp_fdbg_arraydim_s { - int16_t tagid; /* tag id */ - uint32_t size; /* size of dimension */ + int16_t tagid; /**< Tag id */ + uint32_t size; /**< Size of dimension */ } sp_fdbg_arraydim_t; -/* section is .names */ +/** Typedef for .names table */ typedef char * sp_file_nametab_t; #endif //_INCLUDE_SPFILE_HEADERS_H diff --git a/public/sourcepawn/sp_typeutil.h b/public/sourcepawn/sp_typeutil.h index f5146bb2..b0dd39eb 100644 --- a/public/sourcepawn/sp_typeutil.h +++ b/public/sourcepawn/sp_typeutil.h @@ -1,12 +1,44 @@ +/** + * ================================================================ + * SourcePawn (C)2004-2007 AlliedModders LLC. All rights reserved. + * ================================================================ + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEPAWN_VM_TYPEUTIL_H_ #define _INCLUDE_SOURCEPAWN_VM_TYPEUTIL_H_ +/** + * @file sp_typeutil.h + * @brief Defines type utility functions. + */ + #include "sp_vm_types.h" +/** + * @brief Reinterpret-casts a float to a cell (requires -fno-strict-aliasing for GCC). + * + * @param val Float value. + * @return Cell typed version. + */ inline cell_t sp_ftoc(float val) { return *(cell_t *)&val; } + +/** + * @brief Reinterpret-casts a cell to a float (requires -fno-strict-aliasing for GCC). + * + * @param val Cell-packed float value. + * @return Float typed version. + */ inline float sp_ctof(cell_t val) { return *(float *)&val; diff --git a/public/sourcepawn/sp_vm_api.h b/public/sourcepawn/sp_vm_api.h index 41a7d09b..86bedccb 100644 --- a/public/sourcepawn/sp_vm_api.h +++ b/public/sourcepawn/sp_vm_api.h @@ -1,9 +1,29 @@ +/** + * ================================================================ + * SourcePawn (C)2004-2007 AlliedModders LLC. All rights reserved. + * ================================================================ + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEPAWN_VM_API_H_ #define _INCLUDE_SOURCEPAWN_VM_API_H_ +/** + * @file sp_vm_api.h + * @brief Contains all of the object structures used in the SourcePawn API. + */ + #include #include "sp_vm_types.h" +/** SourcePawn VM API Version */ #define SOURCEPAWN_VM_API_VERSION 1 #if defined SOURCEMOD_BUILD @@ -17,10 +37,9 @@ namespace SourcePawn { class IVirtualMachine; - #define SM_PARAM_COPYBACK (1<<0) /* Copy an array/reference back after call */ - - #define SM_PARAM_STRING_UTF8 (1<<0) /* String should be UTF-8 handled */ - #define SM_PARAM_STRING_COPY (1<<1) /* String should be copied into the plugin */ + #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */ + #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */ + #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */ /** * @brief Represents what a function needs to implement in order to be callable. @@ -52,7 +71,7 @@ namespace SourcePawn /** * @brief Pushes a float onto the current call. * - * @param float Parameter value to push. + * @param number Parameter value to push. * @return Error code, if any. */ virtual int PushFloat(float number) =0; @@ -64,7 +83,7 @@ namespace SourcePawn * This means you cannot push a pointer, change it, and push it again and expect * two different values to come out. * - * @param float Parameter value to push. + * @param number Parameter value to push. & @param flags Copy-back flags. * @return Error code, if any. */ @@ -119,6 +138,7 @@ namespace SourcePawn /** * @brief Encapsulates a function call in a plugin. + * * NOTE: Function calls must be atomic to one execution context. * NOTE: This object should not be deleted. It lives for the lifetime of the plugin. */ @@ -139,7 +159,7 @@ namespace SourcePawn * NOTE: You will get an error if you attempt to use CallFunction() with * previously pushed parameters. * - * @param param Array of cell parameters. + * @param params Array of cell parameters. * @param num_params Number of parameters to push. * @param result Pointer to store result of function on return. * @return SourcePawn error code (if any). @@ -156,7 +176,7 @@ namespace SourcePawn /** * @brief Returns the physical address of a by-reference parameter. * - * @param Parameter index to read (beginning at 0). + * @param param Parameter index to read (beginning at 0). * @return Address, or NULL if invalid parameter specified. */ virtual cell_t *GetAddressOfPushedParam(unsigned int param) =0; @@ -200,6 +220,7 @@ namespace SourcePawn class IPluginContext { public: + /** Virtual destructr */ virtual ~IPluginContext() { }; public: /** @@ -525,9 +546,9 @@ namespace SourcePawn */ struct CallStackInfo { - const char *filename; /* NULL if not found */ - unsigned int line; /* 0 if not found */ - const char *function; /* NULL if not found */ + const char *filename; /**< NULL if not found */ + unsigned int line; /**< 0 if not found */ + const char *function; /**< NULL if not found */ }; /** @@ -690,6 +711,7 @@ namespace SourcePawn class ICompilation { public: + /** Virtual destructor */ virtual ~ICompilation() { }; }; diff --git a/public/sourcepawn/sp_vm_base.h b/public/sourcepawn/sp_vm_base.h index 5d295d62..0d1b7136 100644 --- a/public/sourcepawn/sp_vm_base.h +++ b/public/sourcepawn/sp_vm_base.h @@ -1,6 +1,25 @@ +/** + * ================================================================ + * SourcePawn (C)2004-2007 AlliedModders LLC. All rights reserved. + * ================================================================ + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEPAWN_VM_BASE_H_ #define _INCLUDE_SOURCEPAWN_VM_BASE_H_ +/** + * @file sp_vm_base.h + * @brief Contains JIT export/linkage macros. + */ + #include /* :TODO: rename this to sp_vm_linkage.h */ @@ -11,6 +30,7 @@ #define EXPORT_LINK extern "C" __attribute__((visibility("default"))) #endif +/** No longer used */ typedef SourcePawn::IVirtualMachine *(*SP_GETVM_FUNC)(SourcePawn::ISourcePawnEngine *); #endif //_INCLUDE_SOURCEPAWN_VM_BASE_H_ diff --git a/public/sourcepawn/sp_vm_types.h b/public/sourcepawn/sp_vm_types.h index 74e47434..94a02f58 100644 --- a/public/sourcepawn/sp_vm_types.h +++ b/public/sourcepawn/sp_vm_types.h @@ -1,45 +1,64 @@ +/** + * ================================================================ + * SourcePawn (C)2004-2007 AlliedModders LLC. All rights reserved. + * ================================================================ + * + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used + * or modified under the Terms and Conditions of its License Agreement, which is found + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins + * may change at any time. To view the latest information, see: + * http://www.sourcemod.net/license.php + * + * Version: $Id$ + */ + #ifndef _INCLUDE_SOURCEPAWN_VM_TYPES_H #define _INCLUDE_SOURCEPAWN_VM_TYPES_H +/** + * @file sp_vm_types.h + * @brief Contains all run-time SourcePawn structures. + */ + #include "sp_file_headers.h" -typedef uint32_t ucell_t; -typedef int32_t cell_t; -typedef uint32_t funcid_t; +typedef uint32_t ucell_t; /**< Unsigned 32bit integer */ +typedef int32_t cell_t; /**< Basic 32bit signed integer type for plugins */ +typedef uint32_t funcid_t; /**< Function index code */ #include "sp_typeutil.h" -#define SP_MAX_EXEC_PARAMS 32 /* Maximum number of parameters in a function */ +#define SP_MAX_EXEC_PARAMS 32 /**< Maximum number of parameters in a function */ /** - * Error codes - * NOTE: Be sure to update the error string table when changing these + * @brief Error codes for SourcePawn routines. */ -#define SP_ERROR_NONE 0 -#define SP_ERROR_FILE_FORMAT 1 /* File format unrecognized */ -#define SP_ERROR_DECOMPRESSOR 2 /* A decompressor was not found */ -#define SP_ERROR_HEAPLOW 3 /* Not enough space left on the heap */ -#define SP_ERROR_PARAM 4 /* Invalid parameter or parameter type */ -#define SP_ERROR_INVALID_ADDRESS 5 /* A memory address was not valid */ -#define SP_ERROR_NOT_FOUND 6 /* The object in question was not found */ -#define SP_ERROR_INDEX 7 /* Invalid index parameter */ -#define SP_ERROR_STACKLOW 8 /* Nnot enough space left on the stack */ -#define SP_ERROR_NOTDEBUGGING 9 /* Debug mode was not on or debug section not found */ -#define SP_ERROR_INVALID_INSTRUCTION 10 /* Invalid instruction was encountered */ -#define SP_ERROR_MEMACCESS 11 /* Invalid memory access */ -#define SP_ERROR_STACKMIN 12 /* Stack went beyond its minimum value */ -#define SP_ERROR_HEAPMIN 13 /* Heap went beyond its minimum value */ -#define SP_ERROR_DIVIDE_BY_ZERO 14 /* Division by zero */ -#define SP_ERROR_ARRAY_BOUNDS 15 /* Array index is out of bounds */ -#define SP_ERROR_INSTRUCTION_PARAM 16 /* Instruction had an invalid parameter */ -#define SP_ERROR_STACKLEAK 17 /* A native leaked an item on the stack */ -#define SP_ERROR_HEAPLEAK 18 /* A native leaked an item on the heap */ -#define SP_ERROR_ARRAY_TOO_BIG 19 /* A dynamic array is too big */ -#define SP_ERROR_TRACKER_BOUNDS 20 /* Tracker stack is out of bounds */ -#define SP_ERROR_INVALID_NATIVE 21 /* Native was pending or invalid */ -#define SP_ERROR_PARAMS_MAX 22 /* Maximum number of parameters reached */ -#define SP_ERROR_NATIVE 23 /* Error originates from a native */ -#define SP_ERROR_NOT_RUNNABLE 24 /* Function or plugin is not runnable */ +#define SP_ERROR_NONE 0 /**< No error occurred */ +#define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */ +#define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */ +#define SP_ERROR_HEAPLOW 3 /**< Not enough space left on the heap */ +#define SP_ERROR_PARAM 4 /**< Invalid parameter or parameter type */ +#define SP_ERROR_INVALID_ADDRESS 5 /**< A memory address was not valid */ +#define SP_ERROR_NOT_FOUND 6 /**< The object in question was not found */ +#define SP_ERROR_INDEX 7 /**< Invalid index parameter */ +#define SP_ERROR_STACKLOW 8 /**< Nnot enough space left on the stack */ +#define SP_ERROR_NOTDEBUGGING 9 /**< Debug mode was not on or debug section not found */ +#define SP_ERROR_INVALID_INSTRUCTION 10 /**< Invalid instruction was encountered */ +#define SP_ERROR_MEMACCESS 11 /**< Invalid memory access */ +#define SP_ERROR_STACKMIN 12 /**< Stack went beyond its minimum value */ +#define SP_ERROR_HEAPMIN 13 /**< Heap went beyond its minimum value */ +#define SP_ERROR_DIVIDE_BY_ZERO 14 /**< Division by zero */ +#define SP_ERROR_ARRAY_BOUNDS 15 /**< Array index is out of bounds */ +#define SP_ERROR_INSTRUCTION_PARAM 16 /**< Instruction had an invalid parameter */ +#define SP_ERROR_STACKLEAK 17 /**< A native leaked an item on the stack */ +#define SP_ERROR_HEAPLEAK 18 /**< A native leaked an item on the heap */ +#define SP_ERROR_ARRAY_TOO_BIG 19 /**< A dynamic array is too big */ +#define SP_ERROR_TRACKER_BOUNDS 20 /**< Tracker stack is out of bounds */ +#define SP_ERROR_INVALID_NATIVE 21 /**< Native was pending or invalid */ +#define SP_ERROR_PARAMS_MAX 22 /**< Maximum number of parameters reached */ +#define SP_ERROR_NATIVE 23 /**< Error originates from a native */ +#define SP_ERROR_NOT_RUNNABLE 24 /**< Function or plugin is not runnable */ +//Hey you! Update the string table if you add to the end of me! */ /********************************************** *** The following structures are reference structures. @@ -49,60 +68,56 @@ typedef uint32_t funcid_t; **********************************************/ /** - * Information about the core plugin tables. - * These may or may not be present! + * @brief Information about the core plugin tables. These may or may not be present! */ typedef struct sp_plugin_infotab_s { - const char *stringbase; /* base of string table */ - uint32_t publics_num; /* number of publics */ - sp_file_publics_t *publics; /* public table */ - uint32_t natives_num; /* number of natives */ - sp_file_natives_t *natives; /* native table */ - uint32_t pubvars_num; /* number of pubvars */ - sp_file_pubvars_t *pubvars; /* pubvars table */ - uint32_t libraries_num; /* number of libraries */ - sp_file_libraries_t *lib; /* library table */ + const char *stringbase; /**< base of string table */ + uint32_t publics_num; /**< number of publics */ + sp_file_publics_t *publics; /**< public table */ + uint32_t natives_num; /**< number of natives */ + sp_file_natives_t *natives; /**< native table */ + uint32_t pubvars_num; /**< number of pubvars */ + sp_file_pubvars_t *pubvars; /**< pubvars table */ + uint32_t libraries_num; /**< number of libraries */ + sp_file_libraries_t *lib; /**< library table */ } sp_plugin_infotab_t; /** - * Information about the plugin's debug tables. - * These are all present if one is present. + * @brief Information about the plugin's debug tables. These are all present if one is present. */ typedef struct sp_plugin_debug_s { - const char *stringbase; /* base of string table */ - uint32_t files_num; /* number of files */ - sp_fdbg_file_t *files; /* files table */ - uint32_t lines_num; /* number of lines */ - sp_fdbg_line_t *lines; /* lines table */ - uint32_t syms_num; /* number of symbols */ - sp_fdbg_symbol_t *symbols; /* symbol table */ + const char *stringbase; /**< base of string table */ + uint32_t files_num; /**< number of files */ + sp_fdbg_file_t *files; /**< files table */ + uint32_t lines_num; /**< number of lines */ + sp_fdbg_line_t *lines; /**< lines table */ + uint32_t syms_num; /**< number of symbols */ + sp_fdbg_symbol_t *symbols; /**< symbol table */ } sp_plugin_debug_t; -#define SP_FA_SELF_EXTERNAL (1<<0) -#define SP_FA_BASE_EXTERNAL (1<<1) +#define SP_FA_SELF_EXTERNAL (1<<0) /**< Allocation of structure is external */ +#define SP_FA_BASE_EXTERNAL (1<<1) /**< Allocation of base is external */ /** - * The rebased, in-memory format of a plugin. - * This differs from the on-disk structure to ensure - * that the format is properly read. + * @brief The rebased memory format of a plugin. This differs from the on-disk structure + * to ensure that the format is properly read. */ typedef struct sp_plugin_s { - uint8_t *base; /* base of memory */ - uint8_t *pcode; /* p-code */ - uint32_t pcode_size; /* size of p-code */ - uint8_t *data; /* data size */ - uint32_t data_size; /* size of data */ - uint32_t memory; /* required memory */ - uint16_t flags; /* code flags */ - uint32_t allocflags; /* allocation flags */ - sp_plugin_infotab_t info; /* base info table */ - sp_plugin_debug_t debug; /* debug info table */ + uint8_t *base; /**< Base of memory for this plugin. */ + uint8_t *pcode; /**< P-Code of plugin */ + uint32_t pcode_size; /**< Size of p-code */ + uint8_t *data; /**< Data/memory layout */ + uint32_t data_size; /**< Size of data */ + uint32_t memory; /**< Required memory space */ + uint16_t flags; /**< Code flags */ + uint32_t allocflags; /**< Allocation flags */ + sp_plugin_infotab_t info; /**< Base info table */ + sp_plugin_debug_t debug; /**< Debug info table */ } sp_plugin_t; -/** Forward declarations */ namespace SourcePawn { @@ -112,6 +127,10 @@ namespace SourcePawn struct sp_context_s; +/** + * @brief Native callback prototype, passed a context and a parameter stack (0=count, 1+=args). + * A cell must be returned. + */ typedef cell_t (*SPVM_NATIVE_FUNC)(SourcePawn::IPluginContext *, const cell_t *); /********************************************** @@ -120,84 +139,82 @@ typedef cell_t (*SPVM_NATIVE_FUNC)(SourcePawn::IPluginContext *, const cell_t *) **********************************************/ /** - * Offsets and names to a public function. - * By default, these point back to the string table - * in the sp_plugin_infotab_t structure. + * @brief Offsets and names to a public function. */ typedef struct sp_public_s { - funcid_t funcid; /* encoded function id */ - uint32_t code_offs; /* code offset */ - const char *name; /* name */ + funcid_t funcid; /**< Encoded function id */ + uint32_t code_offs; /**< Relocated code offset */ + const char *name; /**< Name of function */ } sp_public_t; /** - * Offsets and names to public variables. - * The offset is relocated and the name by default - * points back to the sp_plugin_infotab_t structure. + * @brief Offsets and names to public variables. + * + * The offset is relocated and the name by default points back to the sp_plugin_infotab_t structure. */ typedef struct sp_pubvar_s { - cell_t *offs; /* pointer to data */ - const char *name; /* name */ + cell_t *offs; /**< Pointer to data */ + const char *name; /**< Name */ } sp_pubvar_t; -#define SP_NATIVE_UNBOUND (0) /* Native is undefined */ -#define SP_NATIVE_BOUND (1) /* Native is bound */ +#define SP_NATIVE_UNBOUND (0) /**< Native is undefined */ +#define SP_NATIVE_BOUND (1) /**< Native is bound */ /** - * Native lookup table, by default names - * point back to the sp_plugin_infotab_t structure. - * A native is NULL if unit + * @brief Native lookup table, by default names point back to the sp_plugin_infotab_t structure. */ typedef struct sp_native_s { - SPVM_NATIVE_FUNC pfn; /* function pointer */ - const char * name; /* name of function */ - uint32_t status; /* status flags */ + SPVM_NATIVE_FUNC pfn; /**< Function pointer */ + const char * name; /**< Name of function */ + uint32_t status; /**< Status flags */ } sp_native_t; /** - * Used for setting natives from modules/host apps. + * @brief Used for setting natives from modules/host apps. */ typedef struct sp_nativeinfo_s { - const char *name; - SPVM_NATIVE_FUNC func; + const char *name; /**< Name of the native */ + SPVM_NATIVE_FUNC func; /**< Address of native implementation */ } sp_nativeinfo_t; /** - * Debug file table + * @brief Run-time debug file table */ typedef struct sp_debug_file_s { - uint32_t addr; /* address into code */ - const char * name; /* name of file */ + uint32_t addr; /**< Address into code */ + const char * name; /**< Name of file */ } sp_debug_file_t; /** - * Note that line is missing. It is not necessary since - * this can be retrieved from the base plugin info. + * @brief Contains run-time debug line table. */ typedef struct sp_debug_line_s { - uint32_t addr; /* address into code */ - uint32_t line; /* line no. */ + uint32_t addr; /**< Address into code */ + uint32_t line; /**< Line number */ } sp_debug_line_t; +/** + * @brief These structures are equivalent. + */ typedef sp_fdbg_arraydim_t sp_debug_arraydim_t; /** - * The majority of this struct is already located in the parent - * block. Thus, only the relocated portions are required. + * @brief The majority of this struct is already located in the parent + * block. Thus, only the relocated portions are required. */ typedef struct sp_debug_symbol_s { - uint32_t codestart; /* relocated code address */ - uint32_t codeend; /* relocated code end address */ - const char * name; /* relocated name */ - sp_debug_arraydim_t *dims; /* relocated dimension struct, if any */ - sp_fdbg_symbol_t *sym; /* pointer to original symbol */ + uint32_t codestart; /**< Relocated code address */ + uint32_t codeend; /**< relocated code end address */ + const char * name; /**< Relocated name */ + sp_debug_arraydim_t *dims; /**< Relocated dimension struct, if any */ + sp_fdbg_symbol_t *sym; /**< Pointer to original symbol */ } sp_debug_symbol_t; /** @@ -209,44 +226,39 @@ typedef struct sp_debug_symbol_s */ typedef int (*SPVM_DEBUGBREAK)(struct sp_context_s *, uint32_t, uint32_t); -#define SPFLAG_PLUGIN_DEBUG (1<<0) /* plugin is in debug mode */ +#define SPFLAG_PLUGIN_DEBUG (1<<0) /**< plugin is in debug mode */ /** - * This is the heart of the VM. It contains all of the runtime - * information about a plugin context. - * Note that user[0..3] can be used for any user based pointers. - * vm[0..3] should not be touched, as it is reserved for the VM. + * @brief This is the heart of the VM. It contains all of the runtime + * information about a plugin context. Note that user[0..3] can be used for any user based pointers. + * However, vm[0..3] should not be touched, as it is reserved for the VM. */ typedef struct sp_context_s { - /* general/parent information */ - void *codebase; /* base of generated code and memory */ - sp_plugin_t *plugin; /* pointer back to parent information */ - SourcePawn::IPluginContext *context; /* pointer to IPluginContext */ - SourcePawn::IVirtualMachine *vmbase; /* pointer to IVirtualMachine */ - void *user[4]; /* user specific pointers */ - void *vm[4]; /* VM specific pointers */ - uint32_t flags; /* compilation flags */ - SPVM_DEBUGBREAK dbreak; /* debug break function */ - /* context runtime information */ - uint8_t *memory; /* data chunk */ - ucell_t mem_size; /* total memory size; */ - cell_t data_size; /* data chunk size, always starts at 0 */ - cell_t heap_base; /* where the heap starts */ - /* execution specific data */ - cell_t hp; /* heap pointer */ - cell_t sp; /* stack pointer */ - cell_t frm; /* frame pointer */ - uint32_t pushcount; /* push count */ - int32_t n_err; /* error code set by a native */ - uint32_t n_idx; /* current native index being executed */ - /* context rebased database */ - sp_public_t *publics; /* public functions table */ - sp_pubvar_t *pubvars; /* public variables table */ - sp_native_t *natives; /* natives table */ - sp_debug_file_t *files; /* files */ - sp_debug_line_t *lines; /* lines */ - sp_debug_symbol_t *symbols; /* symbols */ + void *codebase; /**< Base of generated code and memory */ + sp_plugin_t *plugin; /**< Pointer back to parent information */ + SourcePawn::IPluginContext *context; /**< Pointer to IPluginContext */ + SourcePawn::IVirtualMachine *vmbase; /**< Pointer to IVirtualMachine */ + void *user[4]; /**< User specific pointers */ + void *vm[4]; /**< VM specific pointers */ + uint32_t flags; /**< Compilation flags */ + SPVM_DEBUGBREAK dbreak; /**< Debug break function */ + uint8_t *memory; /**< Data chunk */ + ucell_t mem_size; /**< Total memory size; */ + cell_t data_size; /**< Data chunk size, always starts at 0 */ + cell_t heap_base; /**< Where the heap starts */ + cell_t hp; /**< Heap pointer */ + cell_t sp; /**< Stack pointer */ + cell_t frm; /**< Frame pointer */ + uint32_t pushcount; /**< Push count */ + int32_t n_err; /**< Error code set by a native */ + uint32_t n_idx; /**< Current native index being executed */ + sp_public_t *publics; /**< Public functions table */ + sp_pubvar_t *pubvars; /**< Public variables table */ + sp_native_t *natives; /**< Natives table */ + sp_debug_file_t *files; /**< Files */ + sp_debug_line_t *lines; /**< Lines */ + sp_debug_symbol_t *symbols; /**< Symbols */ } sp_context_t; #endif //_INCLUDE_SOURCEPAWN_VM_TYPES_H