1.1 --- a/plugins/include/sourcemod.inc Fri Mar 28 06:21:34 2008 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,495 +0,0 @@
1.4 -/**
1.5 - * vim: set ts=4 :
1.6 - * =============================================================================
1.7 - * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
1.8 - * =============================================================================
1.9 - *
1.10 - * This file is part of the SourceMod/SourcePawn SDK.
1.11 - *
1.12 - * This program is free software; you can redistribute it and/or modify it under
1.13 - * the terms of the GNU General Public License, version 3.0, as published by the
1.14 - * Free Software Foundation.
1.15 - *
1.16 - * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 - * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 - * details.
1.20 - *
1.21 - * You should have received a copy of the GNU General Public License along with
1.22 - * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 - *
1.24 - * As a special exception, AlliedModders LLC gives you permission to link the
1.25 - * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 - * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 - * by the Valve Corporation. You must obey the GNU General Public License in
1.28 - * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 - * this exception to all derivative works. AlliedModders LLC defines further
1.30 - * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 - * or <http://www.sourcemod.net/license.php>.
1.32 - *
1.33 - * Version: $Id$
1.34 - */
1.35 -
1.36 -#if defined _sourcemod_included
1.37 - #endinput
1.38 -#endif
1.39 -#define _sourcemod_included
1.40 -
1.41 -/**
1.42 - * Plugin public information.
1.43 - */
1.44 -struct Plugin
1.45 -{
1.46 - const String:name[], /**< Plugin Name */
1.47 - const String:description[], /**< Plugin Description */
1.48 - const String:author[], /**< Plugin Author */
1.49 - const String:version[], /**< Plugin Version */
1.50 - const String:url[], /**< Plugin URL */
1.51 -};
1.52 -
1.53 -#include <core>
1.54 -#include <float>
1.55 -#include <vector>
1.56 -#include <string>
1.57 -#include <handles>
1.58 -#include <functions>
1.59 -#include <files>
1.60 -#include <timers>
1.61 -#include <admin>
1.62 -#include <dbi>
1.63 -#include <lang>
1.64 -#include <sorting>
1.65 -#include <textparse>
1.66 -#include <clients>
1.67 -#include <console>
1.68 -#include <events>
1.69 -#include <bitbuffer>
1.70 -#include <usermessages>
1.71 -#include <keyvalues>
1.72 -#include <menus>
1.73 -#include <halflife>
1.74 -#include <adt>
1.75 -#include <banning>
1.76 -#include <commandfilters>
1.77 -
1.78 -/**
1.79 - * Declare this as a struct in your plugin to expose its information.
1.80 - * Example:
1.81 - *
1.82 - * public Plugin:myinfo =
1.83 - * {
1.84 - * name = "My Plugin",
1.85 - * //etc
1.86 - * };
1.87 - */
1.88 -public Plugin:myinfo;
1.89 -
1.90 -/**
1.91 - * Called when the plugin is fully initialized and all known external references are resolved.
1.92 - * This is called even if the plugin type is "private."
1.93 - * @note Errors in this function will cause the plugin to stop running.
1.94 - *
1.95 - * @noreturn
1.96 - */
1.97 -forward OnPluginStart();
1.98 -
1.99 -/**
1.100 - * Called before OnPluginStart, in case the plugin wants to check for load failure.
1.101 - * This is called even if the plugin type is "private." Any natives from modules are
1.102 - * not available at this point. Thus, this forward should only be used for explicit
1.103 - * pre-emptive things, such as adding dynamic natives, or setting certain types of load filters.
1.104 - *
1.105 - * @note It is not safe to call externally resolved natives until OnPluginStart().
1.106 - * @note Any sort of RTE in this function will cause the plugin to fail loading.
1.107 - *
1.108 - * @param myself Handle to the plugin.
1.109 - * @param late Whether or not the plugin was loaded "late" (after map load).
1.110 - * @param error Error message buffer in case load failed.
1.111 - * @param err_max Maximum number of characters for error message buffer.
1.112 - * @return True if load success, false otherwise.
1.113 - */
1.114 -forward bool:AskPluginLoad(Handle:myself, bool:late, String:error[], err_max);
1.115 -
1.116 -/**
1.117 - * Called when the plugin is about to be unloaded.
1.118 - *
1.119 - * @noreturn
1.120 - */
1.121 -forward OnPluginEnd();
1.122 -
1.123 -/**
1.124 - * Called when the plugin's pause status is changing.
1.125 - *
1.126 - * @param pause True if the plugin is being paused, false otherwise.
1.127 - * @noreturn
1.128 - */
1.129 -forward OnPluginPauseChange(bool:pause);
1.130 -
1.131 -/**
1.132 - * Called before every server frame. Note that you should avoid
1.133 - * doing expensive computations here, and you should declare large
1.134 - * local arrays using 'decl' instead of 'new'.
1.135 - */
1.136 -forward OnGameFrame();
1.137 -
1.138 -/**
1.139 - * Called when the map is loaded.
1.140 - *
1.141 - * @note This used to be OnServerLoad(), which is now deprecated.
1.142 - * Plugins still using the old forward will work.
1.143 - */
1.144 -forward OnMapStart();
1.145 -
1.146 -/**
1.147 - * Called right before a map ends.
1.148 - */
1.149 -forward OnMapEnd();
1.150 -
1.151 -/**
1.152 - * Called when the map has loaded, servercfgfile (server.cfg) has been
1.153 - * executed, and all plugin configs are done executing. This is the best
1.154 - * place to inialize plugin functions which are based on cvar data.
1.155 - *
1.156 - * @note This will always be called once and only once per map. It will be
1.157 - * called after OnMapStart().
1.158 - *
1.159 - * @noreturn
1.160 - */
1.161 -forward OnConfigsExecuted();
1.162 -
1.163 -/**
1.164 - * @deprecated Use OnConfigsExecuted() instead.
1.165 - */
1.166 -#pragma deprecated Use OnConfigsExecuted() instead
1.167 -forward OnServerCfg();
1.168 -
1.169 -/**
1.170 - * Called after all plugins have been loaded. This is called once for
1.171 - * every plugin. If a plugin late loads, it will be called immediately
1.172 - * after OnPluginStart().
1.173 - */
1.174 -forward OnAllPluginsLoaded();
1.175 -
1.176 -/**
1.177 - * Called when an action is going to be logged.
1.178 - *
1.179 - * @param source Handle to the object logging the action, or INVALID_HANDLE
1.180 - * if Core is logging the action.
1.181 - * @param ident Type of object logging the action (plugin, ext, or core).
1.182 - * @param client Client the action is from; 0 for server, -1 if not applicable.
1.183 - * @param target Client the action is targetting, or -1 if not applicable.
1.184 - * @param message Message that is being logged.
1.185 - * @return Plugin_Continue will cause Core to defaulty log the message.
1.186 - * Plugin_Handled will stop Core from logging the message.
1.187 - * Plugin_Stop is the same as Handled, but prevents any other
1.188 - * plugins from handling the message.
1.189 - */
1.190 -forward Action:OnLogAction(Handle:source,
1.191 - Identity:ident,
1.192 - client,
1.193 - target,
1.194 - const String:message[]);
1.195 -
1.196 -/**
1.197 - * Returns the calling plugin's Handle.
1.198 - *
1.199 - * @return Handle of the calling plugin.
1.200 - */
1.201 -native Handle:GetMyHandle();
1.202 -
1.203 -/**
1.204 - * Returns an iterator that can be used to search through plugins.
1.205 - *
1.206 - * @return Handle to iterate with. Must be closed via
1.207 - * CloseHandle().
1.208 - * @error Invalid Handle.
1.209 - */
1.210 -native Handle:GetPluginIterator();
1.211 -
1.212 -/**
1.213 - * Returns whether there are more plugins available in the iterator.
1.214 - *
1.215 - * @param iter Handle to the plugin iterator.
1.216 - * @return True on more plugins, false otherwise.
1.217 - * @error Invalid Handle.
1.218 - */
1.219 -native bool:MorePlugins(Handle:iter);
1.220 -
1.221 -/**
1.222 - * Returns the current plugin in the iterator and advances the iterator.
1.223 - *
1.224 - * @param iter Handle to the plugin iterator.
1.225 - * @return Current plugin the iterator is at, before
1.226 - * the iterator is advanced.
1.227 - * @error Invalid Handle.
1.228 - */
1.229 -native Handle:ReadPlugin(Handle:iter);
1.230 -
1.231 -/**
1.232 - * Returns a plugin's status.
1.233 - *
1.234 - * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
1.235 - * @return Status code for the plugin.
1.236 - * @error Invalid Handle.
1.237 - */
1.238 -native PluginStatus:GetPluginStatus(Handle:plugin);
1.239 -
1.240 -/**
1.241 - * Retrieves a plugin's file name relative to the plugins folder.
1.242 - *
1.243 - * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
1.244 - * @param buffer Buffer to the store the file name.
1.245 - * @param maxlength Maximum length of the name buffer.
1.246 - * @noreturn
1.247 - * @error Invalid Handle.
1.248 - */
1.249 -native GetPluginFilename(Handle:plugin, String:buffer[], maxlength);
1.250 -
1.251 -/**
1.252 - * Retrieves whether or not a plugin is being debugged.
1.253 - *
1.254 - * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
1.255 - * @return True if being debugged, false otherwise.
1.256 - * @error Invalid Handle.
1.257 - */
1.258 -native bool:IsPluginDebugging(Handle:hndl);
1.259 -
1.260 -/**
1.261 - * Retrieves a plugin's public info.
1.262 - *
1.263 - * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
1.264 - * @param info Plugin info property to retrieve.
1.265 - * @param buffer Buffer to store info in.
1.266 - * @param maxlength Maximum length of buffer.
1.267 - * @return True on success, false if property is not available.
1.268 - * @error Invalid Handle.
1.269 - */
1.270 -native bool:GetPluginInfo(Handle:plugin, PluginInfo:info, String:buffer[], maxlength);
1.271 -
1.272 -/**
1.273 - * Causes the plugin to enter a failed state. An error will be thrown and
1.274 - * the plugin will be paused until it is unloaded or reloaded.
1.275 - *
1.276 - * @param string Message to print.
1.277 - * @noreturn
1.278 - * @error Always throws SP_ERROR_ABORT.
1.279 - */
1.280 -native SetFailState(const String:string[]);
1.281 -
1.282 -/**
1.283 - * Aborts the current callback and throws an error. This function
1.284 - * does not return in that no code is executed following it.
1.285 - *
1.286 - * @param format String format.
1.287 - * @param ... Format arguments.
1.288 - * @noreturn
1.289 - * @error Always!
1.290 - */
1.291 -native ThrowError(const String:fmt[], any:...);
1.292 -
1.293 -/**
1.294 - * Logs a plugin message to the SourceMod logs. The log message will be
1.295 - * prefixed by the plugin's logtag (filename).
1.296 - *
1.297 - * @param format String format.
1.298 - * @param ... Format arguments.
1.299 - * @noreturn
1.300 - */
1.301 -native LogMessage(const String:format[], any:...);
1.302 -
1.303 -/**
1.304 - * Logs a message to the SourceMod logs without any plugin logtag. This is
1.305 - * useful for re-routing messages from other plugins, for example, messages
1.306 - * from LogAction().
1.307 - *
1.308 - * @param format String format.
1.309 - * @param ... Format arguments.
1.310 - * @noreturn
1.311 - */
1.312 -native LogMessageEx(const String:format[], any:...);
1.313 -
1.314 -/**
1.315 - * Logs a message to any file. The log message will be in the normal
1.316 - * SourceMod format, with the plugin logtag prepended.
1.317 - *
1.318 - * @param file File to write the log message in.
1.319 - * @param format String format.
1.320 - * @param ... Format arguments.
1.321 - * @noreturn
1.322 - * @error File could not be opened/written.
1.323 - */
1.324 -native LogToFile(const String:file[], const String:format[], any:...);
1.325 -
1.326 -/**
1.327 - * Same as LogToFile(), except no plugin logtag is prepended.
1.328 - *
1.329 - * @param file File to write the log message in.
1.330 - * @param format String format.
1.331 - * @param ... Format arguments.
1.332 - * @noreturn
1.333 - * @error File could not be opened/written.
1.334 - */
1.335 -native LogToFileEx(const String:file[], const String:format[], any:...);
1.336 -
1.337 -/**
1.338 - * Logs an action from a command or event whereby interception and routing may
1.339 - * be important. This is intended to be a logging version of ShowActivity().
1.340 - *
1.341 - * @param client Client performing the action, 0 for server, or -1 if not
1.342 - * applicable.
1.343 - * @param target Client being targetted, or -1 if not applicable.
1.344 - * @param message Message format.
1.345 - * @param ... Message formatting parameters.
1.346 - * @noreturn
1.347 - */
1.348 -native LogAction(client, target, const String:message[], any:...);
1.349 -
1.350 -/**
1.351 - * Logs a plugin error message to the SourceMod logs.
1.352 - *
1.353 - * @param format String format.
1.354 - * @param ... Format arguments.
1.355 - * @noreturn
1.356 - */
1.357 -native LogError(const String:format[], any:...);
1.358 -
1.359 -/**
1.360 - * Gets the system time as a unix timestamp.
1.361 - *
1.362 - * @param bigStamp Optional array to store the 64bit timestamp in.
1.363 - * @return 32bit timestamp (number of seconds since unix epoch).
1.364 - */
1.365 -native GetTime(bigStamp[2]={0,0});
1.366 -
1.367 -/**
1.368 - * Produces a date and/or time string value for a timestamp.
1.369 - *
1.370 - * See this URL for valid parameters:
1.371 - * http://opengroup.org/onlinepubs/007908799/xsh/strftime.html
1.372 - *
1.373 - * @param buffer Destination string buffer.
1.374 - * @param maxlength Maximum length of output string buffer.
1.375 - * @param format Formatting rules (passing NULL_STRING will use the rules defined in sm_datetime_format).
1.376 - * @param stamp Optional time stamp.
1.377 - * @noreturn
1.378 - * @error Buffer too small or invalid time format.
1.379 - */
1.380 -native FormatTime(String:buffer[], maxlength, const String:format[], stamp=-1);
1.381 -
1.382 -/**
1.383 - * Loads a game config file.
1.384 - *
1.385 - * @param file File to load. The path must be relative to the 'gamedata' folder under the config folder
1.386 - * and the extension should be omitted.
1.387 - * @return A handle to the game config file or INVALID_HANDLE in failure.
1.388 - */
1.389 -native Handle:LoadGameConfigFile(const String:file[]);
1.390 -
1.391 -/**
1.392 - * Returns an offset value.
1.393 - *
1.394 - * @param gc Game config handle.
1.395 - * @param key Key to retrieve from the offset section.
1.396 - * @return An offset, or -1 on failure.
1.397 - */
1.398 -native GameConfGetOffset(Handle:gc, const String:key[]);
1.399 -
1.400 -/**
1.401 - * Gets the value of a key from the "Keys" section.
1.402 - *
1.403 - * @param gc Game config handle.
1.404 - * @param key Key to retrieve from the Keys section.
1.405 - * @param buffer Destination string buffer.
1.406 - * @param maxlen Maximum length of output string buffer.
1.407 - * @return True if key existed, false otherwise.
1.408 - */
1.409 -native bool:GameConfGetKeyValue(Handle:gc, const String:key[], String:buffer[], maxlen);
1.410 -
1.411 -/**
1.412 - * Returns the operating system's "tick count," which is a number of
1.413 - * milliseconds since the operating system loaded. This can be used
1.414 - * for basic benchmarks.
1.415 - *
1.416 - * @return Tick count in milliseconds.
1.417 - */
1.418 -native GetSysTickCount();
1.419 -
1.420 -/**
1.421 - * Specifies that the given config file should be executed after plugin load.
1.422 - * OnConfigsExecuted() will not be called until the config file has executed,
1.423 - * but it will be called if the execution fails.
1.424 - *
1.425 - * @param autoCreate If true, and the config file does not exist, such a config
1.426 - * file will be automatically created and populated with
1.427 - * information from the plugin's registered cvars.
1.428 - * @param name Name of the config file, excluding the .cfg extension.
1.429 - * If empty, <plugin.filename.cfg> is assumed.
1.430 - * @param folder Folder under cfg/ to use. By default this is "sourcemod."
1.431 - * @noreturn
1.432 - */
1.433 -native AutoExecConfig(bool:autoCreate=true, const String:name[]="", const String:folder[]="sourcemod");
1.434 -
1.435 -/**
1.436 - * Sets a native as optional, such that if it is unloaded, removed,
1.437 - * or otherwise non-existent, the plugin will still work. Calling
1.438 - * removed natives results in a run-time error.
1.439 - *
1.440 - * @param name Native name.
1.441 - * @noreturn
1.442 - */
1.443 -native MarkNativeAsOptional(const String:name[]);
1.444 -
1.445 -/**
1.446 - * Registers a library name for identifying as a dependency to
1.447 - * other plugins.
1.448 - *
1.449 - * @param name Library name.
1.450 - * @noreturn
1.451 - */
1.452 -native RegPluginLibrary(const String:name[]);
1.453 -
1.454 -/**
1.455 - * Returns whether a library exists. This function should be considered
1.456 - * expensive; it should only be called on plugin to determine availability
1.457 - * of resources. Use OnLibraryAdded()/OnLibraryRemoved() to detect changes
1.458 - * in optional resources.
1.459 - *
1.460 - * @param name Library name of a plugin or extension.
1.461 - * @return True if exists, false otherwise.
1.462 - */
1.463 -native bool:LibraryExists(const String:name[]);
1.464 -
1.465 -/**
1.466 - * Returns the status of an extension, by filename.
1.467 - *
1.468 - * @param name Extension name (like "sdktools.ext").
1.469 - * @param error Optional error message buffer.
1.470 - * @param maxlength Length of optional error message buffer.
1.471 - * @return -2 if the extension was not found.
1.472 - * -1 if the extension was found but failed to load.
1.473 - * 0 if the extension loaded but reported an error.
1.474 - * 1 if the extension is running without error.
1.475 - */
1.476 -native GetExtensionFileStatus(const String:name[], String:error[]="", maxlength=0);
1.477 -
1.478 -/**
1.479 - * Called after a library is added that the current plugin references
1.480 - * optionally. A library is either a plugin name or extension name, as
1.481 - * exposed via its include file.
1.482 - *
1.483 - * @param name Library name.
1.484 - */
1.485 -forward OnLibraryAdded(const String:name[]);
1.486 -
1.487 -/**
1.488 - * Called right before a library is removed that the current plugin references
1.489 - * optionally. A library is either a plugin name or extension name, as
1.490 - * exposed via its include file.
1.491 - *
1.492 - * @param name Library name.
1.493 - */
1.494 -forward OnLibraryRemoved(const String:name[]);
1.495 -
1.496 -#include <helpers>
1.497 -#include <entity>
1.498 -
