hal/Hal.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set sw=2 ts=8 et ft=cpp : */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   5  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_Hal_h
   8 #define mozilla_Hal_h
   9
  10 #include "mozilla/hal_sandbox/PHal.h"
  11 #include "mozilla/HalTypes.h"
  12 #include "base/basictypes.h"
  13 #include "mozilla/Observer.h"
  14 #include "mozilla/Types.h"
  15 #include "nsTArray.h"
  16 #include "prlog.h"
  17 #include "mozilla/dom/MozPowerManagerBinding.h"
  18 #include "mozilla/dom/battery/Types.h"
  19 #include "mozilla/dom/network/Types.h"
  20 #include "mozilla/dom/power/Types.h"
  21 #include "mozilla/hal_sandbox/PHal.h"
  22 #include "mozilla/dom/ScreenOrientation.h"
  23 #include "mozilla/HalScreenConfiguration.h"
  24
  25 /*
  26  * Hal.h contains the public Hal API.
  27  *
  28  * By default, this file defines its functions in the hal namespace, but if
  29  * MOZ_HAL_NAMESPACE is defined, we'll define our functions in that namespace.
  30  *
  31  * This is used by HalImpl.h and HalSandbox.h, which define copies of all the
  32  * functions here in the hal_impl and hal_sandbox namespaces.
  33  */
  34
  35 class nsIDOMWindow;
  36
  37 #ifndef MOZ_HAL_NAMESPACE
  38 # define MOZ_HAL_NAMESPACE hal
  39 # define MOZ_DEFINED_HAL_NAMESPACE 1
  40 #endif
  41
  42 namespace mozilla {
  43
  44 namespace hal {
  45
  46 typedef Observer<void_t> AlarmObserver;
  47
  48 class WindowIdentifier;
  49
  50 extern PRLogModuleInfo *GetHalLog();
  51 #define HAL_LOG(msg) PR_LOG(mozilla::hal::GetHalLog(), PR_LOG_DEBUG, msg)
  52 #define HAL_ERR(msg) PR_LOG(mozilla::hal::GetHalLog(), PR_LOG_ERROR, msg)
  53
  54 typedef Observer<int64_t> SystemClockChangeObserver;
  55 typedef Observer<SystemTimezoneChangeInformation> SystemTimezoneChangeObserver;
  56
  57 } // namespace hal
  58
  59 namespace MOZ_HAL_NAMESPACE {
  60
  61 /**
  62  * Turn the default vibrator device on/off per the pattern specified
  63  * by |pattern|.  Each element in the pattern is the number of
  64  * milliseconds to turn the vibrator on or off.  The first element in
  65  * |pattern| is an "on" element, the next is "off", and so on.
  66  *
  67  * If |pattern| is empty, any in-progress vibration is canceled.
  68  *
  69  * Only an active window within an active tab may call Vibrate; calls
  70  * from inactive windows and windows on inactive tabs do nothing.
  71  *
  72  * If you're calling hal::Vibrate from the outside world, pass an
  73  * nsIDOMWindow* in place of the WindowIdentifier parameter.
  74  * The method with WindowIdentifier will be called automatically.
  75  */
  76 void Vibrate(const nsTArray<uint32_t>& pattern,
  77              nsIDOMWindow* aWindow);
  78 void Vibrate(const nsTArray<uint32_t>& pattern,
  79              const hal::WindowIdentifier &id);
  80
  81 /**
  82  * Cancel a vibration started by the content window identified by
  83  * WindowIdentifier.
  84  *
  85  * If the window was the last window to start a vibration, the
  86  * cancellation request will go through even if the window is not
  87  * active.
  88  *
  89  * As with hal::Vibrate(), if you're calling hal::CancelVibrate from the outside
  90  * world, pass an nsIDOMWindow*. The method with WindowIdentifier will be called
  91  * automatically.
  92  */
  93 void CancelVibrate(nsIDOMWindow* aWindow);
  94 void CancelVibrate(const hal::WindowIdentifier &id);
  95
  96 /**
  97  * Inform the battery backend there is a new battery observer.
  98  * @param aBatteryObserver The observer that should be added.
  99  */
 100 void RegisterBatteryObserver(BatteryObserver* aBatteryObserver);
 101
 102 /**
 103  * Inform the battery backend a battery observer unregistered.
 104  * @param aBatteryObserver The observer that should be removed.
 105  */
 106 void UnregisterBatteryObserver(BatteryObserver* aBatteryObserver);
 107
 108 /**
 109  * Returns the current battery information.
 110  */
 111 void GetCurrentBatteryInformation(hal::BatteryInformation* aBatteryInfo);
 112
 113 /**
 114  * Notify of a change in the battery state.
 115  * @param aBatteryInfo The new battery information.
 116  */
 117 void NotifyBatteryChange(const hal::BatteryInformation& aBatteryInfo);
 118
 119 /**
 120  * Determine whether the device's screen is currently enabled.
 121  */
 122 bool GetScreenEnabled();
 123
 124 /**
 125  * Enable or disable the device's screen.
 126  *
 127  * Note that it may take a few seconds for the screen to turn on or off.
 128  */
 129 void SetScreenEnabled(bool aEnabled);
 130
 131 /**
 132  * Determine whether the device's keypad/button backlight is currently enabled.
 133  */
 134 bool GetKeyLightEnabled();
 135
 136 /**
 137  * Enable or disable the device's keypad/button backlight.
 138  */
 139 void SetKeyLightEnabled(bool aEnabled);
 140
 141 /**
 142  * Get the brightness of the device's screen's backlight, on a scale from 0
 143  * (very dim) to 1 (full blast).
 144  *
 145  * If the display is currently disabled, this returns the brightness the
 146  * backlight will have when the display is re-enabled.
 147  */
 148 double GetScreenBrightness();
 149
 150 /**
 151  * Set the brightness of the device's screen's backlight, on a scale from 0
 152  * (very dimm) to 1 (full blast).  Values larger than 1 are treated like 1, and
 153  * values smaller than 0 are treated like 0.
 154  *
 155  * Note that we may reduce the resolution of the given brightness value before
 156  * sending it to the screen.  Therefore if you call SetScreenBrightness(x)
 157  * followed by GetScreenBrightness(), the value returned by
 158  * GetScreenBrightness() may not be exactly x.
 159  */
 160 void SetScreenBrightness(double aBrightness);
 161
 162 /**
 163  * Determine whether the device is allowed to sleep.
 164  */
 165 bool GetCpuSleepAllowed();
 166
 167 /**
 168  * Set whether the device is allowed to suspend automatically after
 169  * the screen is disabled.
 170  */
 171 void SetCpuSleepAllowed(bool aAllowed);
 172
 173 /**
 174  * Register an observer for the sensor of given type.
 175  *
 176  * The observer will receive data whenever the data generated by the
 177  * sensor is avaiable.
 178  */
 179 void RegisterSensorObserver(hal::SensorType aSensor,
 180                             hal::ISensorObserver *aObserver);
 181
 182 /**
 183  * Unregister an observer for the sensor of given type.
 184  */
 185 void UnregisterSensorObserver(hal::SensorType aSensor,
 186                               hal::ISensorObserver *aObserver);
 187
 188 /**
 189  * Post a value generated by a sensor.
 190  *
 191  * This API is internal to hal; clients shouldn't call it directly.
 192  */
 193 void NotifySensorChange(const hal::SensorData &aSensorData);
 194
 195 /**
 196  * Enable sensor notifications from the backend
 197  *
 198  * This method is only visible from implementation of sensor manager.
 199  * Rest of the system should not try this.
 200  */
 201 void EnableSensorNotifications(hal::SensorType aSensor);
 202
 203 /**
 204  * Disable sensor notifications from the backend
 205  *
 206  * This method is only visible from implementation of sensor manager.
 207  * Rest of the system should not try this.
 208  */
 209 void DisableSensorNotifications(hal::SensorType aSensor);
 210
 211
 212 /**
 213  * Inform the network backend there is a new network observer.
 214  * @param aNetworkObserver The observer that should be added.
 215  */
 216 void RegisterNetworkObserver(NetworkObserver* aNetworkObserver);
 217
 218 /**
 219  * Inform the network backend a network observer unregistered.
 220  * @param aNetworkObserver The observer that should be removed.
 221  */
 222 void UnregisterNetworkObserver(NetworkObserver* aNetworkObserver);
 223
 224 /**
 225  * Returns the current network information.
 226  */
 227 void GetCurrentNetworkInformation(hal::NetworkInformation* aNetworkInfo);
 228
 229 /**
 230  * Notify of a change in the network state.
 231  * @param aNetworkInfo The new network information.
 232  */
 233 void NotifyNetworkChange(const hal::NetworkInformation& aNetworkInfo);
 234
 235 /**
 236  * Adjusting system clock.
 237  * @param aDeltaMilliseconds The difference compared with current system clock.
 238  */
 239 void AdjustSystemClock(int64_t aDeltaMilliseconds);
 240
 241 /**
 242  * Set timezone
 243  * @param aTimezoneSpec The definition can be found in
 244  * http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 245  */
 246 void SetTimezone(const nsCString& aTimezoneSpec);
 247
 248 /**
 249  * Get timezone
 250  * http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 251  */
 252 nsCString GetTimezone();
 253
 254 /**
 255  * Get timezone offset
 256  * returns the timezone offset relative to UTC in minutes (DST effect included)
 257  */
 258 int32_t GetTimezoneOffset();
 259
 260 /**
 261  * Register observer for system clock changed notification.
 262  * @param aObserver The observer that should be added.
 263  */
 264 void RegisterSystemClockChangeObserver(
 265   hal::SystemClockChangeObserver* aObserver);
 266
 267 /**
 268  * Unregister the observer for system clock changed.
 269  * @param aObserver The observer that should be removed.
 270  */
 271 void UnregisterSystemClockChangeObserver(
 272   hal::SystemClockChangeObserver* aObserver);
 273
 274 /**
 275  * Notify of a change in the system clock.
 276  * @param aClockDeltaMS
 277  */
 278 void NotifySystemClockChange(const int64_t& aClockDeltaMS);
 279
 280 /**
 281  * Register observer for system timezone changed notification.
 282  * @param aObserver The observer that should be added.
 283  */
 284 void RegisterSystemTimezoneChangeObserver(
 285   hal::SystemTimezoneChangeObserver* aObserver);
 286
 287 /**
 288  * Unregister the observer for system timezone changed.
 289  * @param aObserver The observer that should be removed.
 290  */
 291 void UnregisterSystemTimezoneChangeObserver(
 292   hal::SystemTimezoneChangeObserver* aObserver);
 293
 294 /**
 295  * Notify of a change in the system timezone.
 296  * @param aSystemTimezoneChangeInfo
 297  */
 298 void NotifySystemTimezoneChange(
 299   const hal::SystemTimezoneChangeInformation& aSystemTimezoneChangeInfo);
 300
 301 /**
 302  * Reboot the device.
 303  *
 304  * This API is currently only allowed to be used from the main process.
 305  */
 306 void Reboot();
 307
 308 /**
 309  * Power off the device.
 310  *
 311  * This API is currently only allowed to be used from the main process.
 312  */
 313 void PowerOff();
 314
 315 /**
 316  * Enable wake lock notifications from the backend.
 317  *
 318  * This method is only used by WakeLockObserversManager.
 319  */
 320 void EnableWakeLockNotifications();
 321
 322 /**
 323  * Disable wake lock notifications from the backend.
 324  *
 325  * This method is only used by WakeLockObserversManager.
 326  */
 327 void DisableWakeLockNotifications();
 328
 329 /**
 330  * Inform the wake lock backend there is a new wake lock observer.
 331  * @param aWakeLockObserver The observer that should be added.
 332  */
 333 void RegisterWakeLockObserver(WakeLockObserver* aObserver);
 334
 335 /**
 336  * Inform the wake lock backend a wake lock observer unregistered.
 337  * @param aWakeLockObserver The observer that should be removed.
 338  */
 339 void UnregisterWakeLockObserver(WakeLockObserver* aObserver);
 340
 341 /**
 342  * Adjust a wake lock's counts on behalf of a given process.
 343  *
 344  * In most cases, you shouldn't need to pass the aProcessID argument; the
 345  * default of CONTENT_PROCESS_ID_UNKNOWN is probably what you want.
 346  *
 347  * @param aTopic        lock topic
 348  * @param aLockAdjust   to increase or decrease active locks
 349  * @param aHiddenAdjust to increase or decrease hidden locks
 350  * @param aProcessID    indicates which process we're modifying the wake lock
 351  *                      on behalf of.  It is interpreted as
 352  *
 353  *                      CONTENT_PROCESS_ID_UNKNOWN: The current process
 354  *                      CONTENT_PROCESS_ID_MAIN: The root process
 355  *                      X: The process with ContentChild::GetID() == X
 356  */
 357 void ModifyWakeLock(const nsAString &aTopic,
 358                     hal::WakeLockControl aLockAdjust,
 359                     hal::WakeLockControl aHiddenAdjust,
 360                     uint64_t aProcessID = hal::CONTENT_PROCESS_ID_UNKNOWN);
 361
 362 /**
 363  * Query the wake lock numbers of aTopic.
 364  * @param aTopic        lock topic
 365  * @param aWakeLockInfo wake lock numbers
 366  */
 367 void GetWakeLockInfo(const nsAString &aTopic, hal::WakeLockInformation *aWakeLockInfo);
 368
 369 /**
 370  * Notify of a change in the wake lock state.
 371  * @param aWakeLockInfo The new wake lock information.
 372  */
 373 void NotifyWakeLockChange(const hal::WakeLockInformation& aWakeLockInfo);
 374
 375 /**
 376  * Inform the backend there is a new screen configuration observer.
 377  * @param aScreenConfigurationObserver The observer that should be added.
 378  */
 379 void RegisterScreenConfigurationObserver(hal::ScreenConfigurationObserver* aScreenConfigurationObserver);
 380
 381 /**
 382  * Inform the backend a screen configuration observer unregistered.
 383  * @param aScreenConfigurationObserver The observer that should be removed.
 384  */
 385 void UnregisterScreenConfigurationObserver(hal::ScreenConfigurationObserver* aScreenConfigurationObserver);
 386
 387 /**
 388  * Returns the current screen configuration.
 389  */
 390 void GetCurrentScreenConfiguration(hal::ScreenConfiguration* aScreenConfiguration);
 391
 392 /**
 393  * Notify of a change in the screen configuration.
 394  * @param aScreenConfiguration The new screen orientation.
 395  */
 396 void NotifyScreenConfigurationChange(const hal::ScreenConfiguration& aScreenConfiguration);
 397
 398 /**
 399  * Lock the screen orientation to the specific orientation.
 400  * @return Whether the lock has been accepted.
 401  */
 402 bool LockScreenOrientation(const dom::ScreenOrientation& aOrientation);
 403
 404 /**
 405  * Unlock the screen orientation.
 406  */
 407 void UnlockScreenOrientation();
 408
 409 /**
 410  * Register an observer for the switch of given SwitchDevice.
 411  *
 412  * The observer will receive data whenever the data generated by the
 413  * given switch.
 414  */
 415 void RegisterSwitchObserver(hal::SwitchDevice aDevice, hal::SwitchObserver *aSwitchObserver);
 416
 417 /**
 418  * Unregister an observer for the switch of given SwitchDevice.
 419  */
 420 void UnregisterSwitchObserver(hal::SwitchDevice aDevice, hal::SwitchObserver *aSwitchObserver);
 421
 422 /**
 423  * Notify the state of the switch.
 424  *
 425  * This API is internal to hal; clients shouldn't call it directly.
 426  */
 427 void NotifySwitchChange(const hal::SwitchEvent& aEvent);
 428
 429 /**
 430  * Get current switch information.
 431  */
 432 hal::SwitchState GetCurrentSwitchState(hal::SwitchDevice aDevice);
 433
 434 /**
 435  * Notify switch status change from input device.
 436  */
 437 void NotifySwitchStateFromInputDevice(hal::SwitchDevice aDevice,
 438                                       hal::SwitchState aState);
 439
 440 /**
 441  * Register an observer that is notified when a programmed alarm
 442  * expires.
 443  *
 444  * Currently, there can only be 0 or 1 alarm observers.
 445  */
 446 bool RegisterTheOneAlarmObserver(hal::AlarmObserver* aObserver);
 447
 448 /**
 449  * Unregister the alarm observer.  Doing so will implicitly cancel any
 450  * programmed alarm.
 451  */
 452 void UnregisterTheOneAlarmObserver();
 453
 454 /**
 455  * Notify that the programmed alarm has expired.
 456  *
 457  * This API is internal to hal; clients shouldn't call it directly.
 458  */
 459 void NotifyAlarmFired();
 460
 461 /**
 462  * Program the real-time clock to expire at the time |aSeconds|,
 463  * |aNanoseconds|.  These specify a point in real time relative to the
 464  * UNIX epoch.  The alarm will fire at this time point even if the
 465  * real-time clock is changed; that is, this alarm respects changes to
 466  * the real-time clock.  Return true iff the alarm was programmed.
 467  *
 468  * The alarm can be reprogrammed at any time.
 469  *
 470  * This API is currently only allowed to be used from non-sandboxed
 471  * contexts.
 472  */
 473 bool SetAlarm(int32_t aSeconds, int32_t aNanoseconds);
 474
 475 /**
 476  * Set the priority of the given process.  A process's priority is a two-tuple
 477  * consisting of a hal::ProcessPriority value and a hal::ProcessCPUPriority
 478  * value.
 479  *
 480  * Two processes with the same ProcessCPUPriority value don't necessarily have
 481  * the same CPU priority; the CPU priority we assign to a process is a function
 482  * of its ProcessPriority and ProcessCPUPriority.
 483  *
 484  * Exactly what this does will vary between platforms.  On *nix we might give
 485  * background processes higher nice values.  On other platforms, we might
 486  * ignore this call entirely.
 487  */
 488 void SetProcessPriority(int aPid,
 489                         hal::ProcessPriority aPriority,
 490                         hal::ProcessCPUPriority aCPUPriority,
 491                         uint32_t aLRU = 0);
 492
 493
 494 /**
 495  * Set the current thread's priority to appropriate platform-specific value for
 496  * given functionality. Instead of providing arbitrary priority numbers you
 497  * must specify a type of function like THREAD_PRIORITY_COMPOSITOR.
 498  */
 499 void SetCurrentThreadPriority(hal::ThreadPriority aThreadPriority);
 500
 501 /**
 502  * Register an observer for the FM radio.
 503  */
 504 void RegisterFMRadioObserver(hal::FMRadioObserver* aRadioObserver);
 505
 506 /**
 507  * Unregister the observer for the FM radio.
 508  */
 509 void UnregisterFMRadioObserver(hal::FMRadioObserver* aRadioObserver);
 510
 511 /**
 512  * Notify observers that a call to EnableFMRadio, DisableFMRadio, or FMRadioSeek
 513  * has completed, and indicate what the call returned.
 514  */
 515 void NotifyFMRadioStatus(const hal::FMRadioOperationInformation& aRadioState);
 516
 517 /**
 518  * Enable the FM radio and configure it according to the settings in aInfo.
 519  */
 520 void EnableFMRadio(const hal::FMRadioSettings& aInfo);
 521
 522 /**
 523  * Disable the FM radio.
 524  */
 525 void DisableFMRadio();
 526
 527 /**
 528  * Seek to an available FM radio station.
 529  *
 530  * This can be called off main thread, but all calls must be completed
 531  * before calling DisableFMRadio.
 532  */
 533 void FMRadioSeek(const hal::FMRadioSeekDirection& aDirection);
 534
 535 /**
 536  * Get the current FM radio settings.
 537  */
 538 void GetFMRadioSettings(hal::FMRadioSettings* aInfo);
 539
 540 /**
 541  * Set the FM radio's frequency.
 542  *
 543  * This can be called off main thread, but all calls must be completed
 544  * before calling DisableFMRadio.
 545  */
 546 void SetFMRadioFrequency(const uint32_t frequency);
 547
 548 /**
 549  * Get the FM radio's frequency.
 550  */
 551 uint32_t GetFMRadioFrequency();
 552
 553 /**
 554  * Get FM radio power state
 555  */
 556 bool IsFMRadioOn();
 557
 558 /**
 559  * Get FM radio signal strength
 560  */
 561 uint32_t GetFMRadioSignalStrength();
 562
 563 /**
 564  * Cancel FM radio seeking
 565  */
 566 void CancelFMRadioSeek();
 567
 568 /**
 569  * Get FM radio band settings by country.
 570  */
 571 hal::FMRadioSettings GetFMBandSettings(hal::FMRadioCountry aCountry);
 572
 573 /**
 574  * Start a watchdog to compulsively shutdown the system if it hangs.
 575  * @param aMode Specify how to shutdown the system.
 576  * @param aTimeoutSecs Specify the delayed seconds to shutdown the system.
 577  *
 578  * This API is currently only allowed to be used from the main process.
 579  */
 580 void StartForceQuitWatchdog(hal::ShutdownMode aMode, int32_t aTimeoutSecs);
 581
 582 /**
 583  * Perform Factory Reset to wipe out all user data.
 584  */
 585 void FactoryReset(mozilla::dom::FactoryResetReason& aReason);
 586
 587 /**
 588  * Start monitoring the status of gamepads attached to the system.
 589  */
 590 void StartMonitoringGamepadStatus();
 591
 592 /**
 593  * Stop monitoring the status of gamepads attached to the system.
 594  */
 595 void StopMonitoringGamepadStatus();
 596
 597 /**
 598  * Start monitoring disk space for low space situations.
 599  *
 600  * This API is currently only allowed to be used from the main process.
 601  */
 602 void StartDiskSpaceWatcher();
 603
 604 /**
 605  * Stop monitoring disk space for low space situations.
 606  *
 607  * This API is currently only allowed to be used from the main process.
 608  */
 609 void StopDiskSpaceWatcher();
 610
 611 /**
 612  * Get total system memory of device being run on in bytes.
 613  *
 614  * Returns 0 if we are unable to determine this information from /proc/meminfo.
 615  */
 616 uint32_t GetTotalSystemMemory();
 617
 618 /**
 619  * Get the level of total system memory on device in MiB.
 620  * (round the value up to the next power of two)
 621  *
 622  * Returns 0 if we are unable to determine this information from /proc/meminfo.
 623  */
 624 uint32_t GetTotalSystemMemoryLevel();
 625
 626 /**
 627  * Determine whether the headphone switch event is from input device
 628  */
 629 bool IsHeadphoneEventFromInputDev();
 630
 631 } // namespace MOZ_HAL_NAMESPACE
 632 } // namespace mozilla
 633
 634 #ifdef MOZ_DEFINED_HAL_NAMESPACE
 635 # undef MOZ_DEFINED_HAL_NAMESPACE
 636 # undef MOZ_HAL_NAMESPACE
 637 #endif
 638
 639 #endif  // mozilla_Hal_h