1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/public/ITimerSystem.h Sun Mar 30 07:00:22 2008 +0000
1.3 @@ -0,0 +1,209 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * =============================================================================
1.7 + * SourceMod
1.8 + * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved.
1.9 + * =============================================================================
1.10 + *
1.11 + * This program is free software; you can redistribute it and/or modify it under
1.12 + * the terms of the GNU General Public License, version 3.0, as published by the
1.13 + * Free Software Foundation.
1.14 + *
1.15 + * This program is distributed in the hope that it will be useful, but WITHOUT
1.16 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.17 + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.18 + * details.
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License along with
1.21 + * this program. If not, see <http://www.gnu.org/licenses/>.
1.22 + *
1.23 + * As a special exception, AlliedModders LLC gives you permission to link the
1.24 + * code of this program (as well as its derivative works) to "Half-Life 2," the
1.25 + * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.26 + * by the Valve Corporation. You must obey the GNU General Public License in
1.27 + * all respects for all other code used. Additionally, AlliedModders LLC grants
1.28 + * this exception to all derivative works. AlliedModders LLC defines further
1.29 + * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.30 + * or <http://www.sourcemod.net/license.php>.
1.31 + *
1.32 + * Version: $Id$
1.33 + */
1.34 +
1.35 +#ifndef _INCLUDE_SOURCEMOD_TIMER_SYSTEM_H_
1.36 +#define _INCLUDE_SOURCEMOD_TIMER_SYSTEM_H_
1.37 +
1.38 +/**
1.39 + * @file ITimerSystem.h
1.40 + * @brief Contains functions for creating and managing timers.
1.41 + */
1.42 +
1.43 +
1.44 +#include <IShareSys.h>
1.45 +#include <IForwardSys.h>
1.46 +
1.47 +#define SMINTERFACE_TIMERSYS_NAME "ITimerSys"
1.48 +#define SMINTERFACE_TIMERSYS_VERSION 3
1.49 +
1.50 +namespace SourceMod
1.51 +{
1.52 + class ITimer;
1.53 +
1.54 + /**
1.55 + * @brief Interface for map timers.
1.56 + */
1.57 + class IMapTimer
1.58 + {
1.59 + public:
1.60 + /**
1.61 + * Returns the current map time limit in seconds.
1.62 + *
1.63 + * @return Time limit, in seconds, or
1.64 + * 0 if there is no limit.
1.65 + */
1.66 + virtual int GetMapTimeLimit() =0;
1.67 +
1.68 + /**
1.69 + * Extends the map limit (either positively or negatively) in seconds.
1.70 + *
1.71 + * @param extra_time Time to extend map by. If 0, the map will
1.72 + * be set to have no time limit.
1.73 + */
1.74 + virtual void ExtendMapTimeLimit(int extra_time) =0;
1.75 +
1.76 + /**
1.77 + * Tells the map timer whether it is being used or not.
1.78 + *
1.79 + * Map timers are automatically enabled when they are set, and
1.80 + * automatically disabled if being un-set.
1.81 + *
1.82 + * @param enabled True if enabling, false if disabling.
1.83 + */
1.84 + virtual void SetMapTimerStatus(bool enabled) =0;
1.85 + };
1.86 +
1.87 + /**
1.88 + * @brief Event callbacks for when a timer is executed.
1.89 + */
1.90 + class ITimedEvent
1.91 + {
1.92 + public:
1.93 + /**
1.94 + * @brief Called when a timer is executed.
1.95 + *
1.96 + * @param pTimer Pointer to the timer instance.
1.97 + * @param pData Private pointer passed from host.
1.98 + * @return Pl_Stop to stop timer, Pl_Continue to continue.
1.99 + */
1.100 + virtual ResultType OnTimer(ITimer *pTimer, void *pData) =0;
1.101 +
1.102 + /**
1.103 + * @brief Called when the timer has been killed.
1.104 + *
1.105 + * @param pTimer Pointer to the timer instance.
1.106 + * @param pData Private data pointer passed from host.
1.107 + */
1.108 + virtual void OnTimerEnd(ITimer *pTimer, void *pData) =0;
1.109 + };
1.110 +
1.111 + #define TIMER_FLAG_REPEAT (1<<0) /**< Timer will repeat until stopped */
1.112 + #define TIMER_FLAG_NO_MAPCHANGE (1<<1) /**< Timer will not carry over mapchanges */
1.113 +
1.114 + class ITimerSystem : public SMInterface
1.115 + {
1.116 + public:
1.117 + const char *GetInterfaceName()
1.118 + {
1.119 + return SMINTERFACE_TIMERSYS_NAME;
1.120 + }
1.121 + unsigned int GetInterfaceVersion()
1.122 + {
1.123 + return SMINTERFACE_TIMERSYS_VERSION;
1.124 + }
1.125 + public:
1.126 + /**
1.127 + * @brief Creates a timed event.
1.128 + *
1.129 + * @param pCallbacks Pointer to ITimedEvent callbacks.
1.130 + * @param fInterval Interval, in seconds, of the timed event to occur.
1.131 + * The smallest allowed interval is 0.1 seconds.
1.132 + * @param pData Private data to pass on to the timer.
1.133 + * @param flags Extra flags to pass on to the timer.
1.134 + * @return An ITimer pointer on success, NULL on
1.135 + * failure.
1.136 + */
1.137 + virtual ITimer *CreateTimer(ITimedEvent *pCallbacks,
1.138 + float fInterval,
1.139 + void *pData,
1.140 + int flags) =0;
1.141 +
1.142 + /**
1.143 + * @brief Kills a timer.
1.144 + *
1.145 + * @param pTimer Pointer to the ITimer structure.
1.146 + * @return
1.147 + */
1.148 + virtual void KillTimer(ITimer *pTimer) =0;
1.149 +
1.150 + /**
1.151 + * @brief Arbitrarily fires a timer. If the timer is not a repeating
1.152 + * timer, this will also kill the timer.
1.153 + *
1.154 + * @param pTimer Pointer to the ITimer structure.
1.155 + * @param delayExec If true, and the timer is repeating, the
1.156 + * next execution will be delayed by its
1.157 + * interval.
1.158 + * @return
1.159 + */
1.160 + virtual void FireTimerOnce(ITimer *pTimer, bool delayExec=false) =0;
1.161 +
1.162 + /**
1.163 + * @brief Sets the interface for dealing with map time limits.
1.164 + *
1.165 + * @param pMapTimer Map timer interface pointer.
1.166 + * @return Old pointer.
1.167 + */
1.168 + virtual IMapTimer *SetMapTimer(IMapTimer *pTimer) =0;
1.169 +
1.170 + /**
1.171 + * @brief Notification that the map's time left has changed
1.172 + * via a change in the time limit or a change in the game rules (
1.173 + * such as mp_restartgame).
1.174 + */
1.175 + virtual void MapTimeLeftChanged() =0;
1.176 +
1.177 + /**
1.178 + * @brief Returns the current universal tick time. This
1.179 + * replacement for gpGlobals->curtime and engine->Time() correctly
1.180 + * keeps track of ticks.
1.181 + *
1.182 + * During simulation, it is incremented by the difference between
1.183 + * gpGlobals->curtime and the last simulated tick. Otherwise,
1.184 + * it is incremented by the interval per tick.
1.185 + *
1.186 + * It is not reset past map changes.
1.187 + *
1.188 + * @return Universal ticked time.
1.189 + */
1.190 + virtual float GetTickedTime() =0;
1.191 +
1.192 + /**
1.193 + * @brief Notification that the "starting point" in the game has has
1.194 + * changed. This does not invoke MapTimeLeftChanged() automatically.
1.195 + *
1.196 + * @param offset Optional offset to add to the new time.
1.197 + */
1.198 + virtual void NotifyOfGameStart(float offset = 0.0f) =0;
1.199 +
1.200 + /**
1.201 + * @brief Returns the time left in the map.
1.202 + *
1.203 + * @param pTime Pointer to store time left, in seconds.
1.204 + * If there is no time limit, the number will
1.205 + * be below 0.
1.206 + * @return True on success, false if no support.
1.207 + */
1.208 + virtual bool GetMapTimeLeft(float *pTime) =0;
1.209 + };
1.210 +}
1.211 +
1.212 +#endif //_INCLUDE_SOURCEMOD_TIMER_SYSTEM_H_
