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