1/* Copyright (c) 2012 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/* From dev/ppb_url_util_dev.idl modified Wed Aug 28 19:09:17 2013. */
7
8#ifndef PPAPI_C_DEV_PPB_URL_UTIL_DEV_H_
9#define PPAPI_C_DEV_PPB_URL_UTIL_DEV_H_
10
11#include "ppapi/c/pp_bool.h"
12#include "ppapi/c/pp_instance.h"
13#include "ppapi/c/pp_macros.h"
14#include "ppapi/c/pp_stdint.h"
15#include "ppapi/c/pp_var.h"
16
17#define PPB_URLUTIL_DEV_INTERFACE_0_6 "PPB_URLUtil(Dev);0.6"
18#define PPB_URLUTIL_DEV_INTERFACE_0_7 "PPB_URLUtil(Dev);0.7"
19#define PPB_URLUTIL_DEV_INTERFACE PPB_URLUTIL_DEV_INTERFACE_0_7
20
21/**
22 * @file
23 * This file defines the <code>PPB_URLUtil_Dev</code> interface.
24 */
25
26
27/**
28 * @addtogroup Structs
29 * @{
30 */
31/*
32 * A component specifies the range of the part of the URL. The begin specifies
33 * the index into the string of the first character of that component. The len
34 * specifies the length of that component.
35 *
36 * This range does not include any special delimiter for that component, so
37 * the scheme doesn't include the trailing colon, the username and password
38 * don't include the @ and :, the port doesn't include the colon, the query
39 * doesn't include the ?, and the ref doesn't include the #.
40 *
41 * The exception is that the path *does* include the first /, since that's an
42 * integral part of the path.
43 *
44 * If the component is not present at all, begin will be 0 and len will be -1.
45 * If the component is present but empty, the length will be 0 instead. Example:
46 *   http://foo/search    -> query = (0, -1)
47 *   http://foo/search?   -> query = (18, 0)
48 */
49struct PP_URLComponent_Dev {
50  int32_t begin;
51  int32_t len;
52};
53PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_URLComponent_Dev, 8);
54
55struct PP_URLComponents_Dev {
56  struct PP_URLComponent_Dev scheme;
57  struct PP_URLComponent_Dev username;
58  struct PP_URLComponent_Dev password;
59  struct PP_URLComponent_Dev host;
60  struct PP_URLComponent_Dev port;
61  struct PP_URLComponent_Dev path;
62  struct PP_URLComponent_Dev query;
63  struct PP_URLComponent_Dev ref;
64};
65PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_URLComponents_Dev, 64);
66/**
67 * @}
68 */
69
70/**
71 * @addtogroup Interfaces
72 * @{
73 */
74/*
75 * URL encoding: URLs are supplied to this interface as NULL-terminated 8-bit
76 * strings. You can pass non-ASCII characters which will be interpreted as
77 * UTF-8. Canonicalized URL strings returned by these functions will be ASCII
78 * except for the reference fragment (stuff after the '#') which will be
79 * encoded as UTF-8.
80 */
81struct PPB_URLUtil_Dev_0_7 {
82  /*
83   * Canonicalizes the given URL string according to the rules of the host
84   * browser. If the URL is invalid or the var is not a string, this will
85   * return a Null var and the components structure will be unchanged.
86   *
87   * The components pointer, if non-NULL and the canonicalized URL is valid,
88   * will identify the components of the resulting URL. Components may be NULL
89   * to specify that no component information is necessary.
90   */
91  struct PP_Var (*Canonicalize)(struct PP_Var url,
92                                struct PP_URLComponents_Dev* components);
93  /*
94   *  Resolves the given URL relative to the given base URL. The resulting URL
95   *  is returned as a string. If the resolution is invalid or either of the
96   *  inputs are not strings, a Null var will be returned. The resulting URL
97   *  will also be canonicalized according to the rules of the browser.
98   *
99   *  Note that the "relative" URL may in fact be absolute, in which case it
100   *  will be returned. This function is identical to resolving the full URL
101   *  for an <a href="..."> on a web page. Attempting to resolve a relative URL
102   *  on a base URL that doesn't support this (e.g. "data") will fail and will
103   *  return a Null var, unless the relative URL is itself absolute.
104   *
105   *  The components pointer, if non-NULL and the canonicalized URL is valid,
106   *  will identify the components of the resulting URL. Components may be NULL
107   *  to specify that no component information is necessary.
108   */
109  struct PP_Var (*ResolveRelativeToURL)(
110      struct PP_Var base_url,
111      struct PP_Var relative_string,
112      struct PP_URLComponents_Dev* components);
113  /*
114   *  Identical to ResolveRelativeToURL except that the base URL is the base
115   *  URL of the document containing the given plugin instance.
116   *
117   *  Danger: This will be identical to resolving a relative URL on the page,
118   *  and might be overridden by the page to something different than its actual
119   *  URL via the <base> tag. Therefore, resolving a relative URL of "" won't
120   *  necessarily give you the URL of the page!
121   */
122  struct PP_Var (*ResolveRelativeToDocument)(
123      PP_Instance instance,
124      struct PP_Var relative_string,
125      struct PP_URLComponents_Dev* components);
126  /*
127   * Checks whether the given two URLs are in the same security origin. Returns
128   * FALSE if either of the URLs are invalid.
129   */
130  PP_Bool (*IsSameSecurityOrigin)(struct PP_Var url_a, struct PP_Var url_b);
131  /*
132   * Checks whether the document hosting the given plugin instance can access
133   * the given URL according to the same origin policy of the browser. Returns
134   * PP_FALSE if the instance or the URL is invalid.
135   */
136  PP_Bool (*DocumentCanRequest)(PP_Instance instance, struct PP_Var url);
137  /*
138   * Checks whether the document containing the |active| plugin instance can
139   * access the document containing the |target| plugin instance according to
140   * the security policy of the browser. This includes the same origin policy
141   * and any cross-origin capabilities enabled by the document. If either of
142   * the plugin instances are invalid, returns PP_FALSE.
143   */
144  PP_Bool (*DocumentCanAccessDocument)(PP_Instance active, PP_Instance target);
145  /*
146   * Returns the URL for the document. This is a safe way to retrieve
147   * window.location.href.
148   * The components pointer, if non-NULL and the canonicalized URL is valid,
149   * will identify the components of the resulting URL. Components may be NULL
150   * to specify that no component information is necessary.
151   */
152  struct PP_Var (*GetDocumentURL)(PP_Instance instance,
153                                  struct PP_URLComponents_Dev* components);
154  /*
155   * Returns the Source URL for the plugin. This returns the URL that would be
156   * streamed to the plugin if it were a NPAPI plugin. This is usually the src
157   * attribute on the <embed> element, but the rules are obscure and different
158   * based on whether the plugin is loaded from an <embed> element or an
159   * <object> element.
160   * The components pointer, if non-NULL and the canonicalized URL is valid,
161   * will identify the components of the resulting URL. Components may be NULL
162   * to specify that no component information is necessary.
163   */
164  struct PP_Var (*GetPluginInstanceURL)(
165      PP_Instance instance,
166      struct PP_URLComponents_Dev* components);
167  /*
168   * Returns the Referrer URL of the HTTP request that loaded the plugin. This
169   * is the value of the 'Referer' header of the request. An undefined value
170   * means the 'Referer' header was absent.
171   * The components pointer, if non-NULL and the canonicalized URL is valid,
172   * will identify the components of the resulting URL. Components may be NULL
173   * to specify that no component information is necessary.
174   */
175  struct PP_Var (*GetPluginReferrerURL)(
176      PP_Instance instance,
177      struct PP_URLComponents_Dev* components);
178};
179
180typedef struct PPB_URLUtil_Dev_0_7 PPB_URLUtil_Dev;
181
182struct PPB_URLUtil_Dev_0_6 {
183  struct PP_Var (*Canonicalize)(struct PP_Var url,
184                                struct PP_URLComponents_Dev* components);
185  struct PP_Var (*ResolveRelativeToURL)(
186      struct PP_Var base_url,
187      struct PP_Var relative_string,
188      struct PP_URLComponents_Dev* components);
189  struct PP_Var (*ResolveRelativeToDocument)(
190      PP_Instance instance,
191      struct PP_Var relative_string,
192      struct PP_URLComponents_Dev* components);
193  PP_Bool (*IsSameSecurityOrigin)(struct PP_Var url_a, struct PP_Var url_b);
194  PP_Bool (*DocumentCanRequest)(PP_Instance instance, struct PP_Var url);
195  PP_Bool (*DocumentCanAccessDocument)(PP_Instance active, PP_Instance target);
196  struct PP_Var (*GetDocumentURL)(PP_Instance instance,
197                                  struct PP_URLComponents_Dev* components);
198  struct PP_Var (*GetPluginInstanceURL)(
199      PP_Instance instance,
200      struct PP_URLComponents_Dev* components);
201};
202/**
203 * @}
204 */
205
206#endif  /* PPAPI_C_DEV_PPB_URL_UTIL_DEV_H_ */
207
208