1. Basic functions

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 ATTR_DLL_LOCAL CPVRExample
  : public kodi::addon::CAddonBase,
    public kodi::addon::CInstancePVRClient
{
public:
  CPVRExample()
  {
  }
 
  ~CPVRExample() override;
  {
  }
 
  ...
};
 
ADDONCREATOR(CPVRExample)

CInstancePVRClient() [2/2]

CInstancePVRClient ( const IInstanceInfo & instance )

inlineexplicit

PVR client class constructor used to support multiple instance types.

Parameters

[in]

instance

The instance value given to kodi::addon::CAddonBase::CreateInstance(...).

---

Here's example about the use of this:

class CMyPVRClient : public ::kodi::addon::CInstancePVRClient
{
public:
  CMyPVRClient(const kodi::addon::IInstanceInfo& instance)
    : CInstancePVRClient(instance)
  {
     ...
  }
 
  ...
};
 
ADDON_STATUS CMyAddon::CreateInstance(const kodi::addon::IInstanceInfo& instance,
                                      KODI_ADDON_INSTANCE_HDL& hdl)
{
  kodi::Log(ADDON_LOG_INFO, "Creating my PVR client instance");
  hdl = new CMyPVRClient(instance);
  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

capabilities

The 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 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;
}

---

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]

name

The 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]

version

The 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]

hostname

Hostname 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]

connection

The 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]	total	The total disk space in KiB.
[in]	used	The 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;
}

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]

menuhook

The 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]

menuhook

The 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]	connectionString	The connection string reported by the backend that can be displayed in the UI.
[in]	newState	The by PVR_CONNECTION_STATE defined new state.
[in]	message	A 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.