| // 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 the callback for <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 extension will be notfied via |
| /// <code>chrome.vpnProvider.onPlatformMessage</code>. |
| 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 the callback for <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); |
| |
| /// 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_ |