content/common/websocket_messages.h

   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.
   9 //
  10 // This IPC interface was originally desined based on the WebSocket
  11 // multiplexing draft spec,
  12 // http://tools.ietf.org/html/draft-ietf-hybi-websocket-multiplexing-09. So,
  13 // some of them are given names correspond to the concepts defined in the spec.
  14 //
  15 // A WebSocketBridge object in the renderer and the corresponding WebSocketHost
  16 // object in the browser are associated using an identifier named channel ID.
  17 // The channel id is chosen by the renderer for a new channel. While the
  18 // channel id is unique per-renderer, the browser may have multiple renderers
  19 // using the same channel id.
  20 //
  21 // There're WebSocketDispatcherHost objects for each renderer. Each of
  22 // WebSocketDispatcherHost holds a channel id to WebSocketHost map.
  23 //
  24 // Received messages are routed to the corresponding object by
  25 // WebSocketDispatcher in the renderer and WebSocketDispatcherHost in the
  26 // browser using the channel ID.
  27 //
  28 // The channel ID value is stored in the routing ID member which is available
  29 // when we use the IPC_MESSAGE_ROUTED macro though it's unintended use.
  30
  31 #include <string>
  32 #include <vector>
  33
  34 #include "base/basictypes.h"
  35 #include "content/common/content_export.h"
  36 #include "content/common/websocket.h"
  37 #include "ipc/ipc_message_macros.h"
  38 #include "url/gurl.h"
  39 #include "url/origin.h"
  40
  41 #undef IPC_MESSAGE_EXPORT
  42 #define IPC_MESSAGE_EXPORT CONTENT_EXPORT
  43 #define IPC_MESSAGE_START WebSocketMsgStart
  44
  45 IPC_ENUM_TRAITS_MAX_VALUE(content::WebSocketMessageType,
  46                           content::WEB_SOCKET_MESSAGE_TYPE_LAST)
  47
  48 IPC_STRUCT_TRAITS_BEGIN(content::WebSocketHandshakeRequest)
  49   IPC_STRUCT_TRAITS_MEMBER(url)
  50   IPC_STRUCT_TRAITS_MEMBER(headers)
  51   IPC_STRUCT_TRAITS_MEMBER(headers_text)
  52   IPC_STRUCT_TRAITS_MEMBER(request_time)
  53 IPC_STRUCT_TRAITS_END()
  54
  55 IPC_STRUCT_TRAITS_BEGIN(content::WebSocketHandshakeResponse)
  56   IPC_STRUCT_TRAITS_MEMBER(url)
  57   IPC_STRUCT_TRAITS_MEMBER(status_code)
  58   IPC_STRUCT_TRAITS_MEMBER(status_text)
  59   IPC_STRUCT_TRAITS_MEMBER(headers)
  60   IPC_STRUCT_TRAITS_MEMBER(headers_text)
  61   IPC_STRUCT_TRAITS_MEMBER(response_time)
  62 IPC_STRUCT_TRAITS_END()
  63
  64 // WebSocket messages sent from the renderer to the browser.
  65
  66 // Open new WebSocket connection to |socket_url|. |requested_protocols| is a
  67 // list of tokens identifying sub-protocols the renderer would like to use, as
  68 // described in RFC6455 "Subprotocols Using the WebSocket Protocol".
  69 IPC_MESSAGE_ROUTED4(WebSocketHostMsg_AddChannelRequest,
  70                     GURL /* socket_url */,
  71                     std::vector<std::string> /* requested_protocols */,
  72                     url::Origin /* origin */,
  73                     int /* render_frame_id */)
  74
  75 // WebSocket messages sent from the browser to the renderer.
  76
  77 // Respond to an AddChannelRequest. |selected_protocol| is the sub-protocol the
  78 // server selected, or empty if no sub-protocol was selected. |extensions| is
  79 // the list of extensions negotiated for the connection.
  80 IPC_MESSAGE_ROUTED2(WebSocketMsg_AddChannelResponse,
  81                     std::string /* selected_protocol */,
  82                     std::string /* extensions */)
  83
  84 // Notify the renderer that the browser has started an opening handshake.
  85 // This message is for showing the request in the inspector and
  86 // can be omitted if the inspector is not active.
  87 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyStartOpeningHandshake,
  88                     content::WebSocketHandshakeRequest /* request */)
  89
  90 // Notify the renderer that the browser has finished an opening handshake.
  91 // This message precedes AddChannelResponse.
  92 // This message is for showing the response in the inspector and
  93 // can be omitted if the inspector is not active.
  94 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyFinishOpeningHandshake,
  95                     content::WebSocketHandshakeResponse /* response */)
  96
  97 // Notify the renderer that either:
  98 // - the connection open request (WebSocketHostMsg_AddChannelRequest) failed.
  99 // - the browser is required to fail the connection
 100 //   (see RFC6455 7.1.7 for details).
 101 //
 102 // When the renderer process receives this messages it does the following:
 103 // 1. Fire an error event.
 104 // 2. Show |message| to the inspector.
 105 // 3. Close the channel immediately uncleanly, as if it received
 106 //    DropChannel(was_clean = false, code = 1006, reason = "").
 107 // |message| will be shown in the inspector and won't be passed to the script.
 108 // TODO(yhirano): Find the way to pass |message| directly to the inspector
 109 // process.
 110 IPC_MESSAGE_ROUTED1(WebSocketMsg_NotifyFailure,
 111                     std::string /* message */)
 112
 113 // WebSocket messages that can be sent in either direction.
 114
 115 // Send a non-control frame to the channel.
 116 // - If the sender is the renderer, it will be sent to the remote server.
 117 // - If the sender is the browser, it comes from the remote server.
 118 //
 119 // - |fin| indicates that this frame is the last in the current message.
 120 // - |type| is the type of the message. On the first frame of a message, it
 121 //   must be set to either WEB_SOCKET_MESSAGE_TYPE_TEXT or
 122 //   WEB_SOCKET_MESSAGE_TYPE_BINARY. On subsequent frames, it must be set to
 123 //   WEB_SOCKET_MESSAGE_TYPE_CONTINUATION, and the type is the same as that of
 124 //   the first message. If |type| is WEB_SOCKET_MESSAGE_TYPE_TEXT, then the
 125 //   concatenation of the |data| from every frame in the message must be valid
 126 //   UTF-8. If |fin| is not set, |data| must be non-empty.
 127 IPC_MESSAGE_ROUTED3(WebSocketMsg_SendFrame,
 128                     bool /* fin */,
 129                     content::WebSocketMessageType /* type */,
 130                     std::vector<char> /* data */)
 131
 132 // Add |quota| tokens of send quota for the channel. |quota| must be a positive
 133 // integer. Both the browser and the renderer set send quota for the other
 134 // side, and check that quota has not been exceeded when receiving messages.
 135 // Both sides start a new channel with a quota of 0, and must wait for a
 136 // FlowControl message before calling SendFrame. The total available quota on
 137 // one side must never exceed 0x7FFFFFFFFFFFFFFF tokens.
 138 IPC_MESSAGE_ROUTED1(WebSocketMsg_FlowControl,
 139                     int64 /* quota */)
 140
 141 // Drop the channel.
 142 //
 143 // When sent by the renderer, this will cause a Close message will be sent and
 144 // the TCP/IP connection will be closed.
 145 //
 146 // When sent by the browser, this indicates that a Close has been received, the
 147 // connection was closed, or a network or protocol error occurred.
 148 //
 149 // - |code| is one of the reason codes specified in RFC6455.
 150 // - |reason|, if non-empty, is a UTF-8 encoded string which may be useful for
 151 //   debugging but is not necessarily human-readable, as supplied by the server
 152 //   in the Close message.
 153 // - If |was_clean| is false on a message from the browser, then the WebSocket
 154 //   connection was not closed cleanly. If |was_clean| is false on a message
 155 //   from the renderer, then the connection should be closed immediately without
 156 //   a closing handshake and the renderer cannot accept any new messages on this
 157 //   connection.
 158 IPC_MESSAGE_ROUTED3(WebSocketMsg_DropChannel,
 159                     bool /* was_clean */,
 160                     unsigned short /* code */,
 161                     std::string /* reason */)
 162
 163 // Notify the renderer that a closing handshake has been initiated by the
 164 // server, so that it can set the Javascript readyState to CLOSING.
 165 IPC_MESSAGE_ROUTED0(WebSocketMsg_NotifyClosing)