ppapi/api/dev/ppb_url_util_dev.idl

/* Copyright (c) 2012 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_URLUtil_Dev</code> interface.
 */

label Chrome {
  M17 = 0.6,
  M31 = 0.7
};

/*
 * A component specifies the range of the part of the URL. The begin specifies
 * the index into the string of the first character of that component. The len
 * specifies the length of that component.
 *
 * This range does not include any special delimiter for that component, so
 * the scheme doesn't include the trailing colon, the username and password
 * don't include the @ and :, the port doesn't include the colon, the query
 * doesn't include the ?, and the ref doesn't include the #.
 *
 * The exception is that the path *does* include the first /, since that's an
 * integral part of the path.
 *
 * If the component is not present at all, begin will be 0 and len will be -1.
 * If the component is present but empty, the length will be 0 instead. Example:
 *   http://foo/search    -> query = (0, -1)
 *   http://foo/search?   -> query = (18, 0)
 */
[assert_size(8)]
struct PP_URLComponent_Dev {
  int32_t begin;
  int32_t len;
};

[assert_size(64)]
struct PP_URLComponents_Dev {
  PP_URLComponent_Dev scheme;
  PP_URLComponent_Dev username;
  PP_URLComponent_Dev password;
  PP_URLComponent_Dev host;
  PP_URLComponent_Dev port;
  PP_URLComponent_Dev path;
  PP_URLComponent_Dev query;
  PP_URLComponent_Dev ref;
};

/*
 * URL encoding: URLs are supplied to this interface as NULL-terminated 8-bit
 * strings. You can pass non-ASCII characters which will be interpreted as
 * UTF-8. Canonicalized URL strings returned by these functions will be ASCII
 * except for the reference fragment (stuff after the '#') which will be
 * encoded as UTF-8.
 */
interface PPB_URLUtil_Dev {
  /*
   * Canonicalizes the given URL string according to the rules of the host
   * browser. If the URL is invalid or the var is not a string, this will
   * return a Null var and the components structure will be unchanged.
   *
   * The components pointer, if non-NULL and the canonicalized URL is valid,
   * will identify the components of the resulting URL. Components may be NULL
   * to specify that no component information is necessary.
   */
  PP_Var Canonicalize([in] PP_Var url, [out] PP_URLComponents_Dev components);

  /*
   *  Resolves the given URL relative to the given base URL. The resulting URL
   *  is returned as a string. If the resolution is invalid or either of the
   *  inputs are not strings, a Null var will be returned. The resulting URL
   *  will also be canonicalized according to the rules of the browser.
   *
   *  Note that the "relative" URL may in fact be absolute, in which case it
   *  will be returned. This function is identical to resolving the full URL
   *  for an <a href="..."> on a web page. Attempting to resolve a relative URL
   *  on a base URL that doesn't support this (e.g. "data") will fail and will
   *  return a Null var, unless the relative URL is itself absolute.
   *
   *  The components pointer, if non-NULL and the canonicalized URL is valid,
   *  will identify the components of the resulting URL. Components may be NULL
   *  to specify that no component information is necessary.
   */
  PP_Var ResolveRelativeToURL(
      [in] PP_Var base_url,
      [in] PP_Var relative_string,
      [out] PP_URLComponents_Dev components);

  /*
   *  Identical to ResolveRelativeToURL except that the base URL is the base
   *  URL of the document containing the given plugin instance.
   *
   *  Danger: This will be identical to resolving a relative URL on the page,
   *  and might be overridden by the page to something different than its actual
   *  URL via the <base> tag. Therefore, resolving a relative URL of "" won't
   *  necessarily give you the URL of the page!
   */
  PP_Var ResolveRelativeToDocument(
      [in] PP_Instance instance,
      [in] PP_Var relative_string,
      [out] PP_URLComponents_Dev components);

  /*
   * Checks whether the given two URLs are in the same security origin. Returns
   * FALSE if either of the URLs are invalid.
   */
  PP_Bool IsSameSecurityOrigin([in] PP_Var url_a, [in] PP_Var url_b);

  /*
   * Checks whether the document hosting the given plugin instance can access
   * the given URL according to the same origin policy of the browser. Returns
   * PP_FALSE if the instance or the URL is invalid.
   */
  PP_Bool DocumentCanRequest([in] PP_Instance instance, [in] PP_Var url);

  /*
   * Checks whether the document containing the |active| plugin instance can
   * access the document containing the |target| plugin instance according to
   * the security policy of the browser. This includes the same origin policy
   * and any cross-origin capabilities enabled by the document. If either of
   * the plugin instances are invalid, returns PP_FALSE.
   */
  PP_Bool DocumentCanAccessDocument([in] PP_Instance active,
                                    [in] PP_Instance target);

  /*
   * Returns the URL for the document. This is a safe way to retrieve
   * window.location.href.
   * The components pointer, if non-NULL and the canonicalized URL is valid,
   * will identify the components of the resulting URL. Components may be NULL
   * to specify that no component information is necessary.
   */
  PP_Var GetDocumentURL([in] PP_Instance instance,
                        [out] PP_URLComponents_Dev components);

  /*
   * Returns the Source URL for the plugin. This returns the URL that would be
   * streamed to the plugin if it were a NPAPI plugin. This is usually the src
   * attribute on the <embed> element, but the rules are obscure and different
   * based on whether the plugin is loaded from an <embed> element or an
   * <object> element.
   * The components pointer, if non-NULL and the canonicalized URL is valid,
   * will identify the components of the resulting URL. Components may be NULL
   * to specify that no component information is necessary.
   */
  PP_Var GetPluginInstanceURL([in] PP_Instance instance,
                              [out] PP_URLComponents_Dev components);

  /*
   * Returns the Referrer URL of the HTTP request that loaded the plugin. This
   * is the value of the 'Referer' header of the request. An undefined value
   * means the 'Referer' header was absent.
   * The components pointer, if non-NULL and the canonicalized URL is valid,
   * will identify the components of the resulting URL. Components may be NULL
   * to specify that no component information is necessary.
   */
  [version=0.7]
  PP_Var GetPluginReferrerURL([in] PP_Instance instance,
                              [out] PP_URLComponents_Dev components);
};