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.

[bbudge, 2016/04/27 16:07:14]

nit: called on completion

It's possible that Bind can fail.

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

Done.

+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
+  int32_t Bind([in] PP_Resource vpn_provider,
+               [in] PP_Var configuration_id,
+               [in] PP_Var configuration_name,
+               [in] PP_CompletionCallback callback);
+
+  /**
+   * GetUnbindEvent() registers a callback that will be called when the current
+   * configuration gets unbound.

[bbudge, 2016/04/27 16:07:14]

Can this be called before Bind()?

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

The callback notifies the plugin that an Unbind event occurred (eg. the current
connection got disconnected). It's recommended that all callbacks should be
bound before calling bind to avoid the scenario:
Call Bind -> Bound -> Unbound on host -> Call GetUnbindEvent() -> No event

If called before:
Call GetUnbindEvent() -> Call Bind -> Bound -> Unbound on host -> Receive
GetUnbindEvent() callback

+   *
+   * @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,
+                         [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/27 16:07:13]

Do you mean this will succeed only when the VpnProvider is bound?
Document that call must complete before it can be called again, or that multiple
sends can be in-flight simultaneously).

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

Yes. The connection must be bound. 
As currently implemented, the Resource holds a shared memory buffer that will
cache in flight packets. If there is a spare location, it will return PP_OK and
run the callback immediately, else the callback will run after a packet has been
sent.
Anyway SendPacket must complete before it can be called again.

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

[bbudge, 2016/04/27 16:07:14]

Can this be called before Bind()?
Document that call must complete before it can be called again, or that multiple
receives can be in-flight simultaneously).

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

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
+   * 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/27 16:07:13]

This error / disconnection behavior seems invisible to the plugin. Do you mean
that GetUnbindEvent may callback to the plugin with an error code, and the
plugin may continue to receive packets until the buffers are empty?

If not, I suggest removing this comment, since it is an implementation detail
that is invisible to the plugin.

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

Done.

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