From e6ea726b696c3830db34cae9ded7bbe9e0b7b565 Mon Sep 17 00:00:00 2001 From: Fyren Date: Sun, 1 Mar 2009 16:48:55 -0500 Subject: [PATCH] Improved docs of TIMER_HNDL_CLOSE (bug 3641, r=dvander). --- core/smn_timers.cpp | 13 +++++++------ plugins/include/timers.inc | 30 ++++++++++++++++-------------- 2 files changed, 23 insertions(+), 20 deletions(-) diff --git a/core/smn_timers.cpp b/core/smn_timers.cpp index 3ccc8118..4c9e05dc 100644 --- a/core/smn_timers.cpp +++ b/core/smn_timers.cpp @@ -35,7 +35,8 @@ #include "Logger.h" #include "DebugReporter.h" -#define TIMER_HNDL_CLOSE (1<<9) +#define TIMER_DATA_HNDL_CLOSE (1<<9) +#define TIMER_HNDL_CLOSE (1<<9) HandleType_t g_TimerType; @@ -147,14 +148,14 @@ void TimerNatives::OnTimerEnd(ITimer *pTimer, void *pData) sec.pOwner = pInfo->pContext->GetIdentity(); sec.pIdentity = g_pCoreIdent; - if (pInfo->Flags & TIMER_HNDL_CLOSE) + if (pInfo->Flags & TIMER_DATA_HNDL_CLOSE) { if ((herr=g_HandleSys.FreeHandle(usrhndl, &sec)) != HandleError_None) { g_DbgReporter.GenerateError(pInfo->pContext, pInfo->Hook->GetFunctionID(), SP_ERROR_NATIVE, - "Invalid data handle %x (error %d) passed during timer end", + "Invalid data handle %x (error %d) passed during timer end with TIMER_DATA_HNDL_CLOSE", usrhndl, herr); } @@ -215,7 +216,7 @@ static cell_t smn_CreateTimer(IPluginContext *pCtx, const cell_t *params) if (hndl == BAD_HANDLE) { /* Free this for completeness. */ - if (flags & TIMER_HNDL_CLOSE) + if (flags & TIMER_DATA_HNDL_CLOSE) { HandleSecurity sec(pCtx->GetIdentity(), g_pCoreIdent); g_HandleSys.FreeHandle(params[3], &sec); @@ -255,14 +256,14 @@ static cell_t smn_KillTimer(IPluginContext *pCtx, const cell_t *params) g_Timers.KillTimer(pInfo->Timer); - if (params[2] && !(pInfo->Flags & TIMER_HNDL_CLOSE)) + if (params[2] && !(pInfo->Flags & TIMER_DATA_HNDL_CLOSE)) { sec.pOwner = pInfo->pContext->GetIdentity(); sec.pIdentity = g_pCoreIdent; if ((herr=g_HandleSys.FreeHandle(static_cast(pInfo->UserData), &sec)) != HandleError_None) { - return pCtx->ThrowNativeError("Invalid data handle %x (error %d)", hndl, herr); + return pCtx->ThrowNativeError("Invalid data handle %x (error %d) on timer kill with TIMER_DATA_HNDL_CLOSE", hndl, herr); } } diff --git a/plugins/include/timers.inc b/plugins/include/timers.inc index cfc76f7f..29e1517c 100644 --- a/plugins/include/timers.inc +++ b/plugins/include/timers.inc @@ -39,7 +39,8 @@ #define TIMER_REPEAT (1<<0) /**< Timer will repeat until it returns Plugin_Stop */ #define TIMER_FLAG_NO_MAPCHANGE (1<<1) /**< Timer will not carry over mapchanges */ -#define TIMER_HNDL_CLOSE (1<<9) /**< Timer will automatically call CloseHandle() on its value when finished */ +#define TIMER_HNDL_CLOSE (1<<9) /**< Deprecated define, replaced by below */ +#define TIMER_DATA_HNDL_CLOSE (1<<9) /**< Timer will automatically call CloseHandle() on its data when finished */ /** * Any of the following prototypes will work for a timed function. @@ -50,7 +51,7 @@ funcenum Timer * Called when the timer interval has elapsed. * * @param timer Handle to the timer object. - * @param hndl Handle passed when the timer was created. + * @param hndl Handle passed to CreateTimer() when timer was created. * @return Plugin_Stop to stop a repeating timer, any other value for * default behavior. */ @@ -60,11 +61,11 @@ funcenum Timer * Called when the timer interval has elapsed. * * @param timer Handle to the timer object. - * @param value Value passed when the timer was created. + * @param data Data passed to CreateTimer() when timer was created. * @return Plugin_Stop to stop a repeating timer, any other value for * default behavior. */ - Action:public(Handle:timer, any:value), + Action:public(Handle:timer, any:data), /** * Called when the timer interval has elapsed. @@ -81,18 +82,18 @@ funcenum Timer * * @param interval Interval from the current game time to execute the given function. * @param func Function to execute once the given interval has elapsed. - * @param value Handle or value to give to the timer function. + * @param data Handle or value to pass through to the timer callback function. * @param flags Flags to set (such as repeatability or auto-Handle closing). * @return Handle to the timer object. You do not need to call CloseHandle(). * If the timer could not be created, INVALID_HANDLE will be returned. */ -native Handle:CreateTimer(Float:interval, Timer:func, any:value=INVALID_HANDLE, flags=0); +native Handle:CreateTimer(Float:interval, Timer:func, any:data=INVALID_HANDLE, flags=0); /** * Kills a timer. Use this instead of CloseHandle() if you need more options. * - * @param autoClose If autoClose is true, the timer's value will be - * closed as a handle if TIMER_HNDL_CLOSE was not specified. + * @param autoClose If autoClose is true, the data that was passed to CreateTimer() will + * be closed as a handle if TIMER_DATA_HNDL_CLOSE was not specified. * @noreturn */ native KillTimer(Handle:timer, bool:autoClose=false); @@ -189,20 +190,21 @@ forward OnMapTimeLeftChanged(); native bool:IsServerProcessing(); /** - * Creates a timer associated with a new data pack, and returns the datapack. + * Creates a timer associated with a new datapack, and returns the datapack. * @note The datapack is automatically freed when the timer ends. * @note The position of the datapack is not reset or changed for the timer function. * * @param interval Interval from the current game time to execute the given function. * @param func Function to execute once the given interval has elapsed. - * @param data The newly created datapack is passed though this by-reference parameter. + * @param datapack The newly created datapack is passed though this by-reference + * parameter to the timer callback function. * @param flags Timer flags. * @return Handle to the timer object. You do not need to call CloseHandle(). */ -stock Handle:CreateDataTimer(Float:interval, Timer:func, &Handle:data, flags=0) +stock Handle:CreateDataTimer(Float:interval, Timer:func, &Handle:datapack, flags=0) { - data = CreateDataPack(); - flags |= TIMER_HNDL_CLOSE; - return CreateTimer(interval, func, data, flags); + datapack = CreateDataPack(); + flags |= TIMER_DATA_HNDL_CLOSE; + return CreateTimer(interval, func, datapack, flags); }