dvander@429: /** ds@475: * vim: set ts=4 : dvander@429: * =============================================================== dvander@429: * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved. dvander@429: * =============================================================== dvander@429: * dvander@429: * This file is part of the SourceMod/SourcePawn SDK. This file may only be used dvander@429: * or modified under the Terms and Conditions of its License Agreement, which is found dvander@429: * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins dvander@429: * may change at any time. To view the latest information, see: dvander@429: * http://www.sourcemod.net/license.php dvander@429: * faluco@506: * Version: $Id$ dvander@429: */ dvander@429: dvander@429: #if defined _sourcemod_included dvander@429: #endinput dvander@429: #endif dvander@429: #define _sourcemod_included dvander@429: dvander@619: /** dvander@619: * Plugin public information. dvander@619: */ dvander@429: struct Plugin dvander@429: { dvander@619: const String:name[], /**< Plugin Name */ dvander@619: const String:description[], /**< Plugin Description */ dvander@619: const String:author[], /**< Plugin Author */ dvander@619: const String:version[], /**< Plugin Version */ dvander@619: const String:url[], /**< Plugin URL */ dvander@429: }; dvander@429: dvander@429: #include dvander@429: #include dvander@1069: #include ds@873: #include dvander@429: #include dvander@601: #include ds@873: #include dvander@643: #include ds@873: #include dvander@868: #include ds@913: #include ds@873: #include ds@913: #include ds@873: #include ds@873: #include ds@873: #include ds@873: #include ds@873: #include ds@913: #include ds@873: #include ds@898: #include dvander@1156: #include ds@898: dvander@429: /** dvander@429: * Declare this as a struct in your plugin to expose its information. dvander@429: * Example: dvander@429: * dvander@429: * public Plugin:myinfo = dvander@429: * { dvander@429: * name = "My Plugin", dvander@429: * //etc dvander@429: * }; dvander@429: */ dvander@429: public Plugin:myinfo; dvander@429: dvander@429: /** dvander@429: * Called when the plugin is fully initialized and all known external references are resolved. dvander@429: * This is called even if the plugin type is "private." dvander@619: * @note Errors in this function will cause the plugin to stop running. dvander@429: * dvander@429: * @noreturn dvander@429: */ dvander@536: forward OnPluginStart(); dvander@429: dvander@429: /** dvander@979: * Called before OnPluginStart, in case the plugin wants to check for load failure. dvander@429: * This is called even if the plugin type is "private." Any natives from modules are dvander@429: * not available at this point. Thus, this forward should only be used for explicit dvander@429: * pre-emptive things, such as adding dynamic natives, or setting certain types of load filters. dvander@429: * dvander@619: * @note It is not safe to call externally resolved natives until OnPluginStart(). dvander@619: * @note Any sort of RTE in this function will cause the plugin to fail loading. dvander@429: * dvander@429: * @param myself Handle to the plugin. dvander@429: * @param late Whether or not the plugin was loaded "late" (after map load). dvander@429: * @param error Error message buffer in case load failed. dvander@429: * @param err_max Maximum number of characters for error message buffer. dvander@429: * @return True if load success, false otherwise. dvander@429: */ dvander@429: forward bool:AskPluginLoad(Handle:myself, bool:late, String:error[], err_max); dvander@429: dvander@429: /** dvander@429: * Called when the plugin is about to be unloaded. dvander@429: * dvander@429: * @noreturn dvander@429: */ dvander@429: forward OnPluginEnd(); dvander@429: dvander@429: /** dvander@429: * Called when the plugin's pause status is changing. dvander@429: * ds@475: * @param pause True if the plugin is being paused, false otherwise. dvander@429: * @noreturn dvander@429: */ dvander@429: forward OnPluginPauseChange(bool:pause); dvander@429: dvander@429: /** dvander@531: * Called before every server frame. Note that you should avoid dvander@531: * doing expensive computations here, and you should declare large dvander@531: * local arrays using 'decl' instead of 'new'. dvander@531: */ dvander@531: forward OnGameFrame(); dvander@531: dvander@531: /** dvander@717: * Called when the map is loaded. dvander@717: * dvander@723: * @note This used to be OnServerLoad(), which is now deprecated. dvander@717: * Plugins still using the old forward will work. dvander@643: */ dvander@717: forward OnMapStart(); dvander@643: dvander@643: /** dvander@718: * Called right before a map ends. dvander@718: */ dvander@718: forward OnMapEnd(); dvander@718: dvander@718: /** dvander@978: * Called when the map has loaded, servercfgfile (server.cfg) has been dvander@978: * executed, and all plugin configs are done executing. This is the best dvander@978: * place to inialize plugin functions which are based on cvar data. dvander@723: * dvander@978: * @note This will always be called once and only once per map. It will be dvander@978: * called after OnMapStart(). dvander@978: * dvander@978: * @noreturn dvander@723: */ dvander@978: forward OnConfigsExecuted(); dvander@723: dvander@723: /** dvander@979: * @deprecated Use OnConfigsExecuted() instead. dvander@979: */ dvander@979: forward OnServerCfg(); dvander@979: dvander@979: /** faluco@1221: * Called after all plugins have been loaded. faluco@1221: */ faluco@1221: forward OnAllPluginsLoaded(); faluco@1221: faluco@1221: /** dvander@536: * Returns the calling plugin's Handle. dvander@536: * dvander@536: * @return Handle of the calling plugin. dvander@536: */ dvander@536: native Handle:GetMyHandle(); dvander@536: dvander@618: /** dvander@618: * Returns an iterator that can be used to search through plugins. dvander@618: * dvander@618: * @return Handle to iterate with. Must be closed via dvander@618: * CloseHandle(). dvander@618: * @error Invalid Handle. dvander@618: */ dvander@618: native Handle:GetPluginIterator(); dvander@618: dvander@618: /** dvander@618: * Returns whether there are more plugins available in the iterator. dvander@618: * dvander@618: * @param iter Handle to the plugin iterator. dvander@618: * @return True on more plugins, false otherwise. dvander@618: * @error Invalid Handle. dvander@618: */ dvander@618: native bool:MorePlugins(Handle:iter); dvander@618: dvander@618: /** dvander@618: * Returns the current plugin in the iterator and advances the iterator. dvander@618: * dvander@618: * @param iter Handle to the plugin iterator. dvander@618: * @return Current plugin the iterator is at, before dvander@618: * the iterator is advanced. dvander@618: * @error Invalid Handle. dvander@618: */ dvander@618: native Handle:ReadPlugin(Handle:iter); dvander@618: dvander@618: /** dvander@618: * Returns a plugin's status. dvander@618: * dvander@618: * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin). dvander@618: * @return Status code for the plugin. dvander@618: * @error Invalid Handle. dvander@618: */ dvander@618: native PluginStatus:GetPluginStatus(Handle:plugin); dvander@618: dvander@618: /** dvander@618: * Retrieves a plugin's file name relative to the plugins folder. dvander@618: * dvander@618: * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin). dvander@618: * @param buffer Buffer to the store the file name. dvander@618: * @param maxlength Maximum length of the name buffer. dvander@618: * @noreturn dvander@618: * @error Invalid Handle. dvander@618: */ dvander@618: native GetPluginFilename(Handle:plugin, String:buffer[], maxlength); dvander@618: dvander@618: /** dvander@618: * Retrieves whether or not a plugin is being debugged. dvander@618: * dvander@618: * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin). dvander@618: * @return True if being debugged, false otherwise. dvander@618: * @error Invalid Handle. dvander@618: */ dvander@618: native bool:IsPluginDebugging(Handle:hndl); dvander@618: dvander@618: /** dvander@618: * Retrieves a plugin's public info. dvander@618: * dvander@618: * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin). dvander@618: * @param info Plugin info property to retrieve. dvander@618: * @param buffer Buffer to store info in. dvander@618: * @param maxlength Maximum length of buffer. dvander@618: * @return True on success, false if property is not available. dvander@618: * @error Invalid Handle. dvander@618: */ dvander@618: native bool:GetPluginInfo(Handle:plugin, PluginInfo:info, String:buffer[], maxlength); dvander@560: dvander@560: /** dvander@837: * Causes the plugin to enter a failed state. An error will be thrown and dvander@837: * the plugin will be paused until it is unloaded or reloaded. dvander@837: * dvander@837: * @param string Message to print. dvander@837: * @noreturn dvander@838: * @error Always throws SP_ERROR_ABORT. dvander@837: */ dvander@837: native SetFailState(const String:string[]); dvander@837: dvander@837: /** dvander@560: * Aborts the current callback and throws an error. This function dvander@560: * does not return in that no code is executed following it. dvander@560: * dvander@560: * @param format String format. dvander@560: * @param ... Format arguments. dvander@560: * @noreturn dvander@560: * @error Always! dvander@560: */ ds@634: native ThrowError(const String:fmt[], any:...); dvander@560: dvander@536: /** dvander@429: * Logs a plugin message to the SourceMod logs. dvander@429: * ds@475: * @param format String format. ds@475: * @param ... Format arguments. dvander@429: * @noreturn dvander@429: */ ds@634: native LogMessage(const String:format[], any:...); dvander@429: dvander@429: /** dvander@429: * Logs a plugin error message to the SourceMod logs. dvander@429: * ds@475: * @param format String format. ds@475: * @param ... Format arguments. dvander@429: * @noreturn dvander@429: */ ds@634: native LogError(const String:format[], any:...); dvander@460: dvander@530: /** dvander@595: * Gets the system time as a unix timestamp. dvander@595: * dvander@595: * @param bigStamp Optional array to store the 64bit timestamp in. dvander@595: * @return 32bit timestamp (number of seconds since unix epoch). dvander@595: */ dvander@595: native GetTime(bigStamp[2]={0,0}); dvander@595: dvander@595: /** faluco@1037: * Format date and time. faluco@1037: * faluco@1037: * @param buffer Destination string buffer. faluco@1037: * @param maxlength Maximum length of output string buffer. faluco@1037: * @param format Formatting rules. faluco@1041: * @param stamp Optional time stamp. faluco@1037: * @noreturn faluco@1037: */ faluco@1041: native FormatTime(String:buffer[], maxlength, const String:format[], stamp=-1); faluco@1037: faluco@1037: /** faluco@703: * Loads a game config file. faluco@703: * faluco@703: * @param file File to load. The path must be relative to the 'gamedata' folder under the config folder faluco@703: * and the extension should be omitted. faluco@703: * @return A handle to the game config file or INVALID_HANDLE in failure. faluco@703: */ faluco@703: native Handle:LoadGameConfigFile(const String:file[]); faluco@703: faluco@703: /** faluco@703: * Returns an offset value. faluco@703: * faluco@703: * @param gc Game config handle. faluco@703: * @param key Key to retrieve from the offset section. faluco@703: * @return An offset, or -1 on failure. faluco@703: */ faluco@703: native GameConfGetOffset(Handle:gc, const String:key[]); faluco@703: faluco@703: /** faluco@703: * Gets the value of a key from the "Keys" section. faluco@703: * faluco@703: * @param gc Game config handle. faluco@703: * @param key Key to retrieve from the Keys section. faluco@703: * @param buffer Destination string buffer. faluco@703: * @param maxlen Maximum length of output string buffer. dvander@886: * @return True if key existed, false otherwise. faluco@703: */ faluco@703: native bool:GameConfGetKeyValue(Handle:gc, const String:key[], String:buffer[], maxlen); faluco@703: dvander@886: /** dvander@886: * Returns the operating system's "tick count," which is a number of dvander@886: * milliseconds since the operating system loaded. This can be used dvander@886: * for basic benchmarks. dvander@886: * dvander@886: * @return Tick count in milliseconds. dvander@886: */ dvander@886: native GetSysTickCount(); dvander@886: dvander@978: /** dvander@978: * Specifies that the given config file should be executed after plugin load. dvander@978: * OnConfigsExecuted() will not be called until the config file has executed, dvander@978: * but it will be called if the execution fails. dvander@978: * dvander@978: * @param autoCreate If true, and the config file does not exist, such a config dvander@978: * file will be automatically created and populated with dvander@978: * information from the plugin's registered cvars. dvander@978: * @param name Name of the config file, excluding the .cfg extension. dvander@978: * If empty, is assumed. dvander@978: * @param folder Folder under cfg/ to use. By default this is "sourcemod." dvander@978: * @noreturn dvander@978: */ dvander@978: native AutoExecConfig(bool:autoCreate=true, const String:name[]="", const String:folder[]="sourcemod"); dvander@978: faluco@1112: /** faluco@1112: * Sets a native as optional, such that if it is unloaded, removed, faluco@1112: * or otherwise non-existent, the plugin will still work. Calling faluco@1112: * removed natives results in a run-time error. faluco@1112: * faluco@1112: * @param name Native name. faluco@1112: * @noreturn faluco@1112: */ faluco@1112: native MarkNativeAsOptional(const String:name[]); faluco@1112: faluco@1112: /** faluco@1112: * Registers a library name for identifying as a dependency to faluco@1112: * other plugins. faluco@1112: * faluco@1112: * @param name Library name. faluco@1112: * @noreturn faluco@1112: */ faluco@1112: native RegPluginLibrary(const String:name[]); faluco@1112: dvander@1124: /** dvander@1124: * Returns whether a library exists. dvander@1124: * dvander@1124: * @param name Library name. dvander@1124: * @return True if exists, false otherwise. dvander@1124: */ dvander@1124: native bool:LibraryExists(const String:name[]); dvander@1124: dvander@1124: /** dvander@1124: * Called after a library (plugin) is added that the dvander@1124: * current plugin references optionally. dvander@1124: * dvander@1124: * @param name Library name. dvander@1124: */ dvander@1124: forward OnLibraryAdded(const String:name[]); dvander@1124: dvander@1124: /** dvander@1124: * Called right before a library (plugin) is removed that the dvander@1124: * current plugin references optionally. dvander@1124: * dvander@1124: * @param name Library name. dvander@1124: */ dvander@1124: forward OnLibraryRemoved(const String:name[]); dvander@1124: dvander@460: #include dvander@560: #include