ppapi/api/ppb_net_address.idl

   1 /* Copyright 2013 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_NetAddress</code> interface.
   8  */
   9
  10 label Chrome {
  11   M29 = 1.0
  12 };
  13
  14 /**
  15  * Network address family types.
  16  */
  17 [assert_size(4)]
  18 enum PP_NetAddress_Family {
  19   /**
  20    * The address family is unspecified.
  21    */
  22   PP_NETADDRESS_FAMILY_UNSPECIFIED = 0,
  23   /**
  24    * The Internet Protocol version 4 (IPv4) address family.
  25    */
  26   PP_NETADDRESS_FAMILY_IPV4 = 1,
  27   /**
  28    * The Internet Protocol version 6 (IPv6) address family.
  29    */
  30   PP_NETADDRESS_FAMILY_IPV6 = 2
  31 };
  32
  33 /**
  34  * All members are expressed in network byte order.
  35  */
  36 [assert_size(6)]
  37 struct PP_NetAddress_IPv4 {
  38   /**
  39    * Port number.
  40    */
  41   uint16_t port;
  42   /**
  43    * IPv4 address.
  44    */
  45   uint8_t[4] addr;
  46 };
  47
  48 /**
  49  * All members are expressed in network byte order.
  50  */
  51 [assert_size(18)]
  52 struct PP_NetAddress_IPv6 {
  53   /**
  54    * Port number.
  55    */
  56   uint16_t port;
  57   /**
  58    * IPv6 address.
  59    */
  60   uint8_t[16] addr;
  61 };
  62
  63 /**
  64  * The <code>PPB_NetAddress</code> interface provides operations on network
  65  * addresses.
  66  */
  67 interface PPB_NetAddress {
  68   /**
  69    * Creates a <code>PPB_NetAddress</code> resource with the specified IPv4
  70    * address.
  71    *
  72    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
  73    * a module.
  74    * @param[in] ipv4_addr An IPv4 address.
  75    *
  76    * @return A <code>PP_Resource</code> representing the same address as
  77    * <code>ipv4_addr</code> or 0 on failure.
  78    */
  79   PP_Resource CreateFromIPv4Address([in] PP_Instance instance,
  80                                     [in] PP_NetAddress_IPv4 ipv4_addr);
  81
  82   /**
  83    * Creates a <code>PPB_NetAddress</code> resource with the specified IPv6
  84    * address.
  85    *
  86    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
  87    * a module.
  88    * @param[in] ipv6_addr An IPv6 address.
  89    *
  90    * @return A <code>PP_Resource</code> representing the same address as
  91    * <code>ipv6_addr</code> or 0 on failure.
  92    */
  93   PP_Resource CreateFromIPv6Address([in] PP_Instance instance,
  94                                     [in] PP_NetAddress_IPv6 ipv6_addr);
  95
  96   /**
  97    * Determines if a given resource is a network address.
  98    *
  99    * @param[in] resource A <code>PP_Resource</code> to check.
 100    *
 101    * @return <code>PP_TRUE</code> if the input is a <code>PPB_NetAddress</code>
 102    * resource; <code>PP_FALSE</code> otherwise.
 103    */
 104   PP_Bool IsNetAddress([in] PP_Resource resource);
 105
 106   /**
 107    * Gets the address family.
 108    *
 109    * @param[in] addr A <code>PP_Resource</code> corresponding to a network
 110    * address.
 111    *
 112    * @return The address family on success;
 113    * <code>PP_NETADDRESS_FAMILY_UNSPECIFIED</code> on failure.
 114    */
 115   PP_NetAddress_Family GetFamily([in] PP_Resource addr);
 116
 117   /**
 118    * Returns a human-readable description of the network address. The
 119    * description is in the form of host [ ":" port ] and conforms to
 120    * http://tools.ietf.org/html/rfc3986#section-3.2 for IPv4 and IPv6 addresses
 121    * (e.g., "192.168.0.1", "192.168.0.1:99", or "[::1]:80").
 122    *
 123    * @param[in] addr A <code>PP_Resource</code> corresponding to a network
 124    * address.
 125    * @param[in] include_port Whether to include the port number in the
 126    * description.
 127    *
 128    * @return A string <code>PP_Var</code> on success; an undefined
 129    * <code>PP_Var</code> on failure.
 130    */
 131   PP_Var DescribeAsString([in] PP_Resource addr,
 132                           [in] PP_Bool include_port);
 133
 134   /**
 135    * Fills a <code>PP_NetAddress_IPv4</code> structure if the network address is
 136    * of <code>PP_NETADDRESS_FAMILY_IPV4</code> address family.
 137    * Note that passing a network address of
 138    * <code>PP_NETADDRESS_FAMILY_IPV6</code> address family will fail even if the
 139    * address is an IPv4-mapped IPv6 address.
 140    *
 141    * @param[in] addr A <code>PP_Resource</code> corresponding to a network
 142    * address.
 143    * @param[out] ipv4_addr A <code>PP_NetAddress_IPv4</code> structure to store
 144    * the result.
 145    *
 146    * @return A <code>PP_Bool</code> value indicating whether the operation
 147    * succeeded.
 148    */
 149   PP_Bool DescribeAsIPv4Address([in] PP_Resource addr,
 150                                 [out] PP_NetAddress_IPv4 ipv4_addr);
 151
 152   /**
 153    * Fills a <code>PP_NetAddress_IPv6</code> structure if the network address is
 154    * of <code>PP_NETADDRESS_FAMILY_IPV6</code> address family.
 155    * Note that passing a network address of
 156    * <code>PP_NETADDRESS_FAMILY_IPV4</code> address family will fail - this
 157    * method doesn't map it to an IPv6 address.
 158    *
 159    * @param[in] addr A <code>PP_Resource</code> corresponding to a network
 160    * address.
 161    * @param[out] ipv6_addr A <code>PP_NetAddress_IPv6</code> structure to store
 162    * the result.
 163    *
 164    * @return A <code>PP_Bool</code> value indicating whether the operation
 165    * succeeded.
 166    */
 167   PP_Bool DescribeAsIPv6Address([in] PP_Resource addr,
 168                                 [out] PP_NetAddress_IPv6 ipv6_addr);
 169 };