ppapi/api/dev/ppb_url_util_dev.idl

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