RTCPeerConnection.idl   [plain text]

/*
 * Copyright (C) 2012 Google Inc. All rights reserved.
 * Copyright (C) 2013 Nokia Corporation and/or its subsidiary(-ies).
 * Copyright (C) 2015, 2016 Ericsson AB. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer
 *    in the documentation and/or other materials provided with the
 *    distribution.
 * 3. Neither the name of Google Inc. nor the names of its contributors
 *    may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

[
    ActiveDOMObject,
    Conditional=WEB_RTC,
    ConstructorCallWith=ScriptExecutionContext,
    JSBuiltinConstructor,
    InterfaceName=webkitRTCPeerConnection,
] interface RTCPeerConnection : EventTarget {
    // Private initializer
    [PrivateIdentifier, CallWith=Document, RaisesException] void initializeWith(Dictionary parameters);

    // RTP Media API extensions
    [PrivateIdentifier, PublicIdentifier] sequence<RTCRtpSender> getSenders();
    sequence<RTCRtpReceiver> getReceivers();
    sequence<RTCRtpTransceiver> getTransceivers();

    [PrivateIdentifier, PublicIdentifier, StrictTypeChecking, RaisesException] RTCRtpSender addTrack(MediaStreamTrack track, MediaStream... streams);
    [PrivateIdentifier, PublicIdentifier, StrictTypeChecking, RaisesException] void removeTrack(RTCRtpSender sender);

    [StrictTypeChecking, RaisesException] RTCRtpTransceiver addTransceiver(MediaStreamTrack track, optional RTCRtpTransceiverInit init);
    [StrictTypeChecking, RaisesException] RTCRtpTransceiver addTransceiver(DOMString kind, optional RTCRtpTransceiverInit init);

    // Legacy MediaSream-based API (implemented on top of the RTP Media API)
    [JSBuiltin] sequence<MediaStream> getLocalStreams();
    [PrivateIdentifier, PublicIdentifier] sequence<MediaStream> getRemoteStreams();
    [JSBuiltin] MediaStream getStreamById(DOMString streamId);

    [JSBuiltin] void addStream(MediaStream stream);
    [JSBuiltin] void removeStream(MediaStream stream);

    [JSBuiltin] Promise createOffer(optional Dictionary offerOptions);
    // Legacy signature: Promise createOffer(RTCSessionDescriptionCallback successCallback
    //                                       RTCPeerConnectionErrorCallback errorCallback,
    //                                       optional Dictionary offerOptions);

    [JSBuiltin] Promise createAnswer(optional Dictionary answerOptions);
    // Legacy signature: Promise createAnswer(RTCSessionDescriptionCallback successCallback
    //                                        RTCPeerConnectionErrorCallback errorCallback,
    //                                        optional Dictionary answerOptions);

    [JSBuiltin] Promise setLocalDescription(RTCSessionDescription description);
    // Legacy signature: Promise setLocalDescription(RTCSessionDescription description
    //                                               VoidCallback successCallback,
    //                                               RTCPeerConnectionErrorCallback errorCallback);

    readonly attribute RTCSessionDescription localDescription;
    readonly attribute RTCSessionDescription currentLocalDescription;
    readonly attribute RTCSessionDescription pendingLocalDescription;

    [JSBuiltin] Promise setRemoteDescription(RTCSessionDescription description);
    // Legacy signature: Promise setRemoteDescription(RTCSessionDescription description
    //                                                VoidCallback successCallback,
    //                                                RTCPeerConnectionErrorCallback errorCallback);

    readonly attribute RTCSessionDescription remoteDescription;
    readonly attribute RTCSessionDescription currentRemoteDescription;
    readonly attribute RTCSessionDescription pendingRemoteDescription;

    readonly attribute DOMString signalingState;

    [JSBuiltin] Promise addIceCandidate(RTCIceCandidate candidate);
    // Legacy signature: Promise addIceCandidate(RTCIceCandidate candidate
    //                                           VoidCallback successCallback,
    //                                           RTCPeerConnectionErrorCallback errorCallback);

    readonly attribute DOMString iceGatheringState;
    readonly attribute DOMString iceConnectionState;

    RTCConfiguration getConfiguration();
    [RaisesException] void setConfiguration(Dictionary configuration);

    [JSBuiltin] Promise getStats(optional MediaStreamTrack? selector = null);
    // Legacy signature: Promise getStats(MediaStreamTrack? selector
    //                                    RTCStatsCallback successCallback,
    //                                    RTCPeerConnectionErrorCallback errorCallback);

    // Private API used to implement the overloaded operations above. Queued functions are called by
    // runQueuedOperation() (defined in RTCPeerConnectionInternals.js).
    [PrivateIdentifier] Promise queuedCreateOffer(optional Dictionary offerOptions);
    [PrivateIdentifier] Promise queuedCreateAnswer(optional Dictionary answerOptions);
    [PrivateIdentifier] Promise queuedSetLocalDescription(RTCSessionDescription description);
    [PrivateIdentifier] Promise queuedSetRemoteDescription(RTCSessionDescription description);
    [PrivateIdentifier] Promise queuedAddIceCandidate(RTCIceCandidate candidate);
    [PrivateIdentifier] Promise privateGetStats(MediaStreamTrack? selector);

    [RaisesException] RTCDataChannel createDataChannel([TreatNullAs=EmptyString] DOMString label, optional Dictionary options);

    void close();

    attribute EventHandler onnegotiationneeded;
    attribute EventHandler onicecandidate;
    attribute EventHandler onsignalingstatechange;
    attribute EventHandler ontrack;
    attribute EventHandler oniceconnectionstatechange;
    attribute EventHandler onicegatheringstatechange;
    attribute EventHandler ondatachannel;

    // Legacy event handler (MediaStream-based API)
    attribute EventHandler onaddstream;
};

// This enum is mirrored in RTCRtpTransceiver.idl
enum RTCRtpTransceiverDirection { "sendrecv", "sendonly", "recvonly", "inactive" };

dictionary RTCRtpTransceiverInit {
    RTCRtpTransceiverDirection direction = "sendrecv";
};