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] M52 = 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 configuration created by
+   * <code>chrome.vpnProvider.createConfig</code>. All packets will be routed
+   * via <code>SendPacket</code> and <code>ReceivePacket</code>.
+   *
+   * @param[in] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[in] configuration_id A <code>PP_VARTYPE_STRING</code> representing
+   * the configuration id from the callback of
+   * <code>chrome.vpnProvider.createConfig</code>.
+   *
+   * @param[in] configuration_name A <code>PP_VARTYPE_STRING</code> representing
+   * the configuration name as defined by the user when calling
+   * <code>chrome.vpnProvider.createConfig</code>.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called when
+   * the configuration 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>.

[bbudge, 2016/04/26 18:25:21]

Comment seems to be from IsVpnProvider.

It's helpful to detail some of the possible error codes and their causes here if
possible.

[adrian.belgun, 2016/04/27 14:55:20]

Acknowledged.

+   *
+   */
+  int32_t Bind([in] PP_Resource vpn_provider,
+               [in] PP_Var configuration_id,
+               [in] PP_Var configuration_name,
+               [in] PP_CompletionCallback callback);

[bbudge, 2016/04/26 18:25:20]

nit: blank line

[adrian.belgun, 2016/04/27 14:55:20]

Done.

+  /**
+   * GetUnBindEvent() registers a callback that will be called when the current
+   * configuration gets unbound.

[bbudge, 2016/04/26 18:25:20]

Is it OK to call this before calling Bind? More documentation of behavior would
be helpful here.

[adrian.belgun, 2016/05/04 13:38:45]

Done.

+   *
+   * @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 configuration gets unbound.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
+  int32_t GetUnBindEvent([in]  PP_Resource vpn_provider,

[bbudge, 2016/04/26 18:25:20]

s/UnBind/Unbind

Here and everywhere else in this file.

[adrian.belgun, 2016/04/27 14:55:20]

Done.

+                         [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.

[bbudge, 2016/04/26 18:25:20]

I'm guessing Bind() must have completed successfully first. It should be
documented here.

Also, can more than one Send be in-flight? In other words, will a call to
SendPacket before completion cause PP_ERROR_INPROGRESS?

[adrian.belgun, 2016/05/04 13:38:44]

Done.

+   *
+   * @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>.
+   */
+  int32_t SendPacket([in] PP_Resource vpn_provider,
+                     [in] PP_Var packet,
+                     [in] PP_CompletionCallback callback);
+
+  /**
+   * ReceivePacket() receives an IP packet from the tunnel for the VPN session.
+   * This interface only returns a single packet. That is, this interface must

[bbudge, 2016/04/26 18:25:20]

s/interface/function

[adrian.belgun, 2016/04/27 14:55:20]

Done.

+   * be called at least N times to receive N packet, no matter the size of

[bbudge, 2016/04/26 18:25:20]

s/packet/packets

[adrian.belgun, 2016/04/27 14:55:20]

Done.

+   * each packet.

[bbudge, 2016/04/26 18:25:21]

Same comments as SendPacket regarding behavior.

[adrian.belgun, 2016/05/04 13:38:44]

Done.

+   *
+   * @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

[bbudge, 2016/04/26 18:25:21]

nit: delete 'The' since you're referring to the function parameter.

[adrian.belgun, 2016/04/27 14:55:20]

Done.

+   * ReceivePacket() 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 ReceivePacket() completes.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * If an error is detected or connection is closed, ReceivePacket() returns
+   * <code>PP_ERROR_FAILED</code> after all buffered messages are received.
+   * Until buffered packets become empty, ReceivePacket() continues to return
+   * <code>PP_OK</code> as if connection is still established without errors.

[bbudge, 2016/04/26 18:25:21]

Is this by design? Why not just abort all pending calls?

[adrian.belgun, 2016/05/04 13:38:44]

Done.

+   */
+  int32_t ReceivePacket([in]  PP_Resource vpn_provider,
+                        [out] PP_Var packet,
+                        [in]  PP_CompletionCallback callback);
+};