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