ppapi: PPB_VpnProvider: Define API

ppapi/api/ppb_vpn_provider.idl

+/* 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.
+ */
+
+/**
+ * This file defines the <code>PPB_VpnProvider</code> interface.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  [channel=dev] M51 = 0.1
+};
+
+/**
+ * Use the <code>PPB_VpnProvider</code> interface to implement a VPN client.
+ * Important: This API is available only on Chrome OS.
+ */
+interface PPB_VpnProvider {
+  /**
+   * Create() creates a VpnProvider instance.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying the instance
+   * with the VpnProvider.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a VpnProvider if
+   * successful.
+   */
+  PP_Resource Create([in] PP_Instance instance);
+
+  /**
+   * IsVpnProvider() determines if the provided <code>resource</code> is a
+   * VpnProvider instance.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a
+   * <code>PPB_VpnProvider</code>, <code>PP_FALSE</code> if the
+   * <code>resource</code> is invalid or some type other than
+   * <code>PPB_VpnProvider</code>.
+   */
+  PP_Bool IsVpnProvider([in] PP_Resource resource);
+
+  /**
+   * Bind() binds to an existing connection created by
+   * <code>chrome.vpnProvider.createConfig</code>. All packets will be routed
+   * via <code>SendPacket</code> and <code>GetPacket</code> in the Native 
+   * Client API.
+   *
+   * @param[in] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[in] name A <code>PP_VARTYPE_STRING</code> representing the
+   * connection name as defined by the user when calling
+   * <code>chrome.vpnProvider.createConfig</code>.
+   *
+   * @param[in] id A <code>PP_VARTYPE_STRING</code> representing the connection
+   * id from the callback of <code>chrome.vpnProvider.createConfig</code>.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called when
+   * the connection gets bound.
+   *
+   * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a
+   * <code>PPB_VpnProvider</code>, <code>PP_FALSE</code> if the
+   * <code>resource</code> is invalid or some type other than
+   * <code>PPB_VpnProvider</code>.
+   *
+   */
+  int32_t Bind([in] PP_Resource vpn_provider,
+               [in] PP_Var name,
+               [in] PP_Var id,
+               [in] PP_CompletionCallback callback);
+  /**
+   * GetUnBindEvent() registers a callback that will be called when the current
+   * connection gets unbound.
+   *
+   * @param[in] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called when
+   * the current connection gets unbound.
+   *
+   * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a
+   * <code>PPB_VpnProvider</code>, <code>PP_FALSE</code> if the
+   * <code>resource</code> is invalid or some type other than
+   * <code>PPB_VpnProvider</code>.
+   *
+   */
+  int32_t GetUnBindEvent([in] PP_Resource vpn_provider,
+                         [in] PP_CompletionCallback callback);
+
+
+  /**
+   * SendPacket() 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] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[in] packet A <code>PP_VARTYPE_ARRAY_BUFFER</code> corresponding to
+   * an IP packet to be sent to the platform.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code>
+   *
+   * @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 SendPacket([in] PP_Resource vpn_provider,
+                     [in] PP_Var packet,
+                     [in] PP_CompletionCallback callback);
+
+  /**
+   * SendPacket() sends an IP packet through the tunnel created for the VPN

[bbudge, 2016/03/22 22:38:33]

Looks like a duplicate of above.

[adrian.belgun, 2016/03/29 15:45:44]

Done.

+   * session. This will succeed only when the VPN session is owned by the
+   * module.
+   *
+   * @param[in] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[in] packet A <code>PP_VARTYPE_ARRAY_BUFFER</code> corresponding to
+   * an IP packet to be sent to the platform.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when SendPacket() completes.
+   *
+   * @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 SendPacket([in] PP_Resource vpn_provider,
+                     [in] PP_Var packet,
+                     [in] PP_CompletionCallback callback);
+
+  /**
+   * GetPacket() receives an IP packet from the tunnel for the VPN session.

[bbudge, 2016/03/22 22:38:33]

ReceivePacket?  (Send / Receive, or Put / Get)

[adrian.belgun, 2016/03/29 15:45:44]

Done.

+   * This interface only returns a single packet. That is, this interface must
+   * be called at least N times to receive N packet, no matter the size of
+   * each packet.
+   *
+   * @param[in] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[out] packet The received packet is copied to provided
+   * <code>packet</code>. The <code>packet</code> must remain valid until
+   * GetPacket() completes. Its received <code>PP_VarType</code> will be
+   * <code>PP_VARTYPE_ARRAY_BUFFER</code>.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when GetPacket() completes.
+   *
+   * @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([in]  PP_Resource vpn_provider,
+                    [out] PP_Var packet,
+                    [in]  PP_CompletionCallback callback);
+};
+