xbmc/interfaces/legacy/Monitor.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 "AddonCallback.h"
  12 #include "AddonString.h"
  13
  14 namespace XBMCAddon
  15 {
  16   namespace xbmc
  17   {
  18
  19     ///
  20     /// \ingroup python_xbmc
  21     /// \defgroup python_monitor Monitor
  22     /// @{
  23     /// @brief **Kodi's monitor class.**
  24     ///
  25     /// \python_class{ xbmc.Monitor() }
  26     ///
  27     /// Creates a new monitor to notify addon about changes.
  28     ///
  29     class Monitor : public AddonCallback
  30     {
  31       String Id;
  32       long invokerId;
  33       CEvent abortEvent;
  34     public:
  35       Monitor();
  36
  37 #ifndef SWIG
  38       inline void    OnSettingsChanged() { XBMC_TRACE; invokeCallback(new CallbackFunction<Monitor>(this,&Monitor::onSettingsChanged)); }
  39       inline void    OnScreensaverActivated() { XBMC_TRACE; invokeCallback(new CallbackFunction<Monitor>(this,&Monitor::onScreensaverActivated)); }
  40       inline void    OnScreensaverDeactivated() { XBMC_TRACE; invokeCallback(new CallbackFunction<Monitor>(this,&Monitor::onScreensaverDeactivated)); }
  41       inline void    OnDPMSActivated() { XBMC_TRACE; invokeCallback(new CallbackFunction<Monitor>(this,&Monitor::onDPMSActivated)); }
  42       inline void    OnDPMSDeactivated() { XBMC_TRACE; invokeCallback(new CallbackFunction<Monitor>(this,&Monitor::onDPMSDeactivated)); }
  43       inline void    OnScanStarted(const String &library)
  44       {
  45         XBMC_TRACE;
  46         invokeCallback(
  47             new CallbackFunction<Monitor, const String>(this, &Monitor::onScanStarted, library));
  48       }
  49       inline void    OnScanFinished(const String &library)
  50       {
  51         XBMC_TRACE;
  52         invokeCallback(
  53             new CallbackFunction<Monitor, const String>(this, &Monitor::onScanFinished, library));
  54       }
  55       inline void OnCleanStarted(const String& library)
  56       {
  57         XBMC_TRACE;
  58         invokeCallback(
  59             new CallbackFunction<Monitor, const String>(this, &Monitor::onCleanStarted, library));
  60       }
  61       inline void OnCleanFinished(const String& library)
  62       {
  63         XBMC_TRACE;
  64         invokeCallback(
  65             new CallbackFunction<Monitor, const String>(this, &Monitor::onCleanFinished, library));
  66       }
  67       inline void OnNotification(const String& sender, const String& method, const String& data)
  68       {
  69         XBMC_TRACE;
  70         invokeCallback(new CallbackFunction<Monitor, const String, const String, const String>(
  71             this, &Monitor::onNotification, sender, method, data));
  72       }
  73
  74       inline const String& GetId() { return Id; }
  75       inline long GetInvokerId() { return invokerId; }
  76
  77       /**
  78        * Called from XBPython to notify registered monitors that a script is aborting/ending.
  79        */
  80       void AbortNotify();
  81 #endif
  82
  83 #ifdef DOXYGEN_SHOULD_USE_THIS
  84       ///
  85       /// \ingroup python_monitor
  86       /// @brief \python_func{ onSettingsChanged() }
  87       /// onSettingsChanged method.
  88       ///
  89       /// Will be called when addon settings are changed
  90       ///
  91       onSettingsChanged();
  92 #else
  93       virtual void onSettingsChanged() { XBMC_TRACE; }
  94 #endif
  95
  96 #ifdef DOXYGEN_SHOULD_USE_THIS
  97       ///
  98       /// \ingroup python_monitor
  99       /// @brief \python_func{ onScreensaverActivated() }
 100       /// onScreensaverActivated method.
 101       ///
 102       /// Will be called when screensaver kicks in
 103       ///
 104       onScreensaverActivated();
 105 #else
 106       virtual void onScreensaverActivated() { XBMC_TRACE; }
 107 #endif
 108
 109 #ifdef DOXYGEN_SHOULD_USE_THIS
 110       ///
 111       /// \ingroup python_monitor
 112       /// @brief \python_func{ onScreensaverDeactivated() }
 113       /// onScreensaverDeactivated method.
 114       ///
 115       /// Will be called when screensaver goes off
 116       ///
 117       onScreensaverDeactivated();
 118 #else
 119       virtual void onScreensaverDeactivated() { XBMC_TRACE; }
 120 #endif
 121
 122 #ifdef DOXYGEN_SHOULD_USE_THIS
 123       ///
 124       /// \ingroup python_monitor
 125       /// @brief \python_func{ onDPMSActivated() }
 126       /// onDPMSActivated method.
 127       ///
 128       /// Will be called when energysaving/DPMS gets active
 129       ///
 130       onDPMSActivated();
 131 #else
 132       virtual void onDPMSActivated() { XBMC_TRACE; }
 133 #endif
 134
 135 #ifdef DOXYGEN_SHOULD_USE_THIS
 136       ///
 137       /// \ingroup python_monitor
 138       /// @brief \python_func{ onDPMSDeactivated() }
 139       /// onDPMSDeactivated method.
 140       ///
 141       /// Will be called when energysaving/DPMS is turned off
 142       ///
 143       onDPMSDeactivated();
 144 #else
 145       virtual void onDPMSDeactivated() { XBMC_TRACE; }
 146 #endif
 147
 148 #ifdef DOXYGEN_SHOULD_USE_THIS
 149       ///
 150       /// \ingroup python_monitor
 151       /// @brief \python_func{ onScanStarted(library) }
 152       /// onScanStarted method.
 153       ///
 154       /// @param library             Video / music as string
 155       ///
 156       ///
 157       /// @note Will be called when library clean has ended and return video or
 158       /// music to indicate which library is being scanned
 159       ///
 160       ///
 161       ///-----------------------------------------------------------------------
 162       /// @python_v14 New function added.
 163       ///
 164       onScanStarted(...);
 165 #else
 166       virtual void onScanStarted(const String library) { XBMC_TRACE; }
 167 #endif
 168
 169 #ifdef DOXYGEN_SHOULD_USE_THIS
 170       ///
 171       /// \ingroup python_monitor
 172       /// @brief \python_func{ onScanFinished(library)  }
 173       /// onScanFinished method.
 174       ///
 175       /// @param library             Video / music as string
 176       ///
 177       ///
 178       /// @note Will be called when library clean has ended and return video or
 179       /// music to indicate which library has been scanned
 180       ///
 181       ///
 182       ///-----------------------------------------------------------------------
 183       /// @python_v14 New function added.
 184       ///
 185       onScanFinished(...);
 186 #else
 187       virtual void onScanFinished(const String library) { XBMC_TRACE; }
 188 #endif
 189
 190 #ifdef DOXYGEN_SHOULD_USE_THIS
 191       ///
 192       /// \ingroup python_monitor
 193       /// @brief \python_func{ onCleanStarted(library) }
 194       /// onCleanStarted method.
 195       ///
 196       /// @param library             Video / music as string
 197       ///
 198       ///
 199       /// @note Will be called when library clean has ended and return video or
 200       /// music to indicate which library has been cleaned
 201       ///
 202       ///
 203       ///-----------------------------------------------------------------------
 204       /// @python_v14 New function added.
 205       ///
 206       onCleanStarted(...);
 207 #else
 208       virtual void onCleanStarted(const String library) { XBMC_TRACE; }
 209 #endif
 210
 211 #ifdef DOXYGEN_SHOULD_USE_THIS
 212       ///
 213       /// \ingroup python_monitor
 214       /// @brief \python_func{ onCleanFinished(library) }
 215       /// onCleanFinished method.
 216       ///
 217       /// @param library             Video / music as string
 218       ///
 219       ///
 220       /// @note Will be called when library clean has ended and return video or
 221       /// music to indicate which library has been finished
 222       ///
 223       ///
 224       ///-----------------------------------------------------------------------
 225       /// @python_v14 New function added.
 226       ///
 227       onCleanFinished(...);
 228 #else
 229       virtual void onCleanFinished(const String library) { XBMC_TRACE; }
 230 #endif
 231
 232 #ifdef DOXYGEN_SHOULD_USE_THIS
 233       ///
 234       /// \ingroup python_monitor
 235       /// @brief \python_func{ onNotification(sender, method, data) }
 236       /// onNotification method.
 237       ///
 238       /// @param sender              Sender of the notification
 239       /// @param method              Name of the notification
 240       /// @param data                JSON-encoded data of the notification
 241       ///
 242       /// @note Will be called when Kodi receives or sends a notification
 243       ///
 244       ///
 245       ///-----------------------------------------------------------------------
 246       /// @python_v13 New function added.
 247       ///
 248       onNotification(...);
 249 #else
 250       virtual void onNotification(const String sender, const String method, const String data)
 251       {
 252         XBMC_TRACE;
 253       }
 254 #endif
 255
 256 #ifdef DOXYGEN_SHOULD_USE_THIS
 257       /// \ingroup python_monitor
 258       /// @brief \python_func{ waitForAbort([timeout]) }
 259       /// Wait for Abort
 260       /// \anchor xbmc_Monitor_waitForAbort
 261       ///
 262       /// Block until abort is requested, or until timeout occurs. If an
 263       /// abort requested have already been made, return immediately.
 264       ///
 265       /// @param timeout                 [opt] float - timeout in seconds.
 266       ///                                Default: no timeout.
 267       ///
 268       /// @return                        True when abort have been requested,
 269       ///                                False if a timeout is given and the
 270       ///                                operation times out.
 271       ///
 272       ///
 273       ///-----------------------------------------------------------------------
 274       /// @python_v14 New function added.
 275       ///
 276       /// **Example:**
 277       /// ~~~~~~~~~~~~~{.py}
 278       /// ..
 279       /// monitor = xbmc.Monitor()
 280       /// # do something
 281       /// monitor.waitForAbort(10) # sleeps for 10 secs or returns early if kodi aborts
 282       /// if monitor.abortRequested():
 283       ///     # abort was requested to Kodi (e.g. shutdown), do your cleanup logic
 284       /// ..
 285       /// ~~~~~~~~~~~~~
 286       ///
 287       waitForAbort(...);
 288 #else
 289       bool waitForAbort(double timeout = -1);
 290 #endif
 291
 292 #ifdef DOXYGEN_SHOULD_USE_THIS
 293       /// \ingroup python_monitor
 294       /// @brief \python_func{ abortRequested() }
 295       /// Returns True if abort has been requested.
 296       ///
 297       /// @return                        True if requested
 298       ///
 299       ///
 300       ///-----------------------------------------------------------------------
 301       /// @python_v14 New function added.
 302       ///
 303       abortRequested();
 304 #else
 305       bool abortRequested();
 306 #endif
 307       ~Monitor() override;
 308     };
 309     /** @} */
 310   }
 311 };