The Tor Browser / file revision

 /* -*- 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;

 #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(9ee5874c-ec39-4bc2-b2d7-194a4c98c9d2)]

 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 the websockets code.

      */

     attribute nsILoadGroup loadGroup;

     /**

      * Sec-Websocket-Protocol value

      */

     attribute ACString protocol;

     /**

      * Sec-Websocket-Extensions response header value

      */

     readonly attribute ACString extensions;

     /**

      * 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;

 };