Application timer functions and defines. More...

#include "stbgc.h"

Include dependency graph for ap_tmr.h:

Data Structures
struct	S_ALARM_INFO
struct	S_PVR_RECORD_INFO
struct	s_timer
struct	s_avrec_settings
Defines
#define	INVALID_TIMER_HANDLE 0
#define	TMR_MAX_NAME_LENGTH 128
#define	TMR_PVR_CRID_LEN_MAX 65
#define	TMR_PVR_ADDINFO_LEN_MAX 255
#define	EVENT_DURATION_OVERRUN_TIME 2
Typedefs
typedef struct s_timer	S_TIMER_INFO
typedef struct s_avrec_settings	S_AVREC_SETTINGS
Enumerations
enum	E_TIMER_TYPE { TIMER_TYPE_NONE = 0x00, TIMER_TYPE_ALARM = 0x01, TIMER_TYPE_SLEEP = 0x02, TIMER_TYPE_PVR_RECORD = 0x04, TIMER_TYPE_PRIVATE = 0x80, TIMER_TYPE_ALL = 0xff }
enum	E_TIMER_FREQ { TIMER_FREQ_ONCE, TIMER_FREQ_WEEKLY, TIMER_FREQ_WEEKENDDAYS, TIMER_FREQ_WEEKDAYS, TIMER_FREQ_DAILY, TIMER_FREQ_HOURLY }
Functions
void	ATMR_Initialise (void)
	Performs initialisation of the timers, reading existing entries from the database.
U32BIT	ATMR_AddTimer (S_TIMER_INFO *info)
	Creates a new timer based on the information supplied.
U32BIT	ATMR_AddTimerForEvent (void event_ptr, void serv_ptr, BOOLEAN record, BOOLEAN event_triggered)
	Creates a timer based on the given event. If a recording timer is created, it will be set to record on the default disk, which can be changed afterwards using ATMR_SetDiskId.
BOOLEAN	ATMR_UpdateTimerDuration (U32BIT handle, U32DHMS duration)
	Updates the duration for an existing PVR recording timer.
BOOLEAN	ATMR_DeleteTimer (U32BIT handle)
	Deletes the timer with the given handle.
BOOLEAN	ATMR_GetTimerList (U32BIT *timer_list, U16BIT list_size, E_TIMER_TYPE list_type, BOOLEAN date_time_order)
	Returns a list of all the timer handles and the number of items in the list.
void	ATMR_ReleaseTimerList (U32BIT *timer_list, U16BIT list_size)
	Release the given array of timer handles.
BOOLEAN	ATMR_InitialiseTimer (S_TIMER_INFO timer_info, E_TIMER_TYPE timer_type, void serv_ptr, void *event_ptr)
	Sets up the given timer info structure with default values for the given timer type using the service and event depending on timer type.
BOOLEAN	ATMR_GetTimerInfo (U32BIT handle, S_TIMER_INFO *timer_info)
	Copies timer data for the given timer info the info structure provided.
BOOLEAN	ATMR_StartRecord (U8BIT path)
	Finds the timer using the given decode path and if it's a recording timer the recording will be started.
void	ATMR_RecordingFailed (U8BIT path)
	Handles the timer when a recording fails to start for some reason. This may result in the timer being deleted.
void *	ATMR_GetRecordService (U8BIT path)
	Returns the service for the recording timer on the given path.
U8BIT *	ATMR_GetName (U32BIT handle)
	Get the name of the timer with the given handle.
void	ATMR_SetName (U32BIT handle, U8BIT *name)
	Sets the name of the timer with the given handle.
U32DHMS	ATMR_GetStartDateTime (U32BIT handle)
	Get the start date & time of the timer with the given handle. The date/time returned will be in UTC.
U32DHMS	ATMR_GetDuration (U32BIT handle)
	Returns the duration of the timert with the given handle.
U32DHMS	ATMR_GetEndDateTime (U32BIT handle)
	Get the end date & time of the timer with the given handle. The date/time returned will be in UTC.
E_TIMER_TYPE	ATMR_GetType (U32BIT handle)
	Returns the type of the given timer.
E_TIMER_FREQ	ATMR_GetFrequency (U32BIT handle)
	Returns the frequency setting for the given timer.
BOOLEAN	ATMR_GetChangeService (U32BIT handle)
	Returns the change service setting for an alarm timer.
BOOLEAN	ATMR_GetRampVolume (U32BIT handle)
	Returns the ramp volume setting for an alarm timer.
U16BIT	ATMR_GetEventId (U32BIT handle)
	Returns the event ID for a PVR recording timer.
U16BIT	ATMR_GetServiceId (U32BIT handle)
	Returns the service ID for an alarm or PVR recording timer.
U16BIT	ATMR_GetTransportId (U32BIT handle)
	Returns the transport ID for an alarm or PVR recording timer.
U16BIT	ATMR_GetOriginalNetworkId (U32BIT handle)
	Returns the original network ID for an alarm or PVR recording timer.
BOOLEAN	ATMR_GetMissed (U32BIT handle)
	Gets the timer's missed flag.
BOOLEAN	ATMR_HasSeriesCrid (U32BIT handle)
	Does the timer have a series crid?
BOOLEAN	ATMR_HasRecommendationCrid (U32BIT handle)
	Does the timer have a recommendation crid?
U16BIT	ATMR_GetDiskId (U32BIT handle)
	Returns the disk id for the given timer if the timer is a PVR recording timer.
void	ATMR_SetDiskId (U32BIT handle, U16BIT disk_id)
	Set the disk for the given timer if the timer is a recording timer.
U32BIT	ATMR_GetRecordingHandle (U32BIT handle)
	Returns the recording handle associated with a PVR recording timer.
void	ATMR_HandleTimerEvent (U32BIT timer_handle)
	Used by the DVB stack to handle an event for the given timer. If the timer requires the app to deal with it, such as for sleep or alarm timers, then another event will be sent to the app with an S_TIMER_INFO structure as the event data containing the timer's details to allow the app deal with it. The timer itself will have been updated or deleted.
BOOLEAN	ATMR_CheckRecordStatus (BOOLEAN recordings_can_start)
	Checks all timers to see whether any recordings should be started or stopped as a result of the now event being changed.
void	ATMR_EitUpdated (void)
	Checks each recording timer that's linked to an event to see whether the event is still in the schedule and whether the time has changed, and if it has changed then the timer is updated.
void	ATMR_DeleteRecordingTimer (U32BIT recording_handle)
	Delete the PVR record timer with the given recording handle.
U8BIT	ATMR_GetNumSimultaneousRecordings (U8BIT max_recordings, U32DHMS start_date_time, U32DHMS end_date_time, U32BIT **conflicting_timers)
	Counts the number of simultaneous recordings (EXT and PVR) between the given start and end dates/times.
void *	ATMR_RecordEvent (void serv_ptr, void event_ptr, U8BIT prog_crid, U8BIT series_crid, BOOLEAN is_series, BOOLEAN check_alternatives)
	Adds a timer to perform a recording based on the given event and service. Conflicts are checked and a search is made for an alternative event if necessary.
BOOLEAN	ATMR_RecordSplitEvent (void serv_ptr, U8BIT prog_crid, U32DHMS start_date_time, BOOLEAN radio_service, BOOLEAN search_forward)
	Searches for events within 3 hours of the given start date/time for an event with the given programme CRID and creates a timer to record any found. The search is performed forward or backward from the given start date/time as defined by the search direction argument.
U32BIT	ATMR_GetFirstWakeupTime (U32DHMS rec_date_time, U16BIT onet_id, U16BIT trans_id, U16BIT service_id)
	Searches the timers for the first timer that will cause the DVB to wakeup that hasn't been missed. This will be an alarm or PVR recording timer.
U32BIT	ATMR_FindTimerFromEvent (U16BIT onet_id, U16BIT trans_id, U16BIT serv_id, U16BIT event_id)
	Searches the timers for a recording timer with the given event and service IDs.
U32BIT	ATMR_FindTimerFromCrid (U8BIT *prog_crid)
	Searches the timers for a recording timer with the given programme CRID.
U32BIT	ATMR_FindTimerFromCridAndEvent (U8BIT *prog_crid, U16BIT service_id, U16BIT event_id)
	Searches the timers for a recording timer with the given programme CRID and event ID.
void	ATMR_DeleteTimersForSeriesRecommendations (U8BIT *crid, BOOLEAN is_recommendation)
	Deletes any PVR record timers with the given series CRID.
void	ATMR_SetAdditionalInfo (U32BIT handle, U8BIT *info, U32BIT size)
	Sets the additioinal information string for the specified timer and commits the change to the database.
U8BIT *	ATMR_GetAdditionalInfo (U32BIT handle, U32BIT *size)
	Gets the additional information string associated with a timer. The name is allocated in UI temp memory.
S32BIT	ATMR_GetStartPadding (U32BIT handle)
	Returns the value of start_padding associated with the specified timer The start padding is the number of seconds before (after, if negative) the actual timer start time the timer will be triggered.
BOOLEAN	ATMR_SetStartPadding (U32BIT handle, S32BIT start_padding)
	Sets the value of start_padding associated with the specified timer The start padding is the number of seconds before (after, if negative) the actual timer start time the timer will be triggered.
S32BIT	ATMR_GetEndPadding (U32BIT handle)
	Returns the value of end_padding associated with the specified timer The end padding is the number of seconds after (before, if negative) the actual timer end time the timer will expire.
BOOLEAN	ATMR_SetEndPadding (U32BIT handle, S32BIT end_padding)
	Sets the value of end_padding associated with the specified timer The end padding is the number of seconds after (before, if negative) the actual timer end time the timer will expire.
void	ATMR_DumpAllTimers (void)

Detailed Description

Application timer functions and defines.

Date:: 27/5/2004

Author:: Ocean Blue

Function Documentation

U32BIT ATMR_AddTimer ( S_TIMER_INFO * info )

Creates a new timer based on the information supplied.

Parameters:

info	timer info used to create the timer

Returns:: timer handle, or INVALID_TIMER_HANDLE if creation fails

U32BIT ATMR_AddTimerForEvent	(	void *	event_ptr,
		void *	serv_ptr,
		BOOLEAN	record,
		BOOLEAN	event_triggered
	)

Creates a timer based on the given event. If a recording timer is created, it will be set to record on the default disk, which can be changed afterwards using ATMR_SetDiskId.

Parameters:

event_ptr	- pointer to the event to be recorded
serv_ptr	service the event is on
record	TRUE if a recording timer is to be created, FALSE for an alarm timer
event_triggered	TRUE if the timer should be triggered by the change of event rather than the time

Returns:: timer handle, or INVALID_TIMER_HANDLE if the timer couldn't be created

BOOLEAN ATMR_CheckRecordStatus ( BOOLEAN recordings_can_start )

Checks all timers to see whether any recordings should be started or stopped as a result of the now event being changed.

Parameters:

recordings_can_start TRUE if the event should be checked to start a recording

Returns:: TRUE if a record can be/has been started

void ATMR_DeleteRecordingTimer ( U32BIT recording_handle )

Delete the PVR record timer with the given recording handle.

Parameters:

recording_handle recording handle used by the timer to be deleted

BOOLEAN ATMR_DeleteTimer ( U32BIT handle )

Deletes the timer with the given handle.

Parameters:

handle handle of timer to be deleted

Returns:: TRUE if the timer exists and is deleted, FALSE otherwise

void ATMR_DeleteTimersForSeriesRecommendations	(	U8BIT *	crid,
		BOOLEAN	is_recommendation
	)

Deletes any PVR record timers with the given series CRID.

Parameters:

crid	the series/recommendation CRID to be searched for
is_recommendation	TRUE if the given crid is for a recommendation, FALSE otherwise

U32BIT ATMR_FindTimerFromCrid ( U8BIT * prog_crid )

Searches the timers for a recording timer with the given programme CRID.

Parameters:

prog_crid the programme CRID to be searched for

Returns:: handle of timer, or INVALID_TIMER_HANDLE if no timer is found

U32BIT ATMR_FindTimerFromCridAndEvent	(	U8BIT *	prog_crid,
		U16BIT	service_id,
		U16BIT	event_id
	)

Searches the timers for a recording timer with the given programme CRID and event ID.

Parameters:

prog_crid	the programme CRID to search for
service_id	service ID of the event
event_id	ID of the event

Returns:: handle of timer, or INVALID_TIMER_HANDLE if no timer is found

U32BIT ATMR_FindTimerFromEvent	(	U16BIT	onet_id,
		U16BIT	trans_id,
		U16BIT	serv_id,
		U16BIT	event_id
	)

Searches the timers for a recording timer with the given event and service IDs.

Parameters:

onet_id	original network ID or the service
trans_id	transport ID of the service
serv_id	service ID
event_id	event ID

Returns:: handle of timer, or INVALID_TIMER_HANDLE if no timer is found

U8BIT* ATMR_GetAdditionalInfo	(	U32BIT	handle,
		U32BIT *	size
	)

Gets the additional information string associated with a timer. The name is allocated in UI temp memory.

Parameters:

handle	Timer handle
size	Pointer to variable containing the number of bytes in the string

Returns:: additional information string, or NULL

BOOLEAN ATMR_GetChangeService ( U32BIT handle )

Returns the change service setting for an alarm timer.

Parameters:

handle timer handle

Returns:: value of change service setting, or FALSE if timer is invalid or isn't an alarm timer

U16BIT ATMR_GetDiskId ( U32BIT handle )

Returns the disk id for the given timer if the timer is a PVR recording timer.

Parameters:

handle timer handle

Returns:: disk id if timer is valid and is a recording timer, INVALID_DISK_ID otherwise

U32DHMS ATMR_GetDuration ( U32BIT handle )

Returns the duration of the timert with the given handle.

Parameters:

handle timer handle

Returns:: timer duration, or 0 if the timer handle isn't valid

U32DHMS ATMR_GetEndDateTime ( U32BIT handle )

Get the end date & time of the timer with the given handle. The date/time returned will be in UTC.

Parameters:

handle timer handle

Returns:: UTC end date/time, or 0 if the timer handle isn't valid

S32BIT ATMR_GetEndPadding ( U32BIT handle )

Returns the value of end_padding associated with the specified timer The end padding is the number of seconds after (before, if negative) the actual timer end time the timer will expire.

Parameters:

handle Timer handle

Returns:: start_padding

U16BIT ATMR_GetEventId ( U32BIT handle )

Returns the event ID for a PVR recording timer.

Parameters:

handle timer handle

Returns:: event ID, or 0 if the timer isn't valid or isn't a recording timer

U32BIT ATMR_GetFirstWakeupTime	(	U32DHMS *	rec_date_time,
		U16BIT *	onet_id,
		U16BIT *	trans_id,
		U16BIT *	service_id
	)

Searches the timers for the first timer that will cause the DVB to wakeup that hasn't been missed. This will be an alarm or PVR recording timer.

Parameters:

rec_date_time	pointer to return the date/time of the first timer found
onet_id	returns the original network ID of the service associated with the timer
trans_id	returns the transport ID of the service associated with the timer
service_id	returns the service ID of the service associated with the timer

Returns:: timer handle, or INVALID_TIMER_HANDLE if no timer is found

E_TIMER_FREQ ATMR_GetFrequency ( U32BIT handle )

Returns the frequency setting for the given timer.

Parameters:

handle timer handle

Returns:: frequency setting of the timer, or TIMER_FREQ_ONCE if handle isn't valid

BOOLEAN ATMR_GetMissed ( U32BIT handle )

Gets the timer's missed flag.

Parameters:

handle timer handle

Returns:: TRUE if the timer is marked as missed, FALSE otherwise

U8BIT* ATMR_GetName ( U32BIT handle )

Get the name of the timer with the given handle.

Parameters:

handle timer handle

Returns:: pointer to timer name, this value shouldn't be freed

U8BIT ATMR_GetNumSimultaneousRecordings	(	U8BIT	max_recordings,
		U32DHMS	start_date_time,
		U32DHMS	end_date_time,
		U32BIT **	conflicting_timers
	)

Counts the number of simultaneous recordings (EXT and PVR) between the given start and end dates/times.

Parameters:

max_recordings	the max recordings that can take place at the same time
start_date_time	start date and time of the period to be checked
end_date_time	end date and time of the period to be checked
conflicting_timers	pointer to the list of conflicting timers, the list must to be freed by the caller. If NULL it's ignored.

Returns:: Number of simultaneous recordings during the given period

U16BIT ATMR_GetOriginalNetworkId ( U32BIT handle )

Returns the original network ID for an alarm or PVR recording timer.

Parameters:

handle timer handle

Returns:: original network ID, or ADB_INVALID_DVB_ID if the timer isn't valid or isn't an alarm or recording timer

BOOLEAN ATMR_GetRampVolume ( U32BIT handle )

Returns the ramp volume setting for an alarm timer.

Parameters:

handle timer handle

Returns:: value of ramp volume setting, or FALSE if timer is invalid or isn't an alarm timer

U32BIT ATMR_GetRecordingHandle ( U32BIT handle )

Returns the recording handle associated with a PVR recording timer.

Parameters:

handle timer handle

Returns:: recording handle, or 0 if the timer isn't a PVR recording timer or no recording has been started

void* ATMR_GetRecordService ( U8BIT path )

Returns the service for the recording timer on the given path.

Parameters:

path	recording path

Returns:: service pointer, or NULL if timer not found or service referenced by timer not found

U16BIT ATMR_GetServiceId ( U32BIT handle )

Returns the service ID for an alarm or PVR recording timer.

Parameters:

handle timer handle

Returns:: service ID, or ADB_INVALID_DVB_ID if the timer isn't valid or isn't an alarm or recording timer

U32DHMS ATMR_GetStartDateTime ( U32BIT handle )

Get the start date & time of the timer with the given handle. The date/time returned will be in UTC.

Parameters:

handle timer handle

Returns:: UTC start date/time, or 0 if the timer handle isn't valid

S32BIT ATMR_GetStartPadding ( U32BIT handle )

Returns the value of start_padding associated with the specified timer The start padding is the number of seconds before (after, if negative) the actual timer start time the timer will be triggered.

Parameters:

handle Timer handle

Returns:: start_padding

BOOLEAN ATMR_GetTimerInfo	(	U32BIT	handle,
		S_TIMER_INFO *	timer_info
	)

Copies timer data for the given timer info the info structure provided.

Parameters:

handle	timer handle the data is to be copied from
timer_info	will be filled with info from the timer

Returns:: TRUE if the timer is valid and data is returned, FALSE otherwise

BOOLEAN ATMR_GetTimerList	(	U32BIT **	timer_list,
		U16BIT *	list_size,
		E_TIMER_TYPE	list_type,
		BOOLEAN	date_time_order
	)

Returns a list of all the timer handles and the number of items in the list.

Parameters:

timer_list	pointer to an array of timer handles, the array is allocated by this function
list_size	pointer to the number of items in the returned list
list_type	type of timers to put in the list
date_time_order	TRUE if the list is to be returned in date/time order, FALSE returns the list in alphabetical name order

Returns:: TRUE if a list is returned, FALSE otherwise

U16BIT ATMR_GetTransportId ( U32BIT handle )

Returns the transport ID for an alarm or PVR recording timer.

Parameters:

handle timer handle

Returns:: transport ID, or ADB_INVALID_DVB_ID if the timer isn't valid or isn't an alarm or recording timer

E_TIMER_TYPE ATMR_GetType ( U32BIT handle )

Returns the type of the given timer.

Parameters:

handle timer handle

Returns:: type of the timer, or TIMER_TYPE_NONE if handle isn't valid

void ATMR_HandleTimerEvent ( U32BIT timer_handle )

Used by the DVB stack to handle an event for the given timer. If the timer requires the app to deal with it, such as for sleep or alarm timers, then another event will be sent to the app with an S_TIMER_INFO structure as the event data containing the timer's details to allow the app deal with it. The timer itself will have been updated or deleted.

Parameters:

handle timer handle

BOOLEAN ATMR_HasRecommendationCrid ( U32BIT handle )

Does the timer have a recommendation crid?

Parameters:

handle timer handle

Returns:: TRUE if the timer is valid and is a recording timer and has a recommendation CRID, FALSE otherwise

BOOLEAN ATMR_HasSeriesCrid ( U32BIT handle )

Does the timer have a series crid?

Parameters:

handle timer handle

Returns:: TRUE if the timer is valid and is a recording timer and has a series CRID, FALSE otherwise

BOOLEAN ATMR_InitialiseTimer	(	S_TIMER_INFO *	timer_info,
		E_TIMER_TYPE	timer_type,
		void *	serv_ptr,
		void *	event_ptr
	)

Sets up the given timer info structure with default values for the given timer type using the service and event depending on timer type.

Parameters:

timer_info	pointer to timer info structure to be initialised
timer_type	type of timer to initialise the structure for
serv_ptr	service that will be used for alarm and PVR recording timers
event_ptr	event that will be used for alarm and PVR recording timers

Returns:: TRUE if the structure was setup, FALSE otherwise

void* ATMR_RecordEvent	(	void *	serv_ptr,
		void *	event_ptr,
		U8BIT *	prog_crid,
		U8BIT *	series_crid,
		BOOLEAN	is_series,
		BOOLEAN	check_alternatives
	)

Adds a timer to perform a recording based on the given event and service. Conflicts are checked and a search is made for an alternative event if necessary.

Parameters:

serv_ptr	pointer to service on which recording is to take place
event_ptr	event to be recorded
prog_crid	programme CRID or NULL
other_crid	series or recommendation CRID, or NULL
is_recommendation	TRUE if the above crid is a recommendation crid, FALSE for series
check_alternatives	TRUE if alternative events are to be searched for if the specified event can't be recorded

Returns:: pointer to the event actually recorded, which may be different from the one given, or NULL if the event can't be recorded

void ATMR_RecordingFailed ( U8BIT path )

Handles the timer when a recording fails to start for some reason. This may result in the timer being deleted.

Parameters:

path	- recording path

BOOLEAN ATMR_RecordSplitEvent	(	void *	serv_ptr,
		U8BIT *	prog_crid,
		U32DHMS	start_date_time,
		BOOLEAN	radio_service,
		BOOLEAN	search_forward
	)

Searches for events within 3 hours of the given start date/time for an event with the given programme CRID and creates a timer to record any found. The search is performed forward or backward from the given start date/time as defined by the search direction argument.

Parameters:

serv_ptr	pointer to service on which search is to take place
prog_crid	programme CRID to be searched for
start_date_time	date and time to start searching from
radio_service	TRUE if the search is on a radio service
search_forward	TRUE if the search is to be made for events following the given date/time

Returns:: TRUE if an event is found and is set for recording, FALSE otherwise

void ATMR_ReleaseTimerList	(	U32BIT *	timer_list,
		U16BIT	list_size
	)

Release the given array of timer handles.

Parameters:

timer_list	- timer array to be freed
list_size	- number of items in the list

void ATMR_SetAdditionalInfo	(	U32BIT	handle,
		U8BIT *	info,
		U32BIT	size
	)

Sets the additioinal information string for the specified timer and commits the change to the database.

Parameters:

handle	Timer handle
info	pointer to the string
size	number of bytes in the string

void ATMR_SetDiskId	(	U32BIT	handle,
		U16BIT	disk_id
	)

Set the disk for the given timer if the timer is a recording timer.

Parameters:

handle	timer handle
disk_id	disk id

BOOLEAN ATMR_SetEndPadding	(	U32BIT	handle,
		S32BIT	end_padding
	)

Sets the value of end_padding associated with the specified timer The end padding is the number of seconds after (before, if negative) the actual timer end time the timer will expire.

Parameters:

handle	Timer handle
end_padding	new value for the timer end_padding

Returns:: TRUE if the start_padding could be changed, FALSE otherwise (e.g. due to a conflict)

void ATMR_SetName	(	U32BIT	handle,
		U8BIT *	name
	)

Sets the name of the timer with the given handle.

Parameters:

handle timer handle

BOOLEAN ATMR_SetStartPadding	(	U32BIT	handle,
		S32BIT	start_padding
	)

Sets the value of start_padding associated with the specified timer The start padding is the number of seconds before (after, if negative) the actual timer start time the timer will be triggered.

Parameters:

handle	Timer handle
start_padding	new value for the timer start_padding

Returns:: TRUE if the start_padding could be changed, FALSE otherwise (e.g. due to a conflict)

BOOLEAN ATMR_StartRecord ( U8BIT path )

Finds the timer using the given decode path and if it's a recording timer the recording will be started.

Parameters:

path	decode path being used for the recording

Returns:: TRUE if the recording is started, FALSE otherwise

BOOLEAN ATMR_UpdateTimerDuration	(	U32BIT	handle,
		U32DHMS	duration
	)

Updates the duration for an existing PVR recording timer.

Parameters:

handle	handle of timer to be updated
duration	duration to be set in the timer

Returns:: TRUE if the timer is updated, FALSE otherwise

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Function Documentation