WebSocketChannel implementation

net/websockets/websocket_channel.h

+// Copyright 2013 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_CHANNEL_H_
+#define NET_WEBSOCKETS_WEBSOCKET_CHANNEL_H_
+
+#include <string>
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/callback.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/memory/scoped_vector.h"
+#include "base/memory/weak_ptr.h"
+#include "googleurl/src/gurl.h"
+#include "net/base/net_export.h"
+#include "net/websockets/websocket_frame.h"
+#include "net/websockets/websocket_stream.h"
+
+namespace net {
+
+class URLRequestContext;
+class WebSocketEventInterface;
+
+class NET_EXPORT WebSocketChannel {
+ public:
+  // Create a new WebSocketChannel with the specified parameters.
+  // SendAddChannelRequest() must be sent immediately afterwards to start the
+  // connection process.
+  WebSocketChannel(const GURL& socket_url,
+                   scoped_ptr<WebSocketEventInterface> event_interface);
+  virtual ~WebSocketChannel();
+
+  // Start the connection process.
+  void SendAddChannelRequest(
+      const std::vector<std::string>& requested_protocols,
+      const GURL& origin,
+      URLRequestContext* url_request_context);
+
+  // Send a data frame to the remote side. The frame should usually be no larger
+  // than 32KB to avoid blocking the IO thread. This method has a hard limit of
+  // 2GB. It is the responsibility of the caller to ensure that they have
+  // sufficient send quota to send this data, otherwise the connection will be
+  // closed without sending.
+  void SendFrame(bool fin,
+                 WebSocketFrameHeader::OpCode op_code,
+                 const std::vector<char>& data);
+
+  // Send "quota" units of flow control to the remote side.
+  void SendFlowControl(int64 quota);
+
+  // Send a "Drop Channel" message to the remote side.
+  void SendDropChannel(unsigned short code, const std::string& reason);
+
+  // Start the connection process, using a different factory function from the
+  // default. This is used for testing.
+  void SendAddChannelRequestWithFactory(
+      const std::vector<std::string>& requested_protocols,
+      const GURL& origin,
+      URLRequestContext* url_request_context,
+      base::Callback<scoped_ptr<WebSocketStreamRequest>(
+          const GURL&,
+          const std::vector<std::string>&,
+          const GURL&,
+          URLRequestContext*,
+          const BoundNetLog&,
+          scoped_ptr<WebSocketStream::ConnectDelegate>)> factory);
+
+ private:
+  // We have a simple linear progression of states from CONSTRUCTED to CLOSED,
+  // except that the SEND_CLOSED and RECV_CLOSED states may be skipped in case
+  // of error.
+  enum State {
+    FRESHLY_CONSTRUCTED,
+    CONNECTING,
+    CONNECTED,
+    SEND_CLOSED,
+    RECV_CLOSED,
+    CLOSED,  // also used for FAILED states.
+  };
+
+  // When failing a channel, we may or may not want to send the real reason for
+  // failing to the remote server. This enum is used by FailChannel() to
+  // choose.
+  enum ExposeError {
+    SEND_REAL_ERROR,
+    SEND_INTERNAL_ERROR,
+  };
+
+  // Our implementation of WebSocketStream::ConnectDelegate.
+  class ConnectDelegate;

[tyoshino (SeeGerritForStatus), 2013/07/01 05:15:29]

any reason not to make WebSocketChannel itself derive from
WebSocketStream::ConnectDelegate? if so, please write that here.

[Adam Rice, 2013/07/01 07:59:05]

Done.

+
+  // Success callback from WebSocketStream::CreateAndConnectStream()
+  void OnConnectSuccess(scoped_ptr<WebSocketStream> stream);
+
+  // Failure callback from WebSocketStream::CreateAndConnectStream()
+  void OnConnectFailure(unsigned short websocket_error);
+
+  // Call WebSocketStream::WriteFrames() with the appropriate arguments

[tyoshino (SeeGerritForStatus), 2013/07/01 05:05:18]

Calls

http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Function_Comments

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  void WriteFrames();
+
+  // Callback from WebSocketStream::WriteFrames
+  void OnWriteDone(int result);
+
+  // Call WebSocketStream::ReadFrames() with the appropriate arguments

[tyoshino (SeeGerritForStatus), 2013/07/01 05:05:18]

ditto

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  void ReadFrames();
+
+  // Callback from WebSocketStream::ReadFrames
+  void OnReadDone(int result);
+
+  // Process a single chunk that has been read from the stream.

[tyoshino (SeeGerritForStatus), 2013/07/01 05:05:18]

ditto

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  void ProcessFrameChunk(scoped_ptr<WebSocketFrameChunk> chunk);
+
+  // Low-level method to send a single frame. Used for both data and control
+  // frames. Either sends the frame immediately or buffers it to be scheduled
+  // when the current write finishes.
+  void SendIOBufferWithSize(bool fin,
+                            WebSocketFrameHeader::OpCode op_code,
+                            const scoped_refptr<IOBufferWithSize>& buffer);
+
+  // Internal method to fail a channel in a manner appropriate the current
+  // state. The suppled code and reason are sent back to the renderer; the
+  // server just gets a generic "going away" error (if the current state is
+  // CONNECTED). Resets current_frame_header_ as a side-effect.
+  void FailChannel(ExposeError expose,
+                   unsigned short code,
+                   const std::string& reason);
+
+  // Send a close frame to Start the WebSocket Closing Handshake, or to respond

[tyoshino (SeeGerritForStatus), 2013/07/01 05:05:18]

ditto

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  // to a close frame from the server.
+  void SendClose(unsigned short code, const std::string& reason);
+
+  // Parse a Close frame. If no status code is supplied, then |code| is set to

[tyoshino (SeeGerritForStatus), 2013/07/01 05:05:18]

ditto

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  // 1005 (No status code) with empty |reason|. If the supplied code is
+  // outside the valid range, then 1002 (Protocol error) is set instead. If the
+  // reason text is not valid UTF-8, then |reason| is set to an empty string
+  // instead.
+  void ParseClose(const scoped_refptr<IOBufferWithSize>& buffer,
+                  unsigned short* code,
+                  std::string* reason);
+
+  // The URL to which we connect.
+  const GURL socket_url_;
+
+  // The event_interface_ object to call back into.
+  const scoped_ptr<WebSocketEventInterface> event_interface_;
+
+  // The WebSocketStream to which we are sending/receiving data.
+  scoped_ptr<WebSocketStream> stream_;
+
+  // A data structure containing a vector of frames to be sent and the total
+  // number of bytes contained in the vector.
+  struct SendBuffer;
+  // Data that is currently pending write, or NULL if no write is pending.
+  scoped_ptr<SendBuffer> currently_sending_;

[tyoshino (SeeGerritForStatus), 2013/07/01 05:05:18]

can you name this using some noun?
for example
- pending_send_data_
- data_being_sent_

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  // Data that is queued up to write after the current write completes.
+  // Only non-NULL when such data actually exists.
+  scoped_ptr<SendBuffer> send_next_;

[tyoshino (SeeGerritForStatus), 2013/07/01 05:05:18]

how about putting a blank line here to group members for send op and receive op?

[tyoshino (SeeGerritForStatus), 2013/07/01 05:05:18]

ditto (naming)

[Adam Rice, 2013/07/01 07:59:05]

Done.

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  // Destination for the current call to WebSocketStream::ReadFrames
+  ScopedVector<WebSocketFrameChunk> read_frame_chunks_;
+  // Frame header for the current frame. Only non-NULL if we have had to

[tyoshino (SeeGerritForStatus), 2013/07/01 05:15:29]

current frame -> the frame currently received

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  // fragment the frame to send to the renderer because not all the data is
+  // available yet.
+  scoped_ptr<WebSocketFrameHeader> current_frame_header_;
+  // Handle to an in-progress WebSocketStream creation request.
+  scoped_ptr<WebSocketStreamRequest> stream_request_;
+  // Although it will almost never happen in practice, we can be passed an
+  // incomplete control frame, in which case we need to keep the data around
+  // long enough to reassemble it. This vector will be empty the rest of the
+  // time.
+  scoped_refptr<IOBufferWithSize> incomplete_control_frame_body_;
+  // The point at which we give the renderer a quota refresh (bytes).
+  int send_quota_low_water_mark_;
+  // The amount which we refresh the quota to when it reaches the
+  // low_water_mark (bytes).
+  int send_quota_high_water_mark_;
+  // The current amount of quota that the renderer has available for sending
+  // on this logical channel (bytes).
+  int current_send_quota_;

[tyoshino (SeeGerritForStatus), 2013/07/01 05:15:29]

how about putting a blank line here since the members below are not operation
specific.

[Adam Rice, 2013/07/01 07:59:05]

Done.

+  // The current state of the channel. Mainly used for sanity checking, but also
+  // used to track the close state.
+  State state_;
+  // We may be destroyed while callbacks are pending, so we need weak pointers
+  // for those callbacks.
+  base::WeakPtrFactory<WebSocketChannel> weak_factory_;
+
+  DISALLOW_COPY_AND_ASSIGN(WebSocketChannel);
+};
+
+}  // namespace net
+
+#endif  // NET_WEBSOCKETS_WEBSOCKET_CHANNEL_H_