ppapi/cpp/websocket.h

   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_