WebSocket Pepper API: C++ utility class implementation.

ppapi/cpp/helper/dev/websocket_api_dev.h

Index: ppapi/cpp/helper/dev/websocket_api_dev.h
diff --git a/ppapi/cpp/helper/dev/websocket_api_dev.h b/ppapi/cpp/helper/dev/websocket_api_dev.h
new file mode 100644
index 0000000000000000000000000000000000000000..3cbd79202e9e7137aa5617b946d3d1a0f7de6d13
--- /dev/null
+++ b/ppapi/cpp/helper/dev/websocket_api_dev.h
@@ -0,0 +1,130 @@
+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef PPAPI_CPP_HELPER_DEV_WEBSOCKET_API_DEV_H_
+#define PPAPI_CPP_HELPER_DEV_WEBSOCKET_API_DEV_H_
+
+#include "ppapi/c/dev/ppb_websocket_dev.h"
+
+/// @file
+/// This file defines the helper::WebSocketAPI_Dev interface.
+
+namespace pp {
+
+class CompletionCallback;
+class Instance;
+class Var;
+
+namespace helper {
+
+/// The <code>WebSocketAPI_Dev</code> class
+class WebSocketAPI_Dev {
+ public:
+  /// Constructs a WebSocketAPI_Dev object.
+  WebSocketAPI_Dev(Instance* instance);
+
+  /// Destructs a WebSocketAPI_Dev object.
+  virtual ~WebSocketAPI_Dev();
+
+  /// Connect() connects to the specified WebSocket server. Caller can call
+  /// this method at most once.
+  ///
+  /// @param[in] url A <code>Var</code> of string type representing a WebSocket
+  /// server URL.
+  /// @param[in] protocols A pointer to an array of string type
+  /// <code>Var</code> specifying sub-protocols. Each <code>Var</code>
+  /// represents one sub-protocol and its <code>PP_VarType</code> must be
+  /// <code>PP_VARTYPE_STRING</code>. This argument can be null only if
+  /// <code>protocol_count</code> is 0.
+  /// @param[in] protocol_count The number of sub-protocols in
+  /// <code>protocols</code>.
+  ///
+  /// @return An int32_t containing an error code from
+  /// <code>pp_errors.h</code>.
+  /// See also <code>pp::WebSocket_Dev::Connect</code>.
+  int32_t Connect(const Var& url, const Var protocols[],
+                  uint32_t protocol_count);
+
+  /// Close() closes the specified WebSocket connection by specifying
+  /// <code>code</code> and <code>reason</code>.
+  ///
+  /// @param[in] code The WebSocket close code. Ignored if it is 0.
+  /// @param[in] reason A <code>Var</code> of string type which represents the
+  /// WebSocket close reason. Ignored if it is undefined type.
+  ///
+  /// @return An int32_t containing an error code from
+  /// <code>pp_errors.h</code>.
+  /// See also <code>pp::WebSocket_Dev::Close</code>.
+  int32_t Close(uint16_t code, const Var& reason);
+
+  /// Send() sends a message to the WebSocket server.
+  ///
+  /// @param[in] data A message to send. The message is copied to internal
+  /// buffer. So caller can free <code>data</code> safely after returning
+  /// from the function.
+  ///
+  /// @return An int32_t containing an error code from
+  /// <code>pp_errors.h</code>.
+  /// See also <code>pp::WebSocket_Dev::SendMessage</code>.
+  int32_t Send(const Var& data);
+
+  /// GetBufferedAmount() returns the number of bytes of text and binary
+  /// messages that have been queued for the WebSocket connection to send but
+  /// have not been transmitted to the network yet.
+  ///
+  /// @return Returns the number of bytes.
+  uint64_t GetBufferedAmount();
+
+  /// GetExtensions() returns the extensions selected by the server for the
+  /// specified WebSocket connection.
+  ///
+  /// @return Returns a <code>Var</code> of string type. If called before the
+  /// connection is established, its data is empty string.
+  /// Currently its data is always an empty string.
+  Var GetExtensions();
+
+  /// GetProtocol() returns the sub-protocol chosen by the server for the
+  /// specified WebSocket connection.
+  ///
+  /// @return Returns a <code>Var</code> of string type. If called before the
+  /// connection is established, it contains the empty string.
+  Var GetProtocol();
+
+  /// GetReadyState() returns the ready state of the specified WebSocket
+  /// connection.
+  ///
+  /// @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called
+  /// before connect() is called.
+  PP_WebSocketReadyState_Dev GetReadyState();
+
+  /// GetURL() returns the URL associated with specified WebSocket connection.
+  ///
+  /// @return Returns a <code>Var</code> of string type. If called before the
+  /// connection is established, it contains the empty string.
+  Var GetURL();
+
+  /// OnOpen() is invoked when the connection is established by Connect().
+  virtual void OnOpen() = 0;

[brettw, 2011/12/21 18:31:57]

My expectation for this would be that the plugin code would "have" a WebSocket
that would then call you back via some delegate API. Mixing everything together
would force the calling code to make a wrapper object that derives from
WebSocket, which seems a bit weird to me.

If we do this, it may be a good idea to rename the functions with "WebSocket" in
them and pass the calling object (since you could have more than one socket) so
that the caller would look like this:

class MyInstance : public pp::Instance, public pp::WebSocket::Delegate {
  void StartSocket() {
    // Pass in the WebSocket::Delegate to the connection function for it to call
us back.
    my_socket.Connect(this, "http://foo.com", ...);
  }

  virtual void OnWebSocketOpen(WebSocket* socket);
  virtual void OnWebSocketMessage(WebSocket* socket, const Var& message);
  virtual void OnWebSocketClose(WebSocket* socket);

  pp::WebSocket my_socket;
};

Sometimes mapping these concepts into C++ can be challenging because there are
no closures. Please let me know what you think about this.

[Takashi Toyoshima, 2011/12/22 07:56:29]

I had the same delegate idea originally and proposed in IDL discussion.
http://codereview.chromium.org/8395037#msg16

At that time, of course we have no idea on helper classes, and David thought a
delegate approach without reference counting could be a little dangerous in
viewpoint of object life cycle management and I agreed that.
http://codereview.chromium.org/8395037#msg18

Now, I feel I'd like to revive the delegate approach.
Should I add interfaces like AttachEventHandler(Delegate*) and
DetachEventHandler(Delegate*) to avoid invoking deleted delegates? I think
chromium implement disconnect() interface to detach delegate from object
usually.

I guess callback factory will take care now, then detach interface is not
mandatory. Is my understanding right?
In your example, my_socket must be deleted at least MyInstance's destructor.
Then factory could know that my_socket's callback shouldn't be invoked after
that by its destruction. So, delegates also doesn't be invoked. Queued events
will be dispatched after destruction of MyInstance, but CallbackData detects its
disappearance by back pointer then dismiss the event.

+
+  /// OnMessage() is invoked when a message is received.
+  virtual void OnMessage(const Var& message) = 0;
+
+  /// OnError() is invoked if the user agent was required to fail the WebSocket
+  /// connection or the WebSocket connection is closed with prejudice.
+  /// OnClose() always follows OnError().
+  virtual void OnError() = 0;
+
+  /// OnClose() is invoked when the connection is closed by errors or Close().
+  virtual void OnClose(bool wasClean, uint16_t code, const Var& reason) = 0;
+
+ private:
+  class Implement;
+  Implement* impl_;
+};
+
+}  // namespace helper
+
+}  // namespace pp
+
+#endif  // PPAPI_CPP_HELPER_DEV_WEBSOCKET_API_DEV_H_