Kodi Docs 20.0
Kodi is an open source media player and entertainment hub.
Functions
1. Basic functions
C++ » Interface - kodi::addon » Addon type instances » PVR

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. More...

Functions

 kodi::addon::CInstancePVRClient::CInstancePVRClient ()
 PVR client class constructor. More...
 
 kodi::addon::CInstancePVRClient::CInstancePVRClient (KODI_HANDLE instance, const std::string &kodiVersion="")
 PVR client class constructor used to support multiple instance types. More...
 
 kodi::addon::CInstancePVRClient::~CInstancePVRClient () override=default
 Destructor. More...
 
virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetCapabilities (kodi::addon::PVRCapabilities &capabilities)=0
 Get the list of features that this add-on provides. More...
 
virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetBackendName (std::string &name)=0
 Get the name reported by the backend that will be displayed in the UI. More...
 
virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetBackendVersion (std::string &version)=0
 Get the version string reported by the backend that will be displayed in the UI. More...
 
virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetBackendHostname (std::string &hostname)
 Get the hostname of the pvr backend server. More...
 
virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetConnectionString (std::string &connection)
 To get the connection string reported by the backend that will be displayed in the UI. More...
 
virtual PVR_ERROR kodi::addon::CInstancePVRClient::GetDriveSpace (uint64_t &total, uint64_t &used)
 Get the disk space reported by the backend (if supported). More...
 
virtual PVR_ERROR kodi::addon::CInstancePVRClient::CallSettingsMenuHook (const kodi::addon::PVRMenuhook &menuhook)
 Call one of the settings related menu hooks (if supported). More...
 
void kodi::addon::CInstancePVRClient::AddMenuHook (const kodi::addon::PVRMenuhook &hook)
 Callback to Kodi Function\nAdd or replace a menu hook for the context menu for this add-on More...
 
void kodi::addon::CInstancePVRClient::ConnectionStateChange (const std::string &connectionString, PVR_CONNECTION_STATE newState, const std::string &message)
 Callback to Kodi Function
Notify a state change for a PVR backend connection. More...
 
std::string kodi::addon::CInstancePVRClient::UserPath () const
 Callback to Kodi Function
Get user data path of the PVR addon. More...
 
std::string kodi::addon::CInstancePVRClient::ClientPath () const
 Callback to Kodi Function
Get main client path of the PVR addon. More...
 

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

◆ AddMenuHook()

void kodi::addon::CInstancePVRClient::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);
}
...
kodi::addon::PVRMenuhook
Definition: MenuHook.h:46
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: addon-instance/PVR.h:755
PVR_MENUHOOK_CHANNEL
@ PVR_MENUHOOK_CHANNEL
1 : For channels.
Definition: pvr_menu_hook.h:37
PVR_MENUHOOK_SETTING
@ PVR_MENUHOOK_SETTING
6 : For settings.
Definition: pvr_menu_hook.h:52
kodi::addon::PVRMenuhook::SetHookId
void SetHookId(unsigned int hookId)
required This hook's identifier.
Definition: MenuHook.h:97
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::addon::PVRMenuhook::SetCategory
void SetCategory(PVR_MENUHOOK_CAT category)
required Category of menu hook.
Definition: MenuHook.h:114

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

◆ CallSettingsMenuHook()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::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;
}
QUEUE_INFO
@ QUEUE_INFO
Show info notification message.
Definition: kodi-dev-kit/include/kodi/c-api/General.h:45
PVR_ERROR
PVR_ERROR
Definition: pvr_general.h:35
PVR_ERROR_NO_ERROR
@ PVR_ERROR_NO_ERROR
0 : No error occurred.
Definition: pvr_general.h:37
kodi::addon::PVRMenuhook::GetHookId
unsigned int GetHookId() const
To get with SetHookId() changed values.
Definition: MenuHook.h:100
kodi::addon::PVRMenuhook::GetLocalizedStringId
unsigned int GetLocalizedStringId() const
To get with SetLocalizedStringId() changed values.
Definition: MenuHook.h:110
kodi::QueueNotification
void ATTR_DLL_LOCAL 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: kodi-dev-kit/include/kodi/General.h:375
kodi::GetLocalizedString
std::string ATTR_DLL_LOCAL GetLocalizedString(uint32_t labelId, const std::string &defaultStr="")
Returns an addon's localized 'unicode string'.
Definition: kodi-dev-kit/include/kodi/General.h:137

◆ CInstancePVRClient() [1/2]

kodi::addon::CInstancePVRClient::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 ATTR_DLL_LOCAL CPVRExample
: public kodi::addon::CAddonBase,
public kodi::addon::CInstancePVRClient
{
public:
CPVRExample()
{
}
~CPVRExample() override;
{
}
...
};
ADDONCREATOR(CPVRExample)
ATTR_DLL_LOCAL
#define ATTR_DLL_LOCAL
Definition: addon_base.h:81
kodi::addon::CAddonBase
Definition: kodi-dev-kit/include/kodi/AddonBase.h:332
kodi::addon::CInstancePVRClient
Definition: addon-instance/PVR.h:408
ADDONCREATOR
#define ADDONCREATOR(AddonClass)
Definition: kodi-dev-kit/include/kodi/AddonBase.h:1443

◆ CInstancePVRClient() [2/2]

kodi::addon::CInstancePVRClient::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;
}
KODI_HANDLE
void * KODI_HANDLE
Standard undefined pointer handle.
Definition: addon_base.h:199
ADDON_LOG_INFO
@ ADDON_LOG_INFO
1 : To include information messages in the log file.
Definition: addon_base.h:183
ADDON_STATUS
ADDON_STATUS
Definition: addon_base.h:134
ADDON_STATUS_OK
@ ADDON_STATUS_OK
For everything OK and no error.
Definition: addon_base.h:136
kodi::addon::CInstancePVRClient::CInstancePVRClient
CInstancePVRClient()
PVR client class constructor.
Definition: addon-instance/PVR.h:465
kodi::Log
void ATTR_DLL_LOCAL Log(const AddonLog loglevel, const char *format,...)
Add a message to Kodi's log.
Definition: kodi-dev-kit/include/kodi/AddonBase.h:758

◆ ClientPath()

std::string kodi::addon::CInstancePVRClient::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.

◆ ConnectionStateChange()

void kodi::addon::CInstancePVRClient::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"););
...

◆ GetBackendHostname()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::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

◆ GetBackendName()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::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 kodi::addon::CInstancePVRClient::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.

◆ GetCapabilities()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::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.

@ingroup cpp_kodi_addon_pvr_Defs_PVRCapabilities

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 providers boolean SetSupportsProviders GetSupportsProviders
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
Supports recordings delete boolean SetSupportsRecordingsDelete SetSupportsRecordingsDelete
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;
}
kodi::addon::PVRCapabilities
Definition: kodi-dev-kit/include/kodi/addon-instance/pvr/General.h:116
kodi::addon::PVRCapabilities::SetSupportsEPG
void SetSupportsEPG(bool supportsEPG)
Set true if the add-on provides EPG information.
Definition: kodi-dev-kit/include/kodi/addon-instance/pvr/General.h:162
kodi::addon::PVRCapabilities::SetSupportsTV
void SetSupportsTV(bool supportsTV)
Set true if this add-on provides TV channels.
Definition: kodi-dev-kit/include/kodi/addon-instance/pvr/General.h:175
Note
Valid implementation required.

◆ GetConnectionString()

virtual PVR_ERROR kodi::addon::CInstancePVRClient::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 kodi::addon::CInstancePVRClient::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 KiB.
[in]usedThe used disk space in KiB.
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 = 100 * 1024 * 1024; // To set complete size of drive in KiB (100GB)
used = 12232424; // To set the used amount
return PVR_ERROR_NO_ERROR;
}

◆ UserPath()

std::string kodi::addon::CInstancePVRClient::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.

◆ ~CInstancePVRClient()

kodi::addon::CInstancePVRClient::~CInstancePVRClient ( )
overridedefault

Destructor.