net/websockets/websocket_event_interface.h

   1 // Copyright 2013 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_EVENT_INTERFACE_H_
   6 #define NET_WEBSOCKETS_WEBSOCKET_EVENT_INTERFACE_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/compiler_specific.h"  // for WARN_UNUSED_RESULT
  13 #include "net/base/net_export.h"
  14
  15 class GURL;
  16
  17 namespace net {
  18
  19 class SSLInfo;
  20 struct WebSocketHandshakeRequestInfo;
  21 struct WebSocketHandshakeResponseInfo;
  22
  23 // Interface for events sent from the network layer to the content layer. These
  24 // events will generally be sent as-is to the renderer process.
  25 class NET_EXPORT WebSocketEventInterface {
  26  public:
  27   typedef int WebSocketMessageType;
  28
  29   // Any event can cause the Channel to be deleted. The Channel needs to avoid
  30   // doing further processing in this case. It does not need to do cleanup, as
  31   // cleanup will already have been done as a result of the deletion.
  32   enum ChannelState {
  33     CHANNEL_ALIVE,
  34     CHANNEL_DELETED
  35   };
  36
  37   virtual ~WebSocketEventInterface() {}
  38
  39   // Called in response to an AddChannelRequest. This generally means that a
  40   // response has been received from the remote server, but the response might
  41   // have been generated internally. If |fail| is true, the channel cannot be
  42   // used and should be deleted, returning CHANNEL_DELETED.
  43   virtual ChannelState OnAddChannelResponse(
  44       bool fail,
  45       const std::string& selected_subprotocol,
  46       const std::string& extensions) WARN_UNUSED_RESULT = 0;
  47
  48   // Called when a data frame has been received from the remote host and needs
  49   // to be forwarded to the renderer process.
  50   virtual ChannelState OnDataFrame(
  51       bool fin,
  52       WebSocketMessageType type,
  53       const std::vector<char>& data) WARN_UNUSED_RESULT = 0;
  54
  55   // Called to provide more send quota for this channel to the renderer
  56   // process. Currently the quota units are always bytes of message body
  57   // data. In future it might depend on the type of multiplexing in use.
  58   virtual ChannelState OnFlowControl(int64 quota) WARN_UNUSED_RESULT = 0;
  59
  60   // Called when the remote server has Started the WebSocket Closing
  61   // Handshake. The client should not attempt to send any more messages after
  62   // receiving this message. It will be followed by OnDropChannel() when the
  63   // closing handshake is complete.
  64   virtual ChannelState OnClosingHandshake() WARN_UNUSED_RESULT = 0;
  65
  66   // Called when the channel has been dropped, either due to a network close, a
  67   // network error, or a protocol error. This may or may not be preceeded by a
  68   // call to OnClosingHandshake().
  69   //
  70   // Warning: Both the |code| and |reason| are passed through to Javascript, so
  71   // callers must take care not to provide details that could be useful to
  72   // attackers attempting to use WebSockets to probe networks.
  73   //
  74   // |was_clean| should be true if the closing handshake completed successfully.
  75   //
  76   // The channel should not be used again after OnDropChannel() has been
  77   // called.
  78   //
  79   // This method returns a ChannelState for consistency, but all implementations
  80   // must delete the Channel and return CHANNEL_DELETED.
  81   virtual ChannelState OnDropChannel(bool was_clean,
  82                                      uint16 code,
  83                                      const std::string& reason)
  84       WARN_UNUSED_RESULT = 0;
  85
  86   // Called when the browser fails the channel, as specified in the spec.
  87   //
  88   // The channel should not be used again after OnFailChannel() has been
  89   // called.
  90   //
  91   // This method returns a ChannelState for consistency, but all implementations
  92   // must delete the Channel and return CHANNEL_DELETED.
  93   virtual ChannelState OnFailChannel(const std::string& message)
  94       WARN_UNUSED_RESULT = 0;
  95
  96   // Called when the browser starts the WebSocket Opening Handshake.
  97   virtual ChannelState OnStartOpeningHandshake(
  98       scoped_ptr<WebSocketHandshakeRequestInfo> request) WARN_UNUSED_RESULT = 0;
  99
 100   // Called when the browser finishes the WebSocket Opening Handshake.
 101   virtual ChannelState OnFinishOpeningHandshake(
 102       scoped_ptr<WebSocketHandshakeResponseInfo> response)
 103       WARN_UNUSED_RESULT = 0;
 104
 105   // Callbacks to be used in response to a call to OnSSLCertificateError. Very
 106   // similar to content::SSLErrorHandler::Delegate (which we can't use directly
 107   // due to layering constraints).
 108   class NET_EXPORT SSLErrorCallbacks {
 109    public:
 110     virtual ~SSLErrorCallbacks() {}
 111
 112     // Cancels the SSL response in response to the error.
 113     virtual void CancelSSLRequest(int error, const SSLInfo* ssl_info) = 0;
 114
 115     // Continue with the SSL connection despite the error.
 116     virtual void ContinueSSLRequest() = 0;
 117   };
 118
 119   // Called on SSL Certificate Error during the SSL handshake. Should result in
 120   // a call to either ssl_error_callbacks->ContinueSSLRequest() or
 121   // ssl_error_callbacks->CancelSSLRequest(). Normally the implementation of
 122   // this method will delegate to content::SSLManager::OnSSLCertificateError to
 123   // make the actual decision. The callbacks must not be called after the
 124   // WebSocketChannel has been destroyed.
 125   virtual ChannelState OnSSLCertificateError(
 126       scoped_ptr<SSLErrorCallbacks> ssl_error_callbacks,
 127       const GURL& url,
 128       const SSLInfo& ssl_info,
 129       bool fatal) WARN_UNUSED_RESULT = 0;
 130
 131  protected:
 132   WebSocketEventInterface() {}
 133
 134  private:
 135   DISALLOW_COPY_AND_ASSIGN(WebSocketEventInterface);
 136 };
 137
 138 }  // namespace net
 139
 140 #endif  // NET_WEBSOCKETS_WEBSOCKET_EVENT_INTERFACE_H_