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
15class GURL;
16
17namespace net {
18
19class SSLInfo;
20struct WebSocketHandshakeRequestInfo;
21struct 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.
25class 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_
141