OLD | NEW |
---|---|
(Empty) | |
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. | |
mmenke
2012/08/06 16:15:37
Suggest documenting the lifetime of |response_info
Yuta Kitamura
2012/08/07 06:20:48
Sure, done.
| |
54 virtual int SendHandshakeRequest(const HttpRequestHeaders& headers, | |
55 HttpResponseInfo* response_info, | |
56 const CompletionCallback& callback) = 0; | |
57 | |
58 // Reads WebSocket handshake response from the underlying socket. This | |
59 // function completes when the response headers have been completely | |
60 // received. Must be called after SendHandshakeRequest() completes. | |
61 virtual int ReadHandshakeResponse(const CompletionCallback& callback) = 0; | |
62 | |
63 // Reads WebSocket frame data. This operation finishes when new frame data | |
64 // becomes available. Each frame message might be chopped off in the middle | |
65 // as specified in the description of WebSocketFrameChunk struct. | |
66 // |frame_chunks| must be valid until the operation completes or Close() | |
67 // is called. | |
68 // | |
69 // This function can be called after ReadHandshakeResponse(). This function | |
70 // should not be called while previous call of ReadFrames() is still pending. | |
71 virtual int ReadFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks, | |
72 const CompletionCallback& callback) = 0; | |
73 | |
74 // Writes WebSocket frame data. |frame_chunks| must obey the rule specified | |
75 // in the documentation of WebSocketFrameChunk struct: the first chunk of | |
76 // a WebSocket frame must contain non-NULL |header|, and the last chunk must | |
77 // have |final_chunk| field set to true. Series of chunks representing a | |
78 // WebSocket frame must be consistent (the total length of |data| fields must | |
79 // match |header->payload_length|). |frame_chunks| must be valid until the | |
80 // operation completes or Close() is called. | |
81 // | |
82 // This function can be called after ReadHandshakeResponse(). This function | |
83 // should not be called while previous call of WriteFrames() is still pending. | |
mmenke
2012/08/06 16:15:37
nit: "while the previous call"
Yuta Kitamura
2012/08/07 06:20:48
Done.
| |
84 virtual int WriteFrames(ScopedVector<WebSocketFrameChunk>* frame_chunks, | |
85 const CompletionCallback& callback) = 0; | |
86 | |
87 // Closes the stream. All pending I/O operations (if any) are canceled | |
88 // at this point, so |frame_chunks| can be freed. | |
89 virtual void Close() = 0; | |
90 | |
91 // TODO(yutak): Add following interfaces: | |
92 // - RenewStreamForAuth for authentication (is this necessary?) | |
93 // - GetSSLInfo, GetSSLCertRequsetInfo for SSL | |
94 | |
95 private: | |
96 DISALLOW_COPY_AND_ASSIGN(WebSocketStream); | |
97 }; | |
98 | |
99 } // namespace net | |
100 | |
101 #endif // NET_WEBSOCKETS_WEBSOCKET_STREAM_H_ | |
OLD | NEW |