1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/protocol/websocket/nsIWebSocketChannel.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,159 @@
1.4 +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* vim: set sw=4 ts=4 et tw=80 : */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +interface nsIURI;
1.11 +interface nsIInterfaceRequestor;
1.12 +interface nsILoadGroup;
1.13 +interface nsIWebSocketListener;
1.14 +interface nsIInputStream;
1.15 +
1.16 +#include "nsISupports.idl"
1.17 +
1.18 +/**
1.19 + * Low-level websocket API: handles network protocol.
1.20 + *
1.21 + * This is primarly intended for use by the higher-level nsIWebSocket.idl.
1.22 + * We are also making it scriptable for now, but this may change once we have
1.23 + * WebSockets for Workers.
1.24 + */
1.25 +[scriptable, uuid(9ee5874c-ec39-4bc2-b2d7-194a4c98c9d2)]
1.26 +interface nsIWebSocketChannel : nsISupports
1.27 +{
1.28 + /**
1.29 + * The original URI used to construct the protocol connection. This is used
1.30 + * in the case of a redirect or URI "resolution" (e.g. resolving a
1.31 + * resource: URI to a file: URI) so that the original pre-redirect
1.32 + * URI can still be obtained. This is never null.
1.33 + */
1.34 + readonly attribute nsIURI originalURI;
1.35 +
1.36 + /**
1.37 + * The readonly URI corresponding to the protocol connection after any
1.38 + * redirections are completed.
1.39 + */
1.40 + readonly attribute nsIURI URI;
1.41 +
1.42 + /**
1.43 + * The notification callbacks for authorization, etc..
1.44 + */
1.45 + attribute nsIInterfaceRequestor notificationCallbacks;
1.46 +
1.47 + /**
1.48 + * Transport-level security information (if any)
1.49 + */
1.50 + readonly attribute nsISupports securityInfo;
1.51 +
1.52 + /**
1.53 + * The load group of the websockets code.
1.54 + */
1.55 + attribute nsILoadGroup loadGroup;
1.56 +
1.57 + /**
1.58 + * Sec-Websocket-Protocol value
1.59 + */
1.60 + attribute ACString protocol;
1.61 +
1.62 + /**
1.63 + * Sec-Websocket-Extensions response header value
1.64 + */
1.65 + readonly attribute ACString extensions;
1.66 +
1.67 + /**
1.68 + * Asynchronously open the websocket connection. Received messages are fed
1.69 + * to the socket listener as they arrive. The socket listener's methods
1.70 + * are called on the thread that calls asyncOpen and are not called until
1.71 + * after asyncOpen returns. If asyncOpen returns successfully, the
1.72 + * protocol implementation promises to call at least onStop on the listener.
1.73 + *
1.74 + * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
1.75 + * websocket connection is reopened.
1.76 + *
1.77 + * @param aURI the uri of the websocket protocol - may be redirected
1.78 + * @param aOrigin the uri of the originating resource
1.79 + * @param aListener the nsIWebSocketListener implementation
1.80 + * @param aContext an opaque parameter forwarded to aListener's methods
1.81 + */
1.82 + void asyncOpen(in nsIURI aURI,
1.83 + in ACString aOrigin,
1.84 + in nsIWebSocketListener aListener,
1.85 + in nsISupports aContext);
1.86 +
1.87 + /*
1.88 + * Close the websocket connection for writing - no more calls to sendMsg
1.89 + * or sendBinaryMsg should be made after calling this. The listener object
1.90 + * may receive more messages if a server close has not yet been received.
1.91 + *
1.92 + * @param aCode the websocket closing handshake close code. Set to 0 if
1.93 + * you are not providing a code.
1.94 + * @param aReason the websocket closing handshake close reason
1.95 + */
1.96 + void close(in unsigned short aCode, in AUTF8String aReason);
1.97 +
1.98 + // section 7.4.1 defines these close codes
1.99 + const unsigned short CLOSE_NORMAL = 1000;
1.100 + const unsigned short CLOSE_GOING_AWAY = 1001;
1.101 + const unsigned short CLOSE_PROTOCOL_ERROR = 1002;
1.102 + const unsigned short CLOSE_UNSUPPORTED_DATATYPE = 1003;
1.103 + // code 1004 is reserved
1.104 + const unsigned short CLOSE_NO_STATUS = 1005;
1.105 + const unsigned short CLOSE_ABNORMAL = 1006;
1.106 + const unsigned short CLOSE_INVALID_PAYLOAD = 1007;
1.107 + const unsigned short CLOSE_POLICY_VIOLATION = 1008;
1.108 + const unsigned short CLOSE_TOO_LARGE = 1009;
1.109 + const unsigned short CLOSE_EXTENSION_MISSING = 1010;
1.110 + // Initially used just for server-side internal errors: adopted later for
1.111 + // client-side errors too (not clear if will make into spec: see
1.112 + // http://www.ietf.org/mail-archive/web/hybi/current/msg09372.html
1.113 + const unsigned short CLOSE_INTERNAL_ERROR = 1011;
1.114 + // MUST NOT be set as a status code in Close control frame by an endpoint:
1.115 + // To be used if TLS handshake failed (ex: server certificate unverifiable)
1.116 + const unsigned short CLOSE_TLS_FAILED = 1015;
1.117 +
1.118 + /**
1.119 + * Use to send text message down the connection to WebSocket peer.
1.120 + *
1.121 + * @param aMsg the utf8 string to send
1.122 + */
1.123 + void sendMsg(in AUTF8String aMsg);
1.124 +
1.125 + /**
1.126 + * Use to send binary message down the connection to WebSocket peer.
1.127 + *
1.128 + * @param aMsg the data to send
1.129 + */
1.130 + void sendBinaryMsg(in ACString aMsg);
1.131 +
1.132 + /**
1.133 + * Use to send a binary stream (Blob) to Websocket peer.
1.134 + *
1.135 + * @param aStream The input stream to be sent.
1.136 + */
1.137 + void sendBinaryStream(in nsIInputStream aStream,
1.138 + in unsigned long length);
1.139 +
1.140 + /**
1.141 + * This value determines how often (in seconds) websocket keepalive
1.142 + * pings are sent. If set to 0 (the default), no pings are ever sent.
1.143 + *
1.144 + * This value can currently only be set before asyncOpen is called, else
1.145 + * NS_ERROR_IN_PROGRESS is thrown.
1.146 + *
1.147 + * Be careful using this setting: ping traffic can consume lots of power and
1.148 + * bandwidth over time.
1.149 + */
1.150 + attribute unsigned long pingInterval;
1.151 +
1.152 + /**
1.153 + * This value determines how long (in seconds) the websocket waits for
1.154 + * the server to reply to a ping that has been sent before considering the
1.155 + * connection broken.
1.156 + *
1.157 + * This value can currently only be set before asyncOpen is called, else
1.158 + * NS_ERROR_IN_PROGRESS is thrown.
1.159 + */
1.160 + attribute unsigned long pingTimeout;
1.161 +
1.162 +};
