6. Timers (optional)

Detailed Description

PVR timer methods
For editing and displaying timed work, such as video recording.

Remarks

Only used by Kodi if supportsTimers is set to true.

If a timer changes after the initial import, or if a new one was added, then the add-on should call TriggerTimerUpdate().

---

Timer parts in interface:
Copy this to your project and extend with your parts or leave functions complete away where not used or supported.

Header parts:

PVR_ERROR GetTimerTypes(std::vector<kodi::addon::PVRTimerType>& types) override;
PVR_ERROR GetTimersAmount(int& amount) override;
PVR_ERROR GetTimers(kodi::addon::PVRTimersResultSet& results) override;
PVR_ERROR AddTimer(const kodi::addon::PVRTimer& timer) override;
PVR_ERROR DeleteTimer(const kodi::addon::PVRTimer& timer, bool forceDelete) override;
PVR_ERROR UpdateTimer(const kodi::addon::PVRTimer& timer) override;
PVR_ERROR CallTimerMenuHook(const kodi::addon::PVRMenuhook& menuhook, const kodi::addon::PVRTimer& item) override;

Source parts:

PVR_ERROR CMyInstance::GetTimerTypes(std::vector<kodi::addon::PVRTimerType>& types)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetTimersAmount(int& amount)
{
   return PVR_ERROR_NOT_IMPLEMENTED; 
}
 
PVR_ERROR CMyInstance::GetTimers(kodi::addon::PVRTimersResultSet& results)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::AddTimer(const kodi::addon::PVRTimer& timer)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::DeleteTimer(const kodi::addon::PVRTimer& timer, bool forceDelete)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::UpdateTimer(const kodi::addon::PVRTimer& timer)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::CallTimerMenuHook(const kodi::addon::PVRMenuhook& menuhook, const kodi::addon::PVRTimer& item)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}

Modules
	Group header include
	Group source include

Function Documentation

GetTimerTypes()

virtual PVR_ERROR GetTimerTypes ( std::vector< kodi::addon::PVRTimerType > &  types )

inlinevirtual

Retrieve the timer types supported by the backend.

Parameters

[out]

types

The function has to write the definition of the class PVRTimerType types into this array.

Returns

PVR_ERROR_NO_ERROR if the types were successfully written to the array.

Note

Maximal 32 entries are allowed inside.

---

The following table contains values that can be set with class PVRTimerType :

Name	Type	Set call	Get call	Usage
Identifier	unsigned int	SetId	GetId	required to set
Attributes	unsigned int	SetAttributes	GetAttributes	required to set
Description	std::string	SetDescription	GetDescription	optional
Priority selection	PVRTypeIntValue	SetPriorities	GetPriorities	optional
Priority default selection	int	SetPrioritiesDefault	GetPrioritiesDefault	optional
Lifetime selection	PVRTypeIntValue	SetLifetimes	GetLifetimes	optional
Lifetime default selection	int	SetLifetimesDefault	GetLifetimesDefault	optional
Prevent duplicate episodes selection	PVRTypeIntValue	SetPreventDuplicateEpisodes	GetPreventDuplicateEpisodes	optional
Prevent duplicate episodes default	int	SetPreventDuplicateEpisodesDefault	GetPreventDuplicateEpisodesDefault	optional
Recording group selection	PVRTypeIntValue	SetRecordingGroups	GetRecordingGroups	optional
Recording group default	int	SetRecordingGroupDefault	GetRecordingGroupDefault	optional
Max recordings selection	PVRTypeIntValue	SetMaxRecordings	GetMaxRecordings	optional
Max recordings default	int	SetMaxRecordingsDefault	GetMaxRecordingsDefault	optional

GetTimersAmount()

virtual PVR_ERROR GetTimersAmount ( int &  amount )

inlinevirtual

To get total amount of timers on the backend or -1 on error.

Parameters

[out]

amount

The total amount of timers on the backend

Returns

PVR_ERROR_NO_ERROR if the amount has been fetched successfully.

Note

Required to use if supportsTimers is set to true.

GetTimers()

virtual PVR_ERROR GetTimers ( kodi::addon::PVRTimersResultSet &  results )

inlinevirtual

Request the list of all timers from the backend if supported.

Parameters

[out]

results

List of available timers with class PVRTimer becomes transferred with class PVRTimersResultSet and given to Kodi

Returns

PVR_ERROR_NO_ERROR if the list has been fetched successfully.

Note

Required to use if supportsTimers is set to true.

---

The following table contains values that can be set with class PVRTimer :

Name	Type	Set call	Get call	Usage
Client index	unsigned int	SetClientIndex	GetClientIndex	required to set
State	PVR_TIMER_STATE	SetState	GetState	required to set
Type	unsigned int	SetTimerType	GetTimerType	required to set
Title	std::string	SetTitle	GetTitle	required to set
Parent client index	unsigned int	SetParentClientIndex	GetParentClientIndex	optional
Client channel unique identifier	int	SetClientChannelUid	GetClientChannelUid	optional
Start time	time_t	SetStartTime	GetStartTime	optional
End time	time_t	SetEndTime	GetEndTime	optional
Start any time	bool	SetStartAnyTime	GetStartAnyTime	optional
End any time	bool	SetEndAnyTime	GetEndAnyTime	optional
EPG search string	std::string	SetEPGSearchString	GetEPGSearchString	optional
Full text EPG search	bool	SetFullTextEpgSearch	GetFullTextEpgSearch	optional
Recording store directory	std::string	SetDirectory	GetDirectory	optional
Timer priority	int	SetPriority	GetPriority	optional
Timer lifetime	int	SetLifetime	GetLifetime	optional
Max recordings	int	SetMaxRecordings	GetMaxRecordings	optional
Recording group	unsigned int	SetRecordingGroup	GetRecordingGroup	optional
First start day	time_t	SetFirstDay	GetFirstDay	optional
Used timer weekdays	unsigned int	SetWeekdays	GetWeekdays	optional
Prevent duplicate episodes	unsigned int	SetPreventDuplicateEpisodes	GetPreventDuplicateEpisodes	optional
EPG unique identifier	unsigned int	SetEPGUid	GetEPGUid	optional
Margin start	unsigned int	SetMarginStart	GetMarginStart	optional
Margin end	unsigned int	SetMarginEnd	GetMarginEnd	optional
Genre type	int	SetGenreType	GetGenreType	optional
Genre sub type	int	SetGenreSubType	GetGenreSubType	optional
Series link	std::string	SetSeriesLink	GetSeriesLink	optional

---

Example:

...
PVR_ERROR CMyPVRInstance::GetTimers(kodi::addon::PVRTimersResultSet& results)
{
  // Minimal demo example, in reality bigger and loop to transfer all
  kodi::addon::PVRTimer timer;
  timer.SetClientIndex(123);
  timer.SetState(PVR_TIMER_STATE_SCHEDULED);
  timer.SetTitle("My timer name");
  ...
 
  // Give it now to Kodi
  results.Add(timer);
  return PVR_ERROR_NO_ERROR;
}
...

AddTimer()

virtual PVR_ERROR AddTimer ( const kodi::addon::PVRTimer &  timer )

inlinevirtual

Add a timer on the backend.

Parameters

[in]

timer

The timer to add.

Returns

PVR_ERROR_NO_ERROR if the timer has been added successfully.

Note

Required to use if supportsTimers is set to true.

DeleteTimer()

virtual PVR_ERROR DeleteTimer ( const kodi::addon::PVRTimer &  timer, bool  forceDelete  )

inlinevirtual

Delete a timer on the backend.

Parameters

[in]	timer	The timer to delete.
[in]	forceDelete	Set to true to delete a timer that is currently recording a program.

Returns

PVR_ERROR_NO_ERROR if the timer has been deleted successfully.

Note

Required to use if supportsTimers is set to true.

UpdateTimer()

virtual PVR_ERROR UpdateTimer ( const kodi::addon::PVRTimer &  timer )

inlinevirtual

Update the timer information on the backend.

Parameters

[in]

timer

The timer to update.

Returns

PVR_ERROR_NO_ERROR if the timer has been updated successfully.

Note

Required to use if supportsTimers is set to true.

CallTimerMenuHook()

virtual PVR_ERROR CallTimerMenuHook ( const kodi::addon::PVRMenuhook &  menuhook, const kodi::addon::PVRTimer &  item  )

inlinevirtual

Call one of the timer related menu hooks (if supported).

Supported class PVRMenuhook instances have to be added in constructor(), by calling AddMenuHook() on the callback.

Parameters

[in]	menuhook	The hook to call.
[in]	item	The selected timer item for which the hook was called.

Returns

PVR_ERROR_NO_ERROR if the hook was called successfully.

---

The following table contains values that can be set with class PVRMenuhook :

Name	Type	Set call	Get call	Usage
This hook's identifier	unsigned int	SetHookId	GetHookId	required to set
Localized string Identifier	unsigned int	SetLocalizedStringId	GetLocalizedStringId	required to set
Category of menu hook	PVR_MENUHOOK_CAT	SetCategory	GetCategory	required to set

TriggerTimerUpdate()

void TriggerTimerUpdate ( )

inline

Callback to Kodi Function
Request Kodi to update it's list of timers.

Remarks

Only called from addon itself