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 10label 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)] 34struct PP_URLComponent_Dev { 35 int32_t begin; 36 int32_t len; 37}; 38 39[assert_size(64)] 40struct 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 */ 58interface 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}; 163