Defines, Structures, Typedefs, Functions. More...

Files
file	clTimerApi.h
	Timer APIs.
file	clTimerErrors.h
	Header file of Error Codes returned by the Timer Library.

Classes
struct	ClTimerConfigT
	It contains the timer library configuration information. More...
struct	ClTimerTimeOutT
	The timeout value in seconds and milliseconds. More...

Macros
#define	CL_TIMER_ERR_INVALID_TIMER 0x100
	(0x100) The timer is either already freed, or in a state that makes this operation invalid.
#define	CL_TIMER_ERR_INVALID_TIMER_CONTEXT_TYPE 0x103
	(0x103) The timer context (CL_TIMER_TASK_CONTEXT, or CL_TIMER_SEPARATE_CONTEXT) was set incorrectly.
#define	CL_TIMER_ERR_INVALID_TIMER_TYPE 0x102
	(0x102) The timer type (one-shot or repetitive) was set incorrectly.
#define	CL_TIMER_ERR_NULL_TIMER_CALLBACK 0x104
	(0x104) The timer was created without a callback function.

Typedefs
typedef ClRcT(*	ClTimerCallBackT )(void *)
	The type fo the callback fucntion that will be called on timer expiry.
typedef ClPtrT	ClTimerHandleT
	The type of the handle identifying the timer.

Enumerations
enum	ClTimerContextT { CL_TIMER_TASK_CONTEXT = 0, CL_TIMER_SEPARATE_CONTEXT }
	When the timer expires, decides the method of invocation of the timer callback function. More...
enum	ClTimerTypeT { CL_TIMER_ONE_SHOT = 0, CL_TIMER_REPETITIVE }
	*type of action on timer expiry. More...

Functions
ClRcT	clTimerConfigInitialize (void *pConfigData)
	Configures the Timer library.
ClRcT	clTimerCreate (ClTimerTimeOutT timeOut, ClTimerTypeT type, ClTimerContextT timerTaskSpawn, ClTimerCallBackT fpAction, void pActionArgument, ClTimerHandleT pTimerHandle)
	Creates a timer.
ClRcT	clTimerCreateAndStart (ClTimerTimeOutT timeOut, ClTimerTypeT type, ClTimerContextT timerTaskSpawn, ClTimerCallBackT fpAction, void pActionArgument, ClTimerHandleT pTimerHandle)
	Creates a new timer and activates it.
ClRcT	clTimerDelete (ClTimerHandleT *pTimerHandle)
	Deletes a timer.
ClRcT	clTimerFinalize (void)
	Cleans up the Timer library.
ClRcT	clTimerInitialize (ClPtrT pConfig)
	Initializes the Timer library.
ClRcT	clTimerRestart (ClTimerHandleT timerHandle)
	Restarts a timer.
ClRcT	clTimerStart (ClTimerHandleT timerHandle)
	Starts a timer.
ClRcT	clTimerStop (ClTimerHandleT timerHandle)
	Stops a timer.
ClRcT	clTimerTypeGet (ClTimerHandleT timerHandle, ClUint32T *pTimerType)
	Returns the timer type.
ClRcT	clTimerUpdate (ClTimerHandleT timerHandle, ClTimerTimeOutT newTimeout)
	Updates a timer.

Detailed Description

Defines, Structures, Typedefs, Functions.

Macro Definition Documentation

#define CL_TIMER_ERR_INVALID_TIMER 0x100

(0x100) The timer is either already freed, or in a state that makes this operation invalid.

For example, if you called "start" but the timer is already started.

#define CL_TIMER_ERR_INVALID_TIMER_CONTEXT_TYPE 0x103

(0x103) The timer context (CL_TIMER_TASK_CONTEXT, or CL_TIMER_SEPARATE_CONTEXT) was set incorrectly.

The value is corrupt.

#define CL_TIMER_ERR_INVALID_TIMER_TYPE 0x102

(0x102) The timer type (one-shot or repetitive) was set incorrectly.

The value is corrupt or an unknown timer type.

#define CL_TIMER_ERR_NULL_TIMER_CALLBACK 0x104

(0x104) The timer was created without a callback function.

The callback is called upon timer expiry, so setting a timer without a callback is useless.

Typedef Documentation

typedef ClRcT(* ClTimerCallBackT)(void *)

The type fo the callback fucntion that will be called on timer expiry.

Cast your function to 'ClRcT (*) (void *)'

Enumeration Type Documentation

enum ClTimerContextT

When the timer expires, decides the method of invocation of the timer callback function.

Either timer callback function will be called from same thread context as the timer itself or new separate thread context. Timer task context is slightly more efficient and accurate. However, if you chose timer task context, your callback function must complete rapidly and not block – or you will be denying other timer expirations from being handled.

Enumerator:

CL_TIMER_TASK_CONTEXT	Use the timer thread.
CL_TIMER_SEPARATE_CONTEXT	A new thread will be created to invoke the callback.

enum ClTimerTypeT

*type of action on timer expiry.

repitive start automaticaly starts after timeouts. CL_TIMER_ONE_SHOT:Timer has not started after timeout.

Enumerator:

CL_TIMER_ONE_SHOT	Fire just once.
CL_TIMER_REPETITIVE	Fire periodically.

Function Documentation

ClRcT clTimerConfigInitialize ( void * pConfigData )

Configures the Timer library.

Parameters

pConfigData Pointer to instance of configuration structure. You must pass a pointer to a ClTimerConfigT as the input.

Return values

CL_OK	The API executed successfully.
CL_TIMER_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_NULL_POINTER	On passing a NULL pointer.

Description:

This API is used to configure the timer service library. The configurable parameters in ClTimerConfigT are:

timerResolution : This value is in miliseconds and cannot be less than 10ms. Default value is 10 milliseconds.
timerTaskPriority : This value can vary between 1 and 160. Default value is 150.

ClRcT clTimerCreate	(	ClTimerTimeOutT	timeOut,
		ClTimerTypeT	type,
		ClTimerContextT	timerTaskSpawn,
		ClTimerCallBackT	fpAction,
		void *	pActionArgument,
		ClTimerHandleT *	pTimerHandle
	)

Creates a timer.

Parameters

timeOut	Timeout value of the timer.
type	Type of the timer to be created. It can be either One-shot or repetitive.
timerTaskSpawn	Determines whether the user-function invoked is in a separate task or in the same context as the timer-task.
fpAction	Function to be called after timer expiry.
pActionArgument	Argument to be passed to the callback function (fpAction in this case).
pTimerHandle	(out) Pointer to the memory location where the timer handle created is being copied.

Return values

CL_OK	The API executed successfully.
CL_TIMER_ERR_INVLD_PARAM	On passing invalid parameters.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_TIMER_ERR_NULL_CALLBACK_FUNCTION	On passing a NULL callback function.
CL_TIMER_ERR_INVALID_TYPE	On passing an invalid type.
CL_TIMER_ERR_INVALID_CONTEXT_TYPE	On passing an invalid context.

Description:: This API is used to create a new timer. This timer would remain inactive until the timer is started. The callback function would be executed in the context of the timer task when the timer expires. This API returns a handle which needs to be specified whenever you want to start, stop, restart or destroy the timer.

ClRcT clTimerCreateAndStart	(	ClTimerTimeOutT	timeOut,
		ClTimerTypeT	type,
		ClTimerContextT	timerTaskSpawn,
		ClTimerCallBackT	fpAction,
		void *	pActionArgument,
		ClTimerHandleT *	pTimerHandle
	)

Creates a new timer and activates it.

Parameters

timeOut	Timeout value of the timer.
type	Type of the timer to be created. It can be either One-shot or repetitive.
timerTaskSpawn	Determines whether the user-function invoked is in a separate task or in the same context as the timer-task.
fpAction	Function to be called after timer expiry.
actionArgument	Argument to be passed to the callback function (fpAction in this case).
pTimerHandle	(out) Pointer to the memory location where the timer handle created is being copied.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_PARAMETER	On passing an invalid parameter.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_TIMER_ERR_NULL_CALLBACK_FUNCTION	On passing an invalid callback function.
CL_TIMER_ERR_INVALID_TYPE	If type is invalid.

Description:: This API is used to create a new timer and activate it. It is essentially a combination of clTimerCreate() and clTimerStart(). This API is useful when you want to create a new timer and activate it at the time of its creation.

ClRcT clTimerDelete ( ClTimerHandleT * pTimerHandle )

Deletes a timer.

Note: If the timer being deleted is active, then it is made inactive and deleted.

Parameters

pTimerHandle (out) Pointer to timer handle being deleted. The contents are set to 0.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_TIMER_ERR_INVALID	If the internal timer representation is invalid.

Description:: This API is used to delete an existing timer. It is invoked by the application after the timer has expired. Typically, this API is invoked during the time of application exit, but it can also be called at any other time.

ClRcT clTimerFinalize ( void )

Cleans up the Timer library.

Return values

CL_OK	The API executed successfully.
ERROR	On failure.

Description:: This API is used to clean up the timer service library. This API is invoked during the system shutdown process or when timers are no longer needed.

ClRcT clTimerInitialize ( ClPtrT pConfig )

Initializes the Timer library.

Parameters

pConfig

Return values

CL_OK	The API executed successfully.
ERROR	On failure.

Description:: This API is used to initialize the timer service library. After invoking this API you can create, start, stop and destroy timers.

See Also: clTimerFinalize()

ClRcT clTimerRestart ( ClTimerHandleT timerHandle )

Restarts a timer.

Parameters

timerHandle Handle of the timer being restarted.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_TIMER_ERR_INVLD_STATE	If timer is in invalid state.
CL_TIMER_ERR_INVALID	If the internal timer representation is invalid.

Description:: This API is used to restart a timer.

ClRcT clTimerStart ( ClTimerHandleT timerHandle )

Starts a timer.

Parameters

timerHandle Handle of the timer being started.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_TIMER_ERR_INVALID	If the internal timer representation is invalid.

Description:: This API is used to start a timer. Before the timer can be started, the timer must be created. The callback API is executed when the timeout occurs. The callback API would be executed in the context of the timer task.

ClRcT clTimerStop ( ClTimerHandleT timerHandle )

Stops a timer.

Note: This API only stops the timer and does not destroy it.

Parameters

timerHandle Handle of the timer being stopped.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_TIMER_ERR_INVALID	If the internal timer representation is invalid.

Description:: This API is used to stop a timer. After invoking this API, the timer becomes inactive.

ClRcT clTimerTypeGet	(	ClTimerHandleT	timerHandle,
		ClUint32T *	pTimerType
	)

Returns the timer type.

Parameters

timerHandle	Handle of the timer.
pTimerType	(out) The pointer to the location to which the type of the timer is being copied. It can have two possible values: If the value is - 0: The timer type is One-shot. 1: The timer type is repetitive.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_TIMER_ERR_INVALID	If the internal timer representation is invalid.

Description:: This API is used to query and return for a specific type of timer, whether it is one-shot or repetitive.

ClRcT clTimerUpdate	(	ClTimerHandleT	timerHandle,
		ClTimerTimeOutT	newTimeout
	)

Updates a timer.

Parameters

timerHandle	Handle of the timer being updated.
newTimeout	New timeout value for the timer.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_TIMER_ERR_INVALID	If the internal timer representation is invalid.

Description:: This API is used to update the timeout value of a timer.

Files

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation