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    * \return true if the operation was successful, false otherwise
 207    *
 208    * \sa LoadSettings, LoadUserSettings, HasSettings, HasUserSettings, GetSetting, UpdateSetting
 209    */
 210   bool SaveSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 211
 212   /*!
 213    * \brief Update a user-configured setting with a new value.
 214    *
 215    * \param[in] key the id of the setting to update
 216    * \param[in] value the value that the setting should take
 217    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 218    *               to denote global add-on settings from settings.xml.
 219    *
 220    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 221    */
 222   void UpdateSetting(const std::string& key,
 223                      const std::string& value,
 224                      AddonInstanceId id = ADDON_SETTINGS_ID) override;
 225
 226   /*!
 227    * \brief Update a user-configured setting with a new boolean value.
 228    *
 229    * \param[in] key the id of the setting to update
 230    * \param[in] value the value that the setting should take
 231    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 232    *               to denote global add-on settings from settings.xml.
 233    *
 234    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 235    */
 236   bool UpdateSettingBool(const std::string& key,
 237                          bool value,
 238                          AddonInstanceId id = ADDON_SETTINGS_ID) override;
 239
 240   /*!
 241    * \brief Update a user-configured setting with a new integer value.
 242    *
 243    * \param[in] key the id of the setting to update
 244    * \param[in] value the value that the setting should take
 245    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 246    *               to denote global add-on settings from settings.xml.
 247    *
 248    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 249    */
 250   bool UpdateSettingInt(const std::string& key,
 251                         int value,
 252                         AddonInstanceId id = ADDON_SETTINGS_ID) override;
 253
 254   /*!
 255    * \brief Update a user-configured setting with a new number value.
 256    *
 257    * \param[in] key the id of the setting to update
 258    * \param[in] value the value that the setting should take
 259    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 260    *               to denote global add-on settings from settings.xml.
 261    *
 262    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 263    */
 264   bool UpdateSettingNumber(const std::string& key,
 265                            double value,
 266                            AddonInstanceId id = ADDON_SETTINGS_ID) override;
 267
 268   /*!
 269    * \brief Update a user-configured setting with a new string value.
 270    *
 271    * \param[in] key the id of the setting to update
 272    * \param[in] value the value that the setting should take
 273    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 274    *               to denote global add-on settings from settings.xml.
 275    *
 276    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting
 277    */
 278   bool UpdateSettingString(const std::string& key,
 279                            const std::string& value,
 280                            AddonInstanceId id = ADDON_SETTINGS_ID) override;
 281
 282   /*!
 283    * \brief Retrieve a particular settings value.
 284    *
 285    * If a previously configured user setting is available, we return it's value, else we return the default (if available).
 286    *
 287    * \param[in] key the id of the setting to retrieve
 288    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 289    *               to denote global add-on settings from settings.xml.
 290    * \return the current value of the setting, or the default if the setting has yet to be configured.
 291    *
 292    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 293    */
 294   std::string GetSetting(const std::string& key, AddonInstanceId id = ADDON_SETTINGS_ID) override;
 295
 296   /*!
 297    * \brief Retrieve a particular settings value as boolean.
 298    *
 299    * If a previously configured user setting is available, we return it's value, else we return the default (if available).
 300    *
 301    * \param[in] key the id of the setting to retrieve
 302    * \param[out] value the current value of the setting, or the default if the setting has yet to be configured
 303    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 304    *               to denote global add-on settings from settings.xml.
 305    * \return true if the setting's value was retrieved, false otherwise.
 306    *
 307    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 308    */
 309   bool GetSettingBool(const std::string& key,
 310                       bool& value,
 311                       AddonInstanceId id = ADDON_SETTINGS_ID) override;
 312
 313   /*!
 314    * \brief Retrieve a particular settings value as integer.
 315    *
 316    * If a previously configured user setting is available, we return it's value, else we return the default (if available)
 317    *
 318    * \param[in] key the id of the setting to retrieve
 319    * \param[out] value the current value of the setting, or the default if the setting has yet to be configured
 320    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 321    *               to denote global add-on settings from settings.xml.
 322    * \return true if the setting's value was retrieved, false otherwise.
 323    *
 324    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 325    */
 326   bool GetSettingInt(const std::string& key,
 327                      int& value,
 328                      AddonInstanceId id = ADDON_SETTINGS_ID) override;
 329
 330   /*!
 331    * \brief Retrieve a particular settings value as number.
 332    *
 333    * If a previously configured user setting is available, we return it's value, else we return the default (if available)
 334    *
 335    * \param[in] key the id of the setting to retrieve
 336    * \param[out] value the current value of the setting, or the default if the setting has yet to be configured
 337    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 338    *               to denote global add-on settings from settings.xml.
 339    * \return true if the setting's value was retrieved, false otherwise.
 340    *
 341    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 342    */
 343   bool GetSettingNumber(const std::string& key,
 344                         double& value,
 345                         AddonInstanceId id = ADDON_SETTINGS_ID) override;
 346
 347   /*!
 348    * \brief Retrieve a particular settings value as string
 349    *
 350    * If a previously configured user setting is available, we return it's value, else we return the default (if available)
 351    *
 352    * \param[in] key the id of the setting to retrieve
 353    * \param[out] value the current value of the setting, or the default if the setting has yet to be configured
 354    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 355    *               to denote global add-on settings from settings.xml.
 356    * \return true if the setting's value was retrieved, false otherwise.
 357    *
 358    * \sa LoadSettings, LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, UpdateSetting
 359    */
 360   bool GetSettingString(const std::string& key,
 361                         std::string& value,
 362                         AddonInstanceId id = ADDON_SETTINGS_ID) override;
 363
 364   std::shared_ptr<CAddonSettings> GetSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 365
 366   /*! \brief get the required version of a dependency.
 367    \param dependencyID the addon ID of the dependency.
 368    \return the version this addon requires.
 369    */
 370   CAddonVersion GetDependencyVersion(const std::string& dependencyID) const override;
 371
 372   /*! \brief return whether or not this addon satisfies the given version requirements
 373    \param version the version to meet.
 374    \return true if  min_version <= version <= current_version, false otherwise.
 375    */
 376   bool MeetsVersion(const CAddonVersion& versionMin, const CAddonVersion& version) const override;
 377
 378   bool ReloadSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 379
 380   void ResetSettings(AddonInstanceId id = ADDON_SETTINGS_ID) override;
 381
 382   /*! \brief retrieve the running instance of an add-on if it persists while running.
 383    */
 384   AddonPtr GetRunningInstance() const override { return AddonPtr(); }
 385
 386   void OnPreInstall() override{};
 387   void OnPostInstall(bool update, bool modal) override{};
 388   void OnPreUnInstall() override{};
 389   void OnPostUnInstall() override{};
 390
 391 protected:
 392   /*!
 393    * \brief Whether or not the settings have been initialized.
 394    *
 395    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 396    *               to denote global add-on settings from settings.xml.
 397    * \return true if settings initialize was successfull
 398    */
 399   virtual bool SettingsInitialized(AddonInstanceId id = ADDON_SETTINGS_ID) const;
 400
 401   /*!
 402    * \brief Whether or not the settings have been loaded.
 403    *
 404    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 405    *               to denote global add-on settings from settings.xml.
 406    * \return true if settings are loaded correct
 407    */
 408   virtual bool SettingsLoaded(AddonInstanceId id = ADDON_SETTINGS_ID) const;
 409
 410   /*!
 411    * \brief Load the default settings and override these with any previously configured user settings
 412    *
 413    * \param[in] bForce force the load of settings even if they are already loaded (reload)
 414    * \param[in] loadUserSettings whether or not to load user settings
 415    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 416    *               to denote global add-on settings from settings.xml.
 417    * \return true if settings exist, false otherwise
 418    *
 419    * \sa LoadUserSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting, UpdateSetting
 420    */
 421   bool LoadSettings(bool bForce, bool loadUserSettings, AddonInstanceId id = ADDON_SETTINGS_ID);
 422
 423   /*!
 424    * \brief Load the user settings
 425    *
 426    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 427    *               to denote global add-on settings from settings.xml.
 428    * \return true if user settings exist, false otherwise
 429    *
 430    * \sa LoadSettings, SaveSettings, HasSettings, HasUserSettings, GetSetting, UpdateSetting
 431    */
 432   virtual bool LoadUserSettings(AddonInstanceId id = ADDON_SETTINGS_ID);
 433
 434   /*!
 435    * \brief Whether there are settings to be saved
 436    *
 437    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 438    *               to denote global add-on settings from settings.xml.
 439    * \return true if settings has to save
 440    *
 441    * \sa SaveSettings
 442    */
 443   virtual bool HasSettingsToSave(AddonInstanceId id = ADDON_SETTINGS_ID) const;
 444
 445   /*!
 446    * \brief Parse settings from an XML document
 447    *
 448    * \param[in] doc XML document to parse for settings
 449    * \param[in] loadDefaults if true, the default attribute is used and settings are reset prior to parsing, else the value attribute is used.
 450    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 451    *               to denote global add-on settings from settings.xml.
 452    * \return true if settings are loaded, false otherwise
 453    *
 454    * \sa SettingsToXML
 455    */
 456   virtual bool SettingsFromXML(const CXBMCTinyXML& doc,
 457                                bool loadDefaults,
 458                                AddonInstanceId id = ADDON_SETTINGS_ID);
 459
 460   /*!
 461    * \brief Write settings into an XML document
 462    *
 463    * \param[out] doc XML document to receive the settings
 464    * \param[in] id Instance identifier to use, use @ref ADDON_SETTINGS_ID
 465    *               to denote global add-on settings from settings.xml.
 466    * \return true if settings are saved, false otherwise
 467    *
 468    * \sa SettingsFromXML
 469    */
 470   virtual bool SettingsToXML(CXBMCTinyXML& doc, AddonInstanceId id = ADDON_SETTINGS_ID) const;
 471
 472   const AddonInfoPtr m_addonInfo;
 473
 474 private:
 475   struct CSettingsData
 476   {
 477     bool m_loadSettingsFailed{false};
 478     bool m_hasUserSettings{false};
 479     std::string m_addonSettingsPath;
 480     std::string m_userSettingsPath;
 481     std::shared_ptr<CAddonSettings> m_addonSettings;
 482   };
 483
 484   bool InitSettings(AddonInstanceId id);
 485   std::shared_ptr<CAddonSettings> FindInstanceSettings(AddonInstanceId id) const;
 486
 487   mutable std::unordered_map<AddonInstanceId, CSettingsData> m_settings;
 488   const AddonType m_type;
 489 };
 490
 491 }; // namespace ADDON