Merge pull request #375 from floating-cat/deprecate_domerror

Fix #374: Deprecate DOMError in favor of DOMException.

Author: sjrd

src/main/scala/org/scalajs/dom/experimental/mediastream/MediaStream.scala

@@ -6,8 +6,7 @@ package org.scalajs.dom.experimental.mediastream
 import scala.scalajs.js
 import scala.scalajs.js.|
 import scala.scalajs.js.annotation._
-
-import org.scalajs.dom.raw.{DOMError, Event, EventInit, EventTarget}
+import org.scalajs.dom.raw.{DOMException, Event, EventInit, EventTarget}
 
 /**
  * The MediaStream
@@ -566,14 +565,6 @@ object MediaDeviceInfo {
   }
 }
 
-@js.native
-trait NavigatorMediaStream extends js.Object {
-
-  def getUserMedia(constraints: MediaStreamConstraints,
-      success: js.Function1[MediaStream, Any],
-      error: js.Function1[DOMError, Any]): Unit = js.native
-}
-
 /**
  * The MediaDevices interface provides access to connected media input devices
  * like cameras and microphones, as well as screen sharing. In essence, it

src/main/scala/org/scalajs/dom/experimental/webrtc/WebRTC.scala

@@ -10,7 +10,7 @@ import scala.scalajs.js.|
 
 import org.scalajs.dom.Blob
 import org.scalajs.dom.raw.{
-  DOMError, Event, EventInit, EventTarget, MessageEvent
+  DOMException, Event, EventInit, EventTarget, MessageEvent
 }
 import org.scalajs.dom.experimental.mediastream._
 
@@ -1036,98 +1036,31 @@ class RTCPeerConnection(
   var onsignalingstatechange: js.Function1[Event, Any] = js.native
 
   /**
-   * The createOffer method generates a blob of SDP that contains an RFC 3264
-   * offer with the supported configurations for the session, including
-   * descriptions of the local MediaStreams attached to this RTCPeerConnection,
-   * the codec/RTP/RTCP options supported by this implementation, and any
-   * candidates that have been gathered by the ICE Agent. The options parameter
-   * may be supplied to provide additional control over the offer generated.
-   *
-   * As an offer, the generated SDP will contain the full set of capabilities
-   * supported by the session (as opposed to an answer, which will include only
-   * a specific negotiated subset to use); for each SDP line, the generation
-   * of the SDP must follow the appropriate process for generating an offer.
-   * In the event createOffer is called after the session is established,
-   * createOffer will generate an offer that is compatible with the current
-   * session, incorporating any changes that have been made to the session
-   * since the last complete offer-answer exchange, such as addition or removal
-   * of streams. If no changes have been made, the offer will include the
-   * capabilities of the current local description as well as any additional
-   * capabilities that could be negotiated in an updated offer.
-   *
-   * Session descriptions generated by createOffer must be immediately usable
-   * by setLocalDescription without causing an error as long as
-   * setLocalDescription is called reasonably soon. If a system has limited
-   * resources (e.g. a finite number of decoders), createOffer needs to return
-   * an offer that reflects the current state of the system, so that
-   * setLocalDescription will succeed when it attempts to acquire those
-   * resources. The session descriptions must remain usable by
-   * setLocalDescription without causing an error until at least the end of
-   * the fulfillment callback of the returned promise. Calling this method
-   * is needed to get the ICE user name fragment and password.
-   *
-   * If the RTCPeerConnection is configured to generate Identity assertions,
-   * then the session description shall contain an appropriate assertion.
-   *
-   * If this RTCPeerConnection object is closed before the SDP generation
-   * process completes, the USER agent must suppress the result and not resolve
-   * or reject the returned promise.
-   *
-   * If the SDP generation process completed successfully, the user agent must
-   * resolve the returned promise with a newly created RTCSessionDescription
-   * object, representing the generated offer.
-   *
-   * If the SDP generation process failed for any reason, the user agent must
-   * reject the returned promise with an DOMError object of type TBD as its
-   * argument.
-   *
-   * To Do: Discuss privacy aspects of this from a fingerprinting point of
-   * view - it's probably around as bad as access to a canvas :-)
+   * The createOffer() method of the RTCPeerConnection interface initiates the
+   * creation of an SDP offer for the purpose of starting a new WebRTC connection
+   * to a remote peer. The SDP offer includes information about any MediaStreamTracks
+   * already attached to the WebRTC session, codec, and options supported by the
+   * browser, and any candidates already gathered by the ICE agent, for the purpose
+   * of being sent over the signaling channel to a potential peer to request a connection
+   * or to update the configuration of an existing connection.
    *
+   * The return value is a Promise which, when the offer has been created, is resolved
+   * with a RTCSessionDescription object containing the newly-created offer.
+   *
+   * MDN
    */
   def createOffer(
       options: RTCOfferOptions = js.native): js.Promise[RTCSessionDescription] = js.native
 
   /**
-   * The createAnswer method generates an [SDP] answer with the supported
-   * configuration for the session that is compatible with the parameters in
-   * the remote configuration. Like createOffer, the returned blob contains
-   * descriptions of the local MediaStreams attached to this RTCPeerConnection,
-   * the codec/RTP/RTCP options negotiated for this session, and any candidates
-   * that have been gathered by the ICE Agent. The options parameter may be
-   * supplied to provide additional control over the generated answer.
-   *
-   * As an answer, the generated SDP will contain a specific configuration
-   * that, along with the corresponding offer, specifies how the media plane
-   * should be established. The generation of the SDP must follow the
-   * appropriate process for generating an answer.
-   *
-   * Session descriptions generated by createAnswer must be immediately usable
-   * by setLocalDescription without causing an error as long as
-   * setLocalDescription is called reasonably soon. Like createOffer, the
-   * returned description should reflect the current state of the system. The
-   * session descriptions must remain usable by setLocalDescription without
-   * causing an error until at least the end of the fulfillment callback of
-   * the returned promise. Calling this method is needed to get the ICE user
-   * name fragment and password.
-   *
-   * An answer can be marked as provisional, as described in [RTCWEB-JSEP], by
-   * setting the type to "pranswer".
-   *
-   * If the RTCPeerConnection is configured to generate Identity assertions,
-   * then the session description shall contain an appropriate assertion.
-   *
-   * If this RTCPeerConnection object is closed before the SDP generation process
-   * completes, the USER agent must suppress the result and not resolve or reject
-   * the returned promise.
-   *
-   * If the SDP generation process completed successfully, the user agent must
-   * resolve the returned promise with a newly created RTCSessionDescription
-   * object, representing the generated answer.
-   *
-   * If the SDP generation process failed for any reason, the user agent must
-   * reject the returned promise with a DOMError object of type TBD.
+   * The createAnswer() method on the RTCPeerConnection interface creates an SDP answer to
+   * an offer received from a remote peer during the offer/answer negotiation of a WebRTC
+   * connection. The answer contains information about any media already attached to the
+   * session, codecs and options supported by the browser, and any ICE candidates already
+   * gathered. The answer is delivered to the returned Promise, and should then be sent to
+   * the source of the offer to continue the negotiation process.
    *
+   * MDN
    */
   def createAnswer(): js.Promise[RTCSessionDescription] = js.native
 
@@ -1258,7 +1191,7 @@ class RTCPeerConnection(
    */
   def getStats(selector: MediaStreamTrack,
       callback: js.Function1[RTCStatsReport, Any],
-      error: js.Function1[DOMError, Any]): RTCStatsReport = js.native
+      error: js.Function1[DOMException, Any]): RTCStatsReport = js.native
 
   /**
    * Sets the identity provider to be used for a given RTCPeerConnection object.

src/main/scala/org/scalajs/dom/experimental/webrtc/package.scala

@@ -1,7 +1,8 @@
 package org.scalajs.dom.experimental
 
-import org.scalajs.dom.DOMError
 import org.scalajs.dom.experimental.mediastream._
+import org.scalajs.dom.raw.DOMException
+
 import scala.scalajs.js
 import scala.language.implicitConversions
 
@@ -26,7 +27,7 @@ package object webrtc {
         "Navigator.getUserMedia() is deprecated, use Navigator.mediaDevices.getUserMedia() instead.",
         "2014-05-28")
     def getUserMedia(constraints: MediaStreamConstraints,
-        success: js.Function1[MediaStream, Any],
-        error: js.Function1[DOMError, Any]): Unit = js.native
+        successCallback: js.Function1[MediaStream, Any],
+        errorCallback: js.Function1[DOMException, Any]): Unit = js.native
   }
 }

src/main/scala/org/scalajs/dom/package.scala

@@ -59,6 +59,7 @@ package object dom {
   type DOMException = raw.DOMException
   type DOMImplementation = raw.DOMImplementation
   lazy val DOMException: raw.DOMException.type = raw.DOMException
+  @deprecated("Use DOMException instead", "DOM Level 3 Core")
   type DOMError = raw.DOMError
   type DOMList[T] = raw.DOMList[T]
   type DOMParser = raw.DOMParser

src/main/scala/org/scalajs/dom/raw/Idb.scala

@@ -99,7 +99,7 @@ class IDBObjectStore extends js.Object {
   def deleteIndex(indexName: String): Unit = js.native
 
   /**
-   * This method may raise a DOMException with a DOMError of the following types:
+   * This method may raise a DOMException of one of the following types:
    *
    * MDN
    */
@@ -300,7 +300,7 @@ class IDBCursor extends js.Object {
   def primaryKey: js.Any = js.native
 
   /**
-   * This method may raise a DOMException with a DOMError of the following types:
+   * This method may raise a DOMException of one of the following types:
    *
    * MDN
    */
@@ -436,7 +436,7 @@ object IDBKeyRange extends js.Object {
       upperOpen: Boolean = js.native): IDBKeyRange = js.native
 
   /**
-   * This method may raise a DOMException with a DOMError of the following types:
+   * This method may raise a DOMException of the following types:
    *
    * MDN
    */
@@ -496,16 +496,13 @@ class IDBTransaction extends EventTarget {
   def mode: String = js.native
 
   /**
-   * The error returned in the event of an unsuccessful transaction. Null if the
-   * transaction is not finished, is finished and successfully committed, or was
-   * aborted with IDBTransaction.abort function. Returns the same DOMError as the
-   * request object which caused the transaction to be aborted due to a failed request,
-   * or a DOMError for the transaction failure not due to a failed request (such as
-   * QuotaExceededError or UnknownError).
+   * Returns a DOMException indicating the type of error that occured when there is an
+   * unsuccessful transaction. This property is null if the transaction is not finished,
+   * is finished and successfully committed, or was aborted with IDBTransaction.abort function.
    *
    * MDN
    */
-  def error: DOMError = js.native
+  def error: DOMException = js.native
 
   /**
    * The event handler for the onerror event.
@@ -770,12 +767,12 @@ class IDBRequest extends EventTarget {
   var onsuccess: js.Function1[Event, _] = js.native
 
   /**
-   * A DOMError containing the relevant error. The following error codes are returned
-   * under certain conditions:
+   * Returns a DOMException in the event of an unsuccessful request, indicating what
+   * went wrong.
    *
    * MDN
    */
-  def error: DOMError = js.native
+  def error: DOMException = js.native
 
   /**
    * The transaction for the request. This property can be null for certain requests,

src/main/scala/org/scalajs/dom/raw/lib.scala

@@ -6665,45 +6665,62 @@ abstract class CharacterData extends Node with NonDocumentTypeChildNode {
 class DOMException extends js.Object {
 
   /**
-   * Readonly short. Returns one of the exception code constants (see below).
-   * Deprecated use DOMError.name instead.
+   * Returns a short that contains one of the error code constants one of the
+   * exception code constants (see below) or 0 if none match. This field is used
+   * for historical reasons. New DOM exceptions don't use this anymore: they put
+   * this info in the name attribute.
    *
    * MDN
    */
   @deprecated("Obsolete.", "DOM4")
   def code: Int = js.native
 
+  /**
+   * Returns a DOMString representing a message or description associated with
+   * the given error name.
+   *
+   * MDN
+   */
   def message: String = js.native
+
+  /**
+   * Returns a DOMString that contains one of the strings associated with an
+   * error name.
+   *
+   * MDN
+   */
+  def name: String = js.native
 }
 
 @js.native
 @JSGlobal
 object DOMException extends js.Object {
 
+  val INDEX_SIZE_ERR: Int = js.native
+  val DOMSTRING_SIZE_ERR: Int = js.native
   val HIERARCHY_REQUEST_ERR: Int = js.native
+  val WRONG_DOCUMENT_ERR: Int = js.native
+  val INVALID_CHARACTER_ERR: Int = js.native
+  val NO_DATA_ALLOWED_ERR: Int = js.native
   val NO_MODIFICATION_ALLOWED_ERR: Int = js.native
+  val NOT_FOUND_ERR: Int = js.native
+  val NOT_SUPPORTED_ERR: Int = js.native
+  val INUSE_ATTRIBUTE_ERR: Int = js.native
+  val INVALID_STATE_ERR: Int = js.native
+  val SYNTAX_ERR: Int = js.native
   val INVALID_MODIFICATION_ERR: Int = js.native
   val NAMESPACE_ERR: Int = js.native
-  val INVALID_CHARACTER_ERR: Int = js.native
+  val INVALID_ACCESS_ERR: Int = js.native
+  val VALIDATION_ERR: Int = js.native
   val TYPE_MISMATCH_ERR: Int = js.native
-  val ABORT_ERR: Int = js.native
-  val INVALID_STATE_ERR: Int = js.native
   val SECURITY_ERR: Int = js.native
   val NETWORK_ERR: Int = js.native
-  val WRONG_DOCUMENT_ERR: Int = js.native
-  val QUOTA_EXCEEDED_ERR: Int = js.native
-  val INDEX_SIZE_ERR: Int = js.native
-  val DOMSTRING_SIZE_ERR: Int = js.native
-  val SYNTAX_ERR: Int = js.native
-  val SERIALIZE_ERR: Int = js.native
-  val VALIDATION_ERR: Int = js.native
-  val NOT_FOUND_ERR: Int = js.native
+  val ABORT_ERR: Int = js.native
   val URL_MISMATCH_ERR: Int = js.native
-  val PARSE_ERR: Int = js.native
-  val NO_DATA_ALLOWED_ERR: Int = js.native
-  val NOT_SUPPORTED_ERR: Int = js.native
-  val INVALID_ACCESS_ERR: Int = js.native
-  val INUSE_ATTRIBUTE_ERR: Int = js.native
+  val QUOTA_EXCEEDED_ERR: Int = js.native
+  val TIMEOUT_ERR: Int = js.native
+  val INVALID_NODE_TYPE_ERR: Int = js.native
+  val DATA_CLONE_ERR: Int = js.native
 }
 
 /**
@@ -6992,6 +7009,7 @@ trait MediaQueryList extends js.Object {
  *
  * MDN
  */
+@deprecated("Use DOMException instead", "DOM Level 3 Core")
 @js.native
 trait DOMError extends js.Object {
 
@@ -7001,6 +7019,14 @@ trait DOMError extends js.Object {
    * MDN
    */
   def name: String = js.native
+
+  /**
+   * Readonly DOMString. Returns a message or description associated with the given
+   * error type name.
+   *
+   * MDN
+   */
+  def message: String = js.native
 }
 
 /**
@@ -7808,11 +7834,11 @@ trait MessagePort extends EventTarget {
 class FileReader() extends EventTarget {
 
   /**
-   * A DOMError representing the error that occurred while reading the file.
+   * A DOMException representing the error that occurred while reading the file.
    *
    * MDN
    */
-  def error: DOMError = js.native
+  def error: DOMException = js.native
 
   /**
    * A number indicating the state of the FileReader. This will be one of the State constants.