/addons/sourcemod/scripting/include/logging.inc

  1/**
  2 * vim: set ts=4 :
  3 * =============================================================================
  4 * SourceMod (C)2004-2008 AlliedModders LLC.  All rights reserved.
  5 * =============================================================================
  6 *
  7 * This file is part of the SourceMod/SourcePawn SDK.
  8 *
  9 * This program is free software; you can redistribute it and/or modify it under
 10 * the terms of the GNU General Public License, version 3.0, as published by the
 11 * Free Software Foundation.
 12 * 
 13 * This program is distributed in the hope that it will be useful, but WITHOUT
 14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 15 * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 16 * details.
 17 *
 18 * You should have received a copy of the GNU General Public License along with
 19 * this program.  If not, see <http://www.gnu.org/licenses/>.
 20 *
 21 * As a special exception, AlliedModders LLC gives you permission to link the
 22 * code of this program (as well as its derivative works) to "Half-Life 2," the
 23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
 24 * by the Valve Corporation.  You must obey the GNU General Public License in
 25 * all respects for all other code used.  Additionally, AlliedModders LLC grants
 26 * this exception to all derivative works.  AlliedModders LLC defines further
 27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
 28 * or <http://www.sourcemod.net/license.php>.
 29 *
 30 * Version: $Id$
 31 */
 32 
 33#if defined _sm_logging_included
 34 #endinput
 35#endif
 36#define _sm_logging_included
 37
 38/**
 39 * Logs a plugin message to the SourceMod logs.  The log message will be 
 40 * prefixed by the plugin's logtag (filename).
 41 *
 42 * @param format		String format.
 43 * @param ...			Format arguments.
 44 * @noreturn
 45 */
 46native LogMessage(const String:format[], any:...);
 47
 48/**
 49 * Logs a message to the SourceMod logs without any plugin logtag.  This is 
 50 * useful for re-routing messages from other plugins, for example, messages 
 51 * from LogAction().
 52 *
 53 * @param format		String format.
 54 * @param ...			Format arguments.
 55 * @noreturn
 56 */
 57native LogMessageEx(const String:format[], any:...);
 58
 59/**
 60 * Logs a message to any file.  The log message will be in the normal 
 61 * SourceMod format, with the plugin logtag prepended.
 62 *
 63 * @param file			File to write the log message in.
 64 * @param format		String format.
 65 * @param ...			Format arguments.
 66 * @noreturn
 67 * @error				File could not be opened/written.
 68 */
 69native LogToFile(const String:file[], const String:format[], any:...);
 70
 71/**
 72 * Same as LogToFile(), except no plugin logtag is prepended.
 73 *
 74 * @param file			File to write the log message in.
 75 * @param format		String format.
 76 * @param ...			Format arguments.
 77 * @noreturn
 78 * @error				File could not be opened/written.
 79 */
 80native LogToFileEx(const String:file[], const String:format[], any:...);
 81
 82/**
 83 * Logs an action from a command or event whereby interception and routing may 
 84 * be important.  This is intended to be a logging version of ShowActivity().
 85 *
 86 * @param client		Client performing the action, 0 for server, or -1 if not 
 87 *						applicable.
 88 * @param target		Client being targetted, or -1 if not applicable.
 89 * @param message		Message format.
 90 * @param ...			Message formatting parameters.
 91 * @noreturn
 92 */
 93native LogAction(client, target, const String:message[], any:...);
 94
 95/**
 96 * Logs a plugin error message to the SourceMod logs.
 97 *
 98 * @param format		String format.
 99 * @param ...			Format arguments.
100 * @noreturn
101 */
102native LogError(const String:format[], any:...);
103
104/**
105 * Called when an action is going to be logged.
106 *
107 * @param source		Handle to the object logging the action, or INVALID_HANDLE 
108 *						if Core is logging the action.
109 * @param ident			Type of object logging the action (plugin, ext, or core).
110 * @param client		Client the action is from; 0 for server, -1 if not applicable.
111 * @param target		Client the action is targetting, or -1 if not applicable.
112 * @param message		Message that is being logged.
113 * @return				Plugin_Continue will cause Core to defaulty log the message.
114 *						Plugin_Handled will stop Core from logging the message.
115 * 						Plugin_Stop is the same as Handled, but prevents any other 
116 *						plugins from handling the message.
117 */
118forward Action:OnLogAction(Handle:source, 
119						   Identity:ident,
120						   client,
121						   target,
122						   const String:message[]);
123
124/**
125 * Called when a game log message is received.
126 *
127 * Any Log*() functions called within this callback will not recursively 
128 * pass through.  That is, they will log directly, bypassing this callback.
129 *
130 * Note that this does not capture log messages from the engine.  It only 
131 * captures log messages being sent from the game/mod itself.
132 *
133 * @param message		Message contents.
134 * @return				Plugin_Handled or Plugin_Stop will prevent the message 
135 * 						from being written to the log file.
136 */
137functag public Action:GameLogHook(const String:message[]);
138
139/**
140 * Adds a game log hook.
141 *
142 * @param hook			Hook function.
143 * @noreturn
144 */
145native AddGameLogHook(GameLogHook:hook);
146
147/**
148 * Removes a game log hook.
149 *
150 * @param hook			Hook function.
151 * @noreturn
152 */
153native RemoveGameLogHook(GameLogHook:hook);