ppapi: PPB_VpnProvider: Define API

ppapi/cpp/vpn_provider.h

+// Copyright 2016 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_VPN_PROVIDER_H_
+#define PPAPI_CPP_VPN_PROVIDER_H_
+
+#include <string>
+
+#include "ppapi/c/ppb_vpn_provider.h"
+#include "ppapi/cpp/completion_callback.h"
+
+namespace pp {
+
+class InstanceHandle;
+
+/// @file
+/// This file defines the VpnProvider interface providing a way to implement a
+/// VPN client.
+/// Important: This API is available only on Chrome OS.
+
+/// The <code>VpnProvider</code> class enhances the
+/// <code>chrome.vpnProvider</code> JavaScript API by providing a high
+/// performance path for packet handling.
+///
+/// Permissions: Apps permission <code>vpnProvider</code> is required for
+/// <code>VpnProvider.Bind()</code>.
+///
+/// Typical usage:
+/// - Create a <code>VpnProvider</code> instance.
+/// - Register callbacks via <code>VpnProvider.GetUnbindEvent()</code> and
+///   <code>VpnProvider.ReceivePacket()</code>.
+/// - In the extension follow the usual workflow for configuring a VPN
+///   connection via the <code>chrome.vpnProvider</code> API until the step for
+///   notifying the connection state as "connected".
+/// - Bind to the previously created connection using
+///   <code>VpnProvider.Bind()</code>.
+/// - Notify the connection state as "connected" from JavaScript using
+///   <code>chrome.vpnProvider.notifyConnectionStateChanged</code>.
+/// - When the steps above are completed without errors, a virtual tunnel is
+///   created to the network stack of Chrome OS. IP packets can be sent through
+///   the tunnel using <code>VpnProvider.SendPacket()</code> and any packets
+///   originating on the Chrome OS device will be received using the callback
+///   registered for <code>VpnProvider.ReceivePacket()</code>.
+/// - When the user disconnects from the VPN configuration or there is an error
+///   the callback registered using <code>VpnProvider.GetUnbindEvent()</code>
+///   will be called.
+class VpnProvider : public Resource {
+ public:
+  /// Constructs a VpnProvider object.
+  ///
+  /// @param[in] instance The instance with which this resource will be
+  /// associated.
+  explicit VpnProvider(const InstanceHandle& instance);
+
+  /// Destructs a VpnProvider object.
+  virtual ~VpnProvider();
+
+  /// Static function for determining whether the browser supports the
+  /// <code>VpnProvider</code> interface.
+  ///
+  /// @return true if the interface is available, false otherwise.
+  static bool IsAvailable();
+
+  /// Binds to an existing configuration created from JavaScript by
+  /// <code>chrome.vpnProvider.createConfig</code>. All packets will be routed
+  /// via <code>SendPacket</code> and <code>ReceivePacket</code>. The user
+  /// should register callbacks via <code>GetUnbindEvent</code> and
+  /// <code>ReceivePacket</code> before calling <code>Bind()</code>.
+  ///
+  /// @param[in] configuration_id The configuration id from the callback of
+  /// <code>chrome.vpnProvider.createConfig</code>. This <code>Var</code> must
+  /// be of string type.
+  ///
+  /// @param[in] configuration_name The configuration name as defined by the
+  /// user when calling <code>chrome.vpnProvider.createConfig</code>. This
+  /// <code>Var</code> must be of string type.
+  ///
+  /// @param[in] callback A <code>CompletionCallback</code> to be called on
+  /// completion.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
+  /// Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to
+  /// <code>Bind()</code> has not completed.
+  /// Returns <code>PP_ERROR_BADARGUMENT</code> if the <code>Var</code> type of
+  /// either <code>configuration_id</code> or <code>configuration_name</code> is
+  /// not of string type.
+  /// Returns <code>PP_ERROR_NOACCESS</code> if the caller does the have the
+  /// required "vpnProvider" permission.
+  /// Returns <code>PP_ERROR_FAILED</code> if <code>connection_id</code> and
+  /// <code>connection_name</code> could not be matched with the existing
+  /// connection, or if the plugin originates from a different extension than
+  /// the one that created the connection.
+  int32_t Bind(const Var& configuration_id,
+               const Var& configuration_name,
+               const CompletionCallback& callback);
+
+  /// Registers a callback that will be called when the current configuration
+  /// gets unbound. The callback should be registered before calling
+  /// <code>Bind()</code>.
+  ///
+  /// @param[in] callback A <code>CompletionCallback</code> called when the
+  /// current configuration gets unbound.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
+  /// Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to
+  /// <code>GetUnbindEvent()</code> has not completed.
+  int32_t GetUnbindEvent(const CompletionCallback& callback);
+
+  /// Sends an IP packet through the tunnel created for the VPN session. This
+  /// will succeed only when the VPN session is owned by the module and
+  /// connection is bound.
+  ///
+  /// @param[in] packet IP packet to be sent to the platform. The
+  /// <code>Var</code> must be of ArrayBuffer type.
+  ///
+  /// @param[in] callback A <code>CompletionCallback</code> to be called on
+  /// completion.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
+  /// Returns <code>PP_ERROR_FAILED</code> if the connection is not bound.
+  /// Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to
+  /// <code>SendPacket()</code> has not completed.
+  /// Returns <code>PP_ERROR_BADARGUMENT</code> if the <code>Var</code> type of
+  /// <code>packet</code> is not of ArrayBuffer type.
+  int32_t SendPacket(const Var& packet, const CompletionCallback& callback);
+
+  /// Receives an IP packet from the tunnel for the VPN session. This function
+  /// only returns a single packet. That is, this function must be called at
+  /// least N times to receive N packets, no matter the size of each packet. The
+  /// callback should be registered before calling <code>Bind()</code>.
+  ///
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
+  /// called upon completion of ReceivePacket. It will be passed an ArrayBuffer
+  /// type <code>Var</code> containing an IP packet to be sent to the platform.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
+  /// Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to
+  /// <code>ReceivePacket()</code> has not completed.
+  int32_t ReceivePacket(const CompletionCallbackWithOutput<Var>& callback);
+
+ private:
+  InstanceHandle associated_instance_;
+};
+
+}  // namespace pp
+
+#endif  // PPAPI_CPP_VPN_PROVIDER_H_