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 13 namespace pp { 14 15 class CompletionCallback; 16 class Instance; 17 class Var; 18 19 /// The <code>WebSocketAPI</code> class 20 class 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