[PVR] Addon API 5.0.0

[ksooo]

I'd like to propose the following extensions and changes to the PVR Addon API for Krypton:

1. Introduce "no guilib used" return value for GetGUIAPIVersion and GetMininumGUIAPIVersion. Addons not using guilib now are able to state this, making it unnecessary to recompile these addons on bump of guilib. Discussion on this: kodi.guilib is mandatory, enforce it kodi-pvr/pvr.hts#153
   Addon Maintainer Todo: If GUI lib is not used by the addon, GetGUIAPIVersion and GetMininumGUIAPIVersion should be changed to return "" (empty string). Additionally, addon.xml.in should be changed to not include
2. Introduce a callback function that can used by addons to propagate connection state changes. This makes it possible to inform kodi (users) on events like "wrong credentials", "version mismatches", "connection loss", "successful reconnect after connection loss", ... all not possible today. Once an addon is loaded and connected, today there is no standard way to propagate those changes. Now, Kodi can react on changes, and not just by displaying a kai toast, but for example also by refetching addon properties (after reconnect, version numbers etc. may be different - because backend was just updateted, for example), which is done today exactly once after the addon has been loaded. Discussion on this: Fix GetStatus 'lost connection' handling. kodi-pvr/pvr.hts#136 (comment)
   Addon Maintainer Todo: no mandatory addon changes. recompile of the addon is sufficient. but feel free to use the new functionality to enhance your addon
3. Get rid of another magic number: Introduce EPG_TAG_INVALID_UID
   Addon Maintainer Todo: change all code that denotes an "invalid" epg tag uid to use the new constant for that purpose
4. Remove unused method GetCurrentClientChannel
   Addon Maintainer Todo: yeah, remove that function
5. Introduce a callback function for asynchronous announcment of epg data transfer and event state changes. If an addon supports this feature PVR startup time can be improved signifilly. Kodi can be provided with "realtime" epg data (immediate UI chnages, no more operating on tags already deleted in the backend etc.). Reference implementation for pvr.hts gives quite impressive results. ;-)
   Addon Maintainer Todo: no mandatory addon changes. recompile of the addon is sufficient. but feel free to use the new functionality to enhance your addon
6. Add function SetEpgTimeFrame. This one is needed in conjunction with the new epg data callback. Knowing the epg time frame Kodi is interested in the addon can prevent to send dta to Kodi that are actually not of interest (reduces amount of data transferred from addon to Kodi).
   Addon Maintainer Todo: add this function. refer to https://github.com/xbmc/xbmc/pull/8736/files#diff-e73115cc4e6a02ef7029ee04f8ddd2a8R648 for implementation details
7. Add (optional) field PVR_RECORDING.iChannelUid. Today, it is very expensive to find an epg tag for a given recording due to organization of Kodi core data. Having the channel uid in addition to the epg event uid greatly improves performanace
   Addon Maintainer Todo: no mandatory changes, but highly recommended to fill this field, because it is a prerequisite for performance improvements on the kodi side of things
8. Remove unused PVR_SIGNAL_STATUS.d*Bitrate fields.
   Addon Maintainer Todo: yeah, just remove this if used in your addon
9. Get rid of another magic number: Introduce PVR_CHANNEL_INVALID_UID
   Addon Maintainer Todo: change all code that denotes an "invalid" channel uid to use the new constant for that purpose

@FernetMenta @Jalle19 others... Feedback welcome

[xhaggi]

@ksooo thanks, nice additions, I like the idea with the new callback if the state is changed and everything else except the last commit ;)

[ksooo]

@xhaggi see my comment about the last commit. What you fear (not to see progress at all, because startup takes longer than 30 secs) is not true. ;-)

[xhaggi]

okay then it's fine by me :)

[ksooo]

Feedback from @xhaggi and @FernetMenta incorporated.

[ksooo]

jenkins build this please
(just for testing latest changes - no merge planned yet)

[ksooo]

More feedback from @xhaggi incorporated.

[ksooo]

jenkins build this please

[xhaggi]

@ksooo great thanks :) next would be dropping the readytouse member but as you said it is something for a separate PR

[xhaggi]

and using more friendly method names like IsConnected instead of ReadyToUse

[ksooo]

and using more friendly method names like IsConnected instead of ReadyToUse

yeah, but also in another PR

[ksooo]

jenkins build this please

[xhaggi]

sure :)

[Jalle19]

@ksooo while you're at it, could you remove the GetCurrentClientChannel() method from the API? As far as I can tell Kodi doesn't use it anywhere.

[ksooo]

@Jalle19 good point. Are there more?

[Jalle19]

Not sure, I think that's the only one that's completely unused.

[Tolriq]

Sorry for hijacking but since PVR is really improving and users are really starting to use the full power of it, is there any interested to work on completing the JSON counterpart so that remotes can use that power too ?

Usually I'd talk with Montellese but he have no setup and no real interest in PVR.

[xhaggi]

@Tolriq could you please create a forum thread and tell us which parts we neee to expose over json-rpc. that would be highly appreciated.

[Tolriq]

http://forum.kodi.tv/showthread.php?tid=255793, will complete later today or tomorrow wife not happy I'm late :p

[msduketown]

Nice. Some pro-active API compatibility attempts by community members. @opdenkamp is wearn down and now KSOO and Xhaggi are the PVR-managers? Glad to find out..

[ksooo]

Note: pvr.dvblink and pvr.dvbviewer PRs are intentionally missing, because they require a "real" implementation of API 4.2.0 as they actually support timeshifting. Once 4.2.0 has been implemented for these addons I can submit PRs for 5.0.0

[ksooo]

If nobody objects I will merge this PR tomorrow.

[ksooo]

Rebased.

[ksooo]

jenkins build this please