ppapi/c/dev/ppb_url_util_dev.h

   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  */
  49 struct PP_URLComponent_Dev {
  50   int32_t begin;
  51   int32_t len;
  52 };
  53 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_URLComponent_Dev, 8);
  54
  55 struct 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 };
  65 PP_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  */
  81 struct 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
 180 typedef struct PPB_URLUtil_Dev_0_7 PPB_URLUtil_Dev;
 181
 182 struct 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