Archive:Eden API changes

From Official Kodi Wiki
Revision as of 00:30, 1 October 2011 by Ned Scott (talk | contribs)
Jump to navigation Jump to search

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.

Changed methods

  • JSONRPC
    • Renamed Announce to NotifyAll
    • Renamed and refactored GetNotificationFlags to GetConfiguration
    • Renamed and refactored SetNotificationFlags to SetConfiguration
  • AudioPlayer
    • GetTime have been merged with GetTimeMS to GetTime
    • Record has been removed completely
  • VideoPlayer
    • GetTime have been merged with GetTimeMS to GetTime
  • AudioLibrary
    • Renamed ScanForContent to Scan
  • VideoLibrary
    • Renamed ScanForContent to Scan
  • System
    • Added GetProperties providing "canshutdown", "cansuspend", "canhibernate" and "canreboot"
    • 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

  • 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"

Scrapers

No major API changes at this time.