michael@0: /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ michael@0: /* vim: set sw=4 ts=4 et tw=80 : */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: interface nsIURI; michael@0: interface nsIInterfaceRequestor; michael@0: interface nsILoadGroup; michael@0: interface nsIWebSocketListener; michael@0: interface nsIInputStream; michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: /** michael@0: * Low-level websocket API: handles network protocol. michael@0: * michael@0: * This is primarly intended for use by the higher-level nsIWebSocket.idl. michael@0: * We are also making it scriptable for now, but this may change once we have michael@0: * WebSockets for Workers. michael@0: */ michael@0: [scriptable, uuid(9ee5874c-ec39-4bc2-b2d7-194a4c98c9d2)] michael@0: interface nsIWebSocketChannel : nsISupports michael@0: { michael@0: /** michael@0: * The original URI used to construct the protocol connection. This is used michael@0: * in the case of a redirect or URI "resolution" (e.g. resolving a michael@0: * resource: URI to a file: URI) so that the original pre-redirect michael@0: * URI can still be obtained. This is never null. michael@0: */ michael@0: readonly attribute nsIURI originalURI; michael@0: michael@0: /** michael@0: * The readonly URI corresponding to the protocol connection after any michael@0: * redirections are completed. michael@0: */ michael@0: readonly attribute nsIURI URI; michael@0: michael@0: /** michael@0: * The notification callbacks for authorization, etc.. michael@0: */ michael@0: attribute nsIInterfaceRequestor notificationCallbacks; michael@0: michael@0: /** michael@0: * Transport-level security information (if any) michael@0: */ michael@0: readonly attribute nsISupports securityInfo; michael@0: michael@0: /** michael@0: * The load group of the websockets code. michael@0: */ michael@0: attribute nsILoadGroup loadGroup; michael@0: michael@0: /** michael@0: * Sec-Websocket-Protocol value michael@0: */ michael@0: attribute ACString protocol; michael@0: michael@0: /** michael@0: * Sec-Websocket-Extensions response header value michael@0: */ michael@0: readonly attribute ACString extensions; michael@0: michael@0: /** michael@0: * Asynchronously open the websocket connection. Received messages are fed michael@0: * to the socket listener as they arrive. The socket listener's methods michael@0: * are called on the thread that calls asyncOpen and are not called until michael@0: * after asyncOpen returns. If asyncOpen returns successfully, the michael@0: * protocol implementation promises to call at least onStop on the listener. michael@0: * michael@0: * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the michael@0: * websocket connection is reopened. michael@0: * michael@0: * @param aURI the uri of the websocket protocol - may be redirected michael@0: * @param aOrigin the uri of the originating resource michael@0: * @param aListener the nsIWebSocketListener implementation michael@0: * @param aContext an opaque parameter forwarded to aListener's methods michael@0: */ michael@0: void asyncOpen(in nsIURI aURI, michael@0: in ACString aOrigin, michael@0: in nsIWebSocketListener aListener, michael@0: in nsISupports aContext); michael@0: michael@0: /* michael@0: * Close the websocket connection for writing - no more calls to sendMsg michael@0: * or sendBinaryMsg should be made after calling this. The listener object michael@0: * may receive more messages if a server close has not yet been received. michael@0: * michael@0: * @param aCode the websocket closing handshake close code. Set to 0 if michael@0: * you are not providing a code. michael@0: * @param aReason the websocket closing handshake close reason michael@0: */ michael@0: void close(in unsigned short aCode, in AUTF8String aReason); michael@0: michael@0: // section 7.4.1 defines these close codes michael@0: const unsigned short CLOSE_NORMAL = 1000; michael@0: const unsigned short CLOSE_GOING_AWAY = 1001; michael@0: const unsigned short CLOSE_PROTOCOL_ERROR = 1002; michael@0: const unsigned short CLOSE_UNSUPPORTED_DATATYPE = 1003; michael@0: // code 1004 is reserved michael@0: const unsigned short CLOSE_NO_STATUS = 1005; michael@0: const unsigned short CLOSE_ABNORMAL = 1006; michael@0: const unsigned short CLOSE_INVALID_PAYLOAD = 1007; michael@0: const unsigned short CLOSE_POLICY_VIOLATION = 1008; michael@0: const unsigned short CLOSE_TOO_LARGE = 1009; michael@0: const unsigned short CLOSE_EXTENSION_MISSING = 1010; michael@0: // Initially used just for server-side internal errors: adopted later for michael@0: // client-side errors too (not clear if will make into spec: see michael@0: // http://www.ietf.org/mail-archive/web/hybi/current/msg09372.html michael@0: const unsigned short CLOSE_INTERNAL_ERROR = 1011; michael@0: // MUST NOT be set as a status code in Close control frame by an endpoint: michael@0: // To be used if TLS handshake failed (ex: server certificate unverifiable) michael@0: const unsigned short CLOSE_TLS_FAILED = 1015; michael@0: michael@0: /** michael@0: * Use to send text message down the connection to WebSocket peer. michael@0: * michael@0: * @param aMsg the utf8 string to send michael@0: */ michael@0: void sendMsg(in AUTF8String aMsg); michael@0: michael@0: /** michael@0: * Use to send binary message down the connection to WebSocket peer. michael@0: * michael@0: * @param aMsg the data to send michael@0: */ michael@0: void sendBinaryMsg(in ACString aMsg); michael@0: michael@0: /** michael@0: * Use to send a binary stream (Blob) to Websocket peer. michael@0: * michael@0: * @param aStream The input stream to be sent. michael@0: */ michael@0: void sendBinaryStream(in nsIInputStream aStream, michael@0: in unsigned long length); michael@0: michael@0: /** michael@0: * This value determines how often (in seconds) websocket keepalive michael@0: * pings are sent. If set to 0 (the default), no pings are ever sent. michael@0: * michael@0: * This value can currently only be set before asyncOpen is called, else michael@0: * NS_ERROR_IN_PROGRESS is thrown. michael@0: * michael@0: * Be careful using this setting: ping traffic can consume lots of power and michael@0: * bandwidth over time. michael@0: */ michael@0: attribute unsigned long pingInterval; michael@0: michael@0: /** michael@0: * This value determines how long (in seconds) the websocket waits for michael@0: * the server to reply to a ping that has been sent before considering the michael@0: * connection broken. michael@0: * michael@0: * This value can currently only be set before asyncOpen is called, else michael@0: * NS_ERROR_IN_PROGRESS is thrown. michael@0: */ michael@0: attribute unsigned long pingTimeout; michael@0: michael@0: };