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 PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | |
6 #define PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | |
7 | |
8 #include "ppapi/c/dev/ppb_websocket_dev.h" | |
9 #include "ppapi/cpp/resource.h" | |
10 | |
11 /// @file | |
12 /// This file defines the WebSocket_Dev interface. | |
13 | |
14 namespace pp { | |
15 | |
16 class CompletionCallback; | |
17 class Instance; | |
18 class Var; | |
19 | |
20 /// The <code>WebSocket_Dev</code> class | |
21 class WebSocket_Dev : public Resource { | |
22 public: | |
23 /// Constructs a WebSocket_Dev object. | |
24 WebSocket_Dev(Instance* instance); | |
25 | |
26 /// Destructs a WebSocket_Dev object. | |
27 virtual ~WebSocket_Dev(); | |
28 | |
29 /// Connect() connects to the specified WebSocket server. Caller can call | |
30 /// this method at most once. | |
31 /// | |
32 /// @param[in] url A <code>Var</code> of string type representing a WebSocket | |
33 /// server URL. | |
34 /// @param[in] protocols A pointer to an array of string type | |
35 /// <code>Var</code> specifying sub-protocols. Each <code>Var</code> | |
36 /// represents one sub-protocol. This argument can be null only if | |
37 /// <code>protocol_count</code> is 0. | |
38 /// @param[in] protocol_count The number of sub-protocols in | |
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. | |
43 /// | |
44 /// @return An int32_t containing an error code from | |
45 /// <code>pp_errors.h</code>. | |
46 /// Returns <code>PP_ERROR_BADARGUMENT</code> if specified <code>url</code>, | |
47 /// or <code>protocols</code> contains invalid string as | |
48 /// <code>The WebSocket API specification</code> defines. It corresponds to | |
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. | |
58 int32_t Connect(const Var& url, const Var protocols[], | |
59 uint32_t protocol_count, const CompletionCallback& callback); | |
60 | |
61 /// Close() closes the specified WebSocket connection by specifying | |
62 /// <code>code</code> and <code>reason</code>. | |
63 /// | |
64 /// @param[in] code The WebSocket close code. Ignored if it is 0. | |
65 /// @param[in] reason A <code>Var</code> of string type which represents the | |
66 /// WebSocket close reason. Ignored if it is undefined type. | |
67 /// @param[in] callback A <code>CompletionCallback</code> which is called | |
68 /// when the connection is closed or an error occurs in closing the | |
69 /// connection. | |
70 /// | |
71 /// @return An int32_t containing an error code from | |
72 /// <code>pp_errors.h</code>. | |
73 /// Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains | |
74 /// an invalid character as a UTF-8 string, or longer than 123 bytes. It | |
75 /// corresponds to JavaScript SyntaxError of the specification. | |
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. It will be a <code>Var</code> of | |
91 /// string or ArrayBuffer types on receiving. | |
92 /// @param[in] callback A <code>CompletionCallback</code> which is called | |
93 /// when the receiving message is completed. It is ignored if ReceiveMessage | |
94 /// completes synchronously and returns <code>PP_OK</code>. | |
95 /// | |
96 /// @return An int32_t containing an error code from | |
97 /// <code>pp_errors.h</code>. | |
98 /// If an error is detected or connection is closed, returns | |
99 /// <code>PP_ERROR_FAILED</code> after all buffered messages are received. | |
100 /// Until buffered message become empty, continues to returns | |
101 /// <code>PP_OK</code> as if connection is still established without errors. | |
102 int32_t ReceiveMessage(Var* message, | |
103 const CompletionCallback& callback); | |
104 | |
105 /// Send() sends a message to the WebSocket server. | |
106 /// | |
107 /// @param[in] data A message to send. The message is copied to internal | |
108 /// buffer. So caller can free <code>data</code> safely after returning | |
109 /// from the function. It must be a <code>Var</code> of string or ArrayBuffer | |
110 /// types. | |
111 /// | |
112 /// @return An int32_t containing an error code from | |
113 /// <code>pp_errors.h</code>. | |
114 /// Returns <code>PP_ERROR_FAILED</code> if the ReadyState is | |
115 /// <code>PP_WEBSOCKETREADYSTATE_CONNECTING_DEV</code>. It corresponds | |
116 /// JavaScript InvalidStateError of the specification. | |
117 /// Returns <code>PP_ERROR_BADARGUMENT</code> if provided | |
118 /// <code>message</code> of string type contains an invalid character as a | |
119 /// UTF-8 string. It corresponds to JavaScript SyntaxError of the | |
120 /// specification. | |
121 /// Otherwise, returns <code>PP_OK</code>, but it doesn't necessarily mean | |
122 /// that the server received the message. | |
123 int32_t SendMessage(const Var& message); | |
124 | |
125 /// GetBufferedAmount() returns the number of bytes of text and binary | |
126 /// messages that have been queued for the WebSocket connection to send but | |
127 /// have not been transmitted to the network yet. | |
128 /// | |
129 /// @return Returns the number of bytes. | |
130 uint64_t GetBufferedAmount(); | |
131 | |
132 /// GetCloseCode() returns the connection close code for the WebSocket | |
133 /// connection. | |
134 /// | |
135 /// @return Returns 0 if called before the close code is set. | |
136 uint16_t GetCloseCode(); | |
137 | |
138 /// GetCloseReason() returns the connection close reason for the WebSocket | |
139 /// connection. | |
140 /// | |
141 /// @return Returns a <code>Var</code> of string type. If called before the | |
142 /// close reason is set, it contains an empty string. | |
143 Var GetCloseReason(); | |
144 | |
145 /// GetCloseWasClean() returns if the connection was closed cleanly for the | |
146 /// specified WebSocket connection. | |
147 /// | |
148 /// @return Returns <code>false</code> if called before the connection is | |
149 /// closed, or called on an invalid resource. Otherwise, returns | |
150 /// <code>true</code> if the connection was closed cleanly, or returns | |
151 /// <code>false</code> if the connection was closed for abnormal reasons. | |
152 bool GetCloseWasClean(); | |
153 | |
154 /// GetExtensions() returns the extensions selected by the server for the | |
155 /// specified WebSocket connection. | |
156 /// | |
157 /// @return Returns a <code>Var</code> of string type. If called before the | |
158 /// connection is established, its data is an empty string. | |
159 /// Currently its data is always an empty string. | |
160 Var GetExtensions(); | |
161 | |
162 /// GetProtocol() returns the sub-protocol chosen by the server for the | |
163 /// specified WebSocket connection. | |
164 /// | |
165 /// @return Returns a <code>Var</code> of string type. If called before the | |
166 /// connection is established, it contains the empty string. | |
167 Var GetProtocol(); | |
168 | |
169 /// GetReadyState() returns the ready state of the specified WebSocket | |
170 /// connection. | |
171 /// | |
172 /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called | |
173 /// before connect() is called. | |
174 PP_WebSocketReadyState_Dev GetReadyState(); | |
175 | |
176 /// GetURL() returns the URL associated with specified WebSocket connection. | |
177 /// | |
178 /// @return Returns a <code>Var</code> of string type. If called before the | |
179 /// connection is established, it contains the empty string. | |
180 Var GetURL(); | |
181 }; | |
182 | |
183 } // namespace pp | |
184 | |
185 #endif // PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | |
OLD | NEW |