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 | 21 /// A version that use virtual functions |
19 class WebSocket_Dev : public Resource { | 22 class WebSocket_Dev : public Resource { |
20 public: | 23 public: |
21 /// Constructs a WebSocket_Dev object. | 24 /// Constructs a WebSocket_Dev object. |
22 WebSocket_Dev(); | 25 WebSocket_Dev(Instance* instance); |
23 | 26 |
24 /// Destructs a WebSocket_Dev object. | 27 /// Destructs a WebSocket_Dev object. |
25 virtual ~WebSocket_Dev(); | 28 virtual ~WebSocket_Dev(); |
26 | 29 |
27 /// Connect() connects to the specified WebSocket server. Caller can call | 30 /// Connect() connects to the specified WebSocket server. Caller can call |
28 /// this method at most once. | 31 /// this method at most once. |
29 /// | 32 /// |
30 /// @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. | 33 /// @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>. | 34 /// server URL. |
32 /// @param[in] protocols A pointer to an array of <code>PP_Var</code> | 35 /// @param[in] protocols An array of string type <code>Var</code> specifying |
33 /// specifying sub-protocols. Each <code>PP_Var</code> represents one | 36 /// sub-protocols. Each <code>Var</code> represents one sub-protocol. This |
34 /// sub-protocol and its <code>PP_VarType</code> must be | 37 /// argument can be null only if <code>protocol_count</code> is 0. |
dmichael (off chromium)
2011/12/09 23:05:26
Is there a reason you removed this comment on the
Takashi Toyoshima
2011/12/13 14:08:23
Oh, sorry.
I misunderstand on array like that foo[
| |
35 /// <code>PP_VARTYPE_STRING</code>. This argument can be null only if | |
36 /// <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 the connection is established or an error occurs in establishing | |
42 /// connection. | |
dmichael (off chromium)
2011/12/09 23:05:26
"the" connection ?
Takashi Toyoshima
2011/12/13 14:08:23
s/the/a/. on this and idl definition.
| |
39 /// | 43 /// |
40 /// @return In case of immediate failure, returns an error code as follows. | 44 /// @return Returns <code>PP_OK_COMPLETIONPENDING</code> then callback is |
dmichael (off chromium)
2011/12/09 23:05:26
Maybe this should be worded differently. It can re
Takashi Toyoshima
2011/12/13 14:08:23
Thank you.
I fixed all description on C/C++ APIs w
| |
41 /// Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | 45 /// invoked with one of following results. |
42 /// SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to | 46 /// <code>PP_ERROR_BADARGUMENT</code> corresponds to JavaScript SyntaxError, |
dmichael (off chromium)
2011/12/09 23:05:26
I think it would be better to explain what the err
Takashi Toyoshima
2011/12/13 14:08:23
The error detection rule is complicated, but I try
| |
43 /// JavaScript SecurityError. Otherwise, returns | 47 /// <code>PP_ERROR_NOACCESS</code> corresponds to JavaScript SecurityError. |
44 /// <code>PP_OK_COMPLETIONPENDING</code> and later invokes | 48 /// and returns <code>PP_ERROR_INPROGRESS</code> if the call is not the first |
45 /// <code>OnOpen()</code> on success or <code>OnClose()</code> on failure. | 49 /// time. |
46 int32_t Connect(const Var& url, const Var protocols[], | 50 int32_t Connect(const Var& url, const Var* const protocols, |
dmichael (off chromium)
2011/12/09 23:05:26
Why did you change from const Var protocols[]? In
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
47 uint32_t protocol_count); | 51 uint32_t protocol_count, const CompletionCallback& callback); |
48 | 52 |
49 /// Close() closes the specified WebSocket connection by specifying | 53 /// Close() closes the specified WebSocket connection by specifying |
50 /// <code>code</code> and <code>reason</code>. | 54 /// <code>code</code> and <code>reason</code>. |
51 /// | 55 /// |
52 /// @param[in] code The WebSocket close code. Ignored if it is 0. | 56 /// @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 | 57 /// @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>. | 58 /// WebSocket close reason. Ignored if it is undefined type. |
55 /// Otherwise, its <code>PP_VarType</code> must be | 59 /// @param[in] callback A <code>CompletionCallback</code> which is called |
56 /// <code>PP_VARTYPE_STRING</code>. | 60 /// when the connection is closed or an error occurs in closing connection. |
dmichael (off chromium)
2011/12/09 23:05:26
closing 'the' connection?
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
57 /// | 61 /// |
58 /// @return In case of immediate failure, returns an error code as follows. | 62 /// @return Returns <code>PP_OK_COMPLETIONPENDING</code> then callback is |
59 /// Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | 63 /// invoked with one of following results. |
60 /// SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to | 64 /// <code>PP_ERROR_BADARGUMENT</code> corresponds to JavaScript SyntaxError, |
61 /// JavaScript InvalidAccessError. Otherwise, returns | 65 /// <code>PP_ERROR_NOACCESS</code> corresponds to JavaScript |
62 /// <code>PP_OK_COMPLETIONPENDING</code> and invokes <code>OnClose</code>. | 66 /// InvalidAccessError. Returns <code>PP_ERROR_INPROGRESS</code> if the call |
63 int32_t Close(uint16_t code, const Var& reason); | 67 /// is not the first time. |
68 int32_t Close(uint16_t code, const Var& reason, | |
69 const CompletionCallback& callback); | |
70 | |
71 /// ReceiveMessage() receives a message from the WebSocket server. | |
72 /// This interface only returns bytes of a single message. That is, this | |
dmichael (off chromium)
2011/12/09 23:05:26
I would remove 'bytes of '
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
73 /// interface must be called at least N times to receive N messages, no | |
74 /// matter how small each message is. | |
75 /// | |
76 /// @param[out] message The received message is copied to provided | |
77 /// <code>message</code>. | |
dmichael (off chromium)
2011/12/09 23:05:26
Maybe it's worth noting that the Var passed for |m
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
78 /// @param[in] callback A <code>CompletionCallback</code> which is called | |
79 /// when the receiving message is completed. It is ignored when the function | |
dmichael (off chromium)
2011/12/09 23:05:26
It might be clearer to say something like:
"It is
Takashi Toyoshima
2011/12/13 14:08:23
Thank you for good suggestion.
Fixed.
| |
80 /// return <code>PP_OK</code>. | |
81 /// | |
82 /// @return Returns <code>PP_OK_COMPLETIONPENDING</code> then callback is | |
83 /// invoked with <code>PP_OK</code> or <code>PP_ERROR_FAILED</code>. | |
84 /// If an error is detected or connection is closed, returns | |
85 /// <code>PP_ERROR_FAILED</code> after all buffered messages are received. | |
86 /// Until buffered message become empty, continues to returns | |
87 /// <code>PP_OK</code> as if connection is still established without errors. | |
88 int32_t ReceiveMessage(Var* message, | |
89 const CompletionCallback& callback); | |
64 | 90 |
65 /// Send() sends a message to the WebSocket server. | 91 /// Send() sends a message to the WebSocket server. |
66 /// | 92 /// |
67 /// @param[in] data A message to send. The message is copied to internal | 93 /// @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 | 94 /// buffer. So caller can free <code>data</code> safely after returning |
69 /// from the function. | 95 /// from the function. |
70 /// | 96 /// |
71 /// @return In case of immediate failure, returns an error code as follows. | 97 /// @return In case of immediate failure, returns an error code as follows. |
72 /// Returns <code>PP_ERROR_FAILED</code> corresponding to JavaScript | 98 /// Returns <code>PP_ERROR_FAILED</code> corresponding to JavaScript |
73 /// InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding to | 99 /// InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding to |
74 /// JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. | 100 /// JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. |
75 /// <code>PP_OK</code> doesn't necessarily mean that the server received the | 101 /// <code>PP_OK</code> doesn't necessarily mean that the server received the |
76 /// message. | 102 /// message. |
77 int32_t Send(const Var& data); | 103 int32_t SendMessage(const Var& message); |
78 | 104 |
79 /// GetBufferedAmount() returns the number of bytes of text and binary | 105 /// GetBufferedAmount() returns the number of bytes of text and binary |
80 /// messages that have been queued for the WebSocket connection to send but | 106 /// messages that have been queued for the WebSocket connection to send but |
81 /// have not been transmitted to the network yet. | 107 /// have not been transmitted to the network yet. |
82 /// | 108 /// |
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. | 109 /// @return Returns the number of bytes. |
88 uint64_t GetBufferedAmount(); | 110 uint64_t GetBufferedAmount(); |
89 | 111 |
112 /// GetCloseCode() returns the connection close code for the WebSocket | |
113 /// connection. | |
114 /// | |
115 /// @return Returns 0 if called before the close code is set. | |
116 uint16_t GetCloseCode(); | |
117 | |
118 /// GetCloseReason() returns the connection close reason for the WebSocket | |
119 /// connection. | |
120 /// | |
121 /// @return Returns a <code>Var</code> of string type. If called before the | |
122 /// close reason is set, it contains empty string. | |
dmichael (off chromium)
2011/12/09 23:05:26
contains 'an' empty string?
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
123 Var GetCloseReason(); | |
124 | |
125 /// GetCloseWasClean() returns if the connection was closed cleanly for the | |
126 /// specified WebSocket connection. | |
127 /// | |
128 /// @return Returns <code>false</code> if called before the connection is | |
129 /// closed, or called on an invalid resource. Otherwise, returns | |
130 /// <code>true</code> if the connection was closed cleanly, or returns | |
131 /// <code>false</code> if the connection was closed by abnormal reasons. | |
dmichael (off chromium)
2011/12/09 23:05:26
by->for
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
132 bool GetCloseWasClean(); | |
133 | |
90 /// GetExtensions() returns the extensions selected by the server for the | 134 /// GetExtensions() returns the extensions selected by the server for the |
91 /// specified WebSocket connection. | 135 /// specified WebSocket connection. |
92 /// | 136 /// |
93 /// @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before | 137 /// @return Returns a <code>Var</code> of string type. If called before the |
94 /// the connection is established, its data is empty string. | 138 /// connection is established, its data is empty string. |
95 /// Currently its data is always empty string. | 139 /// Currently its data is always empty string. |
dmichael (off chromium)
2011/12/09 23:05:26
'an' empty string?
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
96 Var GetExtensions(); | 140 Var GetExtensions(); |
97 | 141 |
98 /// GetProtocol() returns the sub-protocol chosen by the server for the | 142 /// GetProtocol() returns the sub-protocol chosen by the server for the |
99 /// specified WebSocket connection. | 143 /// specified WebSocket connection. |
100 /// | 144 /// |
101 /// @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before | 145 /// @return Returns a <code>Var</code> of string type. If called before the |
102 /// the connection is established, its data is empty string. | 146 /// connection is established, it containss empty string. |
dmichael (off chromium)
2011/12/09 23:05:26
"containss"->"contains the"
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
103 Var GetProtocol(); | 147 Var GetProtocol(); |
104 | 148 |
105 /// GetReadyState() returns the ready state of the specified WebSocket | 149 /// GetReadyState() returns the ready state of the specified WebSocket |
106 /// connection. | 150 /// connection. |
107 /// | 151 /// |
108 /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called | 152 /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called |
109 /// before connect() is called. | 153 /// before connect() is called. |
110 PP_WebSocketReadyState_Dev GetReadyState(); | 154 PP_WebSocketReadyState_Dev GetReadyState(); |
111 | 155 |
112 /// GetURL() returns the URL associated with specified WebSocket connection. | 156 /// GetURL() returns the URL associated with specified WebSocket connection. |
113 /// | 157 /// |
114 /// @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before | 158 /// @return Returns a <code>Var</code> of string type. If called before the |
115 /// the connection is established, its data is empty string. | 159 /// connection is established, it contains empty string. |
dmichael (off chromium)
2011/12/09 23:05:26
contains "the"?
Takashi Toyoshima
2011/12/13 14:08:23
Done.
| |
116 Var GetURL(); | 160 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 }; | 161 }; |
132 | 162 |
133 } // namespace pp | 163 } // namespace pp |
134 | 164 |
135 #endif // PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | 165 #endif // PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ |
OLD | NEW |