rvtimer.h

基于h323协议的软phone

		{p: Adds to the total size of the timer queue.}
	}
	{proto: RvSize_t RvTimerQueueAddSize(RvTimerQueue *tqueue, RvSize_t addsize);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be set.}}
		{param: {n: newsize} {d: Number of additional timers to be added.}}
	}
	{returns: Actual number of timers added to the timer queue pool.}
	{notes:
		{note:  The actual number of timers may be larger than that requested since
				the amount added will be a multiple of the number of timers per
				page that was set when the timer queue was constructed. The value
				returned will be the actual new number of timers that was added.}
		{note:  Changes are subject to the limits of the maxtimers setting.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueGetMaxTimers}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Find the current maximum size of the timer queue.}
	}
	{proto: RvSize_t RvTimerQueueGetMaxTimers(RvTimerQueue *tqueue);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be checked.}}
	}
	{returns: Value of the maxtimers setting for timer queue pool.}
	{notes:
		{note:  This setting is not ususally used by FIXED pools since they are limited
				by their actual size.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueSetMaxTimers}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Sets the maximum size of the timer queue.}
	}
	{proto: RvBool RvTimerQueueSetMaxTimers(RvTimerQueue *tqueue, RvSize_t maxtimers);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be set.}}
		{param: {n: maxtimers} {d: New setting for maximum number of timers (0 = no maximum).}}
	}
	{returns: Returns RV_TRUE if successful, otherwise RV_FALSE.}
	{notes:
		{note:  This setting is not ususally used by FIXED pools since they are limited
				by their actual size.}
		{note:  The maxtimers value can not be set below the value of mintimers or
				below the current number of timers in the pool.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueChangeMaxTimers}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Changes the maximum size of the timer queue.}
	}
	{proto: RvBool RvTimerQueueChangeMaxTimers(RvTimerQueue *tqueue, RvSize_t delta, RvBool direction);}
	{params:
		{param: {n: tqueue}     {d: Pointer to timer queue object to be changed.}}
		{param: {n: delta}      {d: The amount to change the maxtimer value by.}}
		{param: {n: direction}  {d: Direction to change value, either RV_TIMER_VALUE_INCREASE or
									RV_TIMER_VALUE_DECREASE.}}
	}
	{returns: Returns RV_TRUE if successful, otherwise RV_FALSE.}
	{notes:
		{note:  This setting is not ususally used by FIXED pools since they are limited
				by their actual size.}
		{note:  The maxtimers value can not be set below the value of mintimers or
				below the current number of timers in the pool.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueGetMinTimers}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Find the current minimum size of the timer queue.}
	}
	{proto: RvSize_t RvTimerQueueGetMinTimers(RvTimerQueue *tqueue);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be checked.}}
	}
	{returns: Value of the mintimers setting for timer queue pool.}
	{notes:
		{note:  This setting is not ususally used by FIXED pools since they are limited
				by their actual size. Nor is it used by EXAPNDING pools since they
				never shrink.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueSetMinTimers}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Sets the minimum size of the timer queue.}
	}
	{proto: RvBool RvTimerQueueSetMinTimers(RvTimerQueue *tqueue, RvSize_t mintimers);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be set.}}
		{param: {n: mintimers} {d: New setting for minimum number of timers.}}
	}
	{returns: Returns RV_TRUE if successful, otherwise RV_FALSE.}
	{notes:
		{note:  This setting is not ususally used by FIXED pools since they are limited
				by their actual size. Increasing a fixed pool minimum beyond its current
				size will use more memory but not add any timers.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueChangeMinTimers}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Changes the minimum size of the timer queue.}
	}
	{proto: RvBool RvTimerQueueChangeMinTimers(RvTimerQueue *tqueue, RvSize_t delta, RvBool direction);}
	{params:
		{param: {n: tqueue}     {d: Pointer to timer queue object to be changed.}}
		{param: {n: delta}      {d: The amount to change the mintimer value by.}}
		{param: {n: direction}  {d: Direction to change value, either RV_TIMER_VALUE_INCREASE or
									RV_TIMER_VALUE_DECREASE.}}
	}
	{returns: Returns RV_TRUE if successful, otherwise RV_FALSE.}
	{notes:
		{note:  This setting is not ususally used by FIXED pools since they are limited
				by their actual size. Increasing a fixed pool minimum beyond its current
				size will use more memory but not add any timers.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueGetFreelevel}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Find the current freelevel of the timer queue.}
	}
	{proto: RvSize_t RvTimerQueueGetFreelevel(RvTimerQueue *tqueue);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be checked.}}
	}
	{returns: Value of the freevalue setting for timer queue pool.}
	{notes:
		{note:  This setting is only used by DYNAMIC timer queues.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueSetFreelevel}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Sets the current freelevel of the timer queue. This is the minimum number
			of free timers per 100 to maintain in the pool when shrinking a DYNAMIC
			timer pool (0 to 100). A value of 0 always releases empty pages and a
			value of 100 never releases empty pages (which is the same as an EXPANDING
			pool).}
	}
	{proto: RvBool RvTimerQueueSetFreelevel(RvTimerQueue *tqueue, RvSize_t freelevel);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be set.}}
		{param: {n: freelevel} {d: New freelevel value to set (0 to 100).}}
	}
	{returns: Returns RV_TRUE if successful, otherwise RV_FALSE.}
	{notes:
		{note:  This setting is only used by DYNAMIC timer queues.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueNextEvent}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Returns the number of nanoseconds until the next timer is supposed
			to be triggered.}
	}
	{proto: RvStatus RvTimerQueueNextEvent(RvTimerQueue *tqueue, RvInt64 *nextevent);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be checked.}}
		{param: {n: nextevent} {d: Pointer to location to store the nanoseconds until the next event.}}
	}
	{returns:   RV_OK if successful otherwise an error code. A warning of RV_TIMER_WARNING_QUEUEEMPTY
				will be returned if there are no events in the timer queue.}
	{notes:
		{note:  The value of nextevent may be negative if the next event is overdue.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueDestruct}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Destructs a timer queue.}
	}
	{proto: RvStatus RvTimerQueueDestruct(RvTimerQueue *tqueue);}
	{params:
		{param: {n: queue} {d: Pointer to timer queue object to be Destructed.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note:  All timers in the queue are lost when the timer queue is destructed.}
		{note:  Insure that no threads are adding timers or servicing timers on the
				timer queue when it is destructing since not all operating systems
				handle the situation gracefully.}
		{note:  This function may only be called once on each timer queue. Thus
				it may not be called simultaneously from multiple threads (with the
				same timer queue to destruct).}
		}
}
$*/
/*$
{function:
	{name: RvTimerStart}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Creates and schedules a timer event. There are two type of timers, ONESHOT and PERIDOC.
			A ONESHOT timer will trigger only once, at the requested time. A PERIODIC timer will
			triggered repeatedly until it is canceled with a call to RvTimerCancel or by the
			callback returning a value of RV_FALSE.}
	}
	{proto: RvStatus RvTimerStart(RvTimer *timer, RvTimerQueue *tqueue, RvInt timertype, RvInt64 delay, RvTimerFunc callback, void *userdata);}
	{params:
		{param: {n: timer}     {d: Pointer to timer object which will be filled in with information needed to indentify the event.}}
		{param: {n: tqueue}    {d: Pointer to timer queue object where timer should be scheduled.}}
		{param: {n: timertype} {d: Type of timer: RV_TIMER_TYPE_ONESHOT or RV_TIMER_TYPE_PERIODIC.}}
		{param: {n: delay}     {d: Time until timer should be triggered, in nanoseconds.}}
		{param: {n: callback}  {d: Function to be called when the timer is triggered.}}
		{param: {n: userdata}  {d: Pointer that will be passed to the callback function when triggered.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note:  There is no construct or destruct calls for the RvTimer type. It is simply used as
				an identifier for the timer event so that it may be canceled. The RvTimer structure
				is not required in order for the timer event to trigger and not keeping that
				structure around in no way effects the operation of the timer other then leaving
				no way to cancel the timer event. Also, the timer parameter may be NULL, which
				simply starts a timer without returning the information needed to cancel it.}
		{note:  The actual accuracy of the timer is dependent upon a number of things including
				the resolution of the timestamp clock, the rate and priority of the thread
				servicing the timer queue, and the cpu load of the system.}
		}
}
$*/
/*$
{function:
	{name: RvTimerCancel}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Cancels a timer event. This function has two slightly different behaviours
			depending on how the blocking parameter is set:}
		{bulletlist:
			{item:  RV_TIMER_CANCEL_BLOCKING: The timer event is garanteed to be canceled
					when the function returns. If the timer event was is the middle of
					being triggered, this function will suspend the calling thread until
					the callback is completed.}
			{item:  RV_TIMER_CANCEL_NONBLOCKING: The timer event is canceled if it is
					not currently in the middle of being triggered. If the timer event
					was is the middle of being triggered a return warning value of
					RV_TIMER_WARNING_BUSY is returned. PERIODIC timers will have future
					triggers canceled so that the trigger currently in progress will be
					the last one.}
		}
	}
	{proto: RvStatus RvTimerCancel(RvTimer *timer, RvBool blocking);}
	{params:
		{param: {n: timer}    {d: Pointer to timer object which identifies the event to cancel.}}
		{param: {n: blocking} {d: Behaviour of cancel: RV_TIMER_CANCEL_BLOCKING or RV_TIMER_CANCEL_NONBLOCKING.}}
	}
	{returns:   RV_OK if successful otherwise an error code. May also return RV_TIMER_WARNING_BUSY
				if blocking is set to RV_TIMER_CANCEL_NONBLOCKING.}
	{notes:
		{note:  Do not cancel a timer that was scheduled on a timer queue that has been destructed.
				Destructing the timer queue automatically cancels and destroys all timers.}
		{note:  Never call RvTimerCancel with blocking set to RV_TIMER_CANCEL_BLOCKING from
				inside of that timers callback. It really should not be necessary to call it
				at all from within its callback.}
	}
}
$*/
/*$
{function:
	{name: RvTimerResolution}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Gets the resolution of the clock used by timers, in nanoseconds.}
	}
	{proto: RvInt64 RvTimerResolution(void);}
	{returns: Resolution of the timer clock, in nanoseconds.}
}
$*/
/*$
{function:
	{name: RvTimerQueueService}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Checks a timer queue and executes events that should be triggered. }
	}
	{proto: RvStatus RvTimerQueueService(RvTimerQueue *tqueue, RvSize_t	maxevents, RvSize_t *numevents);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be serviced.}}
		{param: {n: maxevents} {d: Maximum number of events that should be executed.}}
		{param: {n: numevents} {d: Pointer to variable where the number of events actually executed will be stored.}}
	}
	{returns:   RV_OK if successful otherwise an error code. An error of RV_TIMER_ERROR_QUEUESTOPPED
				will be returned if the queue hass been stopped (with the RvTimerQueueStop function).}
}
$*/

#endif