PageRenderTime 42ms CodeModel.GetById 21ms RepoModel.GetById 0ms app.codeStats 0ms

/gecko_sdk/idl/nsIURI.idl

http://firefox-mac-pdf.googlecode.com/
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. #include "nsISupports.idl"
  40. /**
  41. * URIs are essentially structured names for things -- anything. This interface
  42. * provides accessors to set and query the most basic components of an URI.
  43. * Subclasses, including nsIURL, impose greater structure on the URI.
  44. *
  45. * This interface follows Tim Berners-Lee's URI spec (RFC2396) [1], where the
  46. * basic URI components are defined as such:
  47. * <pre>
  48. * ftp://username:password@hostname:portnumber/pathname
  49. * \ / \ / \ / \ /\ /
  50. * - --------------- ------ -------- -------
  51. * | | | | |
  52. * | | | | Path
  53. * | | | Port
  54. * | | Host /
  55. * | UserPass /
  56. * Scheme /
  57. * \ /
  58. * --------------------------------
  59. * |
  60. * PrePath
  61. * </pre>
  62. * The definition of the URI components has been extended to allow for
  63. * internationalized domain names [2] and the more generic IRI structure [3].
  64. *
  65. * [1] http://www.ietf.org/rfc/rfc2396.txt
  66. * [2] http://www.ietf.org/internet-drafts/draft-ietf-idn-idna-06.txt
  67. * [3] http://www.ietf.org/internet-drafts/draft-masinter-url-i18n-08.txt
  68. */
  69. %{C++
  70. #undef GetPort // XXX Windows!
  71. #undef SetPort // XXX Windows!
  72. %}
  73. /**
  74. * nsIURI - interface for an uniform resource identifier w/ i18n support.
  75. *
  76. * AUTF8String attributes may contain unescaped UTF-8 characters.
  77. * Consumers should be careful to escape the UTF-8 strings as necessary, but
  78. * should always try to "display" the UTF-8 version as provided by this
  79. * interface.
  80. *
  81. * AUTF8String attributes may also contain escaped characters.
  82. *
  83. * Unescaping URI segments is unadvised unless there is intimate
  84. * knowledge of the underlying charset or there is no plan to display (or
  85. * otherwise enforce a charset on) the resulting URI substring.
  86. *
  87. * @status FROZEN
  88. */
  89. [scriptable, uuid(07a22cc0-0ce5-11d3-9331-00104ba0fd40)]
  90. interface nsIURI : nsISupports
  91. {
  92. /************************************************************************
  93. * The URI is broken down into the following principal components:
  94. */
  95. /**
  96. * Returns a string representation of the URI. Setting the spec causes
  97. * the new spec to be parsed, initializing the URI.
  98. *
  99. * Some characters may be escaped.
  100. */
  101. attribute AUTF8String spec;
  102. /**
  103. * The prePath (eg. scheme://user:password@host:port) returns the string
  104. * before the path. This is useful for authentication or managing sessions.
  105. *
  106. * Some characters may be escaped.
  107. */
  108. readonly attribute AUTF8String prePath;
  109. /**
  110. * The Scheme is the protocol to which this URI refers. The scheme is
  111. * restricted to the US-ASCII charset per RFC2396.
  112. */
  113. attribute ACString scheme;
  114. /**
  115. * The username:password (or username only if value doesn't contain a ':')
  116. *
  117. * Some characters may be escaped.
  118. */
  119. attribute AUTF8String userPass;
  120. /**
  121. * The optional username and password, assuming the preHost consists of
  122. * username:password.
  123. *
  124. * Some characters may be escaped.
  125. */
  126. attribute AUTF8String username;
  127. attribute AUTF8String password;
  128. /**
  129. * The host:port (or simply the host, if port == -1).
  130. *
  131. * Characters are NOT escaped.
  132. */
  133. attribute AUTF8String hostPort;
  134. /**
  135. * The host is the internet domain name to which this URI refers. It could
  136. * be an IPv4 (or IPv6) address literal. If supported, it could be a
  137. * non-ASCII internationalized domain name.
  138. *
  139. * Characters are NOT escaped.
  140. */
  141. attribute AUTF8String host;
  142. /**
  143. * A port value of -1 corresponds to the protocol's default port (eg. -1
  144. * implies port 80 for http URIs).
  145. */
  146. attribute long port;
  147. /**
  148. * The path, typically including at least a leading '/' (but may also be
  149. * empty, depending on the protocol).
  150. *
  151. * Some characters may be escaped.
  152. */
  153. attribute AUTF8String path;
  154. /************************************************************************
  155. * An URI supports the following methods:
  156. */
  157. /**
  158. * URI equivalence test (not a strict string comparison).
  159. *
  160. * eg. http://foo.com:80/ == http://foo.com/
  161. */
  162. boolean equals(in nsIURI other);
  163. /**
  164. * An optimization to do scheme checks without requiring the users of nsIURI
  165. * to GetScheme, thereby saving extra allocating and freeing. Returns true if
  166. * the schemes match (case ignored).
  167. */
  168. boolean schemeIs(in string scheme);
  169. /**
  170. * Clones the current URI. For some protocols, this is more than just an
  171. * optimization. For example, under MacOS, the spec of a file URL does not
  172. * necessarily uniquely identify a file since two volumes could share the
  173. * same name.
  174. */
  175. nsIURI clone();
  176. /**
  177. * This method resolves a relative string into an absolute URI string,
  178. * using this URI as the base.
  179. *
  180. * NOTE: some implementations may have no concept of a relative URI.
  181. */
  182. AUTF8String resolve(in AUTF8String relativePath);
  183. /************************************************************************
  184. * Additional attributes:
  185. */
  186. /**
  187. * The URI spec with an ASCII compatible encoding. Host portion follows
  188. * the IDNA draft spec. Other parts are URL-escaped per the rules of
  189. * RFC2396. The result is strictly ASCII.
  190. */
  191. readonly attribute ACString asciiSpec;
  192. /**
  193. * The URI host with an ASCII compatible encoding. Follows the IDNA
  194. * draft spec for converting internationalized domain names (UTF-8) to
  195. * ASCII for compatibility with existing internet infrasture.
  196. */
  197. readonly attribute ACString asciiHost;
  198. /**
  199. * The charset of the document from which this URI originated. An empty
  200. * value implies UTF-8.
  201. *
  202. * If this value is something other than UTF-8 then the URI components
  203. * (e.g., spec, prePath, username, etc.) will all be fully URL-escaped.
  204. * Otherwise, the URI components may contain unescaped multibyte UTF-8
  205. * characters.
  206. */
  207. readonly attribute ACString originCharset;
  208. };