dom/webidl/Navigator.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * The origin of this IDL file is
   7  * http://www.whatwg.org/specs/web-apps/current-work/#the-navigator-object
   8  * http://www.w3.org/TR/tracking-dnt/
   9  * http://www.w3.org/TR/geolocation-API/#geolocation_interface
  10  * http://www.w3.org/TR/battery-status/#navigatorbattery-interface
  11  * http://www.w3.org/TR/vibration/#vibration-interface
  12  * http://www.w3.org/2012/sysapps/runtime/#extension-to-the-navigator-interface-1
  13  * https://dvcs.w3.org/hg/gamepad/raw-file/default/gamepad.html#navigator-interface-extension
  14  * http://www.w3.org/TR/beacon/#sec-beacon-method
  15  *
  16  * © Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and
  17  * Opera Software ASA. You are granted a license to use, reproduce
  18  * and create derivative works of this document.
  19  */
  20
  21 // http://www.whatwg.org/specs/web-apps/current-work/#the-navigator-object
  22 [HeaderFile="Navigator.h", NeedNewResolve]
  23 interface Navigator {
  24   // objects implementing this interface also implement the interfaces given below
  25 };
  26 Navigator implements NavigatorID;
  27 Navigator implements NavigatorLanguage;
  28 Navigator implements NavigatorOnLine;
  29 Navigator implements NavigatorContentUtils;
  30 Navigator implements NavigatorStorageUtils;
  31 Navigator implements NavigatorFeatures;
  32
  33 [NoInterfaceObject, Exposed=(Window,Worker)]
  34 interface NavigatorID {
  35   // WebKit/Blink/Trident/Presto support this (hardcoded "Mozilla").
  36   [Constant, Cached]
  37   readonly attribute DOMString appCodeName; // constant "Mozilla"
  38   [Constant, Cached]
  39   readonly attribute DOMString appName;
  40   [Constant, Cached]
  41   readonly attribute DOMString appVersion;
  42   [Constant, Cached]
  43   readonly attribute DOMString platform;
  44   [Constant, Cached]
  45   readonly attribute DOMString userAgent;
  46   [Constant, Cached]
  47   readonly attribute DOMString product; // constant "Gecko"
  48
  49   // Everyone but WebKit/Blink supports this.  See bug 679971.
  50   boolean taintEnabled(); // constant false
  51 };
  52
  53 [NoInterfaceObject]
  54 interface NavigatorLanguage {
  55
  56   // These 2 values are cached. They are updated when pref
  57   // intl.accept_languages is changed.
  58
  59   [Pure, Cached]
  60   readonly attribute DOMString? language;
  61   [Pure, Cached, Frozen]
  62   readonly attribute sequence<DOMString> languages;
  63 };
  64
  65 [NoInterfaceObject, Exposed=(Window,Worker)]
  66 interface NavigatorOnLine {
  67   readonly attribute boolean onLine;
  68 };
  69
  70 [NoInterfaceObject]
  71 interface NavigatorContentUtils {
  72   // content handler registration
  73   [Throws]
  74   void registerProtocolHandler(DOMString scheme, DOMString url, DOMString title);
  75   [Throws]
  76   void registerContentHandler(DOMString mimeType, DOMString url, DOMString title);
  77   // NOT IMPLEMENTED
  78   //DOMString isProtocolHandlerRegistered(DOMString scheme, DOMString url);
  79   //DOMString isContentHandlerRegistered(DOMString mimeType, DOMString url);
  80   //void unregisterProtocolHandler(DOMString scheme, DOMString url);
  81   //void unregisterContentHandler(DOMString mimeType, DOMString url);
  82 };
  83
  84 [NoInterfaceObject]
  85 interface NavigatorStorageUtils {
  86   // NOT IMPLEMENTED
  87   //void yieldForStorageUpdates();
  88 };
  89
  90 [NoInterfaceObject]
  91 interface NavigatorFeatures {
  92   [CheckPermissions="feature-detection", Throws]
  93   Promise<any> getFeature(DOMString name);
  94
  95   [CheckPermissions="feature-detection", Throws]
  96   Promise<any> hasFeature(DOMString name);
  97 };
  98
  99 // Things that definitely need to be in the spec and and are not for some
 100 // reason.  See https://www.w3.org/Bugs/Public/show_bug.cgi?id=22406
 101 partial interface Navigator {
 102   [Throws]
 103   readonly attribute MimeTypeArray mimeTypes;
 104   [Throws]
 105   readonly attribute PluginArray plugins;
 106 };
 107
 108 // http://www.w3.org/TR/tracking-dnt/ sort of
 109 partial interface Navigator {
 110   readonly attribute DOMString doNotTrack;
 111 };
 112
 113 // http://www.w3.org/TR/geolocation-API/#geolocation_interface
 114 [NoInterfaceObject]
 115 interface NavigatorGeolocation {
 116   [Throws, Pref="geo.enabled"]
 117   readonly attribute Geolocation geolocation;
 118 };
 119 Navigator implements NavigatorGeolocation;
 120
 121 // http://www.w3.org/TR/battery-status/#navigatorbattery-interface
 122 [NoInterfaceObject]
 123 interface NavigatorBattery {
 124     // XXXbz Per spec this should be non-nullable, but we return null in
 125     // torn-down windows.  See bug 884925.
 126     [Throws, Pref="dom.battery.enabled"]
 127     readonly attribute BatteryManager? battery;
 128 };
 129 Navigator implements NavigatorBattery;
 130
 131 // https://wiki.mozilla.org/WebAPI/DataStore
 132 [NoInterfaceObject,
 133  Exposed=(Window,Worker)]
 134 interface NavigatorDataStore {
 135     [Throws, NewObject, Func="Navigator::HasDataStoreSupport"]
 136     Promise<sequence<DataStore>> getDataStores(DOMString name,
 137                                                optional DOMString? owner = null);
 138 };
 139 Navigator implements NavigatorDataStore;
 140
 141 // http://www.w3.org/TR/vibration/#vibration-interface
 142 partial interface Navigator {
 143     // We don't support sequences in unions yet
 144     //boolean vibrate ((unsigned long or sequence<unsigned long>) pattern);
 145     boolean vibrate(unsigned long duration);
 146     boolean vibrate(sequence<unsigned long> pattern);
 147 };
 148
 149 // http://www.w3.org/TR/pointerevents/#extensions-to-the-navigator-interface
 150 partial interface Navigator {
 151     [Pref="dom.w3c_pointer_events.enabled"]
 152     readonly attribute long maxTouchPoints;
 153 };
 154
 155 // Mozilla-specific extensions
 156
 157 callback interface MozIdleObserver {
 158   // Time is in seconds and is read only when idle observers are added
 159   // and removed.
 160   readonly attribute unsigned long time;
 161   void onidle();
 162   void onactive();
 163 };
 164
 165 #ifdef MOZ_B2G
 166 dictionary MobileIdOptions {
 167   boolean forceSelection = false;
 168 };
 169
 170 [NoInterfaceObject]
 171 interface NavigatorMobileId {
 172     // Ideally we would use [CheckPermissions] here, but the "mobileid"
 173     // permission is set to PROMPT_ACTION and [CheckPermissions] only checks
 174     // for ALLOW_ACTION.
 175     // XXXbz what is this promise resolved with?
 176     [Throws, NewObject, Func="Navigator::HasMobileIdSupport"]
 177     Promise<any> getMobileIdAssertion(optional MobileIdOptions options);
 178 };
 179 Navigator implements NavigatorMobileId;
 180 #endif // MOZ_B2G
 181
 182 // nsIDOMNavigator
 183 partial interface Navigator {
 184   [Throws]
 185   readonly attribute DOMString oscpu;
 186   // WebKit/Blink support this; Trident/Presto do not.
 187   readonly attribute DOMString vendor;
 188   // WebKit/Blink supports this (hardcoded ""); Trident/Presto do not.
 189   readonly attribute DOMString vendorSub;
 190   // WebKit/Blink supports this (hardcoded "20030107"); Trident/Presto don't
 191   readonly attribute DOMString productSub;
 192   // WebKit/Blink/Trident/Presto support this.
 193   readonly attribute boolean cookieEnabled;
 194   [Throws]
 195   readonly attribute DOMString buildID;
 196   [Throws, CheckPermissions="power"]
 197   readonly attribute MozPowerManager mozPower;
 198
 199   // WebKit/Blink/Trident/Presto support this.
 200   [Throws]
 201   boolean javaEnabled();
 202
 203   /**
 204    * Navigator requests to add an idle observer to the existing window.
 205    */
 206   [Throws, CheckPermissions="idle"]
 207   void addIdleObserver(MozIdleObserver aIdleObserver);
 208
 209   /**
 210    * Navigator requests to remove an idle observer from the existing window.
 211    */
 212   [Throws, CheckPermissions="idle"]
 213   void removeIdleObserver(MozIdleObserver aIdleObserver);
 214
 215   /**
 216    * Request a wake lock for a resource.
 217    *
 218    * A page holds a wake lock to request that a resource not be turned
 219    * off (or otherwise made unavailable).
 220    *
 221    * The topic is the name of a resource that might be made unavailable for
 222    * various reasons. For example, on a mobile device the power manager might
 223    * decide to turn off the screen after a period of idle time to save power.
 224    *
 225    * The resource manager checks the lock state of a topic before turning off
 226    * the associated resource. For example, a page could hold a lock on the
 227    * "screen" topic to prevent the screensaver from appearing or the screen
 228    * from turning off.
 229    *
 230    * The resource manager defines what each topic means and sets policy.  For
 231    * example, the resource manager might decide to ignore 'screen' wake locks
 232    * held by pages which are not visible.
 233    *
 234    * One topic can be locked multiple times; it is considered released only when
 235    * all locks on the topic have been released.
 236    *
 237    * The returned MozWakeLock object is a token of the lock.  You can
 238    * unlock the lock via the object's |unlock| method.  The lock is released
 239    * automatically when its associated window is unloaded.
 240    *
 241    * @param aTopic resource name
 242    */
 243   [Throws, Pref="dom.wakelock.enabled", Func="Navigator::HasWakeLockSupport"]
 244   MozWakeLock requestWakeLock(DOMString aTopic);
 245 };
 246
 247 // nsIDOMNavigatorDeviceStorage
 248 partial interface Navigator {
 249   [Throws, Pref="device.storage.enabled"]
 250   DeviceStorage? getDeviceStorage(DOMString type);
 251   [Throws, Pref="device.storage.enabled"]
 252   sequence<DeviceStorage> getDeviceStorages(DOMString type);
 253 };
 254
 255 // nsIDOMNavigatorDesktopNotification
 256 partial interface Navigator {
 257   [Throws, Pref="notification.feature.enabled"]
 258   readonly attribute DesktopNotificationCenter mozNotification;
 259 };
 260
 261 // nsIDOMClientInformation
 262 partial interface Navigator {
 263   [Throws]
 264   boolean mozIsLocallyAvailable(DOMString uri, boolean whenOffline);
 265 };
 266
 267 #ifdef MOZ_WEBSMS_BACKEND
 268 partial interface Navigator {
 269   [CheckPermissions="sms", Pref="dom.sms.enabled"]
 270   readonly attribute MozMobileMessageManager? mozMobileMessage;
 271 };
 272 #endif
 273
 274 // NetworkInformation
 275 partial interface Navigator {
 276   [Throws, Pref="dom.netinfo.enabled"]
 277   readonly attribute NetworkInformation connection;
 278 };
 279
 280 // nsIDOMNavigatorCamera
 281 partial interface Navigator {
 282   [Throws, Func="Navigator::HasCameraSupport"]
 283   readonly attribute CameraManager mozCameras;
 284 };
 285
 286 // nsIDOMNavigatorSystemMessages and sort of maybe
 287 // http://www.w3.org/2012/sysapps/runtime/#extension-to-the-navigator-interface-1
 288 callback systemMessageCallback = void (optional object message);
 289 partial interface Navigator {
 290   [Throws, Pref="dom.sysmsg.enabled"]
 291   void    mozSetMessageHandler (DOMString type, systemMessageCallback? callback);
 292   [Throws, Pref="dom.sysmsg.enabled"]
 293   boolean mozHasPendingMessage (DOMString type);
 294 };
 295
 296 #ifdef MOZ_B2G_RIL
 297 partial interface Navigator {
 298   [Throws, Pref="dom.mobileconnection.enabled", CheckPermissions="mobileconnection mobilenetwork"]
 299   readonly attribute MozMobileConnectionArray mozMobileConnections;
 300 };
 301
 302 partial interface Navigator {
 303   [Throws, Pref="dom.cellbroadcast.enabled", CheckPermissions="cellbroadcast"]
 304   readonly attribute MozCellBroadcast mozCellBroadcast;
 305 };
 306
 307 partial interface Navigator {
 308   [Throws, Pref="dom.voicemail.enabled", CheckPermissions="voicemail"]
 309   readonly attribute MozVoicemail mozVoicemail;
 310 };
 311
 312 partial interface Navigator {
 313   [Throws, Pref="dom.icc.enabled", CheckPermissions="mobileconnection"]
 314   readonly attribute MozIccManager? mozIccManager;
 315 };
 316
 317 partial interface Navigator {
 318   [Throws, Pref="dom.telephony.enabled", CheckPermissions="telephony"]
 319   readonly attribute Telephony? mozTelephony;
 320 };
 321 #endif // MOZ_B2G_RIL
 322
 323 #ifdef MOZ_GAMEPAD
 324 // https://dvcs.w3.org/hg/gamepad/raw-file/default/gamepad.html#navigator-interface-extension
 325 partial interface Navigator {
 326   [Throws, Pref="dom.gamepad.enabled"]
 327   sequence<Gamepad?> getGamepads();
 328 };
 329 #endif // MOZ_GAMEPAD
 330
 331 #ifdef MOZ_B2G_BT
 332 partial interface Navigator {
 333   [Throws, CheckPermissions="bluetooth"]
 334   readonly attribute BluetoothManager mozBluetooth;
 335 };
 336 #endif // MOZ_B2G_BT
 337
 338 #ifdef MOZ_B2G_FM
 339 partial interface Navigator {
 340   [Throws, CheckPermissions="fmradio"]
 341   readonly attribute FMRadio mozFMRadio;
 342 };
 343 #endif // MOZ_B2G_FM
 344
 345 #ifdef MOZ_TIME_MANAGER
 346 // nsIDOMMozNavigatorTime
 347 partial interface Navigator {
 348   [Throws, CheckPermissions="time"]
 349   readonly attribute MozTimeManager mozTime;
 350 };
 351 #endif // MOZ_TIME_MANAGER
 352
 353 #ifdef MOZ_AUDIO_CHANNEL_MANAGER
 354 // nsIMozNavigatorAudioChannelManager
 355 partial interface Navigator {
 356   [Throws]
 357   readonly attribute AudioChannelManager mozAudioChannelManager;
 358 };
 359 #endif // MOZ_AUDIO_CHANNEL_MANAGER
 360
 361 #ifdef MOZ_MEDIA_NAVIGATOR
 362 callback NavigatorUserMediaSuccessCallback = void (MediaStream stream);
 363 callback NavigatorUserMediaErrorCallback = void (DOMString error);
 364
 365 partial interface Navigator {
 366   [Throws, Func="Navigator::HasUserMediaSupport"]
 367   void mozGetUserMedia(MediaStreamConstraints constraints,
 368                        NavigatorUserMediaSuccessCallback successCallback,
 369                        NavigatorUserMediaErrorCallback errorCallback);
 370 };
 371
 372 // nsINavigatorUserMedia
 373 callback MozGetUserMediaDevicesSuccessCallback = void (nsIVariant? devices);
 374 partial interface Navigator {
 375   [Throws, ChromeOnly]
 376   void mozGetUserMediaDevices(MediaStreamConstraints constraints,
 377                               MozGetUserMediaDevicesSuccessCallback onsuccess,
 378                               NavigatorUserMediaErrorCallback onerror,
 379                               // The originating innerWindowID is needed to
 380                               // avoid calling the callbacks if the window has
 381                               // navigated away. It is optional only as legacy.
 382                               optional unsigned long long innerWindowID = 0);
 383 };
 384 #endif // MOZ_MEDIA_NAVIGATOR
 385
 386 // Service Workers/Navigation Controllers
 387 partial interface Navigator {
 388   [Pref="dom.serviceWorkers.enabled"]
 389   readonly attribute ServiceWorkerContainer serviceWorker;
 390 };
 391
 392 partial interface Navigator {
 393   [Throws, Pref="beacon.enabled"]
 394   boolean sendBeacon(DOMString url,
 395                      optional (ArrayBufferView or Blob or DOMString or FormData)? data = null);
 396 };