Pepper_42_C++_interfaces
websocket.h
Go to the documentation of this file.
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_WEBSOCKET_H_
6 #define PPAPI_CPP_WEBSOCKET_H_
7 
8 #include "ppapi/c/ppb_websocket.h"
9 #include "ppapi/cpp/resource.h"
10 
11 /// @file
12 /// This file defines the WebSocket interface providing bi-directional,
13 /// full-duplex, communications over a single TCP socket.
14 
15 // Windows headers will redefine SendMessage.
16 #ifdef SendMessage
17 #undef SendMessage
18 #endif
19 
20 namespace pp {
21 
22 class CompletionCallback;
23 class InstanceHandle;
24 class Var;
25 
26 /// The <code>WebSocket</code> class providing bi-directional,
27 /// full-duplex, communications over a single TCP socket.
28 class WebSocket : public Resource {
29  public:
30  /// Constructs a WebSocket object.
31  ///
32  /// @param[in] instance The instance with which this resource will be
33  /// associated.
34  explicit WebSocket(const InstanceHandle& instance);
35 
36  /// Destructs a WebSocket object.
37  virtual ~WebSocket();
38 
39  /// Connect() connects to the specified WebSocket server. You can call this
40  /// function once for an object.
41  ///
42  /// @param[in] url A <code>Var</code> of string type representing a WebSocket
43  /// server URL.
44  ///
45  /// @param[in] protocols A pointer to an array of <code>Var</code> of string
46  /// type specifying sub-protocols. Each <code>Var</code> represents one
47  /// sub-protocol. This argument can be null only if
48  /// <code>protocol_count</code> is 0.
49  ///
50  /// @param[in] protocol_count The number of sub-protocols in
51  /// <code>protocols</code>.
52  ///
53  /// @param[in] callback A <code>CompletionCallback</code> called
54  /// when a connection is established or an error occurs in establishing
55  /// connection.
56  ///
57  /// @return An int32_t containing an error code from
58  /// <code>pp_errors.h</code>.
59  /// Returns <code>PP_ERROR_BADARGUMENT</code> if specified <code>url</code>,
60  /// or <code>protocols</code> contains invalid string as defined in
61  /// the WebSocket API specification. <code>PP_ERROR_BADARGUMENT</code>
62  /// corresponds to a SyntaxError in the WebSocket API specification.
63  /// Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the
64  /// <code>url</code> is not a secure protocol, but the origin of the caller
65  /// has a secure scheme. Also returns <code>PP_ERROR_NOACCESS</code> if the
66  /// port specified in the <code>url</code> is a port that the user agent is
67  /// configured to block access to because it is a well-known port like SMTP.
68  /// <code>PP_ERROR_NOACCESS</code> corresponds to a SecurityError of the
69  /// specification.
70  /// Returns <code>PP_ERROR_INPROGRESS</code> if this is not the first call to
71  /// Connect().
72  int32_t Connect(const Var& url, const Var protocols[],
73  uint32_t protocol_count, const CompletionCallback& callback);
74 
75  /// Close() closes the specified WebSocket connection by specifying
76  /// <code>code</code> and <code>reason</code>.
77  ///
78  /// @param[in] code The WebSocket close code. This is ignored if it is 0.
79  /// <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> must be used for the
80  /// usual case. To indicate some specific error cases, codes in the range
81  /// <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to
82  /// <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and in the range
83  /// <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to
84  /// <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are available.
85  ///
86  /// @param[in] reason A <code>Var</code> of string type representing the
87  /// close reason. This is ignored if it is an undefined type.
88  ///
89  /// @param[in] callback A <code>CompletionCallback</code> called when the
90  /// connection is closed or an error occurs in closing the connection.
91  ///
92  /// @return An int32_t containing an error code from
93  /// <code>pp_errors.h</code>.
94  /// Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains
95  /// an invalid character as a UTF-8 string, or is longer than 123 bytes.
96  /// <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript
97  /// SyntaxError in the WebSocket API specification.
98  /// Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer
99  /// equal to 1000 or in the range 3000 to 4999.
100  /// <code>PP_ERROR_NOACCESS</code> corresponds to an InvalidAccessError in
101  /// the WebSocket API specification. Returns <code>PP_ERROR_INPROGRESS</code>
102  /// if a previous call to Close() is not finished.
103  int32_t Close(uint16_t code, const Var& reason,
104  const CompletionCallback& callback);
105 
106  /// ReceiveMessage() receives a message from the WebSocket server.
107  /// This interface only returns a single message. That is, this interface
108  /// must be called at least N times to receive N messages, no matter the size
109  /// of each message.
110  ///
111  /// @param[out] message The received message is copied to provided
112  /// <code>message</code>. The <code>message</code> must remain valid until
113  /// ReceiveMessage() completes. Its received <code>Var</code> will be of
114  /// string or ArrayBuffer type.
115  ///
116  /// @param[in] callback A <code>CompletionCallback</code> called when
117  /// ReceiveMessage() completes. This callback is ignored if ReceiveMessage()
118  /// completes synchronously and returns <code>PP_OK</code>.
119  ///
120  /// @return An int32_t containing an error code from
121  /// <code>pp_errors.h</code>.
122  /// If an error is detected or connection is closed, ReceiveMessage() returns
123  /// <code>PP_ERROR_FAILED</code> after all buffered messages are received.
124  /// Until buffered message become empty, ReceiveMessage() continues to return
125  /// <code>PP_OK</code> as if connection is still established without errors.
126  int32_t ReceiveMessage(Var* message,
127  const CompletionCallback& callback);
128 
129  /// SendMessage() sends a message to the WebSocket server.
130  ///
131  /// @param[in] message A message to send. The message is copied to an internal
132  /// buffer, so the caller can free <code>message</code> safely after returning
133  /// from the function. This <code>Var</code> must be of string or
134  /// ArrayBuffer types.
135  ///
136  /// @return An int32_t containing an error code from
137  /// <code>pp_errors.h</code>.
138  /// Returns <code>PP_ERROR_FAILED</code> if the ReadyState is
139  /// <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code>.
140  /// <code>PP_ERROR_FAILED</code> corresponds to a JavaScript
141  /// InvalidStateError in the WebSocket API specification.
142  /// Returns <code>PP_ERROR_BADARGUMENT</code> if the provided
143  /// <code>message</code> contains an invalid character as a
144  /// UTF-8 string. <code>PP_ERROR_BADARGUMENT</code> corresponds to a
145  /// JavaScript SyntaxError in the WebSocket API specification.
146  /// Otherwise, returns <code>PP_OK</code>, but it doesn't necessarily mean
147  /// that the server received the message.
148  int32_t SendMessage(const Var& message);
149 
150  /// GetBufferedAmount() returns the number of bytes of text and binary
151  /// messages that have been queued for the WebSocket connection to send, but
152  /// have not been transmitted to the network yet.
153  ///
154  /// @return Returns the number of bytes.
155  uint64_t GetBufferedAmount();
156 
157  /// GetCloseCode() returns the connection close code for the WebSocket
158  /// connection.
159  ///
160  /// @return Returns 0 if called before the close code is set.
161  uint16_t GetCloseCode();
162 
163  /// GetCloseReason() returns the connection close reason for the WebSocket
164  /// connection.
165  ///
166  /// @return Returns a <code>Var</code> of string type. If called before the
167  /// close reason is set, the return value contains an empty string. Returns a
168  /// <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource.
170 
171  /// GetCloseWasClean() returns if the connection was closed cleanly for the
172  /// specified WebSocket connection.
173  ///
174  /// @return Returns <code>false</code> if called before the connection is
175  /// closed, called on an invalid resource, or closed for abnormal reasons.
176  /// Otherwise, returns <code>true</code> if the connection was closed
177  /// cleanly.
178  bool GetCloseWasClean();
179 
180  /// GetExtensions() returns the extensions selected by the server for the
181  /// specified WebSocket connection.
182  ///
183  /// @return Returns a <code>Var</code> of string type. If called before the
184  /// connection is established, the <code>Var</code>'s data is an empty
185  /// string. Returns a <code>PP_VARTYPE_UNDEFINED</code> if called on an
186  /// invalid resource. Currently the <code>Var</code>'s data for valid
187  /// resources are always an empty string.
188  Var GetExtensions();
189 
190  /// GetProtocol() returns the sub-protocol chosen by the server for the
191  /// specified WebSocket connection.
192  ///
193  /// @return Returns a <code>Var</code> of string type. If called before the
194  /// connection is established, the <code>Var</code> contains the empty
195  /// string. Returns a code>PP_VARTYPE_UNDEFINED</code> if called on an
196  /// invalid resource.
197  Var GetProtocol();
198 
199  /// GetReadyState() returns the ready state of the specified WebSocket
200  /// connection.
201  ///
202  /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID</code> if called
203  /// before Connect() is called, or if this function is called on an
204  /// invalid resource.
205  PP_WebSocketReadyState GetReadyState();
206 
207  /// GetURL() returns the URL associated with specified WebSocket connection.
208  ///
209  /// @return Returns a <code>Var</code> of string type. If called before the
210  /// connection is established, the <code>Var</code> contains the empty
211  /// string. Returns a <code>PP_VARTYPE_UNDEFINED</code> if this function
212  /// is called on an invalid resource.
213  Var GetURL();
214 };
215 
216 } // namespace pp
217 
218 #endif // PPAPI_CPP_WEBSOCKET_H_
uint16_t GetCloseCode()
Var GetExtensions()
bool GetCloseWasClean()
uint64_t GetBufferedAmount()
PP_WebSocketReadyState GetReadyState()
WebSocket(const InstanceHandle &instance)
int32_t Close(uint16_t code, const Var &reason, const CompletionCallback &callback)
int32_t ReceiveMessage(Var *message, const CompletionCallback &callback)
int32_t Connect(const Var &url, const Var protocols[], uint32_t protocol_count, const CompletionCallback &callback)
A generic type used for passing data types between the module and the page.
Definition: var.h:21
Var GetCloseReason()
int32_t SendMessage(const Var &message)
A reference counted module resource.
Definition: resource.h:20
virtual ~WebSocket()
Destructs a WebSocket object.