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