2. Channels (required)

Detailed Description

Functions to get available TV or Radio channels
These are mandatory functions for using this addon to get the available channels.

Remarks

Either SetSupportsTV() or SetSupportsRadio() is required to be set to true.
If a channel changes after the initial import, or if a new one was added, then the add-on should call TriggerChannelUpdate().

---

Channel 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 GetProvidersAmount(int& amount) override;
PVR_ERROR GetProviders(kodi::addon::PVRProvidersResultSet& results) override;
PVR_ERROR GetChannelsAmount(int& amount) override;
PVR_ERROR GetChannels(bool radio, kodi::addon::PVRChannelsResultSet& results) override;
PVR_ERROR GetChannelStreamProperties(const kodi::addon::PVRChannel& channel, std::vector<kodi::addon::PVRStreamProperty>& properties) override;
PVR_ERROR GetSignalStatus(int channelUid, kodi::addon::PVRSignalStatus& signalStatus) override;
PVR_ERROR GetDescrambleInfo(int channelUid, kodi::addon::PVRDescrambleInfo& descrambleInfo) override;

Source parts:

PVR_ERROR CMyInstance::GetProvidersAmount(int& amount)
{
   return PVR_ERROR_NOT_IMPLEMENTED; 
}
 
PVR_ERROR CMyInstance::GetProviders(kodi::addon::PVRProvidersResultSet& results)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetChannelsAmount(int& amount)
{
   return PVR_ERROR_NOT_IMPLEMENTED; 
}
 
PVR_ERROR CMyInstance::GetChannels(bool radio, kodi::addon::PVRChannelsResultSet& results)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetChannelStreamProperties(const kodi::addon::PVRChannel& channel, std::vector<kodi::addon::PVRStreamProperty>& properties)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetSignalStatus(int channelUid, kodi::addon::PVRSignalStatus& signalStatus)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}
 
PVR_ERROR CMyInstance::GetDescrambleInfo(int channelUid, kodi::addon::PVRDescrambleInfo& descrambleInfo)
{
  return PVR_ERROR_NOT_IMPLEMENTED;
}

Modules
	Group header include
	Group source include

Function Documentation

GetProvidersAmount()

virtual PVR_ERROR GetProvidersAmount ( int &  amount )

inlinevirtual

The total amount of providers on the backend.

Parameters

[out]

amount

The total amount of providers on the backend

Returns

PVR_ERROR_NO_ERROR if the amount has been fetched successfully.

Remarks

Optional, and only used if supportsProviders is set to true.

GetProviders()

virtual PVR_ERROR GetProviders ( kodi::addon::PVRProvidersResultSet &  results )

inlinevirtual

Request the list of all providers from the backend.

Parameters

[out]

results

The channels defined with class PVRProvider and available at the addon, then transferred with class PVRProvidersResultSet.

Returns

PVR_ERROR_NO_ERROR if the list has been fetched successfully.

Remarks

Optional, and only used if supportsProviders is set to true.

---

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

Name	Type	Set call	Get call	Usage
Unique id	unsigned int	SetUniqueId	GetUniqueId	required to set
Provider name	std::string	SetName	GetName	required to set
Provider type	PVR_PROVIDER_TYPE	SetType	GetType	optional
Icon path	std::string	SetIconPath	GetIconPath	optional
Countries	std::vecotr<std::string>	SetCountries	GetCountries	optional
Langauges	std::vecotr<std::string>	SetLanguages	GetLanguages	optional

---

Example:

...
PVR_ERROR CMyPVRInstance::GetProviders(kodi::addon::PVRProvidersResultSet& results)
{
  // Minimal demo example, in reality bigger and loop to transfer all
  kodi::addon::PVRProvider provider;
  provider.SetUniqueId(123);
  provider.SetProviderName("My provider name");
  provider.SetProviderType(PVR_PROVIDER_TYPE_SATELLITE);
  ...
 
  // Give it now to Kodi
  results.Add(provider);
  return PVR_ERROR_NO_ERROR;
}
...

TriggerProvidersUpdate()

void TriggerProvidersUpdate ( )

inline

Callback to Kodi Function
Request Kodi to update it's list of providers.

Remarks

Only called from addon itself.

GetChannelsAmount()

virtual PVR_ERROR GetChannelsAmount ( int &  amount )

inlinevirtual

The total amount of channels on the backend.

Parameters

[out]

amount

The total amount of channels on the backend

Returns

PVR_ERROR_NO_ERROR if the amount has been fetched successfully.

Remarks

Valid implementation required.

GetChannels()

virtual PVR_ERROR GetChannels ( bool  radio, kodi::addon::PVRChannelsResultSet &  results  )

inlinevirtual

Request the list of all channels from the backend.

Parameters

[in]	radio	True to get the radio channels, false to get the TV channels.
[out]	results	The channels defined with class PVRChannel and available at the addon, them transferred with class PVRChannelsResultSet.

Returns

PVR_ERROR_NO_ERROR if the list has been fetched successfully.

---

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

Name	Type	Set call	Get call	Usage
Unique id	unsigned int	SetUniqueId	GetUniqueId	required to set
Is radio	bool	SetIsRadio	GetIsRadio	required to set
Channel number	unsigned int	SetChannelNumber	GetChannelNumber	optional
Sub channel number	unsigned int	SetSubChannelNumber	GetSubChannelNumber	optional
Channel name	std::string	SetChannelName	GetChannelName	optional
Mime type	std::string	SetMimeType	GetMimeType	optional
Encryption system	unsigned int	SetEncryptionSystem	GetEncryptionSystem	optional
Icon path	std::string	SetIconPath	GetIconPath	optional
Is hidden	bool	SetIsHidden	GetIsHidden	optional
Has archive	bool	SetHasArchive	GetHasArchive	optional
Order	int	SetOrder	GetOrder	optional
Client provider unique identifier	int	SetClientProviderUid	GetClientProviderUid	optional

---

Remarks

If PVRCapabilities::SetSupportsTV() is set to true, a valid result set needs to be provided for radio = false.
If PVRCapabilities::SetSupportsRadio() is set to true, a valid result set needs to be provided for radio = true. At least one of these two must provide a valid result set.

---

Example:

...
PVR_ERROR CMyPVRInstance::GetChannels(bool radio, kodi::addon::PVRChannelsResultSet& results)
{
  // Minimal demo example, in reality bigger and loop to transfer all
  kodi::addon::PVRChannel channel;
  channel.SetUniqueId(123);
  channel.SetIsRadio(false);
  channel.SetChannelNumber(1);
  channel.SetChannelName("My channel name");
  ...
 
  // Give it now to Kodi
  results.Add(channel);
  return PVR_ERROR_NO_ERROR;
}
...

GetChannelStreamProperties()

virtual PVR_ERROR GetChannelStreamProperties ( const kodi::addon::PVRChannel &  channel, std::vector< kodi::addon::PVRStreamProperty > &  properties  )

inlinevirtual

Get the stream properties for a channel from the backend.

Parameters

[in]	channel	The channel to get the stream properties for.
[out]	properties	the properties required to play the stream.

Returns

PVR_ERROR_NO_ERROR if the stream is available.

Remarks

If SetSupportsTV or SetSupportsRadio are set to true and SetHandlesInputStream is set to false.

In this case the implementation must fill the property PVR_STREAM_PROPERTY_STREAMURL with the URL Kodi should resolve to playback the channel.

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::GetChannelStreamProperties(const kodi::addon::PVRChannel& channel,
                                                     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");
  return PVR_ERROR_NO_ERROR;
}
...

GetSignalStatus()

virtual PVR_ERROR GetSignalStatus ( int  channelUid, kodi::addon::PVRSignalStatus &  signalStatus  )

inlinevirtual

Get the signal status of the stream that's currently open.

Parameters

[out]

signalStatus

The signal status.

Returns

PVR_ERROR_NO_ERROR if the signal status has been read successfully, false otherwise.

Remarks

Optional, and only used if SetHandlesInputStream is set to true.

---

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

Name	Type	Set call	Get call	Usage
Adapter name	std::string	SetAdapterName	GetAdapterName	optional
Adapter status	std::string	SetAdapterStatus	GetAdapterStatus	optional
Service name	std::string	SetServiceName	GetServiceName	optional
Provider name	std::string	SetProviderName	GetProviderName	optional
Mux name	std::string	SetMuxName	GetMuxName	optional
Signal/noise ratio	int	SetSNR	GetSNR	optional
Signal strength	int	SetSignal	GetSignal	optional
Bit error rate	long	SetBER	GetBER	optional
Uncorrected blocks	long	SetUNC	GetUNC	optional

---

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:
  ...
  PVR_ERROR SignalStatus(PVRSignalStatus &signalStatus) override
  {
    signalStatus.SetAapterName("Example adapter 1");
    signalStatus.SetAdapterStatus("OK");
    signalStatus.SetSignal(0xFFFF); // 100%
 
    return PVR_ERROR_NO_ERROR;
  }
};
 
ADDONCREATOR(CPVRExample)

GetDescrambleInfo()

virtual PVR_ERROR GetDescrambleInfo ( int  channelUid, kodi::addon::PVRDescrambleInfo &  descrambleInfo  )

inlinevirtual

Get the descramble information of the stream that's currently open.

Parameters

[out]

descrambleInfo

The descramble information.

Returns

PVR_ERROR_NO_ERROR if the descramble information has been read successfully, false otherwise.

Remarks

Optional, and only used if supportsDescrambleInfo is set to true.

---

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

Name	Type	Set call	Get call	Usage
Packet identifier	int	SetPID	GetPID	optional
Conditional access identifier	int	SetCAID	GetCAID	optional
Provider-ID	int	SetProviderID	GetProviderID	optional
ECM time	int	SetECMTime	GetECMTime	optional
Hops	int	SetHops	GetHops	optional
Descramble card system	std::string	SetHops	GetHops	optional
Reader	std::string	SetReader	GetReader	optional
From	std::string	SetFrom	GetFrom	optional
Protocol	std::string	SetProtocol	GetProtocol	optional

TriggerChannelUpdate()

void TriggerChannelUpdate ( )

inline

Callback to Kodi Function
Request Kodi to update it's list of channels.

Remarks

Only called from addon itself.