ppapi/utility/websocket/websocket_api.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_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_