ppapi: PPB_VpnProvider: Define API

ppapi/api/ppb_vpn_provider.idl

+/* 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.
+ */
+
+/**
+ * This file defines the <code>PPB_VpnProvider</code> interface.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  [channel=dev] M44 = 0.1
+};
+
+/**
+ * This enumeration is used by the VPN client to inform the platform of its
+ * current state. This helps provide meaningful messages to the user.
+ */
+[assert_size(4)]
+enum PP_VpnProvider_VpnConnectionState {

[bbudge, 2016/02/24 19:34:21]

nit: PP_VpnProvider_ConnectionState to match enum values, and the other enums.

[adrian.belgun, 2016/03/09 11:07:07]

Done.

+  // Only for compatibility with the JS API

[bbudge, 2016/02/24 19:34:22]

Follow the existing commenting style for enums:
https://code.google.com/p/chromium/codesearch#chromium/src/ppapi/api/pp_file_...

[adrian.belgun, 2016/03/09 11:07:07]

Done.

+  PP_VPN_PROVIDER_CONNECTION_STATE_NONE,

[bbudge, 2016/02/24 19:34:22]

Pepper convention is to explicitly assign the value here. This isn't a normal
enum but an API contract, and we must ensure that actual enum values never
change. 

Also, enum value convention is all caps PP_<api>_<name> E.g.
  PP_VPNPROVIDER_CONNECTIONSTATENONE = 0,

[adrian.belgun, 2016/03/09 11:07:07]

Done.

+  // VPN connection was successful.
+  PP_VPN_PROVIDER_CONNECTION_STATE_CONNECTED,
+  // VPN connection failed.
+  PP_VPN_PROVIDER_CONNECTION_STATE_FAILURE,
+  PP_VPN_PROVIDER_CONNECTION_STATE_LAST = PP_VPN_PROVIDER_CONNECTION_STATE_FAILURE

[bbudge, 2016/02/24 19:34:21]

We don't usually provide a _LAST or _MAX value, since this enum is an API
contract. There are a few exceptions but the reason why this is bad is if a
value is added in a new version of the API (it happens!) then the numeric value
of the _LAST value will change, which may break a client that for some reason is
using this.

[adrian.belgun, 2016/03/09 11:07:07]

Done.

+};
+
+/**
+ * This enumeration is used by the platform to notify the client of the VPN
+ * session status.
+ */
+[assert_size(4)]
+enum PP_VpnProvider_PlatformMessage {
+  // Only for compatibility with the JS API
+  PP_VPN_PROVIDER_PLATFORM_MESSAGE_NONE,
+  // VPN configuration connected.
+  PP_VPN_PROVIDER_PLATFORM_MESSAGE_CONNECTED,
+  // VPN configuration disconnected.
+  PP_VPN_PROVIDER_PLATFORM_MESSAGE_DISCONNECTED,
+  // An error occurred in VPN connection, for example a timeout. A description
+  // of the error is give as the  error argument to
+  // <code>GetPlatformMessage</code>.
+  PP_VPN_PROVIDER_PLATFORM_MESSAGE_ERROR,
+  PP_VPN_PROVIDER_PLATFORM_MESSAGE_LAST = PP_VPN_PROVIDER_PLATFORM_MESSAGE_ERROR
+};
+
+/**
+ * This enumeration is used by the platform to notify the client of the VPN
+ * configuration status.
+ */
+[assert_size(4)]
+enum PP_VpnProvider_ConfigMessage {
+  // Only for compatibility with the JS API
+  PP_VPN_PROVIDER_CONFIG_NONE,
+  // VPN configuration created by the platform.
+  PP_VPN_PROVIDER_CONFIG_CREATED,
+  // VPN configuration removed by the platform.
+  PP_VPN_PROVIDER_CONFIG_REMOVED,
+  PP_VPN_PROVIDER_CONFIG_LAST = PP_VPN_PROVIDER_CONFIG_REMOVED
+};
+
+/**
+ * This enumeration is used by the platform to notify the client of the UI event
+ * type.
+ */
+[assert_size(4)]
+enum PP_VpnProvider_UIEvent {
+  // Only for compatibility with the JS API
+  PP_VPN_PROVIDER_UI_EVENT_NONE,
+  // Request the VPN client to show add configuration dialog to the user.
+  PP_VPN_PROVIDER_UI_EVENT_SHOWADDDIALOG,
+  // Request the VPN client to show configuration settings dialog to the user.
+  PP_VPN_PROVIDER_UI_EVENT_SHOWCONFIGUREDIALOG,
+  PP_VPN_PROVIDER_UI_EVENT_LAST = PP_VPN_PROVIDER_UI_EVENT_SHOWCONFIGUREDIALOG
+};
+
+/**
+ * Use the <code>PPB_VpnProvider</code> interface to implement a VPN client.
+ * Important: This API is available only on Chrome OS.
+ *
+ * VPN Provider interface:
+ *
+ * Typical usage:
+ * - Create VPN configurations using the
+ *   <code>PPB_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>PPB_VpnProvider.GetPlatformMessage()</code>,
+ *   <code>PPB_VpnProvider.GetPacket()</code>,
+ *   <code>PPB_VpnProvider.GetConfigMessage()</code> and
+ *   <code>PPB_VpnProvider.GetUIMessage()</code>.
+ * - When the user connects to the VPN configuration, the
+ *   <code>PPB_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>PPB_VpnProvider.SetParameters()</code> .
+ * - Notify the connection state as
+ *   <code>PP_VPN_PROVIDER_CONNECTION_STATE_CONNECTED</code> using 
+ *   <code>PPB_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>PPB_VpnProvider.SendPacket()</code> and any packets
+ *   originating on the Chrome OS device will be received using the callback of
+ *   <code>PPB_VpnProvider.GetPacket()</code>.
+ * - When the user disconnects from the VPN configuration, the
+ *   <code>PPB_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>PPB_VpnProvider.DestroyConfig()</code>
+ */
+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 WebSocket if

[bbudge, 2016/02/24 19:34:22]

WebSocket -> VpnProvider

[adrian.belgun, 2016/03/09 11:07:07]

Done.

+   * successful.
+   */
+  PP_Resource Create( [in] PP_Instance instance );

[bbudge, 2016/02/24 19:34:22]

nit: eliminate excess spaces (Chromium style convention)

[adrian.belgun, 2016/03/09 11:07:07]

Done.

+
+  /**
+   * 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 );
+
+  /**
+   * CreateConfig() creates a new VPN configuration that persists across
+   * multiple login sessions of the user.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[in] name A <code>PP_Var</code> representing the name of the VPN
+   * configuration. The <code>PP_VarType</code> must be
+   * <code>PP_VARTYPE_STRING</code>.
+   *
+   * @param[out] id A unique ID for the created configuration. The ID is copied
+   * to provided <code>id</code>. The <code>id</code> must remain valid
+   * until CreateConfig() completes. Its received <code>PP_VarType</code>
+   * will be <code>PP_VARTYPE_STRING</code> if a configuration was created,
+   * otherwise it will be <code>PP_VARTYPE_UNDEFINED</code>
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when CreateConfig() completes.</code>.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
+  int32_t CreateConfig(
+    [in]  PP_Resource vpn_provider,
+    [in]  PP_Var name,
+    [out] PP_Var id,
+    [in]  PP_CompletionCallback callback );
+
+  /**
+   * DestroyConfig() destroys a VPN configuration created using this API.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[in] name A <code>PP_Var</code> representing the ID of the VPN
+   * configuration to destroy. The <code>PP_VarType</code> must be
+   * <code>PP_VARTYPE_STRING</code>.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when CreateConfig() completes.</code>.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
+   int32_t DestroyConfig(
+    [in] PP_Resource vpn_provider,
+    [in] PP_Var id,
+    [in] PP_CompletionCallback callback );
+
+  /**
+   * SetParameters() 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 A <code>PP_VARTYPE_STRING</code> corresponding to the
+   * IP address for the VPN interface in CIDR notation. IPv4 is currently the
+   * only supported mode.
+   *
+   * @param[in] broadcast_address A <code>PP_VARTYPE_STRING</code> corresponding
+   * to the broadcast address for the VPN interface. Default: deduced from IP
+   * address and mask.
+   *
+   * @param[in] mtu A <code>int32_t</code> corresponding to the MTU setting for
+   * the VPN interface. Default: 1500 bytes.
+
+   * @param[in] exclusion_list A <code>PP_VARTYPE_ARRAY</code> of
+   * <code>PP_VARTYPE_STRING</code>. 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 A <code>PP_VARTYPE_ARRAY</code> of
+   * <code>PP_VARTYPE_STRING</code>. 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 <code>PP_VARTYPE_ARRAY</code> of
+   * <code>PP_VARTYPE_STRING</code> corresponding to a list of search domains.
+   * Default: no search domain.
+   *
+   * @param[in] dns_servers A <code>PP_VARTYPE_ARRAY</code> of
+   * <code>PP_VARTYPE_STRING</code> values corresponding to a list of IPs for
+   * the DNS servers.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when SetParameters() completes.
+   */
+  int32_t SetParameters(

[bbudge, 2016/02/24 19:34:21]

Another approach is to have a SetOption(resource, option, value) function, with
an enum to specify which option is being set and a PP_Var holding the value.
This will version much more cleanly than a function with lots of parameters when
you need to (inevitably) add another parameter. See PPB_TCP_Socket or
PPB_UDP_Socket for good examples of SetOption.

[adrian.belgun, 2016/03/09 11:07:07]

Done.

Ended up with a SetParameter / CommitParameters combo because all parameters
must be setup at the same time in the underlying layer. Since some parameters
are optional, the user needs to explicitly commit them.

+    [in] PP_Resource vpn_provider,
+    [in] PP_Var address,
+    [in] PP_Var broadcast_address,
+    [in] int32_t mtu,
+    [in] PP_Var exclusion_list,
+    [in] PP_Var inclusion_list,
+    [in] PP_Var domain_search,
+    [in] PP_Var dns_servers,
+    [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.
+   */
+  int32_t SendPacket(
+    [in] PP_Resource vpn_provider,
+    [in] PP_Var packet );

[bbudge, 2016/02/24 19:34:21]

There must be some way (such as a callback) to throttle the plugin unless you
can have unlimited numbers of sent packets in-flight. In general this isn't
possible, since this must involve sending an IPC message to the browser, which
implies that the data must be copied into a message which is held until it can
be sent.

[adrian.belgun, 2016/03/09 11:07:07]

Done.

After adding the callback, the performance of this API was impacted due to
limiting to one the number of packets in flight. A packet queue could be added
to the resource in a further patch set to quickly release the callback. This
commit is only to further the discussion on the IDL. 

+
+  /**
+   * NotifyConnectionStateChanged() notifies the VPN session state to the
+   * platform. 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] status A <code>PP_VpnProvider_VpnConnectionState</code>
+   * corresponding to the VPN session state of the VPN client.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when NotifyConnectionStateChanged() completes.</code>.
+   */
+  int32_t NotifyConnectionStateChanged(
+    [in] PP_Resource vpn_provider,
+    [in] PP_VpnProvider_VpnConnectionState status,
+    [in] PP_CompletionCallback callback );
+
+  /**
+   * GetPacket() 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 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.</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 GetPacket(
+    [in]  PP_Resource vpn_provider,
+    [out] PP_Var packet,
+    [in]  PP_CompletionCallback callback );
+
+/**
+   * GetPlatformMessage() 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] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[out] message A platform message. The message  is copied to the
+   * provided <code>message</code>. The <code>message</code> must remain valid
+   * until GetPlatformMessage() completes. Its received <code>PP_VarType</code>
+   * will be <code>PP_VARTYPE_DICTIONARY</code>. Its key value pairs must be
+   * interpreted as:
+   * - "id": ID of the configuration the message is intended for. Its received
+   *   <code>PP_VarType</code> will be <code>PP_VARTYPE_STRING</code>.
+   * - "message": The message type received from the platform. Its received
+   *   <code>PP_VarType</code> will be <code>PP_VARTYPE_INT32</code> and must
+   *   interpreted as a value in <code>PP_VpnProvider_PlatformMessage</code>.
+   * - "error": Error message when there is an error. Its received
+   *   <code>PP_VarType</code> will be <code>PP_VARTYPE_STRING</code>.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when GetPlatformMessage() completes.</code>.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * If an error is detected, GetPlatformMessage() returns
+   * <code>PP_ERROR_FAILED</code> after all buffered messages are received.
+   * Until buffered messages become empty, GetPlatformMessage() continues to
+   * return <code>PP_OK</code> as if connection is still established without
+   * errors.
+   */
+  int32_t GetPlatformMessage(

[bbudge, 2016/02/24 19:34:21]

I think this API could be significantly simpler and easier to use if you
collapse the three message enums and request functions into a single message
enum and a single GetMessage function.

[adrian.belgun, 2016/03/09 11:07:07]

Done.

+    [in]  PP_Resource vpn_provider,
+    [out] PP_Var message,
+    [in]  PP_CompletionCallback callback );
+
+/**
+   * GetConfigMessage() 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] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[out] message A configuration message. The message  is copied to the
+   * provided <code>message</code>. The <code>message</code> must remain valid
+   * until GetConfigMessage() completes. Its received <code>PP_VarType</code>
+   * will be <code>PP_VARTYPE_DICTIONARY</code>. Its key value pairs must be
+   * interpreted as:
+   * - "id": ID of the configuration the message is intended for. Its received
+   *   <code>PP_VarType</code> will be <code>PP_VARTYPE_STRING</code>.
+   * - "message": The message type received from the platform. Its received
+   *   <code>PP_VarType</code> will be <code>PP_VARTYPE_INT32</code> and must
+   *   interpreted as a value in <code>PP_VpnProvider_ConfigMessage</code>.
+   * - "name": Name of the configuration created. Its received
+   *   <code>PP_VarType</code> will be <code>PP_VARTYPE_STRING</code> if a
+   *   configuration was created, otherwise it will be
+   *   <code>PP_VARTYPE_UNDEFINED</code>.
+   * - "data": Configuration data provided by the administrator.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when GetConfigMessage() completes.</code>.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * If an error is detected, GetConfigMessage() returns
+   * <code>PP_ERROR_FAILED</code> after all buffered messages are received.
+   * Until buffered messages become empty, GetConfigMessage() continues to
+   * return <code>PP_OK</code> as if connection is still established without
+   * errors.
+   */
+  int32_t GetConfigMessage(
+    [in]  PP_Resource vpn_provider,
+    [out] PP_Var message,
+    [in]  PP_CompletionCallback callback );
+
+/**
+   * GetUIMessage() 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] vpn_provider A <code>PP_Resource</code> corresponding to a
+   * VpnProvider.
+   *
+   * @param[out] message A configuration message. The message  is copied to the
+   * provided <code>message</code>. The <code>message</code> must remain valid
+   * until GetConfigMessage() completes. Its received <code>PP_VarType</code>
+   * will be <code>PP_VARTYPE_DICTIONARY</code>. Its key value pairs must be
+   * interpreted as:
+   * - "event": The UI event that is triggered. Its received
+   *   <code>PP_VarType</code> will be <code>PP_VARTYPE_INT32</code> and must
+   *   interpreted as a value in <code>PP_VpnProvider_UIEvent</code>.
+   * - "id": ID of the configuration the message is intended for. Its received
+   *   <code>PP_VarType</code> will be <code>PP_VARTYPE_STRING</code>.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> called
+   * when GetUIMessage() completes.</code>.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * If an error is detected, GetUIMessage() returns
+   * <code>PP_ERROR_FAILED</code> after all buffered messages are received.
+   * Until buffered messages become empty, GetUIMessage() continues to
+   * return <code>PP_OK</code> as if connection is still established without
+   * errors.
+   */
+  int32_t GetUIMessage(
+    [in]  PP_Resource vpn_provider,
+    [out] PP_Var message,
+    [in]  PP_CompletionCallback callback );
+};