Add functions used for building WebSocket frame data.

net/websockets/websocket_frame.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef NET_WEBSOCKETS_WEBSOCKET_FRAME_H_
 #define NET_WEBSOCKETS_WEBSOCKET_FRAME_H_
 #pragma once
 
 #include <vector>
 
@@ skipping 42 matching lines @@
 // series of chunk objects of a WebSocket frame.
 //
 // Frame dissection is necessary to handle WebSocket frame stream containing
 // abritrarily large frames in the browser process. Because the server may send
 // a huge frame that doesn't fit in the memory, we cannot store the entire
 // payload data in the memory.
 //
 // Users of this struct should treat WebSocket frames as a data stream; it's
 // important to keep the frame data flowing, especially in the browser process.
 // Users should not let the data stuck somewhere in the pipeline.
+//
+// This struct is used for reading WebSocket frame data (created by
+// WebSocketFrameParser). To construct WebSocket frames, use functions below.
 struct NET_EXPORT_PRIVATE WebSocketFrameChunk {
   WebSocketFrameChunk();
   ~WebSocketFrameChunk();
 
   // Non-null |header| is provided only if this chunk is the first part of
   // a series of chunks.
   scoped_ptr<WebSocketFrameHeader> header;
 
   // Indicates this part is the last chunk of a frame.
   bool final_chunk;
 
   // |data| is always unmasked even if the frame is masked.
   std::vector<char> data;
 };
 
+// Contains four-byte data representing "masking key" of WebSocket frames.
+struct WebSocketMaskingKey {
+  char key[WebSocketFrameHeader::kMaskingKeyLength];
+};
+
+// Writes wire format of a WebSocket frame header into |output|, and returns
+// the number of bytes written.
+//
+// WebSocket frame format is defined at:
+// <http://tools.ietf.org/html/rfc6455#section-5.2>. This function writes
+// everything but payload data in a WebSocket frame to |buffer|.
+//
+// If |header->masked| is true, |masking_key| must point to a valid
+// WebSocketMaskingKey object containing the masking key for that frame
+// (possibly generated by GenerateWebSocketMaskingKey() function below).
+// Otherwise, |masking_key| must be NULL.
+//
+// |buffer| should have enough size to contain the frame header. Size of a
+// frame header varies from 2 bytes to 14 bytes depending on the payload length
+// and maskedness. If the size of |buffer| is insufficient, this function
+// returns ERR_INVALID_ARGUMENT and does not write any data to |buffer|.
+NET_EXPORT_PRIVATE int WriteWebSocketFrameHeader(
+    const WebSocketFrameHeader& header,
+    const WebSocketMaskingKey* masking_key,
+    char* buffer,
+    size_t buffer_size);

[mmenke, 2012/06/07 14:52:35]

The size_t input / int output strikes me as a bad idea.  I suggest we stick to
int input in both these functions.  We'll still have to used uint64s for frame
offsets/lengths, of course.

Single frames that long don't seem to make much sense, but specs require
support.  However, there's no need for us to support unreasonably long buffers,
internally.

[Yuta Kitamura, 2012/06/08 07:59:28]

Done.

+
+// Generates a masking key suitable for use in a new WebSocket frame.
+NET_EXPORT_PRIVATE WebSocketMaskingKey GenerateWebSocketMaskingKey();
+
+// Masks WebSocket frame payload.
+//
+// A client must mask every WebSocket frame by XOR'ing the frame payload
+// with four-byte random data (masking key). This function applies the masking
+// to the given payload data.
+//
+// This function masks |data| with |masking_key|, assuming |data| is partial
+// data starting from |frame_offset| bytes from the beginning of the payload
+// data.
+//
+// Since frame masking is a reversible operation, this function can also be
+// used for unmasking a WebSocket frame.
+NET_EXPORT_PRIVATE void MaskWebSocketFramePayload(
+    const WebSocketMaskingKey& masking_key,
+    uint64 frame_offset,
+    char* data,
+    size_t data_size);
+
 }  // namespace net
 
 #endif  // NET_WEBSOCKETS_WEBSOCKET_FRAME_H_