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
10label Chrome {
11  M29 = 1.0
12};
13
14/**
15 * Network address family types.
16 */
17[assert_size(4)]
18enum 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)]
37struct 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)]
52struct 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 */
67interface 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};
170