/gecko_sdk/idl/nsIURI.idl
IDL | 232 lines | 26 code | 24 blank | 182 comment | 0 complexity | cf328274535f7b7b2219c33a5844bdba MD5 | raw file
1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2/* ***** BEGIN LICENSE BLOCK ***** 3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1 4 * 5 * The contents of this file are subject to the Mozilla Public License Version 6 * 1.1 (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * http://www.mozilla.org/MPL/ 9 * 10 * Software distributed under the License is distributed on an "AS IS" basis, 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 12 * for the specific language governing rights and limitations under the 13 * License. 14 * 15 * The Original Code is mozilla.org code. 16 * 17 * The Initial Developer of the Original Code is 18 * Netscape Communications Corporation. 19 * Portions created by the Initial Developer are Copyright (C) 1998 20 * the Initial Developer. All Rights Reserved. 21 * 22 * Contributor(s): 23 * Gagan Saksena <gagan@netscape.com> (original author) 24 * Darin Fisher <darin@netscape.com> 25 * 26 * Alternatively, the contents of this file may be used under the terms of 27 * either the GNU General Public License Version 2 or later (the "GPL"), or 28 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 29 * in which case the provisions of the GPL or the LGPL are applicable instead 30 * of those above. If you wish to allow use of your version of this file only 31 * under the terms of either the GPL or the LGPL, and not to allow others to 32 * use your version of this file under the terms of the MPL, indicate your 33 * decision by deleting the provisions above and replace them with the notice 34 * and other provisions required by the GPL or the LGPL. If you do not delete 35 * the provisions above, a recipient may use your version of this file under 36 * the terms of any one of the MPL, the GPL or the LGPL. 37 * 38 * ***** END LICENSE BLOCK ***** */ 39 40#include "nsISupports.idl" 41 42/** 43 * URIs are essentially structured names for things -- anything. This interface 44 * provides accessors to set and query the most basic components of an URI. 45 * Subclasses, including nsIURL, impose greater structure on the URI. 46 * 47 * This interface follows Tim Berners-Lee's URI spec (RFC2396) [1], where the 48 * basic URI components are defined as such: 49 * <pre> 50 * ftp://username:password@hostname:portnumber/pathname 51 * \ / \ / \ / \ /\ / 52 * - --------------- ------ -------- ------- 53 * | | | | | 54 * | | | | Path 55 * | | | Port 56 * | | Host / 57 * | UserPass / 58 * Scheme / 59 * \ / 60 * -------------------------------- 61 * | 62 * PrePath 63 * </pre> 64 * The definition of the URI components has been extended to allow for 65 * internationalized domain names [2] and the more generic IRI structure [3]. 66 * 67 * [1] http://www.ietf.org/rfc/rfc2396.txt 68 * [2] http://www.ietf.org/internet-drafts/draft-ietf-idn-idna-06.txt 69 * [3] http://www.ietf.org/internet-drafts/draft-masinter-url-i18n-08.txt 70 */ 71 72%{C++ 73#undef GetPort // XXX Windows! 74#undef SetPort // XXX Windows! 75%} 76 77/** 78 * nsIURI - interface for an uniform resource identifier w/ i18n support. 79 * 80 * AUTF8String attributes may contain unescaped UTF-8 characters. 81 * Consumers should be careful to escape the UTF-8 strings as necessary, but 82 * should always try to "display" the UTF-8 version as provided by this 83 * interface. 84 * 85 * AUTF8String attributes may also contain escaped characters. 86 * 87 * Unescaping URI segments is unadvised unless there is intimate 88 * knowledge of the underlying charset or there is no plan to display (or 89 * otherwise enforce a charset on) the resulting URI substring. 90 * 91 * @status FROZEN 92 */ 93[scriptable, uuid(07a22cc0-0ce5-11d3-9331-00104ba0fd40)] 94interface nsIURI : nsISupports 95{ 96 /************************************************************************ 97 * The URI is broken down into the following principal components: 98 */ 99 100 /** 101 * Returns a string representation of the URI. Setting the spec causes 102 * the new spec to be parsed, initializing the URI. 103 * 104 * Some characters may be escaped. 105 */ 106 attribute AUTF8String spec; 107 108 /** 109 * The prePath (eg. scheme://user:password@host:port) returns the string 110 * before the path. This is useful for authentication or managing sessions. 111 * 112 * Some characters may be escaped. 113 */ 114 readonly attribute AUTF8String prePath; 115 116 /** 117 * The Scheme is the protocol to which this URI refers. The scheme is 118 * restricted to the US-ASCII charset per RFC2396. 119 */ 120 attribute ACString scheme; 121 122 /** 123 * The username:password (or username only if value doesn't contain a ':') 124 * 125 * Some characters may be escaped. 126 */ 127 attribute AUTF8String userPass; 128 129 /** 130 * The optional username and password, assuming the preHost consists of 131 * username:password. 132 * 133 * Some characters may be escaped. 134 */ 135 attribute AUTF8String username; 136 attribute AUTF8String password; 137 138 /** 139 * The host:port (or simply the host, if port == -1). 140 * 141 * Characters are NOT escaped. 142 */ 143 attribute AUTF8String hostPort; 144 145 /** 146 * The host is the internet domain name to which this URI refers. It could 147 * be an IPv4 (or IPv6) address literal. If supported, it could be a 148 * non-ASCII internationalized domain name. 149 * 150 * Characters are NOT escaped. 151 */ 152 attribute AUTF8String host; 153 154 /** 155 * A port value of -1 corresponds to the protocol's default port (eg. -1 156 * implies port 80 for http URIs). 157 */ 158 attribute long port; 159 160 /** 161 * The path, typically including at least a leading '/' (but may also be 162 * empty, depending on the protocol). 163 * 164 * Some characters may be escaped. 165 */ 166 attribute AUTF8String path; 167 168 169 /************************************************************************ 170 * An URI supports the following methods: 171 */ 172 173 /** 174 * URI equivalence test (not a strict string comparison). 175 * 176 * eg. http://foo.com:80/ == http://foo.com/ 177 */ 178 boolean equals(in nsIURI other); 179 180 /** 181 * An optimization to do scheme checks without requiring the users of nsIURI 182 * to GetScheme, thereby saving extra allocating and freeing. Returns true if 183 * the schemes match (case ignored). 184 */ 185 boolean schemeIs(in string scheme); 186 187 /** 188 * Clones the current URI. For some protocols, this is more than just an 189 * optimization. For example, under MacOS, the spec of a file URL does not 190 * necessarily uniquely identify a file since two volumes could share the 191 * same name. 192 */ 193 nsIURI clone(); 194 195 /** 196 * This method resolves a relative string into an absolute URI string, 197 * using this URI as the base. 198 * 199 * NOTE: some implementations may have no concept of a relative URI. 200 */ 201 AUTF8String resolve(in AUTF8String relativePath); 202 203 204 /************************************************************************ 205 * Additional attributes: 206 */ 207 208 /** 209 * The URI spec with an ASCII compatible encoding. Host portion follows 210 * the IDNA draft spec. Other parts are URL-escaped per the rules of 211 * RFC2396. The result is strictly ASCII. 212 */ 213 readonly attribute ACString asciiSpec; 214 215 /** 216 * The URI host with an ASCII compatible encoding. Follows the IDNA 217 * draft spec for converting internationalized domain names (UTF-8) to 218 * ASCII for compatibility with existing internet infrasture. 219 */ 220 readonly attribute ACString asciiHost; 221 222 /** 223 * The charset of the document from which this URI originated. An empty 224 * value implies UTF-8. 225 * 226 * If this value is something other than UTF-8 then the URI components 227 * (e.g., spec, prePath, username, etc.) will all be fully URL-escaped. 228 * Otherwise, the URI components may contain unescaped multibyte UTF-8 229 * characters. 230 */ 231 readonly attribute ACString originCharset; 232};