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

◆ GetEPGForChannel()

virtual PVR_ERROR 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	`int`	SetParentalRating	GetParentalRating	optional
Parental rating code	`int`	SetParentalRatingCode	GetParentalRatingCode	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;
}
...

◆ IsEPGTagRecordable()

virtual PVR_ERROR 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.

◆ IsEPGTagPlayable()

virtual PVR_ERROR 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.

◆ GetEPGTagEdl()

virtual PVR_ERROR 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 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;
}
...

◆ SetEPGMaxPastDays()

virtual PVR_ERROR 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.

◆ SetEPGMaxFutureDays()

virtual PVR_ERROR 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.

◆ CallEPGMenuHook()

virtual PVR_ERROR 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

◆ EpgMaxPastDays()

int 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

◆ EpgMaxFutureDays()

int 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

◆ TriggerEpgUpdate()

void 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

◆ EpgEventStateChange()

void 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);
  ...
}
 
...