gecko-dev/netwerk/protocol/websocket/nsIWebSocketChannel.idl

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* vim: set sw=4 ts=4 et tw=80 : */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

interface nsIURI;
interface nsIInterfaceRequestor;
interface nsILoadGroup;
interface nsIWebSocketListener;
interface nsIInputStream;
interface nsILoadInfo;
interface nsIDOMNode;
interface nsIPrincipal;

#include "nsISupports.idl"

/**
 * Low-level websocket API: handles network protocol.  
 *
 * This is primarly intended for use by the higher-level nsIWebSocket.idl.
 * We are also making it scriptable for now, but this may change once we have
 * WebSockets for Workers.
 */
[scriptable, uuid(21217c03-2ff7-4f9c-9d10-6d3d94a7d843)]
interface nsIWebSocketChannel : nsISupports
{
    /**
     * The original URI used to construct the protocol connection. This is used
     * in the case of a redirect or URI "resolution" (e.g. resolving a
     * resource: URI to a file: URI) so that the original pre-redirect
     * URI can still be obtained.  This is never null.
     */
    readonly attribute nsIURI originalURI;

    /**
     * The readonly URI corresponding to the protocol connection after any
     * redirections are completed.
     */
    readonly attribute nsIURI URI;

    /**
     * The notification callbacks for authorization, etc..
     */
    attribute nsIInterfaceRequestor notificationCallbacks;

    /**
     * Transport-level security information (if any)
     */
    readonly attribute nsISupports securityInfo;

    /**
     * The load group of of the websocket
     */
    attribute nsILoadGroup loadGroup;

    /**
     * The load info of the websocket
     */
    attribute nsILoadInfo loadInfo;

    /**
     * Sec-Websocket-Protocol value
     */
    attribute ACString protocol;

    /**
     * Sec-Websocket-Extensions response header value
     */
    readonly attribute ACString extensions;

    /**
     * Init the WebSocketChannel with LoadInfo arguments.
     * @param aLoadingNode
     *        The loadingDocument of the channel.
     *        The element or document where the result of this request will be
     *        used. This is the document/element that will get access to the
     *        result of this request. For example for an image load, it's the
     *        document in which the image will be loaded. And for a CSS
     *        stylesheet it's the document whose rendering will be affected by
     *        the stylesheet.
     *        For loads that are not related to any document, such as loads coming
     *        from addons or internal browser features, use null here.
     * @param aLoadingPrincipal
     *        The loadingPrincipal of the channel.
     *        The principal of the document where the result of this request will
     *        be used.
     *        This defaults to the principal of aLoadingNode, so when aLoadingNode
     *        is passed then aLoadingPrincipal can be left as null. However, for
     *        loads where aLoadingNode is null this argument must be passed.
     *        For example for loads from a WebWorker, pass the principal
     *        of that worker. For loads from an addon or from internal browser
     *        features, pass the system principal.
     *        If aLoadingNode is null and the URI being loaded isn't coming from
     *        a webpage, the principal should almost always be the systemPrincipal.
     *        One exception to this is for loads from WebWorkers since they don't
     *        have any nodes to be passed as aLoadingNode.
     *        Please note, aLoadingPrincipal is *not* the principal of the
     *        resource being loaded. But rather the principal of the context
     *        where the resource will be used.
     * @param aTriggeringPrincipal
     *        The triggeringPrincipal of the load.
     *        The triggeringPrincipal is the principal of the resource that caused
     *        this particular URL to be loaded.
     *        For WebSockets, the loadingPrincipal and the triggeringPrincipal
     *        are *always* identical.
     * @param aSecurityFlags
     *        The securityFlags of the channel.
     *        Any of the securityflags defined in nsILoadInfo.idl
     * @param aContentPolicyType
     *        The contentPolicyType of the channel.
     *        Any of the content types defined in nsIContentPolicy.idl
     * @return reference to the new nsIChannel object
     *
     *
     * Keep in mind that URIs coming from a webpage should *never* use the
     * systemPrincipal as the loadingPrincipal.
     *
     * Please note, if you provide both a loadingNode and a loadingPrincipal,
     * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
     * But less error prone is to just supply a loadingNode.
     */
     void initLoadInfo(in nsIDOMNode aLoadingNode,
                       in nsIPrincipal aLoadingPrincipal,
                       in nsIPrincipal aTriggeringPrincipal,
                       in unsigned long aSecurityFlags,
                       in unsigned long aContentPolicyType);

    /**
     * Asynchronously open the websocket connection.  Received messages are fed
     * to the socket listener as they arrive.  The socket listener's methods
     * are called on the thread that calls asyncOpen and are not called until
     * after asyncOpen returns.  If asyncOpen returns successfully, the
     * protocol implementation promises to call at least onStop on the listener.
     *
     * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
     * websocket connection is reopened.
     *
     * @param aURI the uri of the websocket protocol - may be redirected
     * @param aOrigin the uri of the originating resource
     * @param aListener the nsIWebSocketListener implementation
     * @param aContext an opaque parameter forwarded to aListener's methods
     */
    void asyncOpen(in nsIURI aURI,
                   in ACString aOrigin,
                   in nsIWebSocketListener aListener,
                   in nsISupports aContext);

    /*
     * Close the websocket connection for writing - no more calls to sendMsg
     * or sendBinaryMsg should be made after calling this. The listener object
     * may receive more messages if a server close has not yet been received.
     *
     * @param aCode the websocket closing handshake close code. Set to 0 if
     *        you are not providing a code.
     * @param aReason the websocket closing handshake close reason
     */
    void close(in unsigned short aCode, in AUTF8String aReason);
    
    // section 7.4.1 defines these close codes
    const unsigned short CLOSE_NORMAL               = 1000;
    const unsigned short CLOSE_GOING_AWAY           = 1001;
    const unsigned short CLOSE_PROTOCOL_ERROR       = 1002;
    const unsigned short CLOSE_UNSUPPORTED_DATATYPE = 1003;
    //  code 1004 is reserved
    const unsigned short CLOSE_NO_STATUS            = 1005;
    const unsigned short CLOSE_ABNORMAL             = 1006;
    const unsigned short CLOSE_INVALID_PAYLOAD      = 1007;
    const unsigned short CLOSE_POLICY_VIOLATION     = 1008;
    const unsigned short CLOSE_TOO_LARGE            = 1009;
    const unsigned short CLOSE_EXTENSION_MISSING    = 1010;
    // Initially used just for server-side internal errors: adopted later for
    // client-side errors too (not clear if will make into spec: see 
    // http://www.ietf.org/mail-archive/web/hybi/current/msg09372.html
    const unsigned short CLOSE_INTERNAL_ERROR       = 1011;
    // MUST NOT be set as a status code in Close control frame by an endpoint:
    // To be used if TLS handshake failed (ex: server certificate unverifiable)
    const unsigned short CLOSE_TLS_FAILED           = 1015;

    /**
     * Use to send text message down the connection to WebSocket peer.
     *
     * @param aMsg the utf8 string to send
     */
    void sendMsg(in AUTF8String aMsg);

    /**
     * Use to send binary message down the connection to WebSocket peer.
     *
     * @param aMsg the data to send
     */
    void sendBinaryMsg(in ACString aMsg);

    /** 
     * Use to send a binary stream (Blob) to Websocket peer.
     *
     * @param aStream The input stream to be sent.  
     */
    void sendBinaryStream(in nsIInputStream aStream, 
                          in unsigned long length);

    /**
     * This value determines how often (in seconds) websocket keepalive
     * pings are sent.  If set to 0 (the default), no pings are ever sent.
     *
     * This value can currently only be set before asyncOpen is called, else 
     * NS_ERROR_IN_PROGRESS is thrown.
     *
     * Be careful using this setting: ping traffic can consume lots of power and
     * bandwidth over time.
     */
    attribute unsigned long pingInterval;

    /**
     * This value determines how long (in seconds) the websocket waits for
     * the server to reply to a ping that has been sent before considering the
     * connection broken.
     *
     * This value can currently only be set before asyncOpen is called, else 
     * NS_ERROR_IN_PROGRESS is thrown.
     */
    attribute unsigned long pingTimeout;

};