OLD | NEW |
1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | 5 #ifndef PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ |
6 #define PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | 6 #define PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ |
7 | 7 |
8 #include "ppapi/c/dev/ppb_websocket_dev.h" | 8 #include "ppapi/c/dev/ppb_websocket_dev.h" |
| 9 #include "ppapi/cpp/resource.h" |
9 | 10 |
10 /// @file | 11 /// @file |
11 /// This file defines the WebSocket_Dev interface. | 12 /// This file defines the WebSocket_Dev interface. |
12 | 13 |
13 namespace pp { | 14 namespace pp { |
14 | 15 |
| 16 class CompletionCallback; |
| 17 class Instance; |
15 class Var; | 18 class Var; |
16 | 19 |
17 /// The <code>WebSocket_Dev</code> class | 20 /// The <code>WebSocket_Dev</code> class |
18 /// A version that use virtual functions | |
19 class WebSocket_Dev : public Resource { | 21 class WebSocket_Dev : public Resource { |
20 public: | 22 public: |
21 /// Constructs a WebSocket_Dev object. | 23 /// Constructs a WebSocket_Dev object. |
22 WebSocket_Dev(); | 24 WebSocket_Dev(Instance* instance); |
23 | 25 |
24 /// Destructs a WebSocket_Dev object. | 26 /// Destructs a WebSocket_Dev object. |
25 virtual ~WebSocket_Dev(); | 27 virtual ~WebSocket_Dev(); |
26 | 28 |
27 /// Connect() connects to the specified WebSocket server. Caller can call | 29 /// Connect() connects to the specified WebSocket server. Caller can call |
28 /// this method at most once. | 30 /// this method at most once. |
29 /// | 31 /// |
30 /// @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. | 32 /// @param[in] url A <code>Var</code> of string type representing a WebSocket |
31 /// The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. | 33 /// server URL. |
32 /// @param[in] protocols A pointer to an array of <code>PP_Var</code> | 34 /// @param[in] protocols A pointer to an array of string type |
33 /// specifying sub-protocols. Each <code>PP_Var</code> represents one | 35 /// <code>Var</code> specifying sub-protocols. Each <code>Var</code> |
34 /// sub-protocol and its <code>PP_VarType</code> must be | 36 /// represents one sub-protocol. This argument can be null only if |
35 /// <code>PP_VARTYPE_STRING</code>. This argument can be null only if | |
36 /// <code>protocol_count</code> is 0. | 37 /// <code>protocol_count</code> is 0. |
37 /// @param[in] protocol_count The number of sub-protocols in | 38 /// @param[in] protocol_count The number of sub-protocols in |
38 /// <code>protocols</code>. | 39 /// <code>protocols</code>. |
| 40 /// @param[in] callback A <code>CompletionCallback</code> which is called |
| 41 /// when a connection is established or an error occurs in establishing |
| 42 /// connection. |
39 /// | 43 /// |
40 /// @return In case of immediate failure, returns an error code as follows. | 44 /// @return An int32_t containing an error code from |
41 /// Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | 45 /// <code>pp_errors.h</code>. |
42 /// SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to | 46 /// Returns <code>PP_ERROR_BADARGUMENT</code> if specified <code>url</code>, |
43 /// JavaScript SecurityError. Otherwise, returns | 47 /// or <code>protocols</code> contains invalid string as |
44 /// <code>PP_OK_COMPLETIONPENDING</code> and later invokes | 48 /// <code>The WebSocket API specification</code> defines. It corresponds to |
45 /// <code>OnOpen()</code> on success or <code>OnClose()</code> on failure. | 49 /// SyntaxError of the specification. |
| 50 /// Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the |
| 51 /// <code>url</code> is not a secure protocol, but the origin of the caller |
| 52 /// has a secure scheme. Also returns it if the port specified in the |
| 53 /// <code>url</code> is a port to which the user agent is configured to block |
| 54 /// access because the port is a well-known port like SMTP. It corresponds to |
| 55 /// SecurityError of the specification. |
| 56 /// Returns <code>PP_ERROR_INPROGRESS</code> if the call is not the first |
| 57 /// time. |
46 int32_t Connect(const Var& url, const Var protocols[], | 58 int32_t Connect(const Var& url, const Var protocols[], |
47 uint32_t protocol_count); | 59 uint32_t protocol_count, const CompletionCallback& callback); |
48 | 60 |
49 /// Close() closes the specified WebSocket connection by specifying | 61 /// Close() closes the specified WebSocket connection by specifying |
50 /// <code>code</code> and <code>reason</code>. | 62 /// <code>code</code> and <code>reason</code>. |
51 /// | 63 /// |
52 /// @param[in] code The WebSocket close code. Ignored if it is 0. | 64 /// @param[in] code The WebSocket close code. Ignored if it is 0. |
53 /// @param[in] reason A <code>PP_Var</code> which represents the WebSocket | 65 /// @param[in] reason A <code>Var</code> of string type which represents the |
54 /// close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. | 66 /// WebSocket close reason. Ignored if it is undefined type. |
55 /// Otherwise, its <code>PP_VarType</code> must be | 67 /// @param[in] callback A <code>CompletionCallback</code> which is called |
56 /// <code>PP_VARTYPE_STRING</code>. | 68 /// when the connection is closed or an error occurs in closing the |
| 69 /// connection. |
57 /// | 70 /// |
58 /// @return In case of immediate failure, returns an error code as follows. | 71 /// @return An int32_t containing an error code from |
59 /// Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | 72 /// <code>pp_errors.h</code>. |
60 /// SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to | 73 /// Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains |
61 /// JavaScript InvalidAccessError. Otherwise, returns | 74 /// an invalid character as a UTF-8 string, or longer than 123 bytes. It |
62 /// <code>PP_OK_COMPLETIONPENDING</code> and invokes <code>OnClose</code>. | 75 /// corresponds to JavaScript SyntaxError of the specification. |
63 int32_t Close(uint16_t code, const Var& reason); | 76 /// Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer |
| 77 /// equal to 1000 or in the range 3000 to 4999. It corresponds to |
| 78 /// InvalidAccessError of the specification. Returns |
| 79 /// <code>PP_ERROR_INPROGRESS</code> if the call is not the first time. |
| 80 int32_t Close(uint16_t code, const Var& reason, |
| 81 const CompletionCallback& callback); |
| 82 |
| 83 /// ReceiveMessage() receives a message from the WebSocket server. |
| 84 /// This interface only returns a single message. That is, this interface |
| 85 /// must be called at least N times to receive N messages, no matter how |
| 86 /// small each message is. |
| 87 /// |
| 88 /// @param[out] message The received message is copied to provided |
| 89 /// <code>message</code>. The <code>message</code> must remain valid until |
| 90 /// the ReceiveMessage operation completes. |
| 91 /// @param[in] callback A <code>CompletionCallback</code> which is called |
| 92 /// when the receiving message is completed. It is ignored if ReceiveMessage |
| 93 /// completes synchronously and returns <code>PP_OK</code>. |
| 94 /// |
| 95 /// @return An int32_t containing an error code from |
| 96 /// <code>pp_errors.h</code>. |
| 97 /// If an error is detected or connection is closed, returns |
| 98 /// <code>PP_ERROR_FAILED</code> after all buffered messages are received. |
| 99 /// Until buffered message become empty, continues to returns |
| 100 /// <code>PP_OK</code> as if connection is still established without errors. |
| 101 int32_t ReceiveMessage(Var* message, |
| 102 const CompletionCallback& callback); |
64 | 103 |
65 /// Send() sends a message to the WebSocket server. | 104 /// Send() sends a message to the WebSocket server. |
66 /// | 105 /// |
67 /// @param[in] data A message to send. The message is copied to internal | 106 /// @param[in] data A message to send. The message is copied to internal |
68 /// buffer. So caller can free <code>data</code> safely after returning | 107 /// buffer. So caller can free <code>data</code> safely after returning |
69 /// from the function. | 108 /// from the function. |
70 /// | 109 /// |
71 /// @return In case of immediate failure, returns an error code as follows. | 110 /// @return An int32_t containing an error code from |
72 /// Returns <code>PP_ERROR_FAILED</code> corresponding to JavaScript | 111 /// <code>pp_errors.h</code>. |
73 /// InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding to | 112 /// Returns <code>PP_ERROR_FAILED</code> if the ReadyState is |
74 /// JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. | 113 /// <code>PP_WEBSOCKETREADYSTATE_CONNECTING_DEV</code>. It corresponds |
75 /// <code>PP_OK</code> doesn't necessarily mean that the server received the | 114 /// JavaScript InvalidStateError of the specification. |
76 /// message. | 115 /// Returns <code>PP_ERROR_BADARGUMENT</code> if provided |
77 int32_t Send(const Var& data); | 116 /// <code>message</code> of string type contains an invalid character as a |
| 117 /// UTF-8 string. It corresponds to JavaScript SyntaxError of the |
| 118 /// specification. |
| 119 /// Otherwise, returns <code>PP_OK</code>, but it doesn't necessarily mean |
| 120 /// that the server received the message. |
| 121 int32_t SendMessage(const Var& message); |
78 | 122 |
79 /// GetBufferedAmount() returns the number of bytes of text and binary | 123 /// GetBufferedAmount() returns the number of bytes of text and binary |
80 /// messages that have been queued for the WebSocket connection to send but | 124 /// messages that have been queued for the WebSocket connection to send but |
81 /// have not been transmitted to the network yet. | 125 /// have not been transmitted to the network yet. |
82 /// | 126 /// |
83 /// Note: This interface might not be able to return exact bytes in the first | |
84 /// release. Current WebSocket implementation can not estimate exact protocol | |
85 /// frame overheads. | |
86 /// | |
87 /// @return Returns the number of bytes. | 127 /// @return Returns the number of bytes. |
88 uint64_t GetBufferedAmount(); | 128 uint64_t GetBufferedAmount(); |
89 | 129 |
| 130 /// GetCloseCode() returns the connection close code for the WebSocket |
| 131 /// connection. |
| 132 /// |
| 133 /// @return Returns 0 if called before the close code is set. |
| 134 uint16_t GetCloseCode(); |
| 135 |
| 136 /// GetCloseReason() returns the connection close reason for the WebSocket |
| 137 /// connection. |
| 138 /// |
| 139 /// @return Returns a <code>Var</code> of string type. If called before the |
| 140 /// close reason is set, it contains an empty string. |
| 141 Var GetCloseReason(); |
| 142 |
| 143 /// GetCloseWasClean() returns if the connection was closed cleanly for the |
| 144 /// specified WebSocket connection. |
| 145 /// |
| 146 /// @return Returns <code>false</code> if called before the connection is |
| 147 /// closed, or called on an invalid resource. Otherwise, returns |
| 148 /// <code>true</code> if the connection was closed cleanly, or returns |
| 149 /// <code>false</code> if the connection was closed for abnormal reasons. |
| 150 bool GetCloseWasClean(); |
| 151 |
90 /// GetExtensions() returns the extensions selected by the server for the | 152 /// GetExtensions() returns the extensions selected by the server for the |
91 /// specified WebSocket connection. | 153 /// specified WebSocket connection. |
92 /// | 154 /// |
93 /// @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before | 155 /// @return Returns a <code>Var</code> of string type. If called before the |
94 /// the connection is established, its data is empty string. | 156 /// connection is established, its data is an empty string. |
95 /// Currently its data is always empty string. | 157 /// Currently its data is always an empty string. |
96 Var GetExtensions(); | 158 Var GetExtensions(); |
97 | 159 |
98 /// GetProtocol() returns the sub-protocol chosen by the server for the | 160 /// GetProtocol() returns the sub-protocol chosen by the server for the |
99 /// specified WebSocket connection. | 161 /// specified WebSocket connection. |
100 /// | 162 /// |
101 /// @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before | 163 /// @return Returns a <code>Var</code> of string type. If called before the |
102 /// the connection is established, its data is empty string. | 164 /// connection is established, it contains the empty string. |
103 Var GetProtocol(); | 165 Var GetProtocol(); |
104 | 166 |
105 /// GetReadyState() returns the ready state of the specified WebSocket | 167 /// GetReadyState() returns the ready state of the specified WebSocket |
106 /// connection. | 168 /// connection. |
107 /// | 169 /// |
108 /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called | 170 /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called |
109 /// before connect() is called. | 171 /// before connect() is called. |
110 PP_WebSocketReadyState_Dev GetReadyState(); | 172 PP_WebSocketReadyState_Dev GetReadyState(); |
111 | 173 |
112 /// GetURL() returns the URL associated with specified WebSocket connection. | 174 /// GetURL() returns the URL associated with specified WebSocket connection. |
113 /// | 175 /// |
114 /// @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before | 176 /// @return Returns a <code>Var</code> of string type. If called before the |
115 /// the connection is established, its data is empty string. | 177 /// connection is established, it contains the empty string. |
116 Var GetURL(); | 178 Var GetURL(); |
117 | |
118 /// OnOpen() is invoked when the connection is established by Connect(). | |
119 virtual void OnOpen() = 0; | |
120 | |
121 /// OnMessage() is invoked when a message is received. | |
122 virtual void OnMessage(Var message) = 0; | |
123 | |
124 /// OnError() is invoked if the user agent was required to fail the WebSocket | |
125 /// connection or the WebSocket connection is closed with prejudice. | |
126 /// OnClose() always follows OnError(). | |
127 virtual void OnError() = 0; | |
128 | |
129 /// OnClose() is invoked when the connection is closed by errors or Close(). | |
130 virtual void OnClose(bool wasClean, uint16_t code, const Var& reason) = 0; | |
131 }; | 179 }; |
132 | 180 |
133 } // namespace pp | 181 } // namespace pp |
134 | 182 |
135 #endif // PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | 183 #endif // PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ |
OLD | NEW |