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. 169 Var GetCloseReason(); 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_ 219