ds@576: /**
ds@576: * vim: set ts=4 :
ds@1330: * =============================================================================
ds@1947: * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
ds@1330: * =============================================================================
ds@1330: *
ds@1330: * This file is part of the SourceMod/SourcePawn SDK.
ds@576: *
ds@1330: * This program is free software; you can redistribute it and/or modify it under
ds@1330: * the terms of the GNU General Public License, version 3.0, as published by the
ds@1330: * Free Software Foundation.
ds@1330: *
ds@1330: * This program is distributed in the hope that it will be useful, but WITHOUT
ds@1330: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1330: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
ds@1330: * details.
ds@1330: *
ds@1330: * You should have received a copy of the GNU General Public License along with
ds@1330: * this program. If not, see .
ds@1330: *
ds@1330: * As a special exception, AlliedModders LLC gives you permission to link the
ds@1330: * code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1330: * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1330: * by the Valve Corporation. You must obey the GNU General Public License in
ds@1330: * all respects for all other code used. Additionally, AlliedModders LLC grants
ds@1330: * this exception to all derivative works. AlliedModders LLC defines further
ds@1330: * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1330: * or .
ds@576: *
ds@576: * Version: $Id$
ds@576: */
ds@576:
ds@576: #if defined _events_included
ds@576: #endinput
ds@576: #endif
ds@576: #define _events_included
ds@576:
ds@576: /**
ds@576: * Event hook modes determining how hooking should be handled
ds@576: */
ds@576: enum EventHookMode
ds@576: {
ds@576: EventHookMode_Pre, /**< Hook callback fired before event is fired */
ds@576: EventHookMode_Post, /**< Hook callback fired after event is fired */
ds@576: EventHookMode_PostNoCopy /**< Hook callback fired after event is fired, but event data won't be copied */
ds@576: };
ds@576:
dvander@619: /**
dvander@619: * Hook function types for events.
dvander@619: */
ds@576: funcenum EventHook
ds@576: {
ds@576: /**
ds@576: * Called when a game event is fired.
ds@576: *
ds@576: * @param event Handle to event. This could be INVALID_HANDLE if every plugin hooking
ds@576: * this event has set the hook mode EventHookMode_PostNoCopy.
ds@576: * @param name String containing the name of the event.
ds@576: * @param dontBroadcast True if event was not broadcast to clients, false otherwise.
ds@576: * @return Ignored for post hooks. Plugin_Handled will block event if hooked as pre.
ds@576: */
ds@576: Action:public(Handle:event, const String:name[], bool:dontBroadcast),
ds@576: /**
ds@576: * Called when a game event is fired.
ds@576: *
ds@576: * @param event Handle to event. This could be INVALID_HANDLE if every plugin hooking
ds@576: * this event has set the hook mode EventHookMode_PostNoCopy.
ds@576: * @param name String containing the name of the event.
ds@576: * @param dontBroadcast True if event was not broadcast to clients, false otherwise.
ds@576: * @noreturn
ds@576: */
ds@576: public(Handle:event, const String:name[], bool:dontBroadcast),
ds@576: };
ds@576:
ds@576: /**
ds@576: * Creates a hook for when a game event is fired.
ds@576: *
ds@576: * @param name Name of event.
ds@576: * @param callback An EventHook function pointer.
ds@576: * @param mode Optional EventHookMode determining the type of hook.
ds@576: * @noreturn
ds@576: * @error Invalid event name or invalid callback function.
ds@576: */
ds@576: native HookEvent(const String:name[], EventHook:callback, EventHookMode:mode=EventHookMode_Post);
ds@576:
ds@576: /**
ds@801: * Creates a hook for when a game event is fired.
ds@801: *
ds@801: * @param name Name of event.
ds@801: * @param callback An EventHook function pointer.
ds@801: * @param mode Optional EventHookMode determining the type of hook.
ds@801: * @return True if event exists and was hooked successfully, false otherwise.
ds@801: * @error Invalid callback function.
ds@801: */
ds@801: native bool:HookEventEx(const String:name[], EventHook:callback, EventHookMode:mode=EventHookMode_Post);
ds@801:
ds@801: /**
ds@576: * Removes a hook for when a game event is fired.
ds@576: *
ds@576: * @param name Name of event.
ds@576: * @param callback An EventHook function pointer.
ds@576: * @param mode Optional EventHookMode determining the type of hook.
ds@576: * @noreturn
ds@576: * @error Invalid callback function or no active hook for specified event.
ds@576: */
ds@576: native UnhookEvent(const String:name[], EventHook:callback, EventHookMode:mode=EventHookMode_Post);
ds@576:
ds@576: /**
ds@576: * Creates a game event to be fired later.
ds@576: *
dvander@1851: * The Handle should not be closed via CloseHandle(). It must be closed via
dvander@1851: * FireEvent() or CancelCreatedEvent().
dvander@1851: *
ds@576: * @param name Name of event.
ds@713: * @param force If set to true, this forces the event to be created even if it's not being hooked.
ds@713: * Note that this will not force it if the event doesn't exist at all.
ds@713: * @return Handle to event. INVALID_HANDLE is returned if the event doesn't exist or isn't
ds@713: being hooked (unless force is true).
ds@576: */
ds@713: native Handle:CreateEvent(const String:name[], bool:force=false);
ds@576:
ds@576: /**
ds@576: * Fires a game event.
ds@576: *
dvander@1851: * This function closes the event Handle after completing.
dvander@1851: *
ds@576: * @param event Handle to the event.
ds@576: * @param dontBroadcast Optional boolean that determines if event should be broadcast to clients.
ds@576: * @noreturn
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@712: native FireEvent(Handle:event, bool:dontBroadcast=false);
ds@576:
ds@576: /**
ds@576: * Cancels a previously created game event that has not been fired.
ds@576: *
ds@576: * @param event Handled to the event.
ds@576: * @noreturn
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native CancelCreatedEvent(Handle:event);
ds@576:
ds@576: /**
ds@576: * Returns the boolean value of a game event's key.
ds@576: *
ds@576: * @param event Handle to the event.
ds@576: * @param key Name of event key.
ds@576: * @return The boolean value of the specfied event key.
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native bool:GetEventBool(Handle:event, const String:key[]);
ds@576:
ds@576: /**
ds@576: * Sets the boolean value of a game event's key.
ds@576: *
ds@576: * @param event Handle to the event.
ds@576: * @param key Name of event key.
ds@576: * @param value New boolean value.
ds@576: * @noreturn
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native SetEventBool(Handle:event, const String:key[], bool:value);
ds@576:
ds@576: /**
ds@576: * Returns the integer value of a game event's key.
ds@576: *
ds@576: * @param event Handle to the event.
ds@576: * @param key Name of event key.
ds@576: * @return The integer value of the specfied event key.
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native GetEventInt(Handle:event, const String:key[]);
ds@576:
ds@576: /**
ds@576: * Sets the integer value of a game event's key.
ds@576: *
dvander@1851: * Integer value refers to anything that can be reduced to an integer.
dvander@1851: * The various size specifiers, such as "byte" and "short" are still
dvander@1851: * integers, and only refer to how much data will actually be sent
dvander@1851: * over the network (if applicable).
dvander@1851: *
ds@576: * @param event Handle to the event.
ds@576: * @param key Name of event key.
ds@576: * @param value New integer value.
ds@576: * @noreturn
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native SetEventInt(Handle:event, const String:key[], value);
ds@576:
ds@576: /**
ds@576: * Returns the floating point value of a game event's key.
ds@576: *
ds@576: * @param event Handle to the event.
ds@576: * @param key Name of event key.
ds@576: * @return The floating point value of the specfied event key.
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native Float:GetEventFloat(Handle:event, const String:key[]);
ds@576:
ds@576: /**
ds@576: * Sets the floating point value of a game event's key.
ds@576: *
ds@576: * @param event Handle to the event.
ds@576: * @param key Name of event key.
ds@576: * @param value New floating point value.
ds@576: * @noreturn
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native SetEventFloat(Handle:event, const String:key[], Float:value);
ds@576:
ds@576: /**
ds@576: * Retrieves the string value of a game event's key.
ds@576: *
ds@576: * @param event Handle to the event.
ds@576: * @param key Name of event key.
ds@576: * @param value Buffer to store the value of the specified event key.
ds@576: * @param maxlength Maximum length of string buffer.
ds@576: * @noreturn
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native GetEventString(Handle:event, const String:key[], String:value[], maxlength);
ds@576:
ds@576: /**
ds@576: * Sets the string value of a game event's key.
ds@576: *
ds@576: * @param event Handle to the event.
ds@576: * @param key Name of event key.
ds@576: * @param value New string value.
ds@576: * @noreturn
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native SetEventString(Handle:event, const String:key[], const String:value[]);
ds@576:
ds@576: /**
ds@576: * Retrieves the name of a game event.
ds@576: *
ds@576: * @param event Handle to the event.
ds@576: * @param value Buffer to store the name of the event.
ds@576: * @param maxlength Maximum length of string buffer.
ds@576: * @noreturn
ds@576: * @error Invalid or corrupt Handle.
ds@576: */
ds@576: native GetEventName(Handle:event, String:name[], maxlength);