The Tor Browser / file comparison

comparison: netwerk/protocol/websocket/nsIWebSocketChannel.idl

netwerk/protocol/websocket/nsIWebSocketChannel.idl

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:3e8416b73721
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* vim: set sw=4 ts=4 et tw=80 : */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7 interface nsIURI;
8 interface nsIInterfaceRequestor;
9 interface nsILoadGroup;
10 interface nsIWebSocketListener;
11 interface nsIInputStream;
12
13 #include "nsISupports.idl"
14
15 /**
16 * Low-level websocket API: handles network protocol.
17 *
18 * This is primarly intended for use by the higher-level nsIWebSocket.idl.
19 * We are also making it scriptable for now, but this may change once we have
20 * WebSockets for Workers.
21 */
22 [scriptable, uuid(9ee5874c-ec39-4bc2-b2d7-194a4c98c9d2)]
23 interface nsIWebSocketChannel : nsISupports
24 {
25 /**
26 * The original URI used to construct the protocol connection. This is used
27 * in the case of a redirect or URI "resolution" (e.g. resolving a
28 * resource: URI to a file: URI) so that the original pre-redirect
29 * URI can still be obtained. This is never null.
30 */
31 readonly attribute nsIURI originalURI;
32
33 /**
34 * The readonly URI corresponding to the protocol connection after any
35 * redirections are completed.
36 */
37 readonly attribute nsIURI URI;
38
39 /**
40 * The notification callbacks for authorization, etc..
41 */
42 attribute nsIInterfaceRequestor notificationCallbacks;
43
44 /**
45 * Transport-level security information (if any)
46 */
47 readonly attribute nsISupports securityInfo;
48
49 /**
50 * The load group of the websockets code.
51 */
52 attribute nsILoadGroup loadGroup;
53
54 /**
55 * Sec-Websocket-Protocol value
56 */
57 attribute ACString protocol;
58
59 /**
60 * Sec-Websocket-Extensions response header value
61 */
62 readonly attribute ACString extensions;
63
64 /**
65 * Asynchronously open the websocket connection. Received messages are fed
66 * to the socket listener as they arrive. The socket listener's methods
67 * are called on the thread that calls asyncOpen and are not called until
68 * after asyncOpen returns. If asyncOpen returns successfully, the
69 * protocol implementation promises to call at least onStop on the listener.
70 *
71 * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
72 * websocket connection is reopened.
73 *
74 * @param aURI the uri of the websocket protocol - may be redirected
75 * @param aOrigin the uri of the originating resource
76 * @param aListener the nsIWebSocketListener implementation
77 * @param aContext an opaque parameter forwarded to aListener's methods
78 */
79 void asyncOpen(in nsIURI aURI,
80 in ACString aOrigin,
81 in nsIWebSocketListener aListener,
82 in nsISupports aContext);
83
84 /*
85 * Close the websocket connection for writing - no more calls to sendMsg
86 * or sendBinaryMsg should be made after calling this. The listener object
87 * may receive more messages if a server close has not yet been received.
88 *
89 * @param aCode the websocket closing handshake close code. Set to 0 if
90 * you are not providing a code.
91 * @param aReason the websocket closing handshake close reason
92 */
93 void close(in unsigned short aCode, in AUTF8String aReason);
94
95 // section 7.4.1 defines these close codes
96 const unsigned short CLOSE_NORMAL = 1000;
97 const unsigned short CLOSE_GOING_AWAY = 1001;
98 const unsigned short CLOSE_PROTOCOL_ERROR = 1002;
99 const unsigned short CLOSE_UNSUPPORTED_DATATYPE = 1003;
100 // code 1004 is reserved
101 const unsigned short CLOSE_NO_STATUS = 1005;
102 const unsigned short CLOSE_ABNORMAL = 1006;
103 const unsigned short CLOSE_INVALID_PAYLOAD = 1007;
104 const unsigned short CLOSE_POLICY_VIOLATION = 1008;
105 const unsigned short CLOSE_TOO_LARGE = 1009;
106 const unsigned short CLOSE_EXTENSION_MISSING = 1010;
107 // Initially used just for server-side internal errors: adopted later for
108 // client-side errors too (not clear if will make into spec: see
109 // http://www.ietf.org/mail-archive/web/hybi/current/msg09372.html
110 const unsigned short CLOSE_INTERNAL_ERROR = 1011;
111 // MUST NOT be set as a status code in Close control frame by an endpoint:
112 // To be used if TLS handshake failed (ex: server certificate unverifiable)
113 const unsigned short CLOSE_TLS_FAILED = 1015;
114
115 /**
116 * Use to send text message down the connection to WebSocket peer.
117 *
118 * @param aMsg the utf8 string to send
119 */
120 void sendMsg(in AUTF8String aMsg);
121
122 /**
123 * Use to send binary message down the connection to WebSocket peer.
124 *
125 * @param aMsg the data to send
126 */
127 void sendBinaryMsg(in ACString aMsg);
128
129 /**
130 * Use to send a binary stream (Blob) to Websocket peer.
131 *
132 * @param aStream The input stream to be sent.
133 */
134 void sendBinaryStream(in nsIInputStream aStream,
135 in unsigned long length);
136
137 /**
138 * This value determines how often (in seconds) websocket keepalive
139 * pings are sent. If set to 0 (the default), no pings are ever sent.
140 *
141 * This value can currently only be set before asyncOpen is called, else
142 * NS_ERROR_IN_PROGRESS is thrown.
143 *
144 * Be careful using this setting: ping traffic can consume lots of power and
145 * bandwidth over time.
146 */
147 attribute unsigned long pingInterval;
148
149 /**
150 * This value determines how long (in seconds) the websocket waits for
151 * the server to reply to a ping that has been sent before considering the
152 * connection broken.
153 *
154 * This value can currently only be set before asyncOpen is called, else
155 * NS_ERROR_IN_PROGRESS is thrown.
156 */
157 attribute unsigned long pingTimeout;
158
159 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial