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 41 matching lines @@
 // You need to look at |final_chunk| member variable to detect the end of a
 // 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.

[mmenke, 2012/05/21 15:08:37]

nit:  Think that we should have a note that this is only used for reading data
from a WebSocket, not writing it.

[Yuta Kitamura, 2012/05/22 10:29:35]

Done.

 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;
 };
 
+// Writes wire format of a WebSocket frame header into |output|.
+//
+// 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 |output|.
+//
+// If |header->masked| is true, |masking_key| must point to four-byte data
+// representing a masking key for that frame (possibly generated by
+// GenerateWebSocketMaskingKey() function below). Otherwise, |masking_key|
+// must be NULL.
+NET_EXPORT_PRIVATE void WriteWebSocketFrameHeader(
+    const WebSocketFrameHeader* header,

[mmenke, 2012/05/21 15:08:37]

Suggest you make this const WebSocketFrameHeader& header, as it's an input
parameter that can't be NULL.  This is a fairly strong recommendation from the
C++ style guide.

[Yuta Kitamura, 2012/05/22 10:29:35]

Done.

+    const char* masking_key,
+    std::vector<char>* output);
+
+// Generates a masking key suitable for use in a new WebSocket frame.
+//
+// |masking_key| should be non-NULL value pointing four-byte
+// (== kMaskingKeyLength bytes) data. The generated masking key will be written
+// to that buffer.
+NET_EXPORT_PRIVATE void GenearteWebSocketMaskingKey(char* masking_key);

[mmenke, 2012/05/21 15:08:37]

nit: GenearteWebSocketMaskingKey -> GenerateWebSocketMaskingKey

[mmenke, 2012/05/21 15:08:37]

I suggest you make a struct for masking keys, so type safety ensures it's always
the correct size.  May also be a little simpler just to return the masking_key
directly, since it's just a 4-byte array.

[Yuta Kitamura, 2012/05/22 10:29:35]

Introduced a new struct WebSocketMaskingKey. Changed the type of other
functions' arguments as well.

[Yuta Kitamura, 2012/05/22 10:29:35]

Doh! Fixed.

+
+// Masks WebSocket frame payload.
+//
+// A browser must mask every WebSocket frame by XOR'ing the frame payload

[mmenke, 2012/05/21 15:08:37]

nit:  Suggest "client" instead of "browser", as per spec.

[Yuta Kitamura, 2012/05/22 10:29:35]

Done.

+// with four-byte random data (masking key). This function applies the masking
+// to the given payload data.
+//
+// This function masks |frame_data| with |masking_key|, assuming |frame_data|
+// is partial data starting from |frame_offset| bytes from the beginning of
+// the payload data.

[mmenke, 2012/05/21 15:08:37]

Should make clear that this must not be called when the masking key is NULL. 
While the function name implies it, could easily see people assuming this should
always be called.

Alternatively, allow it to be called with a NULL masking_key.

[Yuta Kitamura, 2012/05/22 10:29:35]

Resolved by changing the type of |masking_key| to |const WebSocketMaskingKey&|.

+NET_EXPORT_PRIVATE void MaskWebSocketFramePayload(
+    const char* masking_key,
+    uint64 frame_offset,
+    std::vector<char>* frame_data);
+
 }  // namespace net
 
 #endif  // NET_WEBSOCKETS_WEBSOCKET_FRAME_H_