Kodi Development  19.0
for Binary and Script based Add-Ons
1. Basic functions
C++ » Interface - kodi::addon » Addon type instances » PVR

Detailed Description

Functions to manage the addon and get basic information about it
These are e.g. GetCapabilities to know supported groups at this addon or the others to get information about the source of the PVR stream.

The with "Valid implementation required." declared functions are mandatory, all others are an option.

Basic 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

◆ CInstancePVRClient() [1/2]

CInstancePVRClient ( )
inline

PVR client class constructor.

Used by an add-on that only supports only PVR and only in one instance.

Here's example about the use of this:

#include <kodi/addon-instance/PVR.h>
...
class ATTRIBUTE_HIDDEN CPVRExample
: public kodi::addon::CAddonBase,
public kodi::addon::CInstancePVRClient
{
public:
CPVRExample()
{
}
~CPVRExample() override;
{
}
...
};
ADDONCREATOR(CPVRExample)

◆ CInstancePVRClient() [2/2]

CInstancePVRClient ( KODI_HANDLE  instance,
const std::string &  kodiVersion = "" 
)
inlineexplicit

PVR client class constructor used to support multiple instance types.

Parameters
[in]instanceThe instance value given to kodi::addon::CAddonBase::CreateInstance(...).
[in]kodiVersion[opt] Version used in Kodi for this instance, to allow compatibility to older Kodi versions.
Note
Recommended to set kodiVersion.

Here's example about the use of this:

class CMyPVRClient : public ::kodi::addon::CInstancePVRClient
{
public:
CMyPVRClient(KODI_HANDLE instance, const std::string& kodiVersion)
: CInstancePVRClient(instance, kodiVersion)
{
...
}
...
};
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
const std::string& instanceID,
KODI_HANDLE instance,
const std::string& version,
KODI_HANDLE& addonInstance)
{
kodi::Log(ADDON_LOG_INFO, "Creating my PVR client instance");
addonInstance = new CMyPVRClient(instance, version);
return ADDON_STATUS_OK;
}

◆ ~CInstancePVRClient()

~CInstancePVRClient ( )
overridedefault

Destructor.

◆ GetCapabilities()

virtual PVR_ERROR GetCapabilities ( kodi::addon::PVRCapabilities &  capabilities)
pure virtual

Get the list of features that this add-on provides.

Called by Kodi to query the add-on's capabilities. Used to check which options should be presented in the UI, which methods to call, etc. All capabilities that the add-on supports should be set to true.

Parameters
capabilitiesThe with class PVRCapabilities defined add-on's capabilities.
Returns
PVR_ERROR_NO_ERROR if the properties were fetched successfully.

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

Name Type Set call Get call
Supports EPG boolean SetSupportsEPG GetSupportsEPG
Supports EPG EDL boolean SetSupportsEPGEdl GetSupportsEPGEdl
Supports TV boolean SetSupportsTV GetSupportsTV
Supports radio boolean SetSupportsRadio GetSupportsRadio
Supports recordings boolean SetSupportsRecordings GetSupportsRecordings
Supports recordings undelete boolean SetSupportsRecordingsUndelete SetSupportsRecordingsUndelete
Supports timers boolean SetSupportsTimers GetSupportsTimers
Supports channel groups boolean SetSupportsChannelGroups GetSupportsChannelGroups
Supports channel scan boolean SetSupportsChannelScan GetSupportsChannelScan
Supports channel settings boolean SetSupportsChannelSettings GetSupportsChannelSettings
Handles input stream boolean SetHandlesInputStream GetHandlesInputStream
Handles demuxing boolean SetHandlesDemuxing GetHandlesDemuxing
Supports recording play count boolean SetSupportsRecordingPlayCount GetSupportsRecordingPlayCount
Supports last played position boolean SetSupportsLastPlayedPosition GetSupportsLastPlayedPosition
Supports recording EDL boolean SetSupportsRecordingEdl GetSupportsRecordingEdl
Supports recordings rename boolean SetSupportsRecordingsRename GetSupportsRecordingsRename
Supports recordings lifetime change boolean SetSupportsRecordingsLifetimeChange GetSupportsRecordingsLifetimeChange
Supports descramble info boolean SetSupportsDescrambleInfo GetSupportsDescrambleInfo
Supports async EPG transfer boolean SetSupportsAsyncEPGTransfer GetSupportsAsyncEPGTransfer
Supports recording size boolean SetSupportsRecordingSize GetSupportsRecordingSize
Recordings lifetime values PVRTypeIntValue SetRecordingsLifetimeValues GetRecordingsLifetimeValues
Warning
This class can not be used outside of kodi::addon::CInstancePVRClient::GetCapabilities()

Example:

PVR_ERROR CMyPVRClient::GetCapabilities(kodi::addon::PVRCapabilities& capabilities)
{
capabilities.SetSupportsTV(true);
capabilities.SetSupportsEPG(true);
return PVR_ERROR_NO_ERROR;
}
Note
Valid implementation required.

◆ GetBackendName()

virtual PVR_ERROR GetBackendName ( std::string &  name)
pure virtual

Get the name reported by the backend that will be displayed in the UI.

Parameters
[out]nameThe name reported by the backend that will be displayed in the UI.
Returns
PVR_ERROR_NO_ERROR if successfully done

Example:

PVR_ERROR CMyPVRClient::GetBackendName(std::string& name)
{
name = "My special PVR client";
return PVR_ERROR_NO_ERROR;
}
Note
Valid implementation required.

◆ GetBackendVersion()

virtual PVR_ERROR GetBackendVersion ( std::string &  version)
pure virtual

Get the version string reported by the backend that will be displayed in the UI.

Parameters
[out]versionThe version string reported by the backend that will be displayed in the UI.
Returns
PVR_ERROR_NO_ERROR if successfully done

Example:

PVR_ERROR CMyPVRClient::GetBackendVersion(std::string& version)
{
version = "1.0.0";
return PVR_ERROR_NO_ERROR;
}
Note
Valid implementation required.

◆ GetBackendHostname()

virtual PVR_ERROR GetBackendHostname ( std::string &  hostname)
inlinevirtual

Get the hostname of the pvr backend server.

Parameters
[out]hostnameHostname as ip address or alias. If backend does not utilize a server, return empty string.
Returns
PVR_ERROR_NO_ERROR if successfully done

◆ GetConnectionString()

virtual PVR_ERROR GetConnectionString ( std::string &  connection)
inlinevirtual

To get the connection string reported by the backend that will be displayed in the UI.

Parameters
[out]connectionThe connection string reported by the backend that will be displayed in the UI.
Returns
PVR_ERROR_NO_ERROR if successfully done

◆ GetDriveSpace()

virtual PVR_ERROR GetDriveSpace ( uint64_t &  total,
uint64_t &  used 
)
inlinevirtual

Get the disk space reported by the backend (if supported).

Parameters
[in]totalThe total disk space in bytes.
[in]usedThe used disk space in bytes.
Returns
PVR_ERROR_NO_ERROR if the drive space has been fetched successfully.

Example:

PVR_ERROR CMyPVRClient::GetDriveSpace(uint64_t& total, uint64_t& used)
{
total = 10 * 1024 * 1024 * 1024; // To set complete size of drive in bytes
used = 122324243; // To set the used amount
return PVR_ERROR_NO_ERROR;
}

◆ CallSettingsMenuHook()

virtual PVR_ERROR CallSettingsMenuHook ( const kodi::addon::PVRMenuhook &  menuhook)
inlinevirtual

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

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

Parameters
[in]menuhookThe hook to call.
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

Example:

PVR_ERROR CMyPVRClient::CallSettingsMenuHook(const kodi::addon::PVRMenuhook& menuhook)
{
if (menuhook.GetHookId() == 2)
kodi::QueueNotification(QUEUE_INFO, "", kodi::GetLocalizedString(menuhook.GetLocalizedStringId()));
return PVR_ERROR_NO_ERROR;
}

◆ AddMenuHook()

void AddMenuHook ( const kodi::addon::PVRMenuhook &  hook)
inline

Callback to Kodi Function\nAdd or replace a menu hook for the context menu for this add-on

This is a callback function, called from addon to give Kodi his context menu's.

Parameters
[in]menuhookThe with class PVRMenuhook defined hook to add
Remarks
Only called from addon itself

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

Here's an example of the use of it:

#include <kodi/addon-instance/PVR.h>
...
{
kodi::addon::PVRMenuhook hook;
hook.SetHookId(1);
hook.SetCategory(PVR_MENUHOOK_CHANNEL);
hook.SetLocalizedStringId(30000);
AddMenuHook(hook);
}
{
kodi::addon::PVRMenuhook hook;
hook.SetHookId(2);
hook.SetCategory(PVR_MENUHOOK_SETTING);
hook.SetLocalizedStringId(30001);
AddMenuHook(hook);
}
...

Here another way:

#include <kodi/addon-instance/PVR.h>
...
AddMenuHook(kodi::addon::PVRMenuhook(1, 30000, PVR_MENUHOOK_CHANNEL));
AddMenuHook(kodi::addon::PVRMenuhook(2, 30001, PVR_MENUHOOK_SETTING));
...

◆ ConnectionStateChange()

void ConnectionStateChange ( const std::string &  connectionString,
PVR_CONNECTION_STATE  newState,
const std::string &  message 
)
inline

Callback to Kodi Function
Notify a state change for a PVR backend connection.

Parameters
[in]connectionStringThe connection string reported by the backend that can be displayed in the UI.
[in]newStateThe by PVR_CONNECTION_STATE defined new state.
[in]messageA localized addon-defined string representing the new state, that can be displayed in the UI or empty if the Kodi-defined default string for the new state shall be displayed.
Remarks
Only called from addon itself

Here's an example of the use of it:

#include <kodi/addon-instance/PVR.h>
#include <kodi/General.h> /* for kodi::GetLocalizedString(...) *&zwj;/
...
ConnectionStateChange("PVR demo connection lost", PVR_CONNECTION_STATE_DISCONNECTED, kodi::GetLocalizedString(30005, "Lost connection to Server"););
...

◆ UserPath()

std::string UserPath ( ) const
inline

Callback to Kodi Function
Get user data path of the PVR addon.

Returns
Path of current Kodi user
Remarks
Only called from addon itself
Note
Alternatively, kodi::GetAddonPath() can be used for this.

◆ ClientPath()

std::string ClientPath ( ) const
inline

Callback to Kodi Function
Get main client path of the PVR addon.

Returns
Path of addon client
Remarks
Only called from addon itself.
Note
Alternatively, kodi::GetBaseUserPath() can be used for this.
PVR_ERROR_NO_ERROR
@ PVR_ERROR_NO_ERROR
0 : No error occurred.
Definition: pvr_general.h:44
kodi::addon::CInstancePVRClient::CInstancePVRClient
CInstancePVRClient()
PVR client class constructor.
Definition: PVR.h:442
kodi::Log
void ATTRIBUTE_HIDDEN Log(const AddonLog loglevel, const char *format,...)
Add a message to Kodi's log.
Definition: AddonBase.h:696
ADDON_LOG_INFO
@ ADDON_LOG_INFO
1 : To include information messages in the log file.
Definition: addon_base.h:129
kodi::addon::PVRCapabilities::SetSupportsEPG
void SetSupportsEPG(bool supportsEPG)
Set true if the add-on provides EPG information.
Definition: General.h:160
kodi::addon::PVRMenuhook::GetHookId
unsigned int GetHookId() const
To get with SetHookId() changed values.
Definition: MenuHook.h:100
kodi::addon::PVRMenuhook::SetCategory
void SetCategory(PVR_MENUHOOK_CAT category)
required Category of menu hook.
Definition: MenuHook.h:114
kodi::addon::CInstancePVRClient::AddMenuHook
void AddMenuHook(const kodi::addon::PVRMenuhook &hook)
Callback to Kodi Function\nAdd or replace a menu hook for the context menu for this add-on
Definition: PVR.h:732
kodi::QueueNotification
void ATTRIBUTE_HIDDEN QueueNotification(QueueMsg type, const std::string &header, const std::string &message, const std::string &imageFile="", unsigned int displayTime=5000, bool withSound=true, unsigned int messageTime=1000)
Queue a notification in the GUI.
Definition: General.h:374
kodi::addon::PVRMenuhook::GetLocalizedStringId
unsigned int GetLocalizedStringId() const
To get with SetLocalizedStringId() changed values.
Definition: MenuHook.h:110
kodi::addon::PVRCapabilities
Definition: General.h:116
kodi::addon::PVRCapabilities::SetSupportsTV
void SetSupportsTV(bool supportsTV)
Set true if this add-on provides TV channels.
Definition: General.h:173
PVR_MENUHOOK_SETTING
@ PVR_MENUHOOK_SETTING
6 : For settings.
Definition: pvr_menu_hook.h:54
QUEUE_INFO
@ QUEUE_INFO
Show info notification message.
Definition: general.h:47
kodi::addon::CAddonBase
Add-on main instance class.
Definition: AddonBase.h:316
kodi::addon::PVRMenuhook::SetLocalizedStringId
void SetLocalizedStringId(unsigned int localizedStringId)
required The id of the label for this hook in kodi::GetLocalizedString().
Definition: MenuHook.h:104
kodi::GetLocalizedString
std::string ATTRIBUTE_HIDDEN GetLocalizedString(uint32_t labelId, const std::string &defaultStr="")
Returns an addon's localized 'unicode string'.
Definition: General.h:137
kodi::addon::PVRMenuhook::SetHookId
void SetHookId(unsigned int hookId)
required This hook's identifier.
Definition: MenuHook.h:97
ADDON_STATUS
ADDON_STATUS
Return value of functions in kodi::addon::CAddonBase and associated classes.
Definition: addon_base.h:80
ADDON_STATUS_OK
@ ADDON_STATUS_OK
For everything OK and no error.
Definition: addon_base.h:82
kodi::addon::CInstancePVRClient
Definition: PVR.h:385
PVR_ERROR
PVR_ERROR
Definition: pvr_general.h:42
PVR_MENUHOOK_CHANNEL
@ PVR_MENUHOOK_CHANNEL
1 : For channels.
Definition: pvr_menu_hook.h:39
kodi::addon::PVRMenuhook
Definition: MenuHook.h:46