xbmc/addons/Addon.h

   1 /*
   2  *  Copyright (C) 2005-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 #include "addons/IAddon.h"
  12
  13 #include <memory>
  14 #include <string>
  15 #include <unordered_map>
  16 #include <vector>
  17
  18 class CXBMCTinyXML;
  19
  20 namespace ADDON
  21 {
  22
  23 enum class AddonType;
  24 class CAddonType;
  25
  26 class CAddonInfo;
  27 using AddonInfoPtr = std::shared_ptr<CAddonInfo>;
  28
  29 void OnPreInstall(const AddonPtr& addon);
  30 void OnPostInstall(const AddonPtr& addon, bool update, bool modal);
  31 void OnPreUnInstall(const AddonPtr& addon);
  32 void OnPostUnInstall(const AddonPtr& addon);
  33
  34 class CAddon : public IAddon
  35 {
  36 public:
  37   explicit CAddon(const AddonInfoPtr& addonInfo, AddonType addonType);
  38   ~CAddon() override = default;
  39
  40   /**
  41    * @brief To get the main type of this addon
  42    *
  43    * This is the first type defined in **addon.xml** and can be different to the
  44    * on @ref Type() defined type.
  45    *
  46    * @return The used main type of addon
  47    */
  48   AddonType MainType() const override;
  49
  50   /**
  51    * @brief To get the on this CAddon class processed addon type
  52    *
  53    * @return For this class used addon type
  54    */
  55   AddonType Type() const override { return m_type; }
  56
  57   /**
  58    * @brief To check complete addon (not only this) contains a type
  59    *
  60    * @note This can be overridden by a child e.g. plugin to check for subtype
  61    * e.g. video or music.
  62    *
  63    * @param[in] type The to checked type identifier
  64    * @return true in case the wanted type is supported, false if not
  65    */
  66   bool HasType(AddonType type) const override;
  67
  68   /**
  69    * @brief To check complete addon (not only this) has a specific type
  70    * defined in its first extension point including the provided subcontent
  71    * e.g. video or audio
  72    *
  73    * @param[in] type Type identifier to be checked
  74    * @return true in case the wanted type is the main type, false if not
  75    */
  76   bool HasMainType(AddonType type) const override;
  77
  78   /**
  79    * @brief The get for given addon type information and extension data
  80    *
  81    * @param[in] type The wanted type data
  82    * @return addon type class with @ref CAddonExtensions as information
  83    *
  84    * @note This function return never a "nullptr", in case the wanted type is
  85    * not supported, becomes a dummy of @ref CAddonType given.
  86    *
  87    * ------------------------------------------------------------------------
  88    *
  89    * **Example:**
  90    * ~~~~~~~~~~~~~{.cpp}
  91    * // To get e.g. <extension ... name="blablabla" /> from addon.xml
  92    * std::string name = Type(ADDON_...)->GetValue("@name").asString();
  93    * ~~~~~~~~~~~~~
  94    *
  95    */
  96   const CAddonType* Type(AddonType type) const;
  97
  98   std::string ID() const override;
  99   std::string Name() const override;
 100   bool IsInUse() const override { return false; }
 101   bool IsBinary() const override;
 102   CAddonVersion Version() const override;
 103   CAddonVersion MinVersion() const override;
 104   std::string Summary() const override;
 105   std::string Description() const override;
 106   std::string Path() const override;
 107   std::string Profile() const override;
 108   std::string LibPath() const override;
 109   std::string Author() const override;
 110   std::string ChangeLog() const override;
 111   std::string Icon() const override;
 112   ArtMap Art() const override;
 113   std::vector<std::string> Screenshots() const override;
 114   std::string Disclaimer() const override;
 115   AddonLifecycleState LifecycleState() const override;
 116   std::string LifecycleStateDescription() const override;
 117   CDateTime InstallDate() const override;
 118   CDateTime LastUpdated() const override;
 119   CDateTime LastUsed() const override;
 120   std::string Origin() const override;
 121   std::string OriginName() const override;
 122   uint64_t PackageSize() const override;
 123   const InfoMap& ExtraInfo() const override;
 124   const std::vector<DependencyInfo>& GetDependencies() const override;
 125   std::string FanArt() const override;
 126
 127   /*!
 128    * \brief Check add-on for support from independent work instances.
 129    *
 130    * \return true if the add-on supports individual add-on instances, false otherwise
 131    */
 132   bool SupportsMultipleInstances() const override;
 133
 134   /*!
 135    * \brief Return the used instance path type of the add-on type.
 136    *
 137    * \return The route used to instance handling, @ref AddonInstanceUse::NONE if not supported.
 138    */
 139   AddonInstanceSupport InstanceUseType() const override;
 140
 141   /*!
 142    * \brief Gives active, independently working instance identifiers for this add-on.
 143    *
 144    * This function is supported if add-on type has defined
 145    * @ref AddonInstanceUse::BY_SETTINGS and the associated settings
 146    * are available.
 147    *
 148    * \return List of active instance identifiers.
 149    */
 150   std::vector<AddonInstanceId> GetKnownInstanceIds() const override;
 151
 152   /*!
 153    * \brief Check whether the add-on supports individual settings per add-on instance.
 154    *
 155    * This function is supported if add-on type has defined
 156    * @ref AddonInstanceUse::BY_SETTINGS
 157    *
 158    * \return true if the add-on supports individual settings per add-on instance, false otherwise
 159    */
 160   bool SupportsInstanceSettings() const override;
 161
 162   /*!
 163    * \brief Delete selected instance settings from storage.
 164    *
 165    * The related instance-settings-[0-9...].xml file will be deleted by this method.
 166    *
 167    * \param[in] instance Instance identifier to use.
 168    * \return true on success, false otherwise.
 169    */
 170   bool DeleteInstanceSettings(AddonInstanceId instance) override;
 171
 172   /*!
 173    * \brief Check whether this add-on can be configured by the user.
 174    *
 175    * \return true if the add-on has settings, false otherwise
 176    */
 177   bool CanHaveAddonOrInstanceSettings() override;
 178
 179   /*!
 180    * \brief Check whether this add-on can be configured by the user.
 181    *
 182    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 183    *               to denote global add-on settings from settings.xml.
 184    * \return true if the add-on has settings, false otherwise
 185    *
 186    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasUserSettings, GetSetting, UpdateSetting
 187    */
 188   bool HasSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 189
 190   /*!
 191    * \brief Check whether the user has configured this add-on or not.
 192    *
 193    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 194    *               to denote global add-on settings from settings.xml.
 195    * \return true if previously saved settings are found, false otherwise
 196    *
 197    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, GetSetting, UpdateSetting
 198    */
 199   bool HasUserSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 200
 201   /*!
 202    * \brief Save any user configured settings
 203    *
 204    * \param[in] instance Instance identifier to use, use @ref ADDON_SETTINGS_ID
 205    *                     to denote global add-on settings from settings.xml.
 206    *
 207    * \sa LoadSettings, LoadUserSettings, HasSettings, HasUserSettings, GetSetting, UpdateSetting
 208    */
 209   void SaveSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 210
 211   /*!
 212    * \brief Update a user-configured setting with a new value.
 213    *
 214    * \param[in] key the id of the setting to update
 215    * \param[in] value the value that the setting should take
 216    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 217    *               to denote global add-on settings from settings.xml.
 218    *
 219    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 220    */
 221   void UpdateSetting(const std::string& key,
 222                      const std::string& value,
 223                      AddonInstanceId id = ADDON_SETTINGS_ID) override;
 224
 225   /*!
 226    * \brief Update a user-configured setting with a new boolean value.
 227    *
 228    * \param[in] key the id of the setting to update
 229    * \param[in] value the value that the setting should take
 230    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 231    *               to denote global add-on settings from settings.xml.
 232    *
 233    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 234    */
 235   bool UpdateSettingBool(const std::string& key,
 236                          bool value,
 237                          AddonInstanceId id = ADDON_SETTINGS_ID) override;
 238
 239   /*!
 240    * \brief Update a user-configured setting with a new integer value.
 241    *
 242    * \param[in] key the id of the setting to update
 243    * \param[in] value the value that the setting should take
 244    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 245    *               to denote global add-on settings from settings.xml.
 246    *
 247    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 248    */
 249   bool UpdateSettingInt(const std::string& key,
 250                         int value,
 251                         AddonInstanceId id = ADDON_SETTINGS_ID) override;
 252
 253   /*!
 254    * \brief Update a user-configured setting with a new number value.
 255    *
 256    * \param[in] key the id of the setting to update
 257    * \param[in] value the value that the setting should take
 258    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 259    *               to denote global add-on settings from settings.xml.
 260    *
 261    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 262    */
 263   bool UpdateSettingNumber(const std::string& key,
 264                            double value,
 265                            AddonInstanceId id = ADDON_SETTINGS_ID) override;
 266
 267   /*!
 268    * \brief Update a user-configured setting with a new string value.
 269    *
 270    * \param[in] key the id of the setting to update
 271    * \param[in] value the value that the setting should take
 272    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 273    *               to denote global add-on settings from settings.xml.
 274    *
 275    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 276    */
 277   bool UpdateSettingString(const std::string& key,
 278                            const std::string& value,
 279                            AddonInstanceId id = ADDON_SETTINGS_ID) override;
 280
 281   /*!
 282    * \brief Retrieve a particular settings value.
 283    *
 284    * If a previously configured user setting is available, we return it's value, else we return the default (if available).
 285    *
 286    * \param[in] key the id of the setting to retrieve
 287    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 288    *               to denote global add-on settings from settings.xml.
 289    * \return the current value of the setting, or the default if the setting has yet to be configured.
 290    *
 291    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 292    */
 293   std::string GetSetting(const std::string& key, AddonInstanceId id = ADDON_SETTINGS_ID) override;
 294
 295   /*!
 296    * \brief Retrieve a particular settings value as boolean.
 297    *
 298    * If a previously configured user setting is available, we return it's value, else we return the default (if available).
 299    *
 300    * \param[in] key the id of the setting to retrieve
 301    * \param[out] value the current value of the setting, or the default if the setting has yet to be configured
 302    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 303    *               to denote global add-on settings from settings.xml.
 304    * \return true if the setting's value was retrieved, false otherwise.
 305    *
 306    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 307    */
 308   bool GetSettingBool(const std::string& key,
 309                       bool& value,
 310                       AddonInstanceId id = ADDON_SETTINGS_ID) override;
 311
 312   /*!
 313    * \brief Retrieve a particular settings value as integer.
 314    *
 315    * If a previously configured user setting is available, we return it's value, else we return the default (if available)
 316    *
 317    * \param[in] key the id of the setting to retrieve
 318    * \param[out] value the current value of the setting, or the default if the setting has yet to be configured
 319    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 320    *               to denote global add-on settings from settings.xml.
 321    * \return true if the setting's value was retrieved, false otherwise.
 322    *
 323    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 324    */
 325   bool GetSettingInt(const std::string& key,
 326                      int& value,
 327                      AddonInstanceId id = ADDON_SETTINGS_ID) override;
 328
 329   /*!
 330    * \brief Retrieve a particular settings value as number.
 331    *
 332    * If a previously configured user setting is available, we return it's value, else we return the default (if available)
 333    *
 334    * \param[in] key the id of the setting to retrieve
 335    * \param[out] value the current value of the setting, or the default if the setting has yet to be configured
 336    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 337    *               to denote global add-on settings from settings.xml.
 338    * \return true if the setting's value was retrieved, false otherwise.
 339    *
 340    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 341    */
 342   bool GetSettingNumber(const std::string& key,
 343                         double& value,
 344                         AddonInstanceId id = ADDON_SETTINGS_ID) override;
 345
 346   /*!
 347    * \brief Retrieve a particular settings value as string
 348    *
 349    * If a previously configured user setting is available, we return it's value, else we return the default (if available)
 350    *
 351    * \param[in] key the id of the setting to retrieve
 352    * \param[out] value the current value of the setting, or the default if the setting has yet to be configured
 353    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 354    *               to denote global add-on settings from settings.xml.
 355    * \return true if the setting's value was retrieved, false otherwise.
 356    *
 357    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 358    */
 359   bool GetSettingString(const std::string& key,
 360                         std::string& value,
 361                         AddonInstanceId id = ADDON_SETTINGS_ID) override;
 362
 363   std::shared_ptr<CAddonSettings> GetSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 364
 365   /*! \brief get the required version of a dependency.
 366    \param dependencyID the addon ID of the dependency.
 367    \return the version this addon requires.
 368    */
 369   CAddonVersion GetDependencyVersion(const std::string& dependencyID) const override;
 370
 371   /*! \brief return whether or not this addon satisfies the given version requirements
 372    \param version the version to meet.
 373    \return true if  min_version <= version <= current_version, false otherwise.
 374    */
 375   bool MeetsVersion(const CAddonVersion& versionMin, const CAddonVersion& version) const override;
 376
 377   bool ReloadSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 378
 379   void ResetSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 380
 381   /*! \brief retrieve the running instance of an add-on if it persists while running.
 382    */
 383   AddonPtr GetRunningInstance() const override { return AddonPtr(); }
 384
 385   void OnPreInstall() override{};
 386   void OnPostInstall(bool update, bool modal) override{};
 387   void OnPreUnInstall() override{};
 388   void OnPostUnInstall() override{};
 389
 390 protected:
 391   /*!
 392    * \brief Whether or not the settings have been initialized.
 393    *
 394    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 395    *               to denote global add-on settings from settings.xml.
 396    * \return true if settings initialize was successfull
 397    */
 398   virtual bool SettingsInitialized(AddonInstanceId id = ADDON_SETTINGS_ID) const;
 399
 400   /*!
 401    * \brief Whether or not the settings have been loaded.
 402    *
 403    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 404    *               to denote global add-on settings from settings.xml.
 405    * \return true if settings are loaded correct
 406    */
 407   virtual bool SettingsLoaded(AddonInstanceId id = ADDON_SETTINGS_ID) const;
 408
 409   /*!
 410    * \brief Load the default settings and override these with any previously configured user settings
 411    *
 412    * \param[in] bForce force the load of settings even if they are already loaded (reload)
 413    * \param[in] loadUserSettings whether or not to load user settings
 414    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 415    *               to denote global add-on settings from settings.xml.
 416    * \return true if settings exist, false otherwise
 417    *
 418    * \sa LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting, UpdateSetting
 419    */
 420   bool LoadSettings(bool bForce, bool loadUserSettings, AddonInstanceId id = ADDON_SETTINGS_ID);
 421
 422   /*!
 423    * \brief Load the user settings
 424    *
 425    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 426    *               to denote global add-on settings from settings.xml.
 427    * \return true if user settings exist, false otherwise
 428    *
 429    * \sa LoadSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting, UpdateSetting
 430    */
 431   virtual bool LoadUserSettings(AddonInstanceId id = ADDON_SETTINGS_ID);
 432
 433   /*!
 434    * \brief Whether there are settings to be saved
 435    *
 436    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 437    *               to denote global add-on settings from settings.xml.
 438    * \return true if settings has to save
 439    *
 440    * \sa SaveSettings
 441    */
 442   virtual bool HasSettingsToSave(AddonInstanceId id = ADDON_SETTINGS_ID) const;
 443
 444   /*!
 445    * \brief Parse settings from an XML document
 446    *
 447    * \param[in] doc XML document to parse for settings
 448    * \param[in] loadDefaults if true, the default attribute is used and settings are reset prior to parsing, else the value attribute is used.
 449    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 450    *               to denote global add-on settings from settings.xml.
 451    * \return true if settings are loaded, false otherwise
 452    *
 453    * \sa SettingsToXML
 454    */
 455   virtual bool SettingsFromXML(const CXBMCTinyXML& doc,
 456                                bool loadDefaults,
 457                                AddonInstanceId id = ADDON_SETTINGS_ID);
 458
 459   /*!
 460    * \brief Write settings into an XML document
 461    *
 462    * \param[out] doc XML document to receive the settings
 463    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 464    *               to denote global add-on settings from settings.xml.
 465    * \return true if settings are saved, false otherwise
 466    *
 467    * \sa SettingsFromXML
 468    */
 469   virtual bool SettingsToXML(CXBMCTinyXML& doc, AddonInstanceId id = ADDON_SETTINGS_ID) const;
 470
 471   const AddonInfoPtr m_addonInfo;
 472
 473 private:
 474   struct CSettingsData
 475   {
 476     bool m_loadSettingsFailed{false};
 477     bool m_hasUserSettings{false};
 478     std::string m_addonSettingsPath;
 479     std::string m_userSettingsPath;
 480     std::shared_ptr<CAddonSettings> m_addonSettings;
 481   };
 482
 483   bool InitSettings(AddonInstanceId id);
 484   std::shared_ptr<CAddonSettings> FindInstanceSettings(AddonInstanceId id) const;
 485
 486   mutable std::unordered_map<AddonInstanceId, CSettingsData> m_settings;
 487   const AddonType m_type;
 488 };
 489
 490 }; // namespace ADDON