Clarify the specification of WriteFrames()

net/websockets/websocket_stream.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_STREAM_H_
 #define NET_WEBSOCKETS_WEBSOCKET_STREAM_H_
 
 #include <string>
 #include <vector>
 
@@ skipping 74 matching lines @@
       URLRequestContext* url_request_context,
       const BoundNetLog& net_log,
       scoped_ptr<ConnectDelegate> connect_delegate);
 
   // Derived classes must make sure Close() is called when the stream is not
   // closed on destruction.
   virtual ~WebSocketStream();
 
   // Reads WebSocket frame data. This operation finishes when new frame data
   // becomes available. Each frame message might be chopped off in the middle
-  // as specified in the description of WebSocketFrameChunk struct.
+  // as specified in the description of the WebSocketFrameChunk struct.
   // |frame_chunks| remains owned by the caller and must be valid until the
   // operation completes or Close() is called. |frame_chunks| must be empty on
   // calling.
   //
   // This function should not be called while the previous call of ReadFrames()
   // is still pending.
   //
   // Returns net::OK or one of the net::ERR_* codes.
   //
   // frame_chunks->size() >= 1 if the result is OK.
@@ skipping 14 matching lines @@
   // When the socket is closed on the remote side, this method will return
   // ERR_CONNECTION_CLOSED. It will not return OK with an empty vector.
   //
   // If the connection is closed in the middle of receiving an incomplete frame,
   // ReadFrames may discard the incomplete frame. Since the renderer will
   // discard any incomplete messages when the connection is closed, this makes
   // no difference to the overall semantics.
   virtual int ReadFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
                          const CompletionCallback& callback) = 0;
 
-  // Writes WebSocket frame data. |frame_chunks| must obey the rule specified
-  // in the documentation of WebSocketFrameChunk struct: the first chunk of
-  // a WebSocket frame must contain non-NULL |header|, and the last chunk must
-  // have |final_chunk| field set to true. Series of chunks representing a
-  // WebSocket frame must be consistent (the total length of |data| fields must
-  // match |header->payload_length|). |frame_chunks| must be valid until the
-  // operation completes or Close() is called.
+  // Writes WebSocket frame data. |frame_chunks| must only contain complete
+  // frames. Every chunk must have a non-NULL |header| and the |final_chunk|
+  // boolean set to true.
   //
-  // This function should not be called while previous call of WriteFrames() is
-  // still pending.
+  // The |frame_chunks| pointer must remain valid until the operation completes
+  // or Close() is called. WriteFrames() will modify the contents of
+  // |frame_chunks| in the process of sending the message. After WriteFrames()
+  // has completed it is safe to clear and then re-use the vector, but other
+  // than that the caller should make no assumptions about its contents.
   //
-  // Support for incomplete frames is not guaranteed and may be removed from
-  // future iterations of the API.
+  // This function should not be called while a previous call to WriteFrames()
+  // on the same stream is pending.
+  //
+  // Frame boundaries may not be preserved. Frames may be split or
+  // coalesced. Message boundaries are preserved (as required by WebSocket API
+  // semantics).
   //
   // This method will only return OK if all frames were written completely.
   // Otherwise it will return an appropriate net error code.
   virtual int WriteFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
                           const CompletionCallback& callback) = 0;
 
   // Closes the stream. All pending I/O operations (if any) are cancelled
   // at this point, so |frame_chunks| can be freed.
   virtual void Close() = 0;
 
@@ skipping 49 matching lines @@
  protected:
   WebSocketStream();
 
  private:
   DISALLOW_COPY_AND_ASSIGN(WebSocketStream);
 };
 
 }  // namespace net
 
 #endif  // NET_WEBSOCKETS_WEBSOCKET_STREAM_H_