| OLD | NEW |
|---|
| (Empty) |
| 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_DEV_WEBSOCKET_DEV_H_ | |
| 6 #define PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | |
| 7 | |
| 8 #include "ppapi/c/dev/ppb_websocket_dev.h" | |
| 9 #include "ppapi/cpp/resource.h" | |
| 10 | |
| 11 /// @file | |
| 12 /// This file defines the WebSocket_Dev interface. | |
| 13 | |
| 14 namespace pp { | |
| 15 | |
| 16 class CompletionCallback; | |
| 17 class Instance; | |
| 18 class Var; | |
| 19 | |
| 20 /// The <code>WebSocket_Dev</code> class | |
| 21 class WebSocket_Dev : public Resource { | |
| 22 public: | |
| 23 /// Constructs a WebSocket_Dev object. | |
| 24 WebSocket_Dev(Instance* instance); | |
| 25 | |
| 26 /// Destructs a WebSocket_Dev object. | |
| 27 virtual ~WebSocket_Dev(); | |
| 28 | |
| 29 /// Connect() connects to the specified WebSocket server. Caller can call | |
| 30 /// this method at most once. | |
| 31 /// | |
| 32 /// @param[in] url A <code>Var</code> of string type representing a WebSocket | |
| 33 /// server URL. | |
| 34 /// @param[in] protocols A pointer to an array of string type | |
| 35 /// <code>Var</code> specifying sub-protocols. Each <code>Var</code> | |
| 36 /// represents one sub-protocol. 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 /// @param[in] callback A <code>CompletionCallback</code> which is called | |
| 41 /// when a connection is established or an error occurs in establishing | |
| 42 /// connection. | |
| 43 /// | |
| 44 /// @return An int32_t containing an error code from | |
| 45 /// <code>pp_errors.h</code>. | |
| 46 /// Returns <code>PP_ERROR_BADARGUMENT</code> if specified <code>url</code>, | |
| 47 /// or <code>protocols</code> contains invalid string as | |
| 48 /// <code>The WebSocket API specification</code> defines. It corresponds to | |
| 49 /// SyntaxError of the specification. | |
| 50 /// Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the | |
| 51 /// <code>url</code> is not a secure protocol, but the origin of the caller | |
| 52 /// has a secure scheme. Also returns it if the port specified in the | |
| 53 /// <code>url</code> is a port to which the user agent is configured to block | |
| 54 /// access because the port is a well-known port like SMTP. It corresponds to | |
| 55 /// SecurityError of the specification. | |
| 56 /// Returns <code>PP_ERROR_INPROGRESS</code> if the call is not the first | |
| 57 /// time. | |
| 58 int32_t Connect(const Var& url, const Var protocols[], | |
| 59 uint32_t protocol_count, const CompletionCallback& callback); | |
| 60 | |
| 61 /// Close() closes the specified WebSocket connection by specifying | |
| 62 /// <code>code</code> and <code>reason</code>. | |
| 63 /// | |
| 64 /// @param[in] code The WebSocket close code. Ignored if it is 0. | |
| 65 /// @param[in] reason A <code>Var</code> of string type which represents the | |
| 66 /// WebSocket close reason. Ignored if it is undefined type. | |
| 67 /// @param[in] callback A <code>CompletionCallback</code> which is called | |
| 68 /// when the connection is closed or an error occurs in closing the | |
| 69 /// connection. | |
| 70 /// | |
| 71 /// @return An int32_t containing an error code from | |
| 72 /// <code>pp_errors.h</code>. | |
| 73 /// Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains | |
| 74 /// an invalid character as a UTF-8 string, or longer than 123 bytes. It | |
| 75 /// corresponds to JavaScript SyntaxError of the specification. | |
| 76 /// Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer | |
| 77 /// equal to 1000 or in the range 3000 to 4999. It corresponds to | |
| 78 /// InvalidAccessError of the specification. Returns | |
| 79 /// <code>PP_ERROR_INPROGRESS</code> if the call is not the first time. | |
| 80 int32_t Close(uint16_t code, const Var& reason, | |
| 81 const CompletionCallback& callback); | |
| 82 | |
| 83 /// ReceiveMessage() receives a message from the WebSocket server. | |
| 84 /// This interface only returns a single message. That is, this interface | |
| 85 /// must be called at least N times to receive N messages, no matter how | |
| 86 /// small each message is. | |
| 87 /// | |
| 88 /// @param[out] message The received message is copied to provided | |
| 89 /// <code>message</code>. The <code>message</code> must remain valid until | |
| 90 /// the ReceiveMessage operation completes. | |
| 91 /// @param[in] callback A <code>CompletionCallback</code> which is called | |
| 92 /// when the receiving message is completed. It is ignored if ReceiveMessage | |
| 93 /// completes synchronously and returns <code>PP_OK</code>. | |
| 94 /// | |
| 95 /// @return An int32_t containing an error code from | |
| 96 /// <code>pp_errors.h</code>. | |
| 97 /// If an error is detected or connection is closed, returns | |
| 98 /// <code>PP_ERROR_FAILED</code> after all buffered messages are received. | |
| 99 /// Until buffered message become empty, continues to returns | |
| 100 /// <code>PP_OK</code> as if connection is still established without errors. | |
| 101 int32_t ReceiveMessage(Var* message, | |
| 102 const CompletionCallback& callback); | |
| 103 | |
| 104 /// Send() sends a message to the WebSocket server. | |
| 105 /// | |
| 106 /// @param[in] data A message to send. The message is copied to internal | |
| 107 /// buffer. So caller can free <code>data</code> safely after returning | |
| 108 /// from the function. | |
| 109 /// | |
| 110 /// @return An int32_t containing an error code from | |
| 111 /// <code>pp_errors.h</code>. | |
| 112 /// Returns <code>PP_ERROR_FAILED</code> if the ReadyState is | |
| 113 /// <code>PP_WEBSOCKETREADYSTATE_CONNECTING_DEV</code>. It corresponds | |
| 114 /// JavaScript InvalidStateError of the specification. | |
| 115 /// Returns <code>PP_ERROR_BADARGUMENT</code> if provided | |
| 116 /// <code>message</code> of string type contains an invalid character as a | |
| 117 /// UTF-8 string. It corresponds to JavaScript SyntaxError of the | |
| 118 /// specification. | |
| 119 /// Otherwise, returns <code>PP_OK</code>, but it doesn't necessarily mean | |
| 120 /// that the server received the message. | |
| 121 int32_t SendMessage(const Var& message); | |
| 122 | |
| 123 /// GetBufferedAmount() returns the number of bytes of text and binary | |
| 124 /// messages that have been queued for the WebSocket connection to send but | |
| 125 /// have not been transmitted to the network yet. | |
| 126 /// | |
| 127 /// @return Returns the number of bytes. | |
| 128 uint64_t GetBufferedAmount(); | |
| 129 | |
| 130 /// GetCloseCode() returns the connection close code for the WebSocket | |
| 131 /// connection. | |
| 132 /// | |
| 133 /// @return Returns 0 if called before the close code is set. | |
| 134 uint16_t GetCloseCode(); | |
| 135 | |
| 136 /// GetCloseReason() returns the connection close reason for the WebSocket | |
| 137 /// connection. | |
| 138 /// | |
| 139 /// @return Returns a <code>Var</code> of string type. If called before the | |
| 140 /// close reason is set, it contains an empty string. | |
| 141 Var GetCloseReason(); | |
| 142 | |
| 143 /// GetCloseWasClean() returns if the connection was closed cleanly for the | |
| 144 /// specified WebSocket connection. | |
| 145 /// | |
| 146 /// @return Returns <code>false</code> if called before the connection is | |
| 147 /// closed, or called on an invalid resource. Otherwise, returns | |
| 148 /// <code>true</code> if the connection was closed cleanly, or returns | |
| 149 /// <code>false</code> if the connection was closed for abnormal reasons. | |
| 150 bool GetCloseWasClean(); | |
| 151 | |
| 152 /// GetExtensions() returns the extensions selected by the server for the | |
| 153 /// specified WebSocket connection. | |
| 154 /// | |
| 155 /// @return Returns a <code>Var</code> of string type. If called before the | |
| 156 /// connection is established, its data is an empty string. | |
| 157 /// Currently its data is always an empty string. | |
| 158 Var GetExtensions(); | |
| 159 | |
| 160 /// GetProtocol() returns the sub-protocol chosen by the server for the | |
| 161 /// specified WebSocket connection. | |
| 162 /// | |
| 163 /// @return Returns a <code>Var</code> of string type. If called before the | |
| 164 /// connection is established, it contains the empty string. | |
| 165 Var GetProtocol(); | |
| 166 | |
| 167 /// GetReadyState() returns the ready state of the specified WebSocket | |
| 168 /// connection. | |
| 169 /// | |
| 170 /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called | |
| 171 /// before connect() is called. | |
| 172 PP_WebSocketReadyState_Dev GetReadyState(); | |
| 173 | |
| 174 /// GetURL() returns the URL associated with specified WebSocket connection. | |
| 175 /// | |
| 176 /// @return Returns a <code>Var</code> of string type. If called before the | |
| 177 /// connection is established, it contains the empty string. | |
| 178 Var GetURL(); | |
| 179 | |
| 180 /// SetBinaryType() specifies the binary object type for receiving binary | |
| 181 /// frames representation. Receiving text frames are always mapped to | |
| 182 /// <PP_VARTYPE_STRING</code> var regardless of this attribute. | |
| 183 /// This function should be called before Connect() to ensure receiving all | |
| 184 /// incoming binary frames as the specified binary object type. | |
| 185 /// Default type is <code>PP_WEBSOCKETBINARYTYPE_BLOB_DEV</code>. | |
| 186 /// | |
| 187 /// Currently, Blob bindings is not supported in Pepper, so receiving binary | |
| 188 /// type is always ArrayBuffer. To ensure backward compatibility, you must | |
| 189 /// call this function with | |
| 190 /// <code>PP_WEBSOCKETBINARYTYPE_ARRAYBUFFER_DEV</code> to use binary frames. | |
| 191 /// | |
| 192 /// @param[in] binary_type Binary object type for receiving binary frames | |
| 193 /// representation. | |
| 194 /// | |
| 195 /// @return Returns <code>false</code> if the specified type is not | |
| 196 /// supported. Otherwise, returns <code>true</code>. | |
| 197 /// | |
| 198 bool SetBinaryType(PP_WebSocketBinaryType_Dev binary_type); | |
| 199 | |
| 200 /// GetBinaryType() returns the currently specified binary object type for | |
| 201 /// receiving binary frames. | |
| 202 /// | |
| 203 /// @return Returns <code>PP_WebSocketBinaryType_Dev</code> represents the | |
| 204 /// current binary object type. | |
| 205 PP_WebSocketBinaryType_Dev GetBinaryType(); | |
| 206 }; | |
| 207 | |
| 208 } // namespace pp | |
| 209 | |
| 210 #endif // PPAPI_CPP_DEV_WEBSOCKET_DEV_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 9192009:
WebSocket Pepper API: make the API out of dev (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src