3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
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.
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
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/>.
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>.
33 #if defined _events_included
36 #define _events_included
39 * Event hook modes determining how hooking should be handled
43 EventHookMode_Pre, /**< Hook callback fired before event is fired */
44 EventHookMode_Post, /**< Hook callback fired after event is fired */
45 EventHookMode_PostNoCopy /**< Hook callback fired after event is fired, but event data won't be copied */
49 * Hook function types for events.
54 * Called when a game event is fired.
56 * @param event Handle to event. This could be INVALID_HANDLE if every plugin hooking
57 * this event has set the hook mode EventHookMode_PostNoCopy.
58 * @param name String containing the name of the event.
59 * @param dontBroadcast True if event was not broadcast to clients, false otherwise.
60 * @return Ignored for post hooks. Plugin_Handled will block event if hooked as pre.
62 Action:public(Handle:event, const String:name[], bool:dontBroadcast),
64 * Called when a game event is fired.
66 * @param event Handle to event. This could be INVALID_HANDLE if every plugin hooking
67 * this event has set the hook mode EventHookMode_PostNoCopy.
68 * @param name String containing the name of the event.
69 * @param dontBroadcast True if event was not broadcast to clients, false otherwise.
72 public(Handle:event, const String:name[], bool:dontBroadcast),
76 * Creates a hook for when a game event is fired.
78 * @param name Name of event.
79 * @param callback An EventHook function pointer.
80 * @param mode Optional EventHookMode determining the type of hook.
82 * @error Invalid event name or invalid callback function.
84 native HookEvent(const String:name[], EventHook:callback, EventHookMode:mode=EventHookMode_Post);
87 * Creates a hook for when a game event is fired.
89 * @param name Name of event.
90 * @param callback An EventHook function pointer.
91 * @param mode Optional EventHookMode determining the type of hook.
92 * @return True if event exists and was hooked successfully, false otherwise.
93 * @error Invalid callback function.
95 native bool:HookEventEx(const String:name[], EventHook:callback, EventHookMode:mode=EventHookMode_Post);
98 * Removes a hook for when a game event is fired.
100 * @param name Name of event.
101 * @param callback An EventHook function pointer.
102 * @param mode Optional EventHookMode determining the type of hook.
104 * @error Invalid callback function or no active hook for specified event.
106 native UnhookEvent(const String:name[], EventHook:callback, EventHookMode:mode=EventHookMode_Post);
109 * Creates a game event to be fired later.
111 * The Handle should not be closed via CloseHandle(). It must be closed via
112 * FireEvent() or CancelCreatedEvent().
114 * @param name Name of event.
115 * @param force If set to true, this forces the event to be created even if it's not being hooked.
116 * Note that this will not force it if the event doesn't exist at all.
117 * @return Handle to event. INVALID_HANDLE is returned if the event doesn't exist or isn't
118 being hooked (unless force is true).
120 native Handle:CreateEvent(const String:name[], bool:force=false);
123 * Fires a game event.
125 * This function closes the event Handle after completing.
127 * @param event Handle to the event.
128 * @param dontBroadcast Optional boolean that determines if event should be broadcast to clients.
130 * @error Invalid or corrupt Handle.
132 native FireEvent(Handle:event, bool:dontBroadcast=false);
135 * Cancels a previously created game event that has not been fired.
137 * @param event Handled to the event.
139 * @error Invalid or corrupt Handle.
141 native CancelCreatedEvent(Handle:event);
144 * Returns the boolean value of a game event's key.
146 * @param event Handle to the event.
147 * @param key Name of event key.
148 * @return The boolean value of the specfied event key.
149 * @error Invalid or corrupt Handle.
151 native bool:GetEventBool(Handle:event, const String:key[]);
154 * Sets the boolean value of a game event's key.
156 * @param event Handle to the event.
157 * @param key Name of event key.
158 * @param value New boolean value.
160 * @error Invalid or corrupt Handle.
162 native SetEventBool(Handle:event, const String:key[], bool:value);
165 * Returns the integer value of a game event's key.
167 * @param event Handle to the event.
168 * @param key Name of event key.
169 * @return The integer value of the specfied event key.
170 * @error Invalid or corrupt Handle.
172 native GetEventInt(Handle:event, const String:key[]);
175 * Sets the integer value of a game event's key.
177 * Integer value refers to anything that can be reduced to an integer.
178 * The various size specifiers, such as "byte" and "short" are still
179 * integers, and only refer to how much data will actually be sent
180 * over the network (if applicable).
182 * @param event Handle to the event.
183 * @param key Name of event key.
184 * @param value New integer value.
186 * @error Invalid or corrupt Handle.
188 native SetEventInt(Handle:event, const String:key[], value);
191 * Returns the floating point value of a game event's key.
193 * @param event Handle to the event.
194 * @param key Name of event key.
195 * @return The floating point value of the specfied event key.
196 * @error Invalid or corrupt Handle.
198 native Float:GetEventFloat(Handle:event, const String:key[]);
201 * Sets the floating point value of a game event's key.
203 * @param event Handle to the event.
204 * @param key Name of event key.
205 * @param value New floating point value.
207 * @error Invalid or corrupt Handle.
209 native SetEventFloat(Handle:event, const String:key[], Float:value);
212 * Retrieves the string value of a game event's key.
214 * @param event Handle to the event.
215 * @param key Name of event key.
216 * @param value Buffer to store the value of the specified event key.
217 * @param maxlength Maximum length of string buffer.
219 * @error Invalid or corrupt Handle.
221 native GetEventString(Handle:event, const String:key[], String:value[], maxlength);
224 * Sets the string value of a game event's key.
226 * @param event Handle to the event.
227 * @param key Name of event key.
228 * @param value New string value.
230 * @error Invalid or corrupt Handle.
232 native SetEventString(Handle:event, const String:key[], const String:value[]);
235 * Retrieves the name of a game event.
237 * @param event Handle to the event.
238 * @param value Buffer to store the name of the event.
239 * @param maxlength Maximum length of string buffer.
241 * @error Invalid or corrupt Handle.
243 native GetEventName(Handle:event, String:name[], maxlength);
246 * Sets whether an event's broadcasting will be disabled or not.
248 * This has no effect on events Handles that are not from HookEvent
249 * or HookEventEx callbacks.
251 * @param event Handle to an event from an event hook.
252 * @param dontBroadcast True to disable broadcasting, false otherwise.
254 * @error Invalid Handle.
256 native SetEventBroadcast(Handle:event, bool:dontBroadcast);
