4. EPG methods (optional)

PVR EPG methods
These C ++ class functions of are intended for processing EPG information and for giving it to Kodi. More...

Functions
virtual PVR_ERROR	kodi::addon::CInstancePVRClient::GetEPGForChannel (int channelUid, time_t start, time_t end, kodi::addon::PVREPGTagsResultSet &results)
	Request the EPG for a channel from the backend.
virtual PVR_ERROR	kodi::addon::CInstancePVRClient::IsEPGTagRecordable (const kodi::addon::PVREPGTag &tag, bool &isRecordable)
	Check if the given EPG tag can be recorded.
virtual PVR_ERROR	kodi::addon::CInstancePVRClient::IsEPGTagPlayable (const kodi::addon::PVREPGTag &tag, bool &isPlayable)
	Check if the given EPG tag can be played.
virtual PVR_ERROR	kodi::addon::CInstancePVRClient::GetEPGTagEdl (const kodi::addon::PVREPGTag &tag, std::vector< kodi::addon::PVREDLEntry > &edl)
	Retrieve the edit decision list (EDL) of an EPG tag on the backend.
virtual PVR_ERROR	kodi::addon::CInstancePVRClient::GetEPGTagStreamProperties (const kodi::addon::PVREPGTag &tag, std::vector< kodi::addon::PVRStreamProperty > &properties)
	Get the stream properties for an epg tag from the backend.
virtual PVR_ERROR	kodi::addon::CInstancePVRClient::SetEPGMaxPastDays (int pastDays)
	Tell the client the past time frame to use when notifying epg events back to Kodi.
virtual PVR_ERROR	kodi::addon::CInstancePVRClient::SetEPGMaxFutureDays (int futureDays)
	Tell the client the future time frame to use when notifying epg events back to Kodi.
virtual PVR_ERROR	kodi::addon::CInstancePVRClient::CallEPGMenuHook (const kodi::addon::PVRMenuhook &menuhook, const kodi::addon::PVREPGTag &tag)
	Call one of the EPG related menu hooks (if supported).
int	kodi::addon::CInstancePVRClient::EpgMaxPastDays () const
	Callback to Kodi Function Get the Max past days handled by Kodi.
int	kodi::addon::CInstancePVRClient::EpgMaxFutureDays () const
	Callback to Kodi Function Get the Max future days handled by Kodi.
void	kodi::addon::CInstancePVRClient::TriggerEpgUpdate (unsigned int channelUid)
	Callback to Kodi Function Schedule an EPG update for the given channel channel.
void	kodi::addon::CInstancePVRClient::EpgEventStateChange (kodi::addon::PVREPGTag &tag, EPG_EVENT_STATE newState)
	Callback to Kodi Function Notify a state change for an EPG event.

Detailed Description

PVR EPG methods
These C ++ class functions of are intended for processing EPG information and for giving it to Kodi.

The necessary data is transferred with class PVREPGTag.

Remarks

Only used by Kodi if supportsEPG is set to true.

---

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

Function Documentation

CallEPGMenuHook()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::CallEPGMenuHook ( const kodi::addon::PVRMenuhook & menuhook, const kodi::addon::PVREPGTag & tag )

inlinevirtual

Call one of the EPG 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]	tag	The selected EPG 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

EpgEventStateChange()

void kodi::addon::CInstancePVRClient::EpgEventStateChange ( kodi::addon::PVREPGTag & tag, EPG_EVENT_STATE newState )

inline

Callback to Kodi Function
Notify a state change for an EPG event.

Parameters

[in]	tag	The EPG tag where have event.
[in]	newState	The new state. For EPG_EVENT_CREATED and EPG_EVENT_UPDATED, tag must be filled with all available event data, not just a delta. For EPG_EVENT_DELETED, it is sufficient to fill kodi::addon::PVREPGTag::SetUniqueBroadcastId

Remarks

Only called from addon itself,

---

Example:

...
 
void CMyPVRInstance::MyProcessFunction()
{
  ...
  kodi::addon::PVREPGTag tag; // Here as mini add, in real it should be a complete tag
  tag.SetUniqueId(123);
 
  // added namespace here not needed to have, only to have more clear for where is
  kodi::addon::CInstancePVRClient::EpgEventStateChange(tag, EPG_EVENT_UPDATED);
  ...
}
 
...

EpgMaxFutureDays()

int kodi::addon::CInstancePVRClient::EpgMaxFutureDays ( ) const

inline

Callback to Kodi Function
Get the Max future days handled by Kodi.

If > EPG_TIMEFRAME_UNLIMITED, in async epg mode, deliver only events in the range from 'end time > now - EpgMaxPastDays()' to 'start time < now + EpgMaxFutureDays(). EPG_TIMEFRAME_UNLIMITED, notify all events.

Returns

The Max future days handled by Kodi

EpgMaxPastDays()

int kodi::addon::CInstancePVRClient::EpgMaxPastDays ( ) const

inline

Callback to Kodi Function
Get the Max past days handled by Kodi.

If > EPG_TIMEFRAME_UNLIMITED, in async epg mode, deliver only events in the range from 'end time > now - EpgMaxPastDays()' to 'start time < now + EpgMaxFutureDays(). EPG_TIMEFRAME_UNLIMITED, notify all events.

Returns

The Max past days handled by Kodi

GetEPGForChannel()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetEPGForChannel ( int channelUid, time_t start, time_t end, kodi::addon::PVREPGTagsResultSet & results )

inlinevirtual

Request the EPG for a channel from the backend.

Parameters

[in]	channelUid	The UID of the channel to get the EPG table for.
[in]	start	Get events after this time (UTC).
[in]	end	Get events before this time (UTC).
[out]	results	List where available EPG information becomes transferred with class PVREPGTag and given to Kodi

Returns

PVR_ERROR_NO_ERROR if the table has been fetched successfully.

---

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

Name	Type	Set call	Get call	Usage
Unique broadcast id	unsigned int	SetUniqueBroadcastId	GetUniqueBroadcastId	required to set
Unique channel id	unsigned int	SetUniqueChannelId	GetUniqueChannelId	required to set
Title	std::string	SetTitle	GetTitle	required to set
Start time	time_t	SetStartTime	GetStartTime	required to set
End time	time_t	SetEndTime	GetEndTime	required to set
Plot outline	std::string	SetPlotOutline	GetPlotOutline	optional
Plot	std::string	SetPlot	GetPlot	optional
Original title	std::string	SetOriginalTitle	GetOriginalTitle	optional
Cast	std::string	SetCast	GetCast	optional
Director	std::string	SetDirector	GetDirector	optional
Writer	std::string	SetWriter	GetWriter	optional
Year	int	SetYear	GetYear	optional
IMDB number	std::string	SetIMDBNumber	GetIMDBNumber	optional
Icon path	std::string	SetIconPath	GetIconPath	optional
Genre type	int	SetGenreType	GetGenreType	optional
Genre sub type	int	SetGenreSubType	GetGenreSubType	optional
Genre description	std::string	SetGenreDescription	GetGenreDescription	optional
First aired	time_t	SetFirstAired	GetFirstAired	optional
Parental rating	unsigned int	SetParentalRating	GetParentalRating	optional
Parental rating code	std::string	SetParentalRatingCode	GetParentalRatingCode	optional
Parental rating icon	std::string	SetParentalRatingIcon	GetParentalRatingIcon	optional
Parental rating source	std::string	SetParentalRatingSource	GetParentalRatingSource	optional
Star rating	int	SetStarRating	GetStarRating	optional
Series number	int	SetSeriesNumber	GetSeriesNumber	optional
Episode number	int	SetEpisodeNumber	GetEpisodeNumber	optional
Episode part number	int	SetEpisodePartNumber	GetEpisodePartNumber	optional
Episode name	std::string	SetEpisodeName	GetEpisodeName	optional
Flags	unsigned int	SetFlags	GetFlags	optional
Series link	std::string	SetSeriesLink	GetSeriesLink	optional

---

Remarks

Required if supportsEPG is set to true.

---

Example:

...
PVR_ERROR CMyPVRInstance::GetEPGForChannel(int channelUid,
                                           time_t start,
                                           time_t end,
                                           kodi::addon::PVREPGTagsResultSet& results)
{
  // Minimal demo example, in reality bigger, loop to transfer all and to
  // match wanted times.
  kodi::addon::PVREPGTag tag;
  tag.SetUniqueBroadcastId(123);
  tag.SetUniqueChannelId(123);
  tag.SetTitle("My epg entry name");
  tag.SetGenreType(EPG_EVENT_CONTENTMASK_MOVIEDRAMA);
  tag.SetStartTime(1589148283); // Seconds elapsed since 00:00 hours, Jan 1, 1970 UTC
  tag.SetEndTime(1589151913);
  ...
 
  // Give it now to Kodi
  results.Add(tag);
  return PVR_ERROR_NO_ERROR;
}
...

GetEPGTagEdl()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetEPGTagEdl ( const kodi::addon::PVREPGTag & tag, std::vector< kodi::addon::PVREDLEntry > & edl )

inlinevirtual

Retrieve the edit decision list (EDL) of an EPG tag on the backend.

Parameters

[in]	tag	The epg tag.
[out]	edl	The function has to write the EDL into this array.

Returns

PVR_ERROR_NO_ERROR if the EDL was successfully read or no EDL exists.

Remarks

Required if supportsEPGEdl is set to true.

---

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

Name	Type	Set call	Get call	Usage
Start time	int64_t	SetStart	GetStart	required to set
End time	int64_t	SetEnd	GetEnd	required to set
Type	PVR_EDL_TYPE	SetType	GetType	required to set

---

Remarks

Required if supportsEPGEdl is set to true.

GetEPGTagStreamProperties()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetEPGTagStreamProperties ( const kodi::addon::PVREPGTag & tag, std::vector< kodi::addon::PVRStreamProperty > & properties )

inlinevirtual

Get the stream properties for an epg tag from the backend.

Parameters

[in]	tag	The epg tag to get the stream properties for.
[out]	properties	the properties required to play the stream.

Returns

PVR_ERROR_NO_ERROR if the stream is available.

Remarks

Required if add-on supports playing epg tags. In this case your implementation must fill the property PVR_STREAM_PROPERTY_STREAMURL with the URL Kodi should resolve to playback the epg tag. It return PVR_ERROR_NOT_IMPLEMENTED from parent if this add-on won't provide this function.

Note

The value directly related to inputstream must always begin with the name of the associated add-on, e.g. "inputstream.adaptive.manifest_update_parameter".

---

Example:

...
PVR_ERROR CMyPVRInstance::GetEPGTagStreamProperties(const kodi::addon::PVREPGTag& tag,
                                                    std::vector<kodi::addon::PVRStreamProperty>& properties)
{
  ...
  properties.emplace_back(PVR_STREAM_PROPERTY_INPUTSTREAM, "inputstream.adaptive");
  properties.emplace_back("inputstream.adaptive.manifest_type", "mpd");
  properties.emplace_back("inputstream.adaptive.manifest_update_parameter", "full");
  properties.emplace_back(PVR_STREAM_PROPERTY_MIMETYPE, "application/xml+dash");
  return PVR_ERROR_NO_ERROR;
}
...

IsEPGTagPlayable()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::IsEPGTagPlayable ( const kodi::addon::PVREPGTag & tag, bool & isPlayable )

inlinevirtual

Check if the given EPG tag can be played.

Parameters

[in]	tag	the epg tag to check.
[out]	isPlayable	Set to true if the tag can be played.

Returns

PVR_ERROR_NO_ERROR if bIsPlayable has been set successfully.

Remarks

Required if add-on supports playing epg tags.

IsEPGTagRecordable()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::IsEPGTagRecordable ( const kodi::addon::PVREPGTag & tag, bool & isRecordable )

inlinevirtual

Check if the given EPG tag can be recorded.

Parameters

[in]	tag	the epg tag to check.
[out]	isRecordable	Set to true if the tag can be recorded.

Returns

PVR_ERROR_NO_ERROR if bIsRecordable has been set successfully.

Remarks

Optional, it return PVR_ERROR_NOT_IMPLEMENTED by parent to let Kodi decide.

SetEPGMaxFutureDays()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::SetEPGMaxFutureDays ( int futureDays )

inlinevirtual

Tell the client the future time frame to use when notifying epg events back to Kodi.

The client might push epg events asynchronously to Kodi using the callback function EpgEventStateChange. To be able to only push events that are actually of interest for Kodi, client needs to know about the epg time frame Kodi uses. Kodi supplies the current epg max future time frame value EpgMaxFutureDays() when creating the addon and calls SetEPGMaxFutureDays later whenever Kodi's epg time frame value changes.

Parameters

[in]

futureDays

number of days from "now". EPG_TIMEFRAME_UNLIMITED means that Kodi is interested in all epg events, regardless of event times.

Returns

PVR_ERROR_NO_ERROR if new value was successfully set.

Remarks

Required if supportsEPG is set to true.

SetEPGMaxPastDays()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::SetEPGMaxPastDays ( int pastDays )

inlinevirtual

Tell the client the past time frame to use when notifying epg events back to Kodi.

The client might push epg events asynchronously to Kodi using the callback function EpgEventStateChange. To be able to only push events that are actually of interest for Kodi, client needs to know about the epg time frame Kodi uses. Kodi supplies the current epg max past time frame value EpgMaxPastDays() when creating the addon and calls SetEPGMaxPastDays later whenever Kodi's epg time frame value changes.

Parameters

[in]

pastDays

number of days before "now". EPG_TIMEFRAME_UNLIMITED means that Kodi is interested in all epg events, regardless of event times.

Returns

PVR_ERROR_NO_ERROR if new value was successfully set.

Remarks

Required if supportsEPG is set to true.

TriggerEpgUpdate()

void kodi::addon::CInstancePVRClient::TriggerEpgUpdate ( unsigned int channelUid )

inline

Callback to Kodi Function
Schedule an EPG update for the given channel channel.

Parameters

[in]

channelUid

The unique id of the channel for this add-on

Remarks

Only called from addon itself