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. 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 // WebSocket messages sent from the renderer to the browser.
  30
  31 // Open new virtual WebSocket connection to |socket_url|. |channel_id| is an
  32 // identifier chosen by the renderer for the new channel. It cannot correspond
  33 // to an existing open channel, and must be between 1 and
  34 // 0x7FFFFFFF. |requested_protocols| is a list of tokens identifying
  35 // sub-protocols the renderer would like to use, as described in RFC6455
  36 // "Subprotocols Using the WebSocket Protocol".
  37 //
  38 // The browser process will not send |channel_id| as-is to the remote server; it
  39 // will try to use a short id on the wire. This saves the renderer from
  40 // having to try to choose the ids cleverly.
  41 IPC_MESSAGE_CONTROL4(WebSocketHostMsg_AddChannelRequest,
  42                      int /* channel_id */,
  43                      GURL /* socket_url */,
  44                      std::vector<std::string> /* requested_protocols */,
  45                      GURL /* origin */)
  46
  47 // Web Socket messages sent from the browser to the renderer.
  48
  49 // Respond to an AddChannelRequest for channel |channel_id|. |channel_id| is
  50 // scoped to the renderer process; while it is unique per-renderer, the browser
  51 // may have multiple renderers using the same id. If |fail| is true, the channel
  52 // could not be established (the cause of the failure is not provided to the
  53 // renderer in order to limit its ability to abuse WebSockets to perform network
  54 // probing, etc.). If |fail| is set then the |channel_id| is available for
  55 // re-use. |selected_protocol| is the sub-protocol the server selected,
  56 // or empty if no sub-protocol was selected. |extensions| is the list of
  57 // extensions negotiated for the connection.
  58 IPC_MESSAGE_CONTROL4(WebSocketMsg_AddChannelResponse,
  59                      int /* channel_id */,
  60                      bool /* fail */,
  61                      std::string /* selected_protocol */,
  62                      std::string /* extensions */)
  63
  64 // WebSocket messages that can be sent in either direction.
  65
  66 IPC_ENUM_TRAITS(content::WebSocketMessageType)
  67
  68 // Send a non-control frame on |channel_id|. If the sender is the renderer, it
  69 // will be sent to the remote server. If the sender is the browser, it comes
  70 // from the remote server. |fin| indicates that this frame is the last in the
  71 // current message. |type| is the type of the message. On the first frame of a
  72 // message, it must be set to either WEB_SOCKET_MESSAGE_TYPE_TEXT or
  73 // WEB_SOCKET_MESSAGE_TYPE_BINARY. On subsequent frames, it must be set to
  74 // WEB_SOCKET_MESSAGE_TYPE_CONTINUATION, and the type is the same as that of the
  75 // first message. If |type| is WEB_SOCKET_MESSAGE_TYPE_TEXT, then the
  76 // concatenation of the |data| from every frame in the message must be valid
  77 // UTF-8. If |fin| is not set, |data| must be non-empty.
  78 IPC_MESSAGE_CONTROL4(WebSocketMsg_SendFrame,
  79                      int /* channel_id */,
  80                      bool /* fin */,
  81                      content::WebSocketMessageType /* type */,
  82                      std::vector<char> /* data */)
  83
  84 // Add |quota| tokens of send quota for channel |channel_id|. |quota| must be a
  85 // positive integer. Both the browser and the renderer set send quota for the
  86 // other side, and check that quota has not been exceeded when receiving
  87 // messages. Both sides start a new channel with a quota of 0, and must wait for
  88 // a FlowControl message before calling SendFrame. The total available quota on
  89 // one side must never exceed 0x7FFFFFFFFFFFFFFF tokens.
  90 IPC_MESSAGE_CONTROL2(WebSocketMsg_FlowControl,
  91                      int /* channel_id */,
  92                      int64 /* quota */)
  93
  94 // Drop the channel.
  95 // When sent by the renderer, this will cause a DropChannel message to be sent
  96 // if the multiplex extension is in use, otherwise a Close message will be sent
  97 // and the TCP/IP connection will be closed.
  98 // When sent by the browser, this indicates that a Close or DropChannel has been
  99 // received, the connection was closed, or a network or protocol error
 100 // occurred. On receiving DropChannel, the renderer process may consider the
 101 // |channel_id| available for reuse by a new AddChannelRequest.
 102 // |code| is one of the reason codes specified in RFC6455 or
 103 // draft-ietf-hybi-websocket-multiplexing-09. |reason|, if non-empty, is a
 104 // UTF-8 encoded string which may be useful for debugging but is not necessarily
 105 // human-readable, as supplied by the server in the Close or DropChannel
 106 // message.
 107 IPC_MESSAGE_CONTROL3(WebSocketMsg_DropChannel,
 108                      int /* channel_id */,
 109                      unsigned short /* code */,
 110                      std::string /* reason */)