ds@576: /**
ds@576:  * vim: set ts=4 :
ds@576:  * ===============================================================
ds@576:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
ds@576:  * ===============================================================
ds@576:  *
ds@576:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
ds@576:  * or modified under the Terms and Conditions of its License Agreement, which is found 
ds@576:  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
ds@576:  * may change at any time.  To view the latest information, see:
ds@576:  *   http://www.sourcemod.net/license.php
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@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:  *
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:  *
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:  *
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);