diff options
Diffstat (limited to 'xbmc/interfaces/legacy/ModuleXbmcplugin.h')
| -rw-r--r-- | xbmc/interfaces/legacy/ModuleXbmcplugin.h | 489 |
1 files changed, 489 insertions, 0 deletions
diff --git a/xbmc/interfaces/legacy/ModuleXbmcplugin.h b/xbmc/interfaces/legacy/ModuleXbmcplugin.h new file mode 100644 index 0000000..1aa458c --- /dev/null +++ b/xbmc/interfaces/legacy/ModuleXbmcplugin.h @@ -0,0 +1,489 @@ +/* + * Copyright (C) 2005-2018 Team Kodi + * This file is part of Kodi - https://kodi.tv + * + * SPDX-License-Identifier: GPL-2.0-or-later + * See LICENSES/README.md for more information. + */ + +#pragma once + +#include "AddonString.h" +#include "ListItem.h" +#include "Tuple.h" +#include "swighelper.h" + +#include <vector> + +#ifndef DOXYGEN_SHOULD_SKIP_THIS +namespace XBMCAddon +{ + namespace xbmcplugin + { +#endif /* DOXYGEN_SHOULD_SKIP_THIS */ + + // + /// \defgroup python_xbmcplugin Library - xbmcplugin + /// @{ + /// @brief <b>Plugin functions on Kodi.</b> + /// + /// Offers classes and functions that allow a developer to present + /// information through Kodi's standard menu structure. While plugins don't + /// have the same flexibility as scripts, they boast significantly quicker + /// development time and a more consistent user experience. + // + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.addDirectoryItem(handle, url, listitem [,isFolder, totalItems]) } + /// Callback function to pass directory contents back to Kodi. + /// + /// @param handle integer - handle the plugin was started + /// with. + /// @param url string - url of the entry. would be + /// `plugin://` for another virtual directory + /// @param listitem ListItem - item to add. + /// @param isFolder [opt] bool - True=folder / False=not a + /// folder(default). + /// @param totalItems [opt] integer - total number of items + /// that will be passed.(used for progressbar) + /// @return Returns a bool for successful completion. + /// + /// @note You can use the above as keywords for arguments and skip certain + /// optional arguments. Once you use a keyword, all following arguments + /// require the keyword. + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// if not xbmcplugin.addDirectoryItem(int(sys.argv[1]), 'F:\\Trailers\\300.mov', listitem, totalItems=50): break + /// .. + /// ~~~~~~~~~~~~~ + /// + addDirectoryItem(...); +#else + bool addDirectoryItem(int handle, const String& url, const XBMCAddon::xbmcgui::ListItem* listitem, + bool isFolder = false, int totalItems = 0); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.addDirectoryItems(handle, items[, totalItems]) } + /// Callback function to pass directory contents back to Kodi as a list. + /// + /// @param handle integer - handle the plugin was started + /// with. + /// @param items List - list of (url, listitem[, isFolder]) + /// as a tuple to add. + /// @param totalItems [opt] integer - total number of items + /// that will be passed.(used for progressbar) + /// @return Returns a bool for successful completion. + /// + /// @remark Large lists benefit over using the standard addDirectoryItem(). + /// You may call this more than once to add items in chunks. + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// if not xbmcplugin.addDirectoryItems(int(sys.argv[1]), [(url, listitem, False,)]: raise + /// .. + /// ~~~~~~~~~~~~~ + /// + addDirectoryItems(...); +#else + bool addDirectoryItems(int handle, + const std::vector<Tuple<String,const XBMCAddon::xbmcgui::ListItem*,bool> >& items, + int totalItems = 0); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.endOfDirectory(handle[, succeeded, updateListing, cacheToDisc]) } + /// Callback function to tell Kodi that the end of the directory listing in + /// a virtualPythonFolder module is reached. + /// + /// @param handle integer - handle the plugin was started + /// with. + /// @param succeeded [opt] bool - True=script completed + /// successfully(Default)/False=Script did not. + /// @param updateListing [opt] bool - True=this folder should + /// update the current listing/False=Folder + /// is a subfolder(Default). + /// @param cacheToDisc [opt] bool - True=Folder will cache if + /// extended time(default)/False=this folder + /// will never cache to disc. + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// xbmcplugin.endOfDirectory(int(sys.argv[1]), cacheToDisc=False) + /// .. + /// ~~~~~~~~~~~~~ + /// + endOfDirectory(...); +#else + void endOfDirectory(int handle, bool succeeded = true, bool updateListing = false, + bool cacheToDisc = true); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.setResolvedUrl(handle, succeeded, listitem) } + /// Callback function to tell Kodi that the file plugin has been resolved to + /// a url + /// + /// @param handle integer - handle the plugin was started + /// with. + /// @param succeeded bool - True=script completed + /// successfully/False=Script did not. + /// @param listitem ListItem - item the file plugin resolved + /// to for playback. + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// xbmcplugin.setResolvedUrl(int(sys.argv[1]), True, listitem) + /// .. + /// ~~~~~~~~~~~~~ + /// + setResolvedUrl(...); +#else + void setResolvedUrl(int handle, bool succeeded, const XBMCAddon::xbmcgui::ListItem* listitem); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.addSortMethod(handle, sortMethod [,labelMask, label2Mask]) } + ///------------------------------------------------------------------------- + /// Adds a sorting method for the media list. + /// + /// @param handle integer - handle the plugin was started + /// with. + /// @param sortMethod integer - see available sort methods at + /// the bottom (or see \ref List_of_sort_methods "SortUtils"). + /// | Value | Description | + /// |----------------------------------------------|-----------------------| + /// | xbmcplugin.SORT_METHOD_NONE | Do not sort + /// | xbmcplugin.SORT_METHOD_LABEL | Sort by label + /// | xbmcplugin.SORT_METHOD_LABEL_IGNORE_THE | Sort by the label and ignore "The" before + /// | xbmcplugin.SORT_METHOD_DATE | Sort by the date + /// | xbmcplugin.SORT_METHOD_SIZE | Sort by the size + /// | xbmcplugin.SORT_METHOD_FILE | Sort by the file + /// | xbmcplugin.SORT_METHOD_DRIVE_TYPE | Sort by the drive type + /// | xbmcplugin.SORT_METHOD_TRACKNUM | Sort by the track number + /// | xbmcplugin.SORT_METHOD_DURATION | Sort by the duration + /// | xbmcplugin.SORT_METHOD_TITLE | Sort by the title + /// | xbmcplugin.SORT_METHOD_TITLE_IGNORE_THE | Sort by the title and ignore "The" before + /// | xbmcplugin.SORT_METHOD_ARTIST | Sort by the artist + /// | xbmcplugin.SORT_METHOD_ARTIST_IGNORE_THE | Sort by the artist and ignore "The" before + /// | xbmcplugin.SORT_METHOD_ALBUM | Sort by the album + /// | xbmcplugin.SORT_METHOD_ALBUM_IGNORE_THE | Sort by the album and ignore "The" before + /// | xbmcplugin.SORT_METHOD_GENRE | Sort by the genre + /// | xbmcplugin.SORT_SORT_METHOD_VIDEO_YEAR, xbmcplugin.SORT_METHOD_YEAR | Sort by the year + /// | xbmcplugin.SORT_METHOD_VIDEO_RATING | Sort by the video rating + /// | xbmcplugin.SORT_METHOD_PROGRAM_COUNT | Sort by the program count + /// | xbmcplugin.SORT_METHOD_PLAYLIST_ORDER | Sort by the playlist order + /// | xbmcplugin.SORT_METHOD_EPISODE | Sort by the episode + /// | xbmcplugin.SORT_METHOD_VIDEO_TITLE | Sort by the video title + /// | xbmcplugin.SORT_METHOD_VIDEO_SORT_TITLE | Sort by the video sort title + /// | xbmcplugin.SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE | Sort by the video sort title and ignore "The" before + /// | xbmcplugin.SORT_METHOD_PRODUCTIONCODE | Sort by the production code + /// | xbmcplugin.SORT_METHOD_SONG_RATING | Sort by the song rating + /// | xbmcplugin.SORT_METHOD_MPAA_RATING | Sort by the mpaa rating + /// | xbmcplugin.SORT_METHOD_VIDEO_RUNTIME | Sort by video runtime + /// | xbmcplugin.SORT_METHOD_STUDIO | Sort by the studio + /// | xbmcplugin.SORT_METHOD_STUDIO_IGNORE_THE | Sort by the studio and ignore "The" before + /// | xbmcplugin.SORT_METHOD_UNSORTED | Use list not sorted + /// | xbmcplugin.SORT_METHOD_BITRATE | Sort by the bitrate + /// | xbmcplugin.SORT_METHOD_LISTENERS | Sort by the listeners + /// | xbmcplugin.SORT_METHOD_COUNTRY | Sort by the country + /// | xbmcplugin.SORT_METHOD_DATEADDED | Sort by the added date + /// | xbmcplugin.SORT_METHOD_FULLPATH | Sort by the full path name + /// | xbmcplugin.SORT_METHOD_LABEL_IGNORE_FOLDERS | Sort by the label names and ignore related folder names + /// | xbmcplugin.SORT_METHOD_LASTPLAYED | Sort by last played date + /// | xbmcplugin.SORT_METHOD_PLAYCOUNT | Sort by the play count + /// | xbmcplugin.SORT_METHOD_CHANNEL | Sort by the channel + /// | xbmcplugin.SORT_METHOD_DATE_TAKEN | Sort by the taken date + /// | xbmcplugin.SORT_METHOD_VIDEO_USER_RATING | Sort by the rating of the user of video + /// | xbmcplugin.SORT_METHOD_SONG_USER_RATING | Sort by the rating of the user of song + /// @param labelMask [opt] string - the label mask to use for + /// the first label. + /// - applies to: + /// | sortMethod | labelMask | + /// |---------------------------------------|-----------------------------| + /// | SORT_METHOD_TRACKNUM | Defaults to `[%%N. ]%%T` | + /// | SORT_METHOD_EPISODE | Defaults to `%%H. %%T` | + /// | SORT_METHOD_PRODUCTIONCODE | Defaults to `%%H. %%T` | + /// | All other sort methods | Defaults to `%%T` | + /// + /// + /// @param label2Mask [opt] string - the label mask to use for + /// the second label. Defaults to `%%D` + /// - applies to: + /// | | | | + /// |-----------------------------------------|-----------------------------|-----------------------------------------| + /// | SORT_METHOD_NONE | SORT_METHOD_UNSORTED | SORT_METHOD_VIDEO_TITLE | + /// | SORT_METHOD_TRACKNUM | SORT_METHOD_FILE | SORT_METHOD_TITLE | + /// | SORT_METHOD_TITLE_IGNORE_THE | SORT_METHOD_LABEL | SORT_METHOD_LABEL_IGNORE_THE | + /// | SORT_METHOD_VIDEO_SORT_TITLE | SORT_METHOD_FULLPATH | SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE | + /// | SORT_METHOD_LABEL_IGNORE_FOLDERS | SORT_METHOD_CHANNEL | | + /// @note to add multiple sort methods just call the method multiple times. + /// + /// + /// ------------------------------------------------------------------------ + /// @python_v13 Added new sort **SORT_METHOD_DATE_TAKEN**, **SORT_METHOD_COUNTRY**, + /// **SORT_METHOD_DATEADDED**, **SORT_METHOD_FULLPATH**, **SORT_METHOD_LABEL_IGNORE_FOLDERS**, + /// **SORT_METHOD_LASTPLAYED**, **SORT_METHOD_PLAYCOUNT**, **SORT_METHOD_CHANNEL**. + /// @python_v17 Added new sort **SORT_METHOD_VIDEO_USER_RATING**. + /// @python_v19 Added new option **labelMask**. + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// xbmcplugin.addSortMethod(int(sys.argv[1]), xbmcplugin.SORTMETHOD_DATEADDED) + /// .. + /// ~~~~~~~~~~~~~ + /// + addSortMethod(...); +#else + void addSortMethod(int handle, int sortMethod, const String& labelMask = emptyString, const String& label2Mask = emptyString); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.getSetting(handle, id) } + /// Returns the value of a setting as a string. + /// + /// @param handle integer - handle the plugin was started + /// with. + /// @param id string - id of the setting that the + /// module needs to access. + /// @return Setting value as string + /// + /// @note You can use the above as a keyword. + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// apikey = xbmcplugin.getSetting(int(sys.argv[1]), 'apikey') + /// .. + /// ~~~~~~~~~~~~~ + /// + getSetting(...); +#else + String getSetting(int handle, const char* id); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.setSetting(handle, id, value) } + /// Sets a plugin setting for the current running plugin. + /// + /// @param handle integer - handle the plugin was started with. + /// @param id string - id of the setting that the module needs to access. + /// @param value string or unicode - value of the setting. + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// xbmcplugin.setSetting(int(sys.argv[1]), id='username', value='teamxbmc') + /// .. + /// ~~~~~~~~~~~~~ + /// + setSetting(...); +#else + void setSetting(int handle, const String& id, const String& value); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.setContent(handle, content) } + /// Sets the plugins content. + /// + /// @param handle integer - handle the plugin was started with. + /// @param content string - content type (eg. movies) + /// + /// @par Available content strings + /// | | | | | + /// |:--------:|:--------:|:--------:|:-----------:| + /// | files | songs | artists | albums | + /// | movies | tvshows | episodes | musicvideos | + /// | videos | images | games | -- | + /// + /// @remark Use **videos** for all videos which do not apply to the + /// more specific mentioned ones like "movies", "episodes" etc. + /// A good example is youtube. + /// + /// + /// ------------------------------------------------------------------------ + /// @python_v18 Added new **games** content + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// xbmcplugin.setContent(int(sys.argv[1]), 'movies') + /// .. + /// ~~~~~~~~~~~~~ + /// + setContent(...); +#else + void setContent(int handle, const char* content); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.setPluginCategory(handle, category) } + /// Sets the plugins name for skins to display. + /// + /// @param handle integer - handle the plugin was started with. + /// @param category string or unicode - plugins sub category. + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// xbmcplugin.setPluginCategory(int(sys.argv[1]), 'Comedy') + /// .. + /// ~~~~~~~~~~~~~ + /// + setPluginCategory(...); +#else + void setPluginCategory(int handle, const String& category); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.setPluginFanart(handle, image, color1, color2, color3) } + /// Sets the plugins fanart and color for skins to display. + /// + /// @param handle integer - handle the plugin was started with. + /// @param image [opt] string - path to fanart image. + /// @param color1 [opt] hexstring - color1. (e.g. '0xFFFFFFFF') + /// @param color2 [opt] hexstring - color2. (e.g. '0xFFFF3300') + /// @param color3 [opt] hexstring - color3. (e.g. '0xFF000000') + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// xbmcplugin.setPluginFanart(int(sys.argv[1]), 'special://home/addons/plugins/video/Apple movie trailers II/fanart.png', color2='0xFFFF3300') + /// .. + /// ~~~~~~~~~~~~~ + /// + setPluginFanart(...); +#else + void setPluginFanart(int handle, const char* image = NULL, + const char* color1 = NULL, + const char* color2 = NULL, + const char* color3 = NULL); +#endif + +#ifdef DOXYGEN_SHOULD_USE_THIS + /// + /// \ingroup python_xbmcplugin + /// @brief \python_func{ xbmcplugin.setProperty(handle, key, value) } + /// Sets a container property for this plugin. + /// + /// @param handle integer - handle the plugin was started with. + /// @param key string - property name. + /// @param value string or unicode - value of property. + /// + /// @note Key is NOT case sensitive. + /// + /// + /// ------------------------------------------------------------------------ + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.py} + /// .. + /// xbmcplugin.setProperty(int(sys.argv[1]), 'Emulator', 'M.A.M.E.') + /// .. + /// ~~~~~~~~~~~~~ + /// + setProperty(...); + ///@} +#else + void setProperty(int handle, const char* key, const String& value); +#endif + +#ifndef DOXYGEN_SHOULD_SKIP_THIS + SWIG_CONSTANT(int, SORT_METHOD_NONE); + SWIG_CONSTANT(int, SORT_METHOD_LABEL); + SWIG_CONSTANT(int, SORT_METHOD_LABEL_IGNORE_THE); + SWIG_CONSTANT(int, SORT_METHOD_DATE); + SWIG_CONSTANT(int, SORT_METHOD_SIZE); + SWIG_CONSTANT(int, SORT_METHOD_FILE); + SWIG_CONSTANT(int, SORT_METHOD_DRIVE_TYPE); + SWIG_CONSTANT(int, SORT_METHOD_TRACKNUM); + SWIG_CONSTANT(int, SORT_METHOD_DURATION); + SWIG_CONSTANT(int, SORT_METHOD_TITLE); + SWIG_CONSTANT(int, SORT_METHOD_TITLE_IGNORE_THE); + SWIG_CONSTANT(int, SORT_METHOD_ARTIST); + SWIG_CONSTANT(int, SORT_METHOD_ARTIST_IGNORE_THE); + SWIG_CONSTANT(int, SORT_METHOD_ALBUM); + SWIG_CONSTANT(int, SORT_METHOD_ALBUM_IGNORE_THE); + SWIG_CONSTANT(int, SORT_METHOD_GENRE); + SWIG_CONSTANT2(int, SORT_METHOD_VIDEO_YEAR,SORT_METHOD_YEAR); + SWIG_CONSTANT(int, SORT_METHOD_VIDEO_RATING); + SWIG_CONSTANT(int, SORT_METHOD_PROGRAM_COUNT); + SWIG_CONSTANT(int, SORT_METHOD_PLAYLIST_ORDER); + SWIG_CONSTANT(int, SORT_METHOD_EPISODE); + SWIG_CONSTANT(int, SORT_METHOD_VIDEO_TITLE); + SWIG_CONSTANT(int, SORT_METHOD_VIDEO_SORT_TITLE); + SWIG_CONSTANT(int, SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE); + SWIG_CONSTANT(int, SORT_METHOD_VIDEO_ORIGINAL_TITLE); + SWIG_CONSTANT(int, SORT_METHOD_VIDEO_ORIGINAL_TITLE_IGNORE_THE); + SWIG_CONSTANT(int, SORT_METHOD_PRODUCTIONCODE); + SWIG_CONSTANT(int, SORT_METHOD_SONG_RATING); + SWIG_CONSTANT(int, SORT_METHOD_MPAA_RATING); + SWIG_CONSTANT(int, SORT_METHOD_VIDEO_RUNTIME); + SWIG_CONSTANT(int, SORT_METHOD_STUDIO); + SWIG_CONSTANT(int, SORT_METHOD_STUDIO_IGNORE_THE); + SWIG_CONSTANT(int, SORT_METHOD_UNSORTED); + SWIG_CONSTANT(int, SORT_METHOD_BITRATE); + SWIG_CONSTANT(int, SORT_METHOD_LISTENERS); + SWIG_CONSTANT(int, SORT_METHOD_COUNTRY); + SWIG_CONSTANT(int, SORT_METHOD_DATEADDED); + SWIG_CONSTANT(int, SORT_METHOD_FULLPATH); + SWIG_CONSTANT(int, SORT_METHOD_LABEL_IGNORE_FOLDERS); + SWIG_CONSTANT(int, SORT_METHOD_LASTPLAYED); + SWIG_CONSTANT(int, SORT_METHOD_PLAYCOUNT); + SWIG_CONSTANT(int, SORT_METHOD_CHANNEL); + SWIG_CONSTANT(int, SORT_METHOD_DATE_TAKEN); + SWIG_CONSTANT(int, SORT_METHOD_VIDEO_USER_RATING); + SWIG_CONSTANT(int, SORT_METHOD_SONG_USER_RATING); + } +} +#endif /* DOXYGEN_SHOULD_SKIP_THIS */ |