nsIWebSocketChannel.idl (10248B)
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 nsICookieJarSettings; 8 interface nsIInputStream; 9 interface nsIInterfaceRequestor; 10 interface nsILoadGroup; 11 interface nsILoadInfo; 12 interface nsIPrincipal; 13 interface nsITransportProvider; 14 interface nsITransportSecurityInfo; 15 interface nsIURI; 16 interface nsIWebSocketListener; 17 18 webidl Node; 19 20 #include "nsISupports.idl" 21 #include "nsIContentPolicy.idl" 22 23 24 25 [ref] native OriginAttributes(const mozilla::OriginAttributes); 26 27 /** 28 * Low-level websocket API: handles network protocol. 29 * 30 * This is primarly intended for use by the higher-level nsIWebSocket.idl. 31 * We are also making it scriptable for now, but this may change once we have 32 * WebSockets for Workers. 33 */ 34 [scriptable, builtinclass, uuid(ce71d028-322a-4105-a947-a894689b52bf)] 35 interface nsIWebSocketChannel : nsISupports 36 { 37 /** 38 * The original URI used to construct the protocol connection. This is used 39 * in the case of a redirect or URI "resolution" (e.g. resolving a 40 * resource: URI to a file: URI) so that the original pre-redirect 41 * URI can still be obtained. This is never null. 42 */ 43 [must_use] readonly attribute nsIURI originalURI; 44 45 /** 46 * The readonly URI corresponding to the protocol connection after any 47 * redirections are completed. 48 */ 49 [must_use] readonly attribute nsIURI URI; 50 51 /** 52 * The notification callbacks for authorization, etc.. 53 */ 54 [must_use] attribute nsIInterfaceRequestor notificationCallbacks; 55 56 /** 57 * Transport-level security information (if any) 58 */ 59 [must_use] readonly attribute nsITransportSecurityInfo securityInfo; 60 61 /** 62 * The load group of of the websocket 63 */ 64 [must_use] attribute nsILoadGroup loadGroup; 65 66 /** 67 * The load info of the websocket 68 */ 69 [must_use] attribute nsILoadInfo loadInfo; 70 71 /** 72 * Sec-Websocket-Protocol value 73 */ 74 [must_use] attribute ACString protocol; 75 76 /** 77 * Sec-Websocket-Extensions response header value 78 */ 79 [must_use] readonly attribute ACString extensions; 80 81 /** 82 * The channelId of the underlying http channel. 83 * It's available only after nsIWebSocketListener::onStart 84 */ 85 [must_use] readonly attribute uint64_t httpChannelId; 86 87 /** 88 * Init the WebSocketChannel with LoadInfo arguments. 89 * @param aLoadingNode 90 * @param aLoadingPrincipal 91 * @param aTriggeringPrincipal 92 * @param aCookieJarSettings 93 * @param aSecurityFlags 94 * @param aContentPolicyType 95 * These will be used as values for the nsILoadInfo object on the 96 * created channel. For details, see nsILoadInfo in nsILoadInfo.idl 97 * @return reference to the new nsIChannel object 98 * 99 * Keep in mind that URIs coming from a webpage should *never* use the 100 * systemPrincipal as the loadingPrincipal. 101 * 102 * Please note, if you provide both a loadingNode and a loadingPrincipal, 103 * then loadingPrincipal must be equal to loadingNode->NodePrincipal(). 104 * But less error prone is to just supply a loadingNode. 105 */ 106 [notxpcom] nsresult initLoadInfoNative(in Node aLoadingNode, 107 in nsIPrincipal aLoadingPrincipal, 108 in nsIPrincipal aTriggeringPrincipal, 109 in nsICookieJarSettings aCookieJarSettings, 110 in unsigned long aSecurityFlags, 111 in nsContentPolicyType aContentPolicyType, 112 in unsigned long aSandboxFlags); 113 114 /** 115 * Similar to the previous one but without nsICookieJarSettings. 116 * This method is used by JS code where nsICookieJarSettings is not exposed. 117 */ 118 [must_use] void initLoadInfo(in Node aLoadingNode, 119 in nsIPrincipal aLoadingPrincipal, 120 in nsIPrincipal aTriggeringPrincipal, 121 in unsigned long aSecurityFlags, 122 in nsContentPolicyType aContentPolicyType); 123 124 /** 125 * Asynchronously open the websocket connection. Received messages are fed 126 * to the socket listener as they arrive. The socket listener's methods 127 * are called on the thread that calls asyncOpen and are not called until 128 * after asyncOpen returns. If asyncOpen returns successfully, the 129 * protocol implementation promises to call at least onStop on the listener. 130 * 131 * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the 132 * websocket connection is reopened. 133 * 134 * @param aURI the uri of the websocket protocol - may be redirected 135 * @param aOrigin the uri of the originating resource 136 * @param aOriginAttributes attributes of the originating resource. 137 * @param aInnerWindowID the inner window ID 138 * @param aListener the nsIWebSocketListener implementation 139 * @param aContext an opaque parameter forwarded to aListener's methods 140 */ 141 [implicit_jscontext] 142 void asyncOpen(in nsIURI aURI, 143 in ACString aOrigin, 144 in jsval aOriginAttributes, 145 in unsigned long long aInnerWindowID, 146 in nsIWebSocketListener aListener, 147 in nsISupports aContext); 148 149 [must_use, noscript] 150 void asyncOpenNative(in nsIURI aURI, 151 in ACString aOrigin, 152 in OriginAttributes aOriginAttributes, 153 in unsigned long long aInnerWindowID, 154 in nsIWebSocketListener aListener, 155 in nsISupports aContext); 156 157 /* 158 * Close the websocket connection for writing - no more calls to sendMsg 159 * or sendBinaryMsg should be made after calling this. The listener object 160 * may receive more messages if a server close has not yet been received. 161 * 162 * @param aCode the websocket closing handshake close code. Set to 0 if 163 * you are not providing a code. 164 * @param aReason the websocket closing handshake close reason 165 */ 166 [must_use] void close(in unsigned short aCode, in AUTF8String aReason); 167 168 // section 7.4.1 defines these close codes 169 const unsigned short CLOSE_NORMAL = 1000; 170 const unsigned short CLOSE_GOING_AWAY = 1001; 171 const unsigned short CLOSE_PROTOCOL_ERROR = 1002; 172 const unsigned short CLOSE_UNSUPPORTED_DATATYPE = 1003; 173 // code 1004 is reserved 174 const unsigned short CLOSE_NO_STATUS = 1005; 175 const unsigned short CLOSE_ABNORMAL = 1006; 176 const unsigned short CLOSE_INVALID_PAYLOAD = 1007; 177 const unsigned short CLOSE_POLICY_VIOLATION = 1008; 178 const unsigned short CLOSE_TOO_LARGE = 1009; 179 const unsigned short CLOSE_EXTENSION_MISSING = 1010; 180 // Initially used just for server-side internal errors: adopted later for 181 // client-side errors too (not clear if will make into spec: see 182 // http://www.ietf.org/mail-archive/web/hybi/current/msg09372.html 183 const unsigned short CLOSE_INTERNAL_ERROR = 1011; 184 // MUST NOT be set as a status code in Close control frame by an endpoint: 185 // To be used if TLS handshake failed (ex: server certificate unverifiable) 186 const unsigned short CLOSE_TLS_FAILED = 1015; 187 188 /** 189 * Use to send text message down the connection to WebSocket peer. 190 * 191 * @param aMsg the utf8 string to send 192 */ 193 [must_use] void sendMsg(in AUTF8String aMsg); 194 195 /** 196 * Use to send binary message down the connection to WebSocket peer. 197 * 198 * @param aMsg the data to send 199 */ 200 [must_use] void sendBinaryMsg(in ACString aMsg); 201 202 /** 203 * Use to send a binary stream (Blob) to Websocket peer. 204 * 205 * @param aStream The input stream to be sent. 206 */ 207 [must_use] void sendBinaryStream(in nsIInputStream aStream, 208 in unsigned long length); 209 210 /** 211 * This value determines how often (in seconds) websocket keepalive 212 * pings are sent. If set to 0 (the default), no pings are ever sent. 213 * 214 * This value can currently only be set before asyncOpen is called, else 215 * NS_ERROR_IN_PROGRESS is thrown. 216 * 217 * Be careful using this setting: ping traffic can consume lots of power and 218 * bandwidth over time. 219 */ 220 [must_use] attribute unsigned long pingInterval; 221 222 /** 223 * This value determines how long (in seconds) the websocket waits for 224 * the server to reply to a ping that has been sent before considering the 225 * connection broken. 226 * 227 * This value can currently only be set before asyncOpen is called, else 228 * NS_ERROR_IN_PROGRESS is thrown. 229 */ 230 [must_use] attribute unsigned long pingTimeout; 231 232 /** 233 * Unique ID for this channel. It's not readonly because when the channel is 234 * created via IPC, the serial number is received from the child process. 235 */ 236 [must_use] attribute unsigned long serial; 237 238 /** 239 * Set a nsITransportProvider and negotated extensions to be used by this 240 * channel. Calling this function also means that this channel will 241 * implement the server-side part of a websocket connection rather than the 242 * client-side part. 243 */ 244 [must_use] void setServerParameters(in nsITransportProvider aProvider, 245 in ACString aNegotiatedExtensions); 246 247 %{C++ 248 inline uint32_t Serial() 249 { 250 uint32_t serial; 251 nsresult rv = GetSerial(&serial); 252 if (NS_WARN_IF(NS_FAILED(rv))) { 253 return 0; 254 } 255 return serial; 256 } 257 258 inline uint64_t HttpChannelId() 259 { 260 uint64_t httpChannelId; 261 nsresult rv = GetHttpChannelId(&httpChannelId); 262 if (NS_WARN_IF(NS_FAILED(rv))) { 263 return 0; 264 } 265 return httpChannelId; 266 } 267 %} 268 };