ppapi: PPB_VpnProvider: Define API

ppapi/cpp/vpn_provider.h

+// Copyright 2015 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.
+///
+/// Typical usage:
+/// - Create VPN configurations using the
+///   <code>VpnProvider.CreateConfig()</code> method. A VPN configuration is
+///   a persistent entry shown to the user in a native Chrome OS UI. The user
+///   can select a VPN configuration from a list and connect to it or disconnect
+///   from it.
+/// - Register callbacks to the events via
+///   <code>VpnProvider.GetPlatformMessage()</code>,
+///   <code>VpnProvider.GetPacket()</code>,
+///   <code>VpnProvider.GetConfigMessage()</code> and
+///   <code>VpnProvider.GetUIMessage()</code>.
+/// - When the user connects to the VPN configuration, the
+///   <code>VpnProvider.GetPlatformMessage()</code> callback will be called with
+///   the message <code>PP_VPN_PROVIDER_PLATFORM_MESSAGE_CONNECTED</code>.
+///   We refer to the period between the messages
+///   <code>PP_VPN_PROVIDER_PLATFORM_MESSAGE_CONNECTED</code> and
+///   <code>PP_VPN_PROVIDER_PLATFORM_MESSAGE_DISCONNECTED</code> as a VPN
+///   session. In this time period, the module that receives the message is said
+///   to own the VPN session.
+/// - You will need to re-register the callbacks after they are called.
+/// - Initiate connection to the VPN server and start the VPN client.
+/// - Set the Parameters of the connection using
+///   <code>VpnProvider.SetParameters()</code> .
+/// - Notify the connection state as
+///   <code>PP_VPN_PROVIDER_CONNECTION_STATE_CONNECTED</code> using
+///   <code>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 of
+///   <code>VpnProvider.GetPacket()</code>.
+/// - When the user disconnects from the VPN configuration, the
+///   <code>VpnProvider.GetPlatformMessage()</code> callback will be fired
+///   with the message <code>PP_VPN_PROVIDER_PLATFORM_MESSAGE_DISCONNECTED
+///   </code>.
+/// - If the VPN configuration is no longer necessary, it can be destroyed using
+///   <code>VpnProvider.DestroyConfig()</code>
+
+/// The <code>VpnProvider</code> class providing a way to implement a VPN
+/// client.
+class VpnProvider : public Resource {
+ public:
+  /// Constructs a VpnProvider object.
+  ///
+  /// @param[in] instance The instance with which this resource will be
+  /// associated.
+  explicit VpnProvider(Instance* instance);
+
+  /// Destructs a WebSocket 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();
+
+  /// Creates a new VPN configuration that persists across multiple login
+  /// sessions of the user.
+  ///
+  /// @param[in] name The name of the VPN configuration.
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
+  /// called upon completion of CreateConfig. It will be passed a string
+  /// <code>Var</code> containing the appropriate ID string for
+  /// <code>name</code>.
+  int32_t CreateConfig(const std::string& name,
+                       const CompletionCallbackWithOutput<Var>& callback);
+
+  /// Destroys a VPN configuration created using this API.
+  ///
+  /// @param[in] name The name of the VPN configuration.
+  /// @param[in] callback A <code>CompletionCallback</code> to be
+  /// called upon completion of DestroyConfig.
+  int32_t DestroyConfig(const std::string& id,
+                        const CompletionCallback& callback);
+
+  /// Sets the parameters for the VPN session. This should be called immediately
+  /// after <code>PP_VPN_PROVIDER_CONNECTION_STATE_CONNECTED</code> is received
+  /// from the platform. This will succeed only when the VPN  session is owned
+  /// by the module.
+  ///
+  /// @param[in] address IP address for the VPN interface in CIDR notation. IPv4
+  /// is currently the only supported mode.
+  /// @param[in] broadcast_address IP address for the VPN interface in CIDR
+  /// notation. IPv4 is currently the only supported mode.
+  /// @param[in] mtu MTU setting for the VPN interface. Default: 1500 bytes.
+  /// @param[in] exclusion_list Exclude network traffic to the list of IP blocks
+  /// in CIDR notation from the tunnel. This can be used to bypass traffic to
+  /// and from the VPN server. When many rules match a destination, the rule
+  /// with the longest matching prefix wins. Entries that correspond to the same
+  /// CIDR block are treated as duplicates. Such duplicates in the collated
+  /// (exclusion_list + inclusion_list) list are eliminated and the exact
+  /// duplicate entry that will be eliminated is undefined.
+  /// @param[in] inclusion_list Include network traffic to the list of IP blocks
+  /// in CIDR notation to the tunnel. This parameter can be used to set up a
+  /// split tunnel. By default no traffic is directed to the tunnel. Adding the
+  /// entry "0.0.0.0/0" to this list gets all the user traffic redirected to the
+  /// tunnel. When many rules match a destination, the rule with the longest
+  /// matching prefix wins. Entries that correspond to the same CIDR block are
+  /// treated as duplicates. Such duplicates in the collated (exclusion_list +
+  /// inclusion_list) list are eliminated and the exact duplicate entry that
+  /// will be eliminated is undefined.
+  /// @param[in] domain_search A list of search domains. Default: no search
+  /// domain.
+  /// @param[in] dns_servers List of IPs for the DNS servers.
+  /// @param[in] callback A <code>CompletionCallback</code> to be
+  /// called upon completion of DestroyConfig.
+  int32_t SetParameters(const std::string& address,
+                        const std::string& broadcast_address,
+                        const int32_t& mtu,
+                        const std::vector<std::string>& exclusion_list,
+                        const std::vector<std::string>& inclusion_list,
+                        const std::vector<std::string>& domain_search,
+                        const std::vector<std::string>& dns_servers,
+                        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.
+  ///
+  /// @param[in] data IP packet to be sent to the platform. Its received
+  /// <code>Var</code> will be of ArrayBuffer type.
+  int32_t SendPacket(const Var& packet);
+
+  /// Notifies the VPN session state to the platform. This will succeed only
+  /// when the VPN session is owned by the module.
+  ///
+  /// @param[in] status VPN session state of the VPN client.
+  /// @param[in] callback A <code>CompletionCallback</code> to be
+  /// called upon completion of NotifyConnectionStateChanged.
+  int32_t NotifyConnectionStateChanged(PP_VpnProvider_VpnConnectionState status,
+                                       const CompletionCallback& callback);
+
+  /// Receives an IP packet from the tunnel for the VPN session.
+  /// This interface only returns a single packet. That is, this interface must
+  /// be called at least N times to receive N packets, no matter the size of
+  /// each packet.
+  ///
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
+  /// called upon completion of GetPacket. 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>.
+  /// If an error is detected or connection is closed, GetPacket() returns
+  /// <code>PP_ERROR_FAILED</code> after all buffered messages are received.
+  /// Until buffered packets become empty, GetPacket() continues to return
+  /// <code>PP_OK</code> as if connection is still established without errors.
+  int32_t GetPacket(const CompletionCallbackWithOutput<Var>& callback);
+
+  /// Receives a platform message from the platform for a VPN configuration.
+  /// This interface only returns a single message. That is, this interface must
+  /// be called at least N times to receive N messages.
+  ///
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
+  /// called upon completion of GetPlatformMessage. It will be passed a
+  /// VarDictionary type <code>Var</code> containing a platform message. Its key
+  /// value pairs must be interpreted as:
+  /// - "id": A string <code>Var</code> containing the ID of the configuration
+  ///   the message is intended for.
+  /// - "message": A int <code>Var</code> containing the message type received
+  ///   from the platform. It must interpreted as a value in
+  ///   <code>PP_VpnProvider_PlatformMessage</code>.
+  /// - "error": A string <code>Var</code> containing the error message when
+  ///   there is an error.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
+  /// If an error is detected or connection is closed, GetPlatformMessage()
+  /// returns <code>PP_ERROR_FAILED</code> after all buffered messages are
+  /// received. Until buffered packets become empty, GetPlatformMessage()
+  /// continues to return <code>PP_OK</code> as if connection is still
+  /// established without errors.
+  int32_t GetPlatformMessage(const CompletionCallbackWithOutput<Var>& callback);
+
+  /// Receives an event from the platform for the creation or destruction of a
+  /// VPN configuration.
+  /// This interface only returns a single message. That is, this interface must
+  /// be called at least N times to receive N messages.
+  ///
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
+  /// called upon completion of GetPlatformMessage. It will be passed a
+  /// VarDictionary type <code>Var</code> containing a platform message. Its key
+  /// value pairs must be interpreted as:
+  /// - "id": A string <code>Var</code> containing the ID of the configuration
+  ///   the message is intended for.
+  /// - "message": A int <code>Var</code> containing the message type received
+  ///   from the platform. It must interpreted as a value in
+  ///   <code>PP_VpnProvider_ConfigMessage</code>.
+  /// - "name": A string <code>Var</code> containing the bame of the
+  ///   configuration created.
+  /// - "data": A <code>Var</code> containing configuration data provided by the
+  ///   administrator.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
+  /// If an error is detected or connection is closed, GetConfigMessage()
+  /// returns <code>PP_ERROR_FAILED</code> after all buffered messages are
+  /// received. Until buffered packets become empty, GetConfigMessage()
+  /// continues to return <code>PP_OK</code> as if connection is still
+  /// established without errors.
+  int32_t GetConfigMessage(const CompletionCallbackWithOutput<Var>& callback);
+
+  /// Receives an UI event for the extension. UI events are signals from the
+  /// platform that indicate to the app that a UI dialog needs to be shown to
+  /// the user.
+  /// This interface only returns a single message. That is, this interface must
+  /// be called at least N times to receive N messages.
+  ///
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
+  /// called upon completion of GetPlatformMessage. It will be passed a
+  /// VarDictionary type <code>Var</code> containing a platform message. Its key
+  /// value pairs must be interpreted as:
+  /// - "event": A int <code>Var</code> containing the event type received
+  ///   from the platform. It must interpreted as a value in
+  ///   <code>PP_VpnProvider_UIEvent</code>.
+  /// - "id": A string <code>Var</code> containing the ID of the configuration
+  ///   the event is intended for.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
+  /// If an error is detected or connection is closed, GetUIMessage() returns
+  /// <code>PP_ERROR_FAILED</code> after all buffered messages are received.
+  /// Until buffered packets become empty, GetUIMessage() continues to return
+  /// <code>PP_OK</code> as if connection is still established without errors.
+  int32_t GetUIMessage(const CompletionCallbackWithOutput<Var>& callback);
+
+ private:
+  InstanceHandle associated_instance_;
+};
+
+}  // namespace pp
+
+#endif  // PPAPI_CPP_VPN_PROVIDER_H_