xbmc/pvr/addons/PVRClients.h

   1 /*
   2  *  Copyright (C) 2012-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/IAddonManagerCallback.h"
  12 #include "addons/kodi-dev-kit/include/kodi/c-api/addon-instance/pvr/pvr_general.h"
  13 #include "threads/CriticalSection.h"
  14
  15 #include <functional>
  16 #include <map>
  17 #include <memory>
  18 #include <string>
  19 #include <vector>
  20
  21 class CVariant;
  22
  23 namespace ADDON
  24 {
  25   struct AddonEvent;
  26   class CAddonInfo;
  27 }
  28
  29 namespace PVR
  30 {
  31 class CPVRChannel;
  32 class CPVRChannelGroup;
  33 class CPVRChannelGroupMember;
  34 class CPVRChannelGroups;
  35 class CPVRProvidersContainer;
  36 class CPVRClient;
  37 class CPVREpg;
  38 class CPVRRecordings;
  39 class CPVRTimerType;
  40 class CPVRTimersContainer;
  41
  42 typedef std::map<int, std::shared_ptr<CPVRClient>> CPVRClientMap;
  43
  44 /**
  45    * Holds generic data about a backend (number of channels etc.)
  46    */
  47 struct SBackend
  48 {
  49   std::string clientname;
  50   std::string instancename;
  51   std::string name;
  52   std::string version;
  53   std::string host;
  54   int numTimers = 0;
  55   int numRecordings = 0;
  56   int numDeletedRecordings = 0;
  57   int numProviders = 0;
  58   int numChannelGroups = 0;
  59   int numChannels = 0;
  60   uint64_t diskUsed = 0;
  61   uint64_t diskTotal = 0;
  62 };
  63
  64   class CPVRClients : public ADDON::IAddonMgrCallback
  65   {
  66   public:
  67     CPVRClients();
  68     ~CPVRClients() override;
  69
  70     /*!
  71      * @brief Start all clients.
  72      */
  73     void Start();
  74
  75     /*!
  76      * @brief Stop all clients.
  77      */
  78     void Stop();
  79
  80     /*!
  81      * @brief Continue all clients.
  82      */
  83     void Continue();
  84
  85     /*!
  86      * @brief Update all clients, sync with Addon Manager state (start, restart, shutdown clients).
  87      * @param changedAddonId The id of the changed addon, empty string denotes 'any addon'.
  88      * @param changedInstanceId The Identifier of the changed add-on instance
  89      */
  90     void UpdateClients(
  91         const std::string& changedAddonId = "",
  92         ADDON::AddonInstanceId changedInstanceId = ADDON::ADDON_SINGLETON_INSTANCE_ID);
  93
  94     /*!
  95      * @brief Restart a single client add-on.
  96      * @param addonId The add-on to restart.
  97      * @param instanceId Instance identifier to use
  98      * @param bDataChanged True if the client's data changed, false otherwise (unused).
  99      * @return True if the client was found and restarted, false otherwise.
 100      */
 101     bool RequestRestart(const std::string& addonId,
 102                         ADDON::AddonInstanceId instanceId,
 103                         bool bDataChanged) override;
 104
 105     /*!
 106      * @brief Stop a client.
 107      * @param clientId The id of the client to stop.
 108      * @param restart If true, restart the client.
 109      * @return True if the client was found, false otherwise.
 110      */
 111     bool StopClient(int clientId, bool restart);
 112
 113     /*!
 114      * @brief Handle addon events (enable, disable, ...).
 115      * @param event The addon event.
 116      */
 117     void OnAddonEvent(const ADDON::AddonEvent& event);
 118
 119     /*!
 120      * @brief Get the number of created clients.
 121      * @return The amount of created clients.
 122      */
 123     int CreatedClientAmount() const;
 124
 125     /*!
 126      * @brief Check whether there are any created clients.
 127      * @return True if at least one client is created.
 128      */
 129     bool HasCreatedClients() const;
 130
 131     /*!
 132      * @brief Check whether a given client ID points to a created client.
 133      * @param iClientId The client ID.
 134      * @return True if the the client ID represents a created client, false otherwise.
 135      */
 136     bool IsCreatedClient(int iClientId) const;
 137
 138     /*!
 139      * @brief Get the the client for the given client id, if it is created.
 140      * @param clientId The ID of the client to get.
 141      * @return The client if found, nullptr otherwise.
 142      */
 143     std::shared_ptr<CPVRClient> GetCreatedClient(int clientId) const;
 144
 145     /*!
 146      * @brief Get all created clients.
 147      * @return All created clients.
 148      */
 149     CPVRClientMap GetCreatedClients() const;
 150
 151     /*!
 152      * @brief Get the ID of the first created client.
 153      * @return the ID or PVR_CLIENT_INVALID_UID if no clients are created;
 154      */
 155     int GetFirstCreatedClientID() const;
 156
 157     /*!
 158      * @brief Check whether there are any created, but not (yet) connected clients.
 159      * @return True if at least one client is ignored.
 160      */
 161     bool HasIgnoredClients() const;
 162
 163     /*!
 164      * @brief Get the number of enabled clients.
 165      * @return The amount of enabled clients.
 166      */
 167     int EnabledClientAmount() const;
 168
 169     /*!
 170      * @brief Check whether a given client ID points to an enabled client.
 171      * @param clientId The client ID.
 172      * @return True if the the client ID represents an enabled client, false otherwise.
 173      */
 174     bool IsEnabledClient(int clientId) const;
 175
 176     /*!
 177      * @brief Get a list of the enabled client infos.
 178      * @return A list of enabled client infos.
 179      */
 180     std::vector<CVariant> GetEnabledClientInfos() const;
 181
 182     /*!
 183      * @brief Get info required for providers. Include both enabled and disabled PVR add-ons
 184      * @return A list containing the information required to create client providers.
 185      */
 186     std::vector<CVariant> GetClientProviderInfos() const;
 187
 188     //@}
 189
 190     /*! @name general methods */
 191     //@{
 192
 193     /*!
 194      * @brief Returns properties about all created clients
 195      * @return the properties
 196      */
 197     std::vector<SBackend> GetBackendProperties() const;
 198
 199     //@}
 200
 201     /*! @name Timer methods */
 202     //@{
 203
 204     /*!
 205      * @brief Get all timers from the given clients
 206      * @param clients The clients to fetch data from. Leave empty to fetch data from all created clients.
 207      * @param timers Store the timers in this container.
 208      * @param failedClients in case of errors will contain the ids of the clients for which the timers could not be obtained.
 209      * @return true on success for all clients, false in case of error for at least one client.
 210      */
 211     bool GetTimers(const std::vector<std::shared_ptr<CPVRClient>>& clients,
 212                    CPVRTimersContainer* timers,
 213                    std::vector<int>& failedClients) const;
 214
 215     /*!
 216      * @brief Update all timer types from the given clients
 217      * @param clients The clients to fetch data from. Leave empty to fetch data from all created clients.
 218      * @param failedClients in case of errors will contain the ids of the clients for which the timer types could not be obtained.
 219      * @return PVR_ERROR_NO_ERROR if the operation succeeded, the respective PVR_ERROR value otherwise.
 220      */
 221     PVR_ERROR UpdateTimerTypes(const std::vector<std::shared_ptr<CPVRClient>>& clients,
 222                                std::vector<int>& failedClients);
 223
 224     /*!
 225      * @brief Get all timer types supported by the backends, without updating them from the backends.
 226      * @return the types.
 227      */
 228     const std::vector<std::shared_ptr<CPVRTimerType>> GetTimerTypes() const;
 229
 230     //@}
 231
 232     /*! @name Recording methods */
 233     //@{
 234
 235     /*!
 236      * @brief Get all recordings from the given clients
 237      * @param clients The clients to fetch data from. Leave empty to fetch data from all created clients.
 238      * @param recordings Store the recordings in this container.
 239      * @param deleted If true, return deleted recordings, return not deleted recordings otherwise.
 240      * @param failedClients in case of errors will contain the ids of the clients for which the recordings could not be obtained.
 241      * @return PVR_ERROR_NO_ERROR if the operation succeeded, the respective PVR_ERROR value otherwise.
 242      */
 243     PVR_ERROR GetRecordings(const std::vector<std::shared_ptr<CPVRClient>>& clients,
 244                             CPVRRecordings* recordings,
 245                             bool deleted,
 246                             std::vector<int>& failedClients) const;
 247
 248     /*!
 249      * @brief Delete all "soft" deleted recordings permanently on the backend.
 250      * @return PVR_ERROR_NO_ERROR if the operation succeeded, the respective PVR_ERROR value otherwise.
 251      */
 252     PVR_ERROR DeleteAllRecordingsFromTrash();
 253
 254     //@}
 255
 256     /*! @name EPG methods */
 257     //@{
 258
 259     /*!
 260      * @brief Tell all clients the past time frame to use when notifying epg events back to Kodi.
 261      *
 262      * The clients might push epg events asynchronously to Kodi using the callback function
 263      * EpgEventStateChange. To be able to only push events that are actually of interest for Kodi,
 264      * clients need to know about the future epg time frame Kodi uses.
 265      *
 266      * @param[in] iPastDays number of days before "now".
 267      *                        @ref EPG_TIMEFRAME_UNLIMITED means that Kodi is interested in all
 268      *                        epg events, regardless of event times.
 269      * @return @ref PVR_ERROR_NO_ERROR if the operation succeeded, the respective @ref PVR_ERROR
 270      *         value otherwise.
 271      */
 272     PVR_ERROR SetEPGMaxPastDays(int iPastDays);
 273
 274     /*!
 275      * @brief Tell all clients the future time frame to use when notifying epg events back to Kodi.
 276      *
 277      * The clients might push epg events asynchronously to Kodi using the callback function
 278      * EpgEventStateChange. To be able to only push events that are actually of interest for Kodi,
 279      * clients need to know about the future epg time frame Kodi uses.
 280      *
 281      * @param[in] iFutureDays number of days from "now".
 282      *                        @ref EPG_TIMEFRAME_UNLIMITED means that Kodi is interested in all
 283      *                        epg events, regardless of event times.
 284      * @return @ref PVR_ERROR_NO_ERROR if the operation succeeded, the respective @ref PVR_ERROR
 285      *         value otherwise.
 286      */
 287     PVR_ERROR SetEPGMaxFutureDays(int iFutureDays);
 288
 289     //@}
 290
 291     /*! @name Channel methods */
 292     //@{
 293
 294     /*!
 295      * @brief Get all channels from the given clients.
 296      * @param clients The clients to fetch data from. Leave empty to fetch data from all created clients.
 297      * @param bRadio Whether to fetch radio or TV channels.
 298      * @param channels The container to store the channels.
 299      * @param failedClients in case of errors will contain the ids of the clients for which the channels could not be obtained.
 300      * @return PVR_ERROR_NO_ERROR if the channels were fetched successfully, last error otherwise.
 301      */
 302     PVR_ERROR GetChannels(const std::vector<std::shared_ptr<CPVRClient>>& clients,
 303                           bool bRadio,
 304                           std::vector<std::shared_ptr<CPVRChannel>>& channels,
 305                           std::vector<int>& failedClients) const;
 306
 307     /*!
 308      * @brief Get all providers from backends.
 309      * @param clients The clients to fetch data from. Leave empty to fetch data from all created clients.
 310      * @param group The container to store the providers in.
 311      * @param failedClients in case of errors will contain the ids of the clients for which the providers could not be obtained.
 312      * @return PVR_ERROR_NO_ERROR if the providers were fetched successfully, last error otherwise.
 313      */
 314     PVR_ERROR GetProviders(const std::vector<std::shared_ptr<CPVRClient>>& clients,
 315                            CPVRProvidersContainer* providers,
 316                            std::vector<int>& failedClients) const;
 317
 318     /*!
 319      * @brief Get all channel groups from the given clients.
 320      * @param clients The clients to fetch data from. Leave empty to fetch data from all created clients.
 321      * @param groups Store the channel groups in this container.
 322      * @param failedClients in case of errors will contain the ids of the clients for which the channel groups could not be obtained.
 323      * @return PVR_ERROR_NO_ERROR if the channel groups were fetched successfully, last error otherwise.
 324      */
 325     PVR_ERROR GetChannelGroups(const std::vector<std::shared_ptr<CPVRClient>>& clients,
 326                                CPVRChannelGroups* groups,
 327                                std::vector<int>& failedClients) const;
 328
 329     /*!
 330      * @brief Get all group members of a channel group from the given clients.
 331      * @param clients The clients to fetch data from. Leave empty to fetch data from all created clients.
 332      * @param group The group to get the member for.
 333      * @param groupMembers The container for the group members.
 334      * @param failedClients in case of errors will contain the ids of the clients for which the channel group members could not be obtained.
 335      * @return PVR_ERROR_NO_ERROR if the channel group members were fetched successfully, last error otherwise.
 336      */
 337     PVR_ERROR GetChannelGroupMembers(
 338         const std::vector<std::shared_ptr<CPVRClient>>& clients,
 339         CPVRChannelGroup* group,
 340         std::vector<std::shared_ptr<CPVRChannelGroupMember>>& groupMembers,
 341         std::vector<int>& failedClients) const;
 342
 343     /*!
 344      * @brief Get a list of clients providing a channel scan dialog.
 345      * @return All clients supporting channel scan.
 346      */
 347     std::vector<std::shared_ptr<CPVRClient>> GetClientsSupportingChannelScan() const;
 348
 349     /*!
 350      * @brief Get a list of clients providing a channel settings dialog.
 351      * @return All clients supporting channel settings.
 352      */
 353     std::vector<std::shared_ptr<CPVRClient>> GetClientsSupportingChannelSettings(bool bRadio) const;
 354
 355     /*!
 356      * @brief Get whether or not any client supports recording size.
 357      * @return True if any client supports recording size.
 358      */
 359     bool AnyClientSupportingRecordingsSize() const;
 360
 361     /*!
 362      * @brief Get whether or not any client supports EPG.
 363      * @return True if any client supports EPG.
 364      */
 365     bool AnyClientSupportingEPG() const;
 366
 367     /*!
 368      * @brief Get whether or not any client supports recordings.
 369      * @return True if any client supports recordings.
 370      */
 371     bool AnyClientSupportingRecordings() const;
 372     //@}
 373
 374     /*!
 375      * @brief Get whether or not any client supports recordings delete.
 376      * @return True if any client supports recordings delete.
 377      */
 378     bool AnyClientSupportingRecordingsDelete() const;
 379     //@}
 380
 381     /*! @name Power management methods */
 382     //@{
 383
 384     /*!
 385      * @brief Propagate "system sleep" event to clients
 386      */
 387     void OnSystemSleep();
 388
 389     /*!
 390      * @brief Propagate "system wakeup" event to clients
 391      */
 392     void OnSystemWake();
 393
 394     /*!
 395      * @brief Propagate "power saving activated" event to clients
 396      */
 397     void OnPowerSavingActivated();
 398
 399     /*!
 400      * @brief Propagate "power saving deactivated" event to clients
 401      */
 402     void OnPowerSavingDeactivated();
 403
 404     //@}
 405
 406     /*!
 407      * @brief Notify a change of an addon connection state.
 408      * @param client The changed client.
 409      * @param strConnectionString A human-readable string providing additional information.
 410      * @param newState The new connection state.
 411      * @param strMessage A human readable string replacing default state message.
 412      */
 413     void ConnectionStateChange(CPVRClient* client,
 414                                const std::string& strConnectionString,
 415                                PVR_CONNECTION_STATE newState,
 416                                const std::string& strMessage);
 417
 418   private:
 419     /*!
 420      * @brief Get the known instance ids for a given addon id.
 421      * @param addonID The addon id.
 422      * @return The list of known instance ids.
 423      */
 424     std::vector<ADDON::AddonInstanceId> GetKnownInstanceIds(const std::string& addonID) const;
 425
 426     bool GetAddonsWithStatus(
 427         const std::string& changedAddonId,
 428         std::vector<std::pair<std::shared_ptr<ADDON::CAddonInfo>, bool>>& addonsWithStatus) const;
 429
 430     std::vector<std::pair<ADDON::AddonInstanceId, bool>> GetInstanceIdsWithStatus(
 431         const std::shared_ptr<ADDON::CAddonInfo>& addon, bool addonIsEnabled) const;
 432
 433     /*!
 434      * @brief Get the client instance for a given client id.
 435      * @param clientId The id of the client to get.
 436      * @return The client if found, nullptr otherwise.
 437      */
 438     std::shared_ptr<CPVRClient> GetClient(int clientId) const;
 439
 440     /*!
 441      * @brief Check whether a client is known.
 442      * @param iClientId The id of the client to check.
 443      * @return True if this client is known, false otherwise.
 444      */
 445     bool IsKnownClient(int iClientId) const;
 446
 447     /*!
 448      * @brief Get all created clients and clients not (yet) ready to use.
 449      * @param clientsReady Store the created clients in this map.
 450      * @param clientsNotReady Store the the ids of the not (yet) ready clients in this list.
 451      * @return PVR_ERROR_NO_ERROR in case all clients are ready, PVR_ERROR_SERVER_ERROR otherwise.
 452      */
 453     PVR_ERROR GetCallableClients(CPVRClientMap& clientsReady,
 454                                  std::vector<int>& clientsNotReady) const;
 455
 456     typedef std::function<PVR_ERROR(const std::shared_ptr<CPVRClient>&)> PVRClientFunction;
 457
 458     /*!
 459      * @brief Wraps calls to the given clients in order to do common pre and post function invocation actions.
 460      * @param strFunctionName The function name, for logging purposes.
 461      * @param clients The clients to wrap.
 462      * @param function The function to wrap. It has to have return type PVR_ERROR and must take a const reference to a std::shared_ptr<CPVRClient> as parameter.
 463      * @param failedClients Contains a list of the ids of clients for that the call failed, if any.
 464      * @return PVR_ERROR_NO_ERROR on success, any other PVR_ERROR_* value otherwise.
 465      */
 466     PVR_ERROR ForClients(const char* strFunctionName,
 467                          const std::vector<std::shared_ptr<CPVRClient>>& clients,
 468                          const PVRClientFunction& function,
 469                          std::vector<int>& failedClients) const;
 470
 471     /*!
 472      * @brief Wraps calls to all created clients in order to do common pre and post function invocation actions.
 473      * @param strFunctionName The function name, for logging purposes.
 474      * @param function The function to wrap. It has to have return type PVR_ERROR and must take a const reference to a std::shared_ptr<CPVRClient> as parameter.
 475      * @return PVR_ERROR_NO_ERROR on success, any other PVR_ERROR_* value otherwise.
 476      */
 477     PVR_ERROR ForCreatedClients(const char* strFunctionName,
 478                                 const PVRClientFunction& function) const;
 479
 480     /*!
 481      * @brief Wraps calls to all created clients in order to do common pre and post function invocation actions.
 482      * @param strFunctionName The function name, for logging purposes.
 483      * @param function The function to wrap. It has to have return type PVR_ERROR and must take a const reference to a std::shared_ptr<CPVRClient> as parameter.
 484      * @param failedClients Contains a list of the ids of clients for that the call failed, if any.
 485      * @return PVR_ERROR_NO_ERROR on success, any other PVR_ERROR_* value otherwise.
 486      */
 487     PVR_ERROR ForCreatedClients(const char* strFunctionName,
 488                                 const PVRClientFunction& function,
 489                                 std::vector<int>& failedClients) const;
 490
 491     mutable CCriticalSection m_critSection;
 492     CPVRClientMap m_clientMap;
 493   };
 494 }