DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (5b81998bb7ab)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
/* -*- 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;

};