net/websockets/websocket_stream.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_WEBSOCKETS_WEBSOCKET_STREAM_H_
   6 #define NET_WEBSOCKETS_WEBSOCKET_STREAM_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/memory/scoped_vector.h"
  10 #include "net/base/completion_callback.h"
  11
  12 namespace net {
  13
  14 class BoundNetLog;
  15 class HttpRequestHeaders;
  16 struct HttpRequestInfo;
  17 class HttpResponseInfo;
  18 struct WebSocketFrameChunk;
  19
  20 // WebSocketStream is a transport-agnostic interface for reading and writing
  21 // WebSocket frames. This class provides an abstraction for WebSocket streams
  22 // based on various transport layer, such as normal WebSocket connections
  23 // (WebSocket protocol upgraded from HTTP handshake), SPDY transports, or
  24 // WebSocket connections with multiplexing extension. Subtypes of
  25 // WebSocketStream are responsible for managing the underlying transport
  26 // appropriately.
  27 //
  28 // All functions except Close() can be asynchronous. If an operation cannot
  29 // be finished synchronously, the function returns ERR_IO_PENDING, and
  30 // |callback| will be called when the operation is finished. Non-null |callback|
  31 // must be provided to these functions.
  32
  33 class WebSocketStream {
  34  public:
  35   WebSocketStream() {}
  36
  37   // Derived classes must make sure Close() is called when the stream is not
  38   // closed on destruction.
  39   virtual ~WebSocketStream() {}
  40
  41   // Initializes stream. Must be called before calling SendHandshakeRequest().
  42   // Returns a net error code, possibly ERR_IO_PENDING, as stated above.
  43   //
  44   // |request_info.url| must be a URL starting with "ws://" or "wss://".
  45   // |request_info.method| must be "GET". |request_info.upload_data| is
  46   // ignored.
  47   virtual int InitializeStream(const HttpRequestInfo& request_info,
  48                                const BoundNetLog& net_log,
  49                                const CompletionCallback& callback) = 0;
  50
  51   // Writes WebSocket handshake request to the underlying socket. Must be
  52   // called after InitializeStream() completes and before
  53   // ReadHandshakeResponse() is called.
  54   //
  55   // |response_info| must remain valid until the stream is destroyed.
  56   virtual int SendHandshakeRequest(const HttpRequestHeaders& headers,
  57                                    HttpResponseInfo* response_info,
  58                                    const CompletionCallback& callback) = 0;
  59
  60   // Reads WebSocket handshake response from the underlying socket. This
  61   // function completes when the response headers have been completely
  62   // received. Must be called after SendHandshakeRequest() completes.
  63   virtual int ReadHandshakeResponse(const CompletionCallback& callback) = 0;
  64
  65   // Reads WebSocket frame data. This operation finishes when new frame data
  66   // becomes available. Each frame message might be chopped off in the middle
  67   // as specified in the description of WebSocketFrameChunk struct.
  68   // |frame_chunks| must be valid until the operation completes or Close()
  69   // is called.
  70   //
  71   // This function can be called after ReadHandshakeResponse(). This function
  72   // should not be called while the previous call of ReadFrames() is still
  73   // pending.
  74   virtual int ReadFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
  75                          const CompletionCallback& callback) = 0;
  76
  77   // Writes WebSocket frame data. |frame_chunks| must obey the rule specified
  78   // in the documentation of WebSocketFrameChunk struct: the first chunk of
  79   // a WebSocket frame must contain non-NULL |header|, and the last chunk must
  80   // have |final_chunk| field set to true. Series of chunks representing a
  81   // WebSocket frame must be consistent (the total length of |data| fields must
  82   // match |header->payload_length|). |frame_chunks| must be valid until the
  83   // operation completes or Close() is called.
  84   //
  85   // This function can be called after ReadHandshakeResponse(). This function
  86   // should not be called while previous call of WriteFrames() is still pending.
  87   virtual int WriteFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks,
  88                           const CompletionCallback& callback) = 0;
  89
  90   // Closes the stream. All pending I/O operations (if any) are canceled
  91   // at this point, so |frame_chunks| can be freed.
  92   virtual void Close() = 0;
  93
  94   // TODO(yutak): Add following interfaces:
  95   // - RenewStreamForAuth for authentication (is this necessary?)
  96   // - GetSSLInfo, GetSSLCertRequsetInfo for SSL
  97
  98  private:
  99   DISALLOW_COPY_AND_ASSIGN(WebSocketStream);
 100 };
 101
 102 }  // namespace net
 103
 104 #endif  // NET_WEBSOCKETS_WEBSOCKET_STREAM_H_