/addons/sourcemod/scripting/include/logging.inc
Pascal | 153 lines | 151 code | 2 blank | 0 comment | 2 complexity | 938829efcd841a7e026b5f3b239d0b0f MD5 | raw file
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);