PageRenderTime 26ms CodeModel.GetById 19ms RepoModel.GetById 0ms app.codeStats 0ms

/gecko_sdk/idl/nsIURL.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 179 lines | 15 code | 17 blank | 147 comment | 0 complexity | 287d614d982720335dd8f6f5353cbc11 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 "nsIURI.idl"
  40. /**
  41. * The nsIURL interface provides convenience methods that further
  42. * break down the path portion of nsIURI:
  43. *
  44. * http://host/directory/fileBaseName.fileExtension?query
  45. * http://host/directory/fileBaseName.fileExtension#ref
  46. * http://host/directory/fileBaseName.fileExtension;param
  47. * \ \ /
  48. * \ -----------------------
  49. * \ | /
  50. * \ fileName /
  51. * ----------------------------
  52. * |
  53. * filePath
  54. *
  55. * @status FROZEN
  56. */
  57. [scriptable, uuid(d6116970-8034-11d3-9399-00104ba0fd40)]
  58. interface nsIURL : nsIURI
  59. {
  60. /*************************************************************************
  61. * The URL path is broken down into the following principal components:
  62. */
  63. /**
  64. * Returns a path including the directory and file portions of a
  65. * URL. For example, the filePath of "http://host/foo/bar.html#baz"
  66. * is "/foo/bar.html".
  67. *
  68. * Some characters may be escaped.
  69. */
  70. attribute AUTF8String filePath;
  71. /**
  72. * Returns the parameters specified after the ; in the URL.
  73. *
  74. * Some characters may be escaped.
  75. */
  76. attribute AUTF8String param;
  77. /**
  78. * Returns the query portion (the part after the "?") of the URL.
  79. * If there isn't one, an empty string is returned.
  80. *
  81. * Some characters may be escaped.
  82. */
  83. attribute AUTF8String query;
  84. /**
  85. * Returns the reference portion (the part after the "#") of the URL.
  86. * If there isn't one, an empty string is returned.
  87. *
  88. * Some characters may be escaped.
  89. */
  90. attribute AUTF8String ref;
  91. /*************************************************************************
  92. * The URL filepath is broken down into the following sub-components:
  93. */
  94. /**
  95. * Returns the directory portion of a URL. If the URL denotes a path to a
  96. * directory and not a file, e.g. http://host/foo/bar/, then the Directory
  97. * attribute accesses the complete /foo/bar/ portion, and the FileName is
  98. * the empty string. If the trailing slash is omitted, then the Directory
  99. * is /foo/ and the file is bar (i.e. this is a syntactic, not a semantic
  100. * breakdown of the Path). And hence don't rely on this for something to
  101. * be a definitely be a file. But you can get just the leading directory
  102. * portion for sure.
  103. *
  104. * Some characters may be escaped.
  105. */
  106. attribute AUTF8String directory;
  107. /**
  108. * Returns the file name portion of a URL. If the URL denotes a path to a
  109. * directory and not a file, e.g. http://host/foo/bar/, then the Directory
  110. * attribute accesses the complete /foo/bar/ portion, and the FileName is
  111. * the empty string. Note that this is purely based on searching for the
  112. * last trailing slash. And hence don't rely on this to be a definite file.
  113. *
  114. * Some characters may be escaped.
  115. */
  116. attribute AUTF8String fileName;
  117. /*************************************************************************
  118. * The URL filename is broken down even further:
  119. */
  120. /**
  121. * Returns the file basename portion of a filename in a url.
  122. *
  123. * Some characters may be escaped.
  124. */
  125. attribute AUTF8String fileBaseName;
  126. /**
  127. * Returns the file extension portion of a filename in a url. If a file
  128. * extension does not exist, the empty string is returned.
  129. *
  130. * Some characters may be escaped.
  131. */
  132. attribute AUTF8String fileExtension;
  133. /**
  134. * This method takes a uri and compares the two. The common uri portion
  135. * is returned as a string. The minimum common uri portion is the
  136. * protocol, and any of these if present: login, password, host and port
  137. * If no commonality is found, "" is returned. If they are identical, the
  138. * whole path with file/ref/etc. is returned. For file uris, it is
  139. * expected that the common spec would be at least "file:///" since '/' is
  140. * a shared common root.
  141. *
  142. * Examples:
  143. * this.spec aURIToCompare.spec result
  144. * 1) http://mozilla.org/ http://www.mozilla.org/ ""
  145. * 2) http://foo.com/bar/ ftp://foo.com/bar/ ""
  146. * 3) http://foo.com:8080/ http://foo.com/bar/ ""
  147. * 4) ftp://user@foo.com/ ftp://user:pw@foo.com/ ""
  148. * 5) ftp://foo.com/bar/ ftp://foo.com/bar ftp://foo.com/
  149. * 6) ftp://foo.com/bar/ ftp://foo.com/bar/b.html ftp://foo.com/bar/
  150. * 7) http://foo.com/a.htm#i http://foo.com/b.htm http://foo.com/
  151. * 8) ftp://foo.com/c.htm#i ftp://foo.com/c.htm ftp://foo.com/c.htm
  152. * 9) file:///a/b/c.html file:///d/e/c.html file:///
  153. */
  154. AUTF8String getCommonBaseSpec(in nsIURI aURIToCompare);
  155. /**
  156. * This method takes a uri and returns a substring of this if it can be
  157. * made relative to the uri passed in. If no commonality is found, the
  158. * entire uri spec is returned. If they are identical, "" is returned.
  159. * Filename, query, etc are always returned except when uris are identical.
  160. */
  161. AUTF8String getRelativeSpec(in nsIURI aURIToCompare);
  162. };