net/websockets/websocket_frame.h

   1 // Copyright (c) 2012 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 #ifndef NET_WEBSOCKETS_WEBSOCKET_FRAME_H_
   6 #define NET_WEBSOCKETS_WEBSOCKET_FRAME_H_
   7
   8 #include <vector>
   9
  10 #include "base/basictypes.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "net/base/net_export.h"
  14
  15 namespace net {
  16
  17 class IOBufferWithSize;
  18
  19 // Represents a WebSocket frame header.
  20 //
  21 // Members of this class correspond to each element in WebSocket frame header
  22 // (see http://tools.ietf.org/html/rfc6455#section-5.2).
  23 struct NET_EXPORT WebSocketFrameHeader {
  24   typedef int OpCode;
  25   static const OpCode kOpCodeContinuation;
  26   static const OpCode kOpCodeText;
  27   static const OpCode kOpCodeBinary;
  28   static const OpCode kOpCodeClose;
  29   static const OpCode kOpCodePing;
  30   static const OpCode kOpCodePong;
  31
  32   // These values must be a compile-time constant. "enum hack" is used here
  33   // to make MSVC happy.
  34   enum {
  35     kBaseHeaderSize = 2,
  36     kMaximumExtendedLengthSize = 8,
  37     kMaskingKeyLength = 4
  38   };
  39
  40   // Members below correspond to each item in WebSocket frame header.
  41   // See <http://tools.ietf.org/html/rfc6455#section-5.2> for details.
  42   bool final;
  43   bool reserved1;
  44   bool reserved2;
  45   bool reserved3;
  46   OpCode opcode;
  47   bool masked;
  48   uint64 payload_length;
  49 };
  50
  51 // Contains payload data of part of a WebSocket frame.
  52 //
  53 // Payload of a WebSocket frame may be divided into multiple chunks.
  54 // You need to look at |final_chunk| member variable to detect the end of a
  55 // series of chunk objects of a WebSocket frame.
  56 //
  57 // Frame dissection is necessary to handle WebSocket frame stream containing
  58 // abritrarily large frames in the browser process. Because the server may send
  59 // a huge frame that doesn't fit in the memory, we cannot store the entire
  60 // payload data in the memory.
  61 //
  62 // Users of this struct should treat WebSocket frames as a data stream; it's
  63 // important to keep the frame data flowing, especially in the browser process.
  64 // Users should not let the data stuck somewhere in the pipeline.
  65 //
  66 // This struct is used for reading WebSocket frame data (created by
  67 // WebSocketFrameParser). To construct WebSocket frames, use functions below.
  68 struct NET_EXPORT WebSocketFrameChunk {
  69   WebSocketFrameChunk();
  70   ~WebSocketFrameChunk();
  71
  72   // Non-null |header| is provided only if this chunk is the first part of
  73   // a series of chunks.
  74   scoped_ptr<WebSocketFrameHeader> header;
  75
  76   // Indicates this part is the last chunk of a frame.
  77   bool final_chunk;
  78
  79   // |data| is always unmasked even if the frame is masked. |data| might be
  80   // null in the first chunk.
  81   scoped_refptr<IOBufferWithSize> data;
  82 };
  83
  84 // Contains four-byte data representing "masking key" of WebSocket frames.
  85 struct WebSocketMaskingKey {
  86   char key[WebSocketFrameHeader::kMaskingKeyLength];
  87 };
  88
  89 // Returns the size of WebSocket frame header. The size of WebSocket frame
  90 // header varies from 2 bytes to 14 bytes depending on the payload length
  91 // and maskedness.
  92 NET_EXPORT int GetWebSocketFrameHeaderSize(
  93     const WebSocketFrameHeader& header);
  94
  95 // Writes wire format of a WebSocket frame header into |output|, and returns
  96 // the number of bytes written.
  97 //
  98 // WebSocket frame format is defined at:
  99 // <http://tools.ietf.org/html/rfc6455#section-5.2>. This function writes
 100 // everything but payload data in a WebSocket frame to |buffer|.
 101 //
 102 // If |header->masked| is true, |masking_key| must point to a valid
 103 // WebSocketMaskingKey object containing the masking key for that frame
 104 // (possibly generated by GenerateWebSocketMaskingKey() function below).
 105 // Otherwise, |masking_key| must be NULL.
 106 //
 107 // |buffer| should have enough size to contain the frame header.
 108 // GetWebSocketFrameHeaderSize() can be used to know the size of header
 109 // beforehand. If the size of |buffer| is insufficient, this function returns
 110 // ERR_INVALID_ARGUMENT and does not write any data to |buffer|.
 111 NET_EXPORT int WriteWebSocketFrameHeader(
 112     const WebSocketFrameHeader& header,
 113     const WebSocketMaskingKey* masking_key,
 114     char* buffer,
 115     int buffer_size);
 116
 117 // Generates a masking key suitable for use in a new WebSocket frame.
 118 NET_EXPORT WebSocketMaskingKey GenerateWebSocketMaskingKey();
 119
 120 // Masks WebSocket frame payload.
 121 //
 122 // A client must mask every WebSocket frame by XOR'ing the frame payload
 123 // with four-byte random data (masking key). This function applies the masking
 124 // to the given payload data.
 125 //
 126 // This function masks |data| with |masking_key|, assuming |data| is partial
 127 // data starting from |frame_offset| bytes from the beginning of the payload
 128 // data.
 129 //
 130 // Since frame masking is a reversible operation, this function can also be
 131 // used for unmasking a WebSocket frame.
 132 NET_EXPORT void MaskWebSocketFramePayload(
 133     const WebSocketMaskingKey& masking_key,
 134     uint64 frame_offset,
 135     char* data,
 136     int data_size);
 137
 138 }  // namespace net
 139
 140 #endif  // NET_WEBSOCKETS_WEBSOCKET_FRAME_H_