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_UTILITY_WEBSOCKET_WEBSOCKET_API_H_
6#define PPAPI_UTILITY_WEBSOCKET_WEBSOCKET_API_H_
7
8#include "ppapi/c/ppb_websocket.h"
9
10/// @file
11/// This file defines the WebSocketAPI interface.
12
13namespace pp {
14
15class CompletionCallback;
16class Instance;
17class Var;
18
19/// The <code>WebSocketAPI</code> class
20class WebSocketAPI {
21 public:
22  /// Constructs a WebSocketAPI object.
23  explicit WebSocketAPI(Instance* instance);
24
25  /// Destructs a WebSocketAPI object.
26  virtual ~WebSocketAPI();
27
28  /// Connect() connects to the specified WebSocket server. Caller can call
29  /// this method at most once.
30  ///
31  /// @param[in] url A <code>Var</code> of string type representing a WebSocket
32  /// server URL.
33  /// @param[in] protocols A pointer to an array of string type
34  /// <code>Var</code> specifying sub-protocols. Each <code>Var</code>
35  /// represents one sub-protocol and its <code>PP_VarType</code> must be
36  /// <code>PP_VARTYPE_STRING</code>. 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  ///
41  /// @return An int32_t containing an error code from
42  /// <code>pp_errors.h</code>.
43  /// See also <code>pp::WebSocket::Connect</code>.
44  int32_t Connect(const Var& url, const Var protocols[],
45                  uint32_t protocol_count);
46
47  /// Close() closes the specified WebSocket connection by specifying
48  /// <code>code</code> and <code>reason</code>.
49  ///
50  /// @param[in] code The WebSocket close code. Ignored if it is 0.
51  /// @param[in] reason A <code>Var</code> of string type which represents the
52  /// WebSocket close reason. Ignored if it is undefined type.
53  ///
54  /// @return An int32_t containing an error code from
55  /// <code>pp_errors.h</code>.
56  /// See also <code>pp::WebSocket::Close</code>.
57  int32_t Close(uint16_t code, const Var& reason);
58
59  /// Send() sends a message to the WebSocket server.
60  ///
61  /// @param[in] data A message to send. The message is copied to internal
62  /// buffer. So caller can free <code>data</code> safely after returning
63  /// from the function.
64  ///
65  /// @return An int32_t containing an error code from
66  /// <code>pp_errors.h</code>.
67  /// See also <code>pp::WebSocket::SendMessage</code>.
68  int32_t Send(const Var& data);
69
70  /// GetBufferedAmount() returns the number of bytes of text and binary
71  /// messages that have been queued for the WebSocket connection to send but
72  /// have not been transmitted to the network yet.
73  ///
74  /// @return Returns the number of bytes.
75  uint64_t GetBufferedAmount();
76
77  /// GetExtensions() returns the extensions selected by the server for the
78  /// specified WebSocket connection.
79  ///
80  /// @return Returns a <code>Var</code> of string type. If called before the
81  /// connection is established, its data is empty string.
82  /// Currently its data is always an empty string.
83  Var GetExtensions();
84
85  /// GetProtocol() returns the sub-protocol chosen by the server for the
86  /// specified WebSocket connection.
87  ///
88  /// @return Returns a <code>Var</code> of string type. If called before the
89  /// connection is established, it contains the empty string.
90  Var GetProtocol();
91
92  /// GetReadyState() returns the ready state of the specified WebSocket
93  /// connection.
94  ///
95  /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID</code> if called
96  /// before connect() is called.
97  PP_WebSocketReadyState GetReadyState();
98
99  /// GetURL() returns the URL associated with specified WebSocket connection.
100  ///
101  /// @return Returns a <code>Var</code> of string type. If called before the
102  /// connection is established, it contains the empty string.
103  Var GetURL();
104
105  /// WebSocketDidOpen() is invoked when the connection is established by
106  /// Connect().
107  virtual void WebSocketDidOpen() = 0;
108
109  /// WebSocketDidClose() is invoked when the connection is closed by errors or
110  /// Close().
111  virtual void WebSocketDidClose(bool wasClean,
112                                 uint16_t code,
113                                 const Var& reason) = 0;
114
115  /// HandleWebSocketMessage() is invoked when a message is received.
116  virtual void HandleWebSocketMessage(const Var& message) = 0;
117
118  /// HandleWebSocketError() is invoked if the user agent was required to fail
119  /// the WebSocket connection or the WebSocket connection is closed with
120  /// prejudice. DidClose() always follows HandleError().
121  virtual void HandleWebSocketError() = 0;
122
123 private:
124  class Implement;
125  Implement* impl_;
126};
127
128}  // namespace pp
129
130#endif  // PPAPI_UTILITY_WEBSOCKET_WEBSOCKET_API_H_
131