Archive:Eden API changes

From Official Kodi Wiki
Jump to navigation Jump to search

Addons

Eden will represent the first repository update, and as a result we have taken the opportunity to change the API for several subsystems. Any add-ons that are submitted for inclusion in Eden-pre and Eden will require compatibility with the new APIs.

The Eden-pre repository will be created soon, while the APIs may still change somewhat. When the APIs are frozen, the final Eden repository will open and final API compatibility will be enforced.

Be sure to read the Official Repository Guidlines before submitting a pull request.

Scripts and Plugins

XBMC now uses an external version of Python rather than a self-built one. This brings many benefits but means that some plugins/scripts will have to change slightly. In order to be considered for inclusion in the Eden repository, the following must be true.

  • The version of the xbmc.python api is now 2.0. Your script or plugin will be required to reflect this dependency before it will be accepted into the eden-pre repository. Setting the xbmc.python api dependency greater than 1.0 triggers the enforcement of several deprecations. See the Backwards-compat section below.
  • You can no longer assume that "os.getcwd" will return the root directory of the add-on. In-fact, the usage of cwd is highly discouraged and may be deprecated all together in future releases.
  • Do not use 'special://' paths with os python module functionality (file or directory create/delete/access/read/write/stat/etc). You should translate any paths that may be prefixed this way using xbmc.translatePath(path) or use the new xbmcvfs module.
  • Newer python (2.5 and up) includes a sqlite module as part of the python distribution. You should import sqlite3 instead of the former use of pysqlite2. An acceptable import that will allow the same python code to work in both eden and previous versions would be:
try:
    from sqlite3 import dbapi2 as sqlite
    logFile.info("Loading sqlite3 as DB engine")
except:
    from pysqlite2 import dbapi2 as sqlite
    logFile.info("Loading pysqlite2 as DB engine")
  • Direct use of sqlite/mysql to access XBMC's databases is HIGHLY discouraged and may be rejected. Use a properly abstracted interface like JSONRPC instead.
  • The Recently Added add-on is deprecated. Functionality has been moved into core.

Backwards Compatibility

If your add-on depends on xbmc.python version 1.0 or less, backwards-compatibly mode is enabled (note: as it says above, if this is the case it will not be accepted into the eden repository). This was done in an effort to try to keep out-of-date addons working.

Certain deprecated functions like os.getcwd() will produce a warning in backwards-compatibility mode, whereas they will fail outright otherwise. Add-ons with this enabled will not be accepted into the Eden repo, they should instead be updated.

Skins

For now, see the discussion on the forum. Docs coming soon.

JSON-RPC

This interface has been almost entirely redone for Eden, and is still a work in progress. This means that there won't be any backwards compatibility to the JSON-RPC API provided in Dharma (10.0).

General changes (Implementation)

The whole implementation of the JSON-RPC server has been refactored to be compliant with the JSON-RPC 2.0 specification. These changes involve:

  • Client-side announcements (methods can be called without the "id" field which will result in the execution of the method without returning a response)
  • Bulk requests (multiple method calls can be sent as an array in a single json rpc request; all methods are executed and the response contains all responses of the bulk request in an array)
  • Default JSON output in compact format (Advanced Settings option to disable compact json output)
  • support for by-value OR by-position parameters
  • "params" must always be an array (by-position) or an object (by-value) but never a simple type

Error responses

If a client sends a JSON-RPC request which does not match the JSON schema description defined by JSONRPC.Introspect, the data object of the response will contain a detailed error description defined by the following JSON schema:

{
  "type": "object",
  "properties": {
    "method": { "type": "string", "required": true },
    "message": { "type": "string" },
    "stack": { "type": "object",
      "id": "stackentry",
      "properties": {
        "name": { "type": "string", "required": true },
        "type": { "type": "string", "required": true },
        "message": { "type": "string" },
        "property": { "$ref": "stackentry" }
      }
    }
  }
}

API changes

For migration guidance, see the discussion on the forum.

Namespace changes

  • VideoPlayer merged into Player
  • AudioPlayer merged into Player
  • PicturePlayer merged into Player
  • Playlist removed
  • VideoPlaylist merged into Playlist
  • AudioPlaylist merged into Playlist
  • Application added
  • Input added
  • XBMC will only contain very XBMC-specific and deprecated methods

Changed methods

  • Multiple
    • Renamed fields parameter to properties
  • JSONRPC
    • Renamed Announce to NotifyAll
    • Renamed and refactored GetNotificationFlags to GetConfiguration
    • Renamed and refactored SetNotificationFlags to SetConfiguration
  • AudioPlayer
    • Completely merged into Player
  • VideoPlayer
    • Completely merged into Player
  • PicturePlayer
    • Completely merged into Player
  • AudioPlaylist
    • Completely merged into Playlist
  • VideoPlaylist
    • Completely merged into Playlist
  • Files
    • Renamed property returned by GetSources from shares to sources
    • Refactored Download into PrepareDownload and Download
  • AudioLibrary
    • Renamed ScanForContent to Scan
  • VideoLibrary
    • Renamed ScanForContent to Scan
  • Application
    • Renamed value parameter of SetVolume to volume
    • Refactored ToggleMute into SetMute which takes the following parameter values: true, false, "toggle"
  • System
    • GetInfoLabels has been moved to the XBMC namespace
    • GetInfoBooleans has been moved to the XBMC namespace
  • XBMC
    • Log has been removed completely
    • SetVolume has been moved to the Application namespace
    • ToggleMute has been moved to the Application namespace
    • Quit has been moved to the Application namespace
    • GetVolume has been replaced by Application.GetProperties

New methods

  • Player
    • Open: Moved and refactored from XBMC.Play and XBMC.StartSlideshow
    • GetProperties: Provides properties (like player type, playlist id, position etc) about a specific player
    • GetItem: Get the currently playing item of a specific player
    • PlayPause: Moved and merged from AudioPlayer, VideoPlayer and PicturePlayer
    • Stop: Moved and merged from AudioPlayer, VideoPlayer and PicturePlayer
    • SetSpeed: Moved, merged, renamed and refactored from AudioPlayer/VideoPlayer/PicturePlayer.Rewind/.FastForward
    • Seek: Moved, merged, renamed and refactored from AudioPlayer/VideoPlayer/PicturePlayer.SeekTime/.SeekPercentage
    • MoveLeft: Moved from PicturePlayer
    • MoveRight: Moved from PicturePlayer
    • MoveUp: Moved from PicturePlayer
    • MoveDown: Moved from PicturePlayer
    • ZoomOut: Moved from PicturePlayer
    • ZoomIn: Moved from PicturePlayer
    • Zoom: Moved from PicturePlayer
    • Rotate: Moved from PicturePlayer
    • GoPrevious: Moved, merged and renamed from AudioPlayer/VideoPlayer/PicturePlayer.SkipPrevious
    • GoNext: Moved, merged and renamed from AudioPlayer/VideoPlayer/PicturePlayer.SkipNext
    • GoTo: Jumps to the given position in the playlist played by a specific player
    • Shuffle: Moved and merged from AudioPlaylist and VideoPlaylist
    • UnShuffle: Moved and merged from AudioPlaylist and VideoPlaylist
    • Repeat: Moved and merged from AudioPlaylist and VideoPlaylist
    • SetAudioStream: Changes the currently active audio stream in a specific player
    • SetSubtitle: Changes the currently active subtitle in a specific player
  • Playlist
    • GetPlaylists: returns the currently loaded playlists and their type
    • GetProperties: provides properties for a certain playlist
  • AudioLibrary
    • GetArtistDetails: requires an artistid and returns details about a single artist
    • GetAlbumDetails: requires an albumid and returns details about a single album
    • GetSongDetails: requires a songid and returns details about a single song
    • GetRecentlyAddedAlbums: returns the most recently added albums
    • GetRecentlyAddedSongs: returns the most recently added songs
    • Export: exports the details for each artist, album and song stored in the library
    • Clean: cleans the library from any no-longer existing artists, albums and songs
  • VideoLibrary
    • GetMovieDetails: requires a movieid and returns details about a single movie
    • GetMovieSets: returns a list of all movie sets in the video library
    • GetMovieSetDetails: requires a setid and returns details about a movie set and a list of movies it contains
    • GetTVShowDetails: requires a tvshowid and returns details about a single tv show
    • GetEpisodeDetails: requires an episodeid and returns details about a single episode
    • GetMusicVideoDetails: requires a musicvideoid and returns details about a single music video
    • GetGenres: returns a list of all video related genres
    • Export: exports the details for each movie, tvshow, episode and musicvideo stored in the library
    • Clean: cleans the library from any no-longer existing movie, tvshow, episode and musicvideo
  • Input
    • Up: Move up in the GUI
    • Down: Move down in the GUI
    • Left: Move left in the GUI
    • Right: Move right in the GUI
    • Select: Select the current control/item in the GUI
    • Back: Go one level up (parent directory) in the GUI
    • Home: Go back to the home screen
  • System
    • GetProperties: Provides access to the properties "canshutdown", "cansuspend", "canhibernate" and "canreboot"
  • Application
    • GetProperties: Provides access to the properties "volume" and "muted"
    • SetVolume: Moved from XBMC.SetVolume and the parameter has been renamed to "volume"
    • SetMute: Moved and refactored from XBMC.ToggleMute. It can either set muted/not muted or just toggle as before
    • Quit: Moved from XBMC.Quit
  • XBMC
    • GetInfoLabels: Moved from System namespace
    • GetInfoBooleans: Moved from System namespace

Scrapers

No major API changes at this time.

Screensavers and visualizations

These methods now have a ADDON_ prefix to avoid global namespace clashes

  • Create
  • Stop
  • Destroy
  • GetStatus
  • HasSettings
  • GetSettings
  • SetSetting
  • FreeSettings

References