xbmc/peripherals/Peripherals.h

   1 /*
   2  *  Copyright (C) 2005-2024 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 "bus/PeripheralBus.h"
  12 #include "devices/Peripheral.h"
  13 #include "interfaces/IAnnouncer.h"
  14 #include "messaging/IMessageTarget.h"
  15 #include "peripherals/events/interfaces/IEventScannerCallback.h"
  16 #include "settings/lib/ISettingCallback.h"
  17 #include "threads/CriticalSection.h"
  18 #include "threads/Thread.h"
  19 #include "utils/Observer.h"
  20
  21 #include <memory>
  22 #include <vector>
  23
  24 class CFileItemList;
  25 class CInputManager;
  26 class CSetting;
  27 class CSettingsCategory;
  28 class CAction;
  29 class CKey;
  30
  31 namespace tinyxml2
  32 {
  33 class XMLElement;
  34 }
  35
  36 namespace KODI
  37 {
  38 namespace GAME
  39 {
  40 class CControllerManager;
  41 }
  42
  43 namespace JOYSTICK
  44 {
  45 class IButtonMapper;
  46 }
  47 } // namespace KODI
  48
  49 namespace PERIPHERALS
  50 {
  51 class CEventScanner;
  52
  53 /*!
  54  * \ingroup peripherals
  55  */
  56 class CPeripherals : public ISettingCallback,
  57                      public Observable,
  58                      public KODI::MESSAGING::IMessageTarget,
  59                      public IEventScannerCallback,
  60                      public ANNOUNCEMENT::IAnnouncer
  61 {
  62 public:
  63   explicit CPeripherals(CInputManager& inputManager,
  64                         KODI::GAME::CControllerManager& controllerProfiles);
  65
  66   ~CPeripherals() override;
  67
  68   /*!
  69    * @brief Initialise the peripherals manager.
  70    */
  71   void Initialise();
  72
  73   /*!
  74    * @brief Clear all data known by the peripherals manager.
  75    */
  76   void Clear();
  77
  78   /*!
  79    * @brief Get the instance of the peripheral at the given location.
  80    * @param strLocation The location.
  81    * @param busType The bus to query. Default (PERIPHERAL_BUS_UNKNOWN) searches all busses.
  82    * @return The peripheral or NULL if it wasn't found.
  83    */
  84   PeripheralPtr GetPeripheralAtLocation(const std::string& strLocation,
  85                                         PeripheralBusType busType = PERIPHERAL_BUS_UNKNOWN) const;
  86
  87   /*!
  88    * @brief Check whether a peripheral is present at the given location.
  89    * @param strLocation The location.
  90    * @param busType The bus to query. Default (PERIPHERAL_BUS_UNKNOWN) searches all busses.
  91    * @return True when a peripheral was found, false otherwise.
  92    */
  93   bool HasPeripheralAtLocation(const std::string& strLocation,
  94                                PeripheralBusType busType = PERIPHERAL_BUS_UNKNOWN) const;
  95
  96   /*!
  97    * @brief Get the bus that holds the device with the given location.
  98    * @param strLocation The location.
  99    * @return The bus or NULL if no device was found.
 100    */
 101   PeripheralBusPtr GetBusWithDevice(const std::string& strLocation) const;
 102
 103   /*!
 104    * @brief Check if any busses support the given feature
 105    * @param feature The feature to check for
 106    * @return True if a bus supports the feature, false otherwise
 107    */
 108   bool SupportsFeature(PeripheralFeature feature) const;
 109
 110   /*!
 111    * @brief Get all peripheral instances that have the given feature.
 112    * @param results The list of results.
 113    * @param feature The feature to search for.
 114    * @param busType The bus to query. Default (PERIPHERAL_BUS_UNKNOWN) searches all busses.
 115    * @return The number of devices that have been found.
 116    */
 117   int GetPeripheralsWithFeature(PeripheralVector& results,
 118                                 const PeripheralFeature feature,
 119                                 PeripheralBusType busType = PERIPHERAL_BUS_UNKNOWN) const;
 120
 121   size_t GetNumberOfPeripherals() const;
 122
 123   /*!
 124    * @brief Check whether there is at least one device present with the given feature.
 125    * @param feature The feature to check for.
 126    * @param busType The bus to query. Default (PERIPHERAL_BUS_UNKNOWN) searches all busses.
 127    * @return True when at least one device was found with this feature, false otherwise.
 128    */
 129   bool HasPeripheralWithFeature(const PeripheralFeature feature,
 130                                 PeripheralBusType busType = PERIPHERAL_BUS_UNKNOWN) const;
 131
 132   /*!
 133    * @brief Called when a device has been added to a bus.
 134    * @param bus The bus the device was added to.
 135    * @param peripheral The peripheral that has been added.
 136    */
 137   void OnDeviceAdded(const CPeripheralBus& bus, const CPeripheral& peripheral);
 138
 139   /*!
 140    * @brief Called when a device has been deleted from a bus.
 141    * @param bus The bus from which the device removed.
 142    * @param peripheral The peripheral that has been removed.
 143    */
 144   void OnDeviceDeleted(const CPeripheralBus& bus, const CPeripheral& peripheral);
 145
 146   /*!
 147    * @brief Creates a new instance of a peripheral.
 148    * @param bus The bus on which this peripheral is present.
 149    * @param result The scan result from the device scanning code.
 150    * @return The new peripheral or NULL if it could not be created.
 151    */
 152   void CreatePeripheral(CPeripheralBus& bus, const PeripheralScanResult& result);
 153
 154   /*!
 155    * @brief Add the settings that are defined in the mappings file to the peripheral (if there is
 156    * anything defined).
 157    * @param peripheral The peripheral to get the settings for.
 158    */
 159   void GetSettingsFromMapping(CPeripheral& peripheral) const;
 160
 161   /*!
 162    * @brief Trigger a device scan on all known busses
 163    */
 164   void TriggerDeviceScan(const PeripheralBusType type = PERIPHERAL_BUS_UNKNOWN);
 165
 166   /*!
 167    * @brief Get the instance of a bus given it's type.
 168    * @param type The bus type.
 169    * @return The bus or NULL if it wasn't found.
 170    */
 171   PeripheralBusPtr GetBusByType(const PeripheralBusType type) const;
 172
 173   /*!
 174    * @brief Get all fileitems for a path.
 175    * @param strPath The path to the directory to get the items from.
 176    * @param items The item list.
 177    */
 178   void GetDirectory(const std::string& strPath, CFileItemList& items) const;
 179
 180   /*!
 181    * @brief Get the instance of a peripheral given it's path.
 182    * @param strPath The path to the peripheral.
 183    * @return The peripheral or NULL if it wasn't found.
 184    */
 185   PeripheralPtr GetByPath(const std::string& strPath) const;
 186
 187   /*!
 188    * @brief Try to let one of the peripherals handle an action.
 189    * @param action The change to handle.
 190    * @return True when this change was handled by a peripheral (and should not be handled by
 191    * anything else), false otherwise.
 192    */
 193   bool OnAction(const CAction& action);
 194
 195   /*!
 196    * @brief Check whether there's a peripheral that reports to be muted.
 197    * @return True when at least one peripheral reports to be muted, false otherwise.
 198    */
 199   bool IsMuted();
 200
 201   /*!
 202    * @brief Try to toggle the mute status via a peripheral.
 203    * @return True when this change was handled by a peripheral (and should not be handled by
 204    * anything else), false otherwise.
 205    */
 206   bool ToggleMute();
 207
 208   /*!
 209    * @brief Try to toggle the playing device state via a peripheral.
 210    * @param mode Whether to activate, put on standby or toggle the source.
 211    * @return True when the playing device has been switched on, false otherwise.
 212    */
 213   bool ToggleDeviceState(const CecStateChange mode = STATE_SWITCH_TOGGLE);
 214
 215   /*!
 216    * @brief Try to mute the audio via a peripheral.
 217    * @return True when this change was handled by a peripheral (and should not be handled by
 218    * anything else), false otherwise.
 219    */
 220   bool Mute()
 221   {
 222     return ToggleMute();
 223   } //! @todo CEC only supports toggling the mute status at this time
 224
 225   /*!
 226    * @brief Try to unmute the audio via a peripheral.
 227    * @return True when this change was handled by a peripheral (and should not be handled by
 228    * anything else), false otherwise.
 229    */
 230   bool UnMute()
 231   {
 232     return ToggleMute();
 233   } //! @todo CEC only supports toggling the mute status at this time
 234
 235   /*!
 236    * @brief Try to get a keypress from a peripheral.
 237    * @param frameTime The current frametime.
 238    * @param key The fetched key.
 239    * @return True when a keypress was fetched, false otherwise.
 240    */
 241   bool GetNextKeypress(float frameTime, CKey& key);
 242
 243   /*!
 244    * @brief Register with the event scanner to control scan timing
 245    * @return A handle that unregisters itself when expired
 246    */
 247   EventPollHandlePtr RegisterEventPoller();
 248
 249   /*!
 250    * @brief Register with the event scanner to disable event processing
 251    * @return A handle that unregisters itself when expired
 252    */
 253   EventLockHandlePtr RegisterEventLock();
 254
 255   /*!
 256    *
 257    */
 258   void OnUserNotification();
 259
 260   /*!
 261    * @brief Request peripherals with the specified feature to perform a quick test
 262    * @return true if any peripherals support the feature, false otherwise
 263    */
 264   void TestFeature(PeripheralFeature feature);
 265
 266   /*!
 267    * \brief Request all devices with power-off support to power down
 268    */
 269   void PowerOffDevices();
 270
 271   bool SupportsCEC() const
 272   {
 273 #if defined(HAVE_LIBCEC)
 274     return true;
 275 #else
 276     return false;
 277 #endif
 278   }
 279
 280   // implementation of IEventScannerCallback
 281   void ProcessEvents(void) override;
 282
 283   /*!
 284    * \brief Initialize button mapping
 285    *
 286    * This command enables button mapping on all busses. Button maps allow
 287    * connect events from the driver to the higher-level features used by
 288    * controller profiles.
 289    *
 290    * If user input is required, a blocking dialog may be shown.
 291    */
 292   void EnableButtonMapping();
 293
 294   /*!
 295    * \brief Get an add-on that can provide button maps for a device
 296    * \return An add-on that provides button maps, or empty if no add-on is found
 297    */
 298   PeripheralAddonPtr GetAddonWithButtonMap(const CPeripheral* device);
 299
 300   /*!
 301    * \brief Reset all button maps to the defaults for all devices and the given controller
 302    * \param controllerId The controller profile to reset
 303    * @todo Add a device parameter to allow resetting button maps per-device
 304    */
 305   void ResetButtonMaps(const std::string& controllerId);
 306
 307   /*!
 308    * \brief Register a button mapper interface
 309    * \param mapper The button mapper
 310    *
 311    * Clients implementing the IButtonMapper interface call
 312    * \ref CPeripherals::RegisterJoystickButtonMapper to register themselves
 313    * as eligible for button mapping commands.
 314    *
 315    * When registering the mapper is forwarded to all peripherals. See
 316    * \ref CPeripheral::RegisterJoystickButtonMapper for what is done to the
 317    * mapper after being given to the peripheral.
 318    */
 319   void RegisterJoystickButtonMapper(KODI::JOYSTICK::IButtonMapper* mapper);
 320
 321   /*!
 322    * \brief Unregister a button mapper interface
 323    * \param mapper The button mapper
 324    */
 325   void UnregisterJoystickButtonMapper(KODI::JOYSTICK::IButtonMapper* mapper);
 326
 327   // implementation of ISettingCallback
 328   void OnSettingChanged(const std::shared_ptr<const CSetting>& setting) override;
 329   void OnSettingAction(const std::shared_ptr<const CSetting>& setting) override;
 330
 331   // implementation of IMessageTarget
 332   void OnApplicationMessage(KODI::MESSAGING::ThreadMessage* pMsg) override;
 333   int GetMessageMask() override;
 334
 335   // implementation of IAnnouncer
 336   void Announce(ANNOUNCEMENT::AnnouncementFlag flag,
 337                 const std::string& sender,
 338                 const std::string& message,
 339                 const CVariant& data) override;
 340
 341   /*!
 342    * \brief Access the input manager passed to the constructor
 343    */
 344   CInputManager& GetInputManager()
 345   {
 346     return m_inputManager;
 347   }
 348
 349   /*!
 350    * \brief Access controller profiles through the construction parameter
 351    */
 352   KODI::GAME::CControllerManager& GetControllerProfiles()
 353   {
 354     return m_controllerProfiles;
 355   }
 356
 357   /*!
 358    * \brief Get a mutex that allows for add-on install tasks to block on each other
 359    */
 360   CCriticalSection& GetAddonInstallMutex()
 361   {
 362     return m_addonInstallMutex;
 363   }
 364
 365 private:
 366   bool LoadMappings();
 367   bool GetMappingForDevice(const CPeripheralBus& bus, PeripheralScanResult& result) const;
 368   static void GetSettingsFromMappingsFile(
 369       tinyxml2::XMLElement* xmlNode, std::map<std::string, PeripheralDeviceSetting>& m_settings);
 370
 371   void OnDeviceChanged();
 372
 373   // Construction parameters
 374   CInputManager& m_inputManager;
 375   KODI::GAME::CControllerManager& m_controllerProfiles;
 376
 377 #if !defined(HAVE_LIBCEC)
 378   bool m_bMissingLibCecWarningDisplayed = false;
 379 #endif
 380   std::vector<PeripheralBusPtr> m_busses;
 381   std::vector<PeripheralDeviceMapping> m_mappings;
 382   std::unique_ptr<CEventScanner> m_eventScanner;
 383   mutable CCriticalSection m_critSectionBusses;
 384   mutable CCriticalSection m_critSectionMappings;
 385   CCriticalSection m_addonInstallMutex;
 386 };
 387 } // namespace PERIPHERALS