1 // Copyright 2013 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 // Multiply-included message file, hence no include guard. 6 7 // This file defines the IPCs for the browser-side implementation of 8 // WebSockets. For the legacy renderer-side implementation, see 9 // socket_stream_messages.h. 10 // TODO(ricea): Fix this comment when the legacy implementation has been 11 // removed. 12 // 13 // This IPC interface is based on the WebSocket multiplexing draft spec, 14 // http://tools.ietf.org/html/draft-ietf-hybi-websocket-multiplexing-09 15 16 #include <string> 17 #include <vector> 18 19 #include "base/basictypes.h" 20 #include "content/common/content_export.h" 21 #include "content/common/websocket.h" 22 #include "ipc/ipc_message_macros.h" 23 #include "url/gurl.h" 24 25 #undef IPC_MESSAGE_EXPORT 26 #define IPC_MESSAGE_EXPORT CONTENT_EXPORT 27 #define IPC_MESSAGE_START WebSocketMsgStart 28 29 IPC_STRUCT_TRAITS_BEGIN(content::WebSocketHandshakeRequest) 30 IPC_STRUCT_TRAITS_MEMBER(url) 31 IPC_STRUCT_TRAITS_MEMBER(headers) 32 IPC_STRUCT_TRAITS_MEMBER(request_time) 33 IPC_STRUCT_TRAITS_END() 34 35 IPC_STRUCT_TRAITS_BEGIN(content::WebSocketHandshakeResponse) 36 IPC_STRUCT_TRAITS_MEMBER(url) 37 IPC_STRUCT_TRAITS_MEMBER(status_code) 38 IPC_STRUCT_TRAITS_MEMBER(status_text) 39 IPC_STRUCT_TRAITS_MEMBER(headers) 40 IPC_STRUCT_TRAITS_MEMBER(response_time) 41 IPC_STRUCT_TRAITS_END() 42 43 // WebSocket messages sent from the renderer to the browser. 44 45 // Open new virtual WebSocket connection to |socket_url|. |channel_id| is an 46 // identifier chosen by the renderer for the new channel. It cannot correspond 47 // to an existing open channel, and must be between 1 and 48 // 0x7FFFFFFF. |requested_protocols| is a list of tokens identifying 49 // sub-protocols the renderer would like to use, as described in RFC6455 50 // "Subprotocols Using the WebSocket Protocol". 51 // 52 // The browser process will not send |channel_id| as-is to the remote server; it 53 // will try to use a short id on the wire. This saves the renderer from 54 // having to try to choose the ids cleverly. 55 IPC_MESSAGE_ROUTED3(WebSocketHostMsg_AddChannelRequest, 56 GURL /* socket_url */, 57 std::vector<std::string> /* requested_protocols */, 58 GURL /* origin */) 59 60 // WebSocket messages sent from the browser to the renderer. 61 62 // Respond to an AddChannelRequest for channel |channel_id|. |channel_id| is 63 // scoped to the renderer process; while it is unique per-renderer, the browser 64 // may have multiple renderers using the same id. If |fail| is true, the channel 65 // could not be established (the cause of the failure is not provided to the 66 // renderer in order to limit its ability to abuse WebSockets to perform network 67 // probing, etc.). If |fail| is set then the |channel_id| is available for 68 // re-use. |selected_protocol| is the sub-protocol the server selected, 69 // or empty if no sub-protocol was selected. |extensions| is the list of 70 // extensions negotiated for the connection. 71 IPC_MESSAGE_ROUTED3(WebSocketMsg_AddChannelResponse, 72 bool /* fail */, 73 std::string /* selected_protocol */, 74 std::string /* extensions */) 75 76 // Notify the renderer that the browser has started an opening handshake. 77 // This message is for showing the request in the inspector and 78 // can be omitted if the inspector is not active. 79 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyStartOpeningHandshake, 80 content::WebSocketHandshakeRequest /* request */) 81 82 // Notify the renderer that the browser has finished an opening handshake. 83 // This message precedes AddChannelResponse. 84 // This message is for showing the response in the inspector and 85 // can be omitted if the inspector is not active. 86 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyFinishOpeningHandshake, 87 content::WebSocketHandshakeResponse /* response */) 88 89 // Notify the renderer that the browser is required to fail the connection 90 // (see RFC6455 7.1.7 for details). 91 // When the renderer process receives this messages it does the following: 92 // 1. Fire an error event. 93 // 2. Show |message| to the inspector. 94 // 3. Close the channel immediately uncleanly, as if it received 95 // DropChannel(was_clean = false, code = 1006, reason = ""). 96 // |message| will be shown in the inspector and won't be passed to the script. 97 // TODO(yhirano): Find the way to pass |message| directly to the inspector 98 // process. 99 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyFailure, 100 std::string /* message */) 101 102 // WebSocket messages that can be sent in either direction. 103 104 IPC_ENUM_TRAITS(content::WebSocketMessageType) 105 106 // Send a non-control frame on |channel_id|. If the sender is the renderer, it 107 // will be sent to the remote server. If the sender is the browser, it comes 108 // from the remote server. |fin| indicates that this frame is the last in the 109 // current message. |type| is the type of the message. On the first frame of a 110 // message, it must be set to either WEB_SOCKET_MESSAGE_TYPE_TEXT or 111 // WEB_SOCKET_MESSAGE_TYPE_BINARY. On subsequent frames, it must be set to 112 // WEB_SOCKET_MESSAGE_TYPE_CONTINUATION, and the type is the same as that of the 113 // first message. If |type| is WEB_SOCKET_MESSAGE_TYPE_TEXT, then the 114 // concatenation of the |data| from every frame in the message must be valid 115 // UTF-8. If |fin| is not set, |data| must be non-empty. 116 IPC_MESSAGE_ROUTED3(WebSocketMsg_SendFrame, 117 bool /* fin */, 118 content::WebSocketMessageType /* type */, 119 std::vector<char> /* data */) 120 121 // Add |quota| tokens of send quota for channel |channel_id|. |quota| must be a 122 // positive integer. Both the browser and the renderer set send quota for the 123 // other side, and check that quota has not been exceeded when receiving 124 // messages. Both sides start a new channel with a quota of 0, and must wait for 125 // a FlowControl message before calling SendFrame. The total available quota on 126 // one side must never exceed 0x7FFFFFFFFFFFFFFF tokens. 127 IPC_MESSAGE_ROUTED1(WebSocketMsg_FlowControl, 128 int64 /* quota */) 129 130 // Drop the channel. 131 // When sent by the renderer, this will cause a DropChannel message to be sent 132 // if the multiplex extension is in use, otherwise a Close message will be sent 133 // and the TCP/IP connection will be closed. 134 // When sent by the browser, this indicates that a Close or DropChannel has been 135 // received, the connection was closed, or a network or protocol error 136 // occurred. On receiving DropChannel, the renderer process may consider the 137 // |channel_id| available for reuse by a new AddChannelRequest. 138 // |code| is one of the reason codes specified in RFC6455 or 139 // draft-ietf-hybi-websocket-multiplexing-09. |reason|, if non-empty, is a 140 // UTF-8 encoded string which may be useful for debugging but is not necessarily 141 // human-readable, as supplied by the server in the Close or DropChannel 142 // message. 143 // If |was_clean| is false on a message from the browser, then the WebSocket 144 // connection was not closed cleanly. If |was_clean| is false on a message from 145 // the renderer, then the connection should be closed immediately without a 146 // closing handshake and the renderer cannot accept any new messages on this 147 // connection. 148 IPC_MESSAGE_ROUTED3(WebSocketMsg_DropChannel, 149 bool /* was_clean */, 150 unsigned short /* code */, 151 std::string /* reason */) 152