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