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.

Header parts:

PVR_ERROR GetCapabilities(kodi::addon::PVRCapabilities& capabilities) override;
PVR_ERROR GetBackendName(std::string& name) override;
PVR_ERROR GetBackendVersion(std::string& version) override;
PVR_ERROR GetBackendHostname(std::string& hostname) override;
PVR_ERROR GetConnectionString(std::string& connection) override;
PVR_ERROR GetDriveSpace(uint64_t& total, uint64_t& used) override;
PVR_ERROR CallSettingsMenuHook(const kodi::addon::PVRMenuhook& menuhook) override;

Source parts:

PVR_ERROR CMyInstance::GetCapabilities(kodi::addon::PVRCapabilities& capabilities)
{
  // Required in interface to have!
  // ...
}
 
PVR_ERROR CMyInstance::GetBackendName(std::string& name)
{
  // Required in interface to have!
  // ...
}
 
PVR_ERROR CMyInstance::GetBackendVersion(std::string& version)
{
  // Required in interface to have!
  // ...
}
 
PVR_ERROR CMyInstance::GetBackendHostname(std::string& hostname)
{
   return PVR_ERROR_NOT_IMPLEMENTED; 
}
 
PVR_ERROR CMyInstance::GetConnectionString(std::string& connection)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetDriveSpace(uint64_t& total, uint64_t& used)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::CallSettingsMenuHook(const kodi::addon::PVRMenuhook& menuhook)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}

Modules
	Group header include

	Group source include

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

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.

Detailed Description

Modules

Function Documentation

◆ CInstancePVRClient() [1/2]

◆ CInstancePVRClient() [2/2]

◆ ~CInstancePVRClient()

◆ GetCapabilities()

◆ GetBackendName()

◆ GetBackendVersion()

◆ GetBackendHostname()

◆ GetConnectionString()

◆ GetDriveSpace()

◆ CallSettingsMenuHook()

◆ AddMenuHook()

◆ ConnectionStateChange()

◆ UserPath()

◆ ClientPath()