5. Recordings (optional)

Detailed Description

PVR recording methods
To transfer available recordings of the PVR backend and to allow possible playback.

Remarks

Only used by Kodi if supportsRecordings is set to true.

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

---

Recordings 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 GetRecordingsAmount(bool deleted, int& amount) override;
PVR_ERROR GetRecordings(bool deleted, kodi::addon::PVRRecordingsResultSet& results) override;
PVR_ERROR DeleteRecording(const kodi::addon::PVRRecording& recording) override;
PVR_ERROR UndeleteRecording(const kodi::addon::PVRRecording& recording) override;
PVR_ERROR DeleteAllRecordingsFromTrash() override;
PVR_ERROR RenameRecording(const kodi::addon::PVRRecording& recording) override;
PVR_ERROR SetRecordingLifetime(const kodi::addon::PVRRecording& recording) override;
PVR_ERROR SetRecordingPlayCount(const kodi::addon::PVRRecording& recording, int count) override;
PVR_ERROR SetRecordingLastPlayedPosition(const kodi::addon::PVRRecording& recording, int lastplayedposition) override;
PVR_ERROR GetRecordingLastPlayedPosition(const kodi::addon::PVRRecording& recording, int& position) override;
PVR_ERROR GetRecordingEdl(const kodi::addon::PVRRecording& recording, std::vector<kodi::addon::PVREDLEntry>& edl) override;
PVR_ERROR GetRecordingSize(const kodi::addon::PVRRecording& recording, int64_t& size) override;
PVR_ERROR GetRecordingStreamProperties(const kodi::addon::PVRRecording& recording, std::vector<kodi::addon::PVRStreamProperty>& properties) override;
PVR_ERROR CallRecordingMenuHook(const kodi::addon::PVRMenuhook& menuhook, const kodi::addon::PVRRecording& item) override;

Source parts:

PVR_ERROR CMyInstance::GetRecordingsAmount(bool deleted, int& amount)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetRecordings(bool deleted, kodi::addon::PVRRecordingsResultSet& results)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::DeleteRecording(const kodi::addon::PVRRecording& recording)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::UndeleteRecording(const kodi::addon::PVRRecording& recording)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::DeleteAllRecordingsFromTrash()
{
   return PVR_ERROR_NOT_IMPLEMENTED; 
}
 
PVR_ERROR CMyInstance::RenameRecording(const kodi::addon::PVRRecording& recording)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::SetRecordingLifetime(const kodi::addon::PVRRecording& recording)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::SetRecordingPlayCount(const kodi::addon::PVRRecording& recording, int count)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::SetRecordingLastPlayedPosition(const kodi::addon::PVRRecording& recording, int lastplayedposition)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetRecordingLastPlayedPosition(const kodi::addon::PVRRecording& recording, int& position)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetRecordingEdl(const kodi::addon::PVRRecording& recording, std::vector<kodi::addon::PVREDLEntry>& edl)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetRecordingSize(const kodi::addon::PVRRecording& recording, int64_t& size)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetRecordingStreamProperties(const kodi::addon::PVRRecording& recording, std::vector<kodi::addon::PVRStreamProperty>& properties)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::CallRecordingMenuHook(const kodi::addon::PVRMenuhook& menuhook, const kodi::addon::PVRRecording& item)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}

Modules
	Group header include
	Group source include

Function Documentation

GetRecordingsAmount()

virtual PVR_ERROR GetRecordingsAmount ( bool  deleted, int &  amount  )

inlinevirtual

To get amount of recording present on backend.

Parameters

[in]	deleted	if set return deleted recording (called if supportsRecordingsUndelete set to true)
[out]	amount	The total amount of recordings on the backend

Returns

PVR_ERROR_NO_ERROR if the amount has been fetched successfully.

Remarks

Optional, and only used if supportsRecordings is set to true.

GetRecordings()

virtual PVR_ERROR GetRecordings ( bool  deleted, kodi::addon::PVRRecordingsResultSet &  results  )

inlinevirtual

Request the list of all recordings from the backend, if supported.

Recording entries are added to Kodi by calling TransferRecordingEntry() on the callback.

Parameters

[in]	deleted	if set return deleted recording (called if supportsRecordingsUndelete set to true)
[out]	results	List of available recordings with class PVRRecording becomes transferred with class PVRRecordingsResultSet and given to Kodi

Returns

PVR_ERROR_NO_ERROR if the recordings have been fetched successfully.

Remarks

Optional, and only used if supportsRecordings is set to true.

---

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

Name	Type	Set call	Get call	Usage
Recording id	std::string	SetRecordingId	GetRecordingId	required to set
Title	std::string	SetTitle	GetTitle	required to set
Episode name	std::string	SetEpisodeName	GetEpisodeName	optional
Series number	int	SetSeriesNumber	GetSeriesNumber	optional
Episode number	int	SetEpisodeNumber	GetEpisodeNumber	optional
Year	int	SetYear	GetYear	optional
Directory	std::string	SetDirectory	GetDirectory	optional
Plot outline	std::string	SetPlotOutline	GetPlotOutline	optional
Plot	std::string	SetPlot	GetPlot	optional
Genre description	std::string	SetGenreDescription	GetGenreDescription	optional
Channel name	std::string	SetChannelName	GetChannelName	optional
Icon path	std::string	SetIconPath	GetIconPath	optional
Thumbnail path	std::string	SetThumbnailPath	GetThumbnailPath	optional
Fanart path	std::string	SetFanartPath	GetFanartPath	optional
Recording time	time_t	SetRecordingTime	GetRecordingTime	optional
Duration	int	SetDuration	GetDuration	optional
Priority	int	SetPriority	GetPriority	optional
Lifetime	int	SetLifetime	GetLifetime	optional
Genre type	int	SetGenreType	GetGenreType	optional
Genre sub type	int	SetGenreSubType	GetGenreSubType	optional
Play count	int	SetPlayCount	GetPlayCount	optional
Last played position	int	SetLastPlayedPosition	GetLastPlayedPosition	optional
Is deleted	bool	SetIsDeleted	GetIsDeleted	optional
EPG event id	unsigned int	SetEPGEventId	GetEPGEventId	optional
Channel unique id	int	SetChannelUid	GetChannelUid	optional
Channel type	PVR_RECORDING_CHANNEL_TYPE	SetChannelType	GetChannelType	optional
First aired	std::string	SetFirstAired	GetFirstAired	optional
Flags	std::string	SetFlags	GetFlags	optional
Size in bytes	std::string	SetSizeInBytes	GetSizeInBytes	optional
Client provider unique identifier	int	SetClientProviderUid	GetClientProviderUid	optional
Provider name	std::string	SetProviderlName	GetProviderName	optional

---

Example:

...
PVR_ERROR CMyPVRInstance::GetRecordings(bool deleted, kodi::addon::PVRRecordingsResultSet& results)
{
  // Minimal demo example, in reality bigger and loop to transfer all
  kodi::addon::PVRRecording recording;
  recording.SetRecordingId(123);
  recording.SetTitle("My recording name");
  ...
 
  // Give it now to Kodi
  results.Add(recording);
  return PVR_ERROR_NO_ERROR;
}
...

DeleteRecording()

virtual PVR_ERROR DeleteRecording ( const kodi::addon::PVRRecording &  recording )

inlinevirtual

Delete a recording on the backend.

Parameters

[in]

recording

The class PVRRecording to delete.

Returns

PVR_ERROR_NO_ERROR if the recording has been deleted successfully.

Remarks

Optional, and only used if supportsRecordings is set to true.

UndeleteRecording()

virtual PVR_ERROR UndeleteRecording ( const kodi::addon::PVRRecording &  recording )

inlinevirtual

Undelete a recording on the backend.

Parameters

[in]

recording

The class PVRRecording to undelete.

Returns

PVR_ERROR_NO_ERROR if the recording has been undeleted successfully.

Remarks

Optional, and only used if supportsRecordingsUndelete is set to true.

DeleteAllRecordingsFromTrash()

virtual PVR_ERROR DeleteAllRecordingsFromTrash ( )

inlinevirtual

Delete all recordings permanent which in the deleted folder on the backend.

Returns

PVR_ERROR_NO_ERROR if the recordings has been deleted successfully.

RenameRecording()

virtual PVR_ERROR RenameRecording ( const kodi::addon::PVRRecording &  recording )

inlinevirtual

Rename a recording on the backend.

Parameters

[in]

recording

The class PVRRecording to rename, containing the new name.

Returns

PVR_ERROR_NO_ERROR if the recording has been renamed successfully.

Remarks

Optional, and only used if supportsRecordings is set to true.

SetRecordingLifetime()

virtual PVR_ERROR SetRecordingLifetime ( const kodi::addon::PVRRecording &  recording )

inlinevirtual

Set the lifetime of a recording on the backend.

Parameters

[in]

recording

The class PVRRecording to change the lifetime for. recording.iLifetime contains the new lieftime value.

Returns

PVR_ERROR_NO_ERROR if the recording's lifetime has been set successfully.

Remarks

Required if supportsRecordingsLifetimeChange is set to true.

SetRecordingPlayCount()

virtual PVR_ERROR SetRecordingPlayCount ( const kodi::addon::PVRRecording &  recording, int  count  )

inlinevirtual

Set the play count of a recording on the backend.

Parameters

[in]	recording	The class PVRRecording to change the play count.
[in]	count	Play count.

Returns

PVR_ERROR_NO_ERROR if the recording's play count has been set successfully.

Remarks

Required if supportsRecordingPlayCount is set to true.

SetRecordingLastPlayedPosition()

virtual PVR_ERROR SetRecordingLastPlayedPosition ( const kodi::addon::PVRRecording &  recording, int  lastplayedposition  )

inlinevirtual

Set the last watched position of a recording on the backend.

Parameters

[in]	recording	The class PVRRecording.
[in]	lastplayedposition	The last watched position in seconds

Returns

PVR_ERROR_NO_ERROR if the position has been stored successfully.

Remarks

Required if supportsLastPlayedPosition is set to true.

GetRecordingLastPlayedPosition()

virtual PVR_ERROR GetRecordingLastPlayedPosition ( const kodi::addon::PVRRecording &  recording, int &  position  )

inlinevirtual

Retrieve the last watched position of a recording on the backend.

Parameters

[in]	recording	The class PVRRecording.
[out]	position	The last watched position in seconds

Returns

PVR_ERROR_NO_ERROR if the amount has been fetched successfully.

Remarks

Required if supportsRecordingPlayCount is set to true.

GetRecordingEdl()

virtual PVR_ERROR GetRecordingEdl ( const kodi::addon::PVRRecording &  recording, std::vector< kodi::addon::PVREDLEntry > &  edl  )

inlinevirtual

Retrieve the edit decision list (EDL) of a recording on the backend.

Parameters

[in]	recording	The class PVRRecording.
[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 supportsRecordingEdl 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

GetRecordingSize()

virtual PVR_ERROR GetRecordingSize ( const kodi::addon::PVRRecording &  recording, int64_t &  size  )

inlinevirtual

Retrieve the size of a recording on the backend.

Parameters

[in]	recording	The recording to get the size in bytes for.
[out]	size	The size in bytes of the recording

Returns

PVR_ERROR_NO_ERROR if the recording's size has been set successfully.

Remarks

Required if supportsRecordingSize is set to true.

GetRecordingStreamProperties()

virtual PVR_ERROR GetRecordingStreamProperties ( const kodi::addon::PVRRecording &  recording, std::vector< kodi::addon::PVRStreamProperty > &  properties  )

inlinevirtual

Get the stream properties for a recording from the backend.

Parameters

[in]	recording	The class PVRRecording 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 supportsRecordings is set to true and the add-on does not implement recording stream functions (OpenRecordedStream, ...).
In this case your implementation must fill the property PVR_STREAM_PROPERTY_STREAMURL with the URL Kodi should resolve to playback the recording.

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::GetRecordingStreamProperties(const kodi::addon::PVRRecording& recording,
                                                       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;
}
...

CallRecordingMenuHook()

virtual PVR_ERROR CallRecordingMenuHook ( const kodi::addon::PVRMenuhook &  menuhook, const kodi::addon::PVRRecording &  item  )

inlinevirtual

Call one of the recording 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 recording 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

RecordingNotification()

void RecordingNotification ( const std::string &  recordingName, const std::string &  fileName, bool  on  )

inline

Callback to Kodi Function
Display a notification in Kodi that a recording started or stopped on the server.

Parameters

[in]	recordingName	The name of the recording to display
[in]	fileName	The filename of the recording
[in]	on	True when recording started, false when it stopped

Remarks

Only called from addon itself

TriggerRecordingUpdate()

void TriggerRecordingUpdate ( )

inline

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

Remarks

Only called from addon itself