Kodi Development  20.0
for Binary and Script based Add-Ons
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 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;
Definition: MenuHook.h:46
Definition: Recordings.h:39
Definition: Recordings.h:512
PVR_ERROR
Definition: pvr_general.h:35
virtual PVR_ERROR CallRecordingMenuHook(const kodi::addon::PVRMenuhook &menuhook, const kodi::addon::PVRRecording &item)
Call one of the recording related menu hooks (if supported).
Definition: PVR.h:2015
virtual PVR_ERROR GetRecordings(bool deleted, kodi::addon::PVRRecordingsResultSet &results)
Request the list of all recordings from the backend, if supported.
Definition: PVR.h:1790
virtual PVR_ERROR RenameRecording(const kodi::addon::PVRRecording &recording)
Rename a recording on the backend.
Definition: PVR.h:1844
virtual PVR_ERROR GetRecordingSize(const kodi::addon::PVRRecording &recording, int64_t &size)
Retrieve the size of a recording on the backend.
Definition: PVR.h:1951
virtual PVR_ERROR SetRecordingLastPlayedPosition(const kodi::addon::PVRRecording &recording, int lastplayedposition)
Set the last watched position of a recording on the backend.
Definition: PVR.h:1896
virtual PVR_ERROR GetRecordingEdl(const kodi::addon::PVRRecording &recording, std::vector< kodi::addon::PVREDLEntry > &edl)
Retrieve the edit decision list (EDL) of a recording on the backend.
Definition: PVR.h:1934
virtual PVR_ERROR GetRecordingStreamProperties(const kodi::addon::PVRRecording &recording, std::vector< kodi::addon::PVRStreamProperty > &properties)
Get the stream properties for a recording from the backend.
Definition: PVR.h:1993
virtual PVR_ERROR GetRecordingsAmount(bool deleted, int &amount)
To get amount of recording present on backend.
Definition: PVR.h:1743
virtual PVR_ERROR SetRecordingLifetime(const kodi::addon::PVRRecording &recording)
Set the lifetime of a recording on the backend.
Definition: PVR.h:1862
virtual PVR_ERROR SetRecordingPlayCount(const kodi::addon::PVRRecording &recording, int count)
Set the play count of a recording on the backend.
Definition: PVR.h:1880
virtual PVR_ERROR UndeleteRecording(const kodi::addon::PVRRecording &recording)
Undelete a recording on the backend.
Definition: PVR.h:1820
virtual PVR_ERROR GetRecordingLastPlayedPosition(const kodi::addon::PVRRecording &recording, int &position)
Retrieve the last watched position of a recording on the backend.
Definition: PVR.h:1913
virtual PVR_ERROR DeleteAllRecordingsFromTrash()
Delete all recordings permanent which in the deleted folder on the backend.
Definition: PVR.h:1831
virtual PVR_ERROR DeleteRecording(const kodi::addon::PVRRecording &recording)
Delete a recording on the backend.
Definition: PVR.h:1805

Source parts:

PVR_ERROR CMyInstance::GetRecordingsAmount(bool deleted, int& amount)
{
}
PVR_ERROR CMyInstance::GetRecordings(bool deleted, kodi::addon::PVRRecordingsResultSet& results)
{
}
PVR_ERROR CMyInstance::DeleteRecording(const kodi::addon::PVRRecording& recording)
{
}
PVR_ERROR CMyInstance::UndeleteRecording(const kodi::addon::PVRRecording& recording)
{
}
PVR_ERROR CMyInstance::DeleteAllRecordingsFromTrash()
{
}
PVR_ERROR CMyInstance::RenameRecording(const kodi::addon::PVRRecording& recording)
{
}
PVR_ERROR CMyInstance::SetRecordingLifetime(const kodi::addon::PVRRecording& recording)
{
}
PVR_ERROR CMyInstance::SetRecordingPlayCount(const kodi::addon::PVRRecording& recording, int count)
{
}
PVR_ERROR CMyInstance::SetRecordingLastPlayedPosition(const kodi::addon::PVRRecording& recording, int lastplayedposition)
{
}
PVR_ERROR CMyInstance::GetRecordingLastPlayedPosition(const kodi::addon::PVRRecording& recording, int& position)
{
}
PVR_ERROR CMyInstance::GetRecordingEdl(const kodi::addon::PVRRecording& recording, std::vector<kodi::addon::PVREDLEntry>& edl)
{
}
PVR_ERROR CMyInstance::GetRecordingSize(const kodi::addon::PVRRecording& recording, int64_t& size)
{
}
PVR_ERROR CMyInstance::GetRecordingStreamProperties(const kodi::addon::PVRRecording& recording, std::vector<kodi::addon::PVRStreamProperty>& properties)
{
}
PVR_ERROR CMyInstance::CallRecordingMenuHook(const kodi::addon::PVRMenuhook& menuhook, const kodi::addon::PVRRecording& item)
{
}
@ PVR_ERROR_NOT_IMPLEMENTED
-2 : The method that Kodi called is not implemented by the add-on.
Definition: pvr_general.h:43

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]deletedif set return deleted recording (called if supportsRecordingsUndelete set to true)
[out]amountThe 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]deletedif set return deleted recording (called if supportsRecordingsUndelete set to true)
[out]resultsList 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
recording.SetRecordingId(123);
recording.SetTitle("My recording name");
...
// Give it now to Kodi
results.Add(recording);
}
...
@ PVR_ERROR_NO_ERROR
0 : No error occurred.
Definition: pvr_general.h:37
void SetTitle(const std::string &title)
required The title of this recording.
Definition: Recordings.h:120
void SetRecordingId(const std::string &recordingId)
required Unique identifier of the recording on the client.
Definition: Recordings.h:109
void Add(const kodi::addon::PVRRecording &tag)
To add and give content from addon to Kodi on related call.
Definition: Recordings.h:528

◆ DeleteRecording()

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

Delete a recording on the backend.

Parameters
[in]recordingThe 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]recordingThe 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]recordingThe 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]recordingThe 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]recordingThe class PVRRecording to change the play count.
[in]countPlay 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]recordingThe class PVRRecording.
[in]lastplayedpositionThe 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]recordingThe class PVRRecording.
[out]positionThe 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]recordingThe class PVRRecording.
[out]edlThe 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]recordingThe recording to get the size in bytes for.
[out]sizeThe 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]recordingThe class PVRRecording to get the stream properties for.
[out]propertiesThe 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");
}
...
#define PVR_STREAM_PROPERTY_MIMETYPE
the MIME type of the stream that should be played.
Definition: pvr_general.h:237
#define PVR_STREAM_PROPERTY_INPUTSTREAM
To define in stream properties the name of the inputstream add-on that should be used.
Definition: pvr_general.h:162

◆ 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]menuhookThe hook to call.
[in]itemThe 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]recordingNameThe name of the recording to display
[in]fileNameThe filename of the recording
[in]onTrue 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