src/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 "base/basictypes.h"
#include "base/memory/scoped_vector.h"
#include "net/base/completion_callback.h"

namespace net {

class BoundNetLog;
class HttpRequestHeaders;
struct HttpRequestInfo;
class HttpResponseInfo;
struct WebSocketFrameChunk;

// WebSocketStream is a transport-agnostic interface for reading and writing
// WebSocket frames. This class provides an abstraction for WebSocket streams
// based on various transport layer, such as normal WebSocket connections
// (WebSocket protocol upgraded from HTTP handshake), SPDY transports, or
// WebSocket connections with multiplexing extension. Subtypes of
// WebSocketStream are responsible for managing the underlying transport
// appropriately.
//
// All functions except Close() can be asynchronous. If an operation cannot
// be finished synchronously, the function returns ERR_IO_PENDING, and
// |callback| will be called when the operation is finished. Non-null |callback|
// must be provided to these functions.

class WebSocketStream {
 public:
  WebSocketStream() {}

  // Derived classes must make sure Close() is called when the stream is not
  // closed on destruction.
  virtual ~WebSocketStream() {}

  // Initializes stream. Must be called before calling SendHandshakeRequest().
  // Returns a net error code, possibly ERR_IO_PENDING, as stated above.
  //
  // |request_info.url| must be a URL starting with "ws://" or "wss://".
  // |request_info.method| must be "GET". |request_info.upload_data| is
  // ignored.
  virtual int InitializeStream(const HttpRequestInfo& request_info,
                               const BoundNetLog& net_log,
                               const CompletionCallback& callback) = 0;

  // Writes WebSocket handshake request to the underlying socket. Must be
  // called after InitializeStream() completes and before
  // ReadHandshakeResponse() is called.
  //
  // |response_info| must remain valid until the stream is destroyed.
  virtual int SendHandshakeRequest(const HttpRequestHeaders& headers,
                                   HttpResponseInfo* response_info,
                                   const CompletionCallback& callback) = 0;

  // Reads WebSocket handshake response from the underlying socket. This
  // function completes when the response headers have been completely
  // received. Must be called after SendHandshakeRequest() completes.
  virtual int ReadHandshakeResponse(const CompletionCallback& callback) = 0;

  // 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.
  // |frame_chunks| must be valid until the operation completes or Close()
  // is called.
  //
  // This function can be called after ReadHandshakeResponse(). This function
  // should not be called while the previous call of ReadFrames() is still
  // pending.
  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.
  //
  // This function can be called after ReadHandshakeResponse(). This function
  // should not be called while previous call of WriteFrames() is still pending.
  virtual int WriteFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
                          const CompletionCallback& callback) = 0;

  // Closes the stream. All pending I/O operations (if any) are canceled
  // at this point, so |frame_chunks| can be freed.
  virtual void Close() = 0;

  // TODO(yutak): Add following interfaces:
  // - RenewStreamForAuth for authentication (is this necessary?)
  // - GetSSLInfo, GetSSLCertRequsetInfo for SSL

 private:
  DISALLOW_COPY_AND_ASSIGN(WebSocketStream);
};

}  // namespace net

#endif  // NET_WEBSOCKETS_WEBSOCKET_STREAM_H_