xpcom/io/nsIFile.idl

   1 /* -*- Mode: C++; tab-width: 4; 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 Communicator client code, released
  16  * March 31, 1998.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 1998-1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Doug Turner <dougt@netscape.com>
  25  *   Christopher Blizzard <blizzard@mozilla.org>
  26  *   Darin Fisher <darin@netscape.com>
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of
  29  * either of the GNU General Public License Version 2 or later (the "GPL"),
  30  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  31  * in which case the provisions of the GPL or the LGPL are applicable instead
  32  * of those above. If you wish to allow use of your version of this file only
  33  * under the terms of either the GPL or the LGPL, and not to allow others to
  34  * use your version of this file under the terms of the MPL, indicate your
  35  * decision by deleting the provisions above and replace them with the notice
  36  * and other provisions required by the GPL or the LGPL. If you do not delete
  37  * the provisions above, a recipient may use your version of this file under
  38  * the terms of any one of the MPL, the GPL or the LGPL.
  39  *
  40  * ***** END LICENSE BLOCK ***** */
  41
  42 #include "nsISupports.idl"
  43
  44 interface nsISimpleEnumerator;
  45
  46 /**
  47  * This is the only correct cross-platform way to specify a file.
  48  * Strings are not such a way. If you grew up on windows or unix, you
  49  * may think they are.  Welcome to reality.
  50  *
  51  * All methods with string parameters have two forms.  The preferred
  52  * form operates on UCS-2 encoded characters strings.  An alternate
  53  * form operates on characters strings encoded in the "native" charset.
  54  *
  55  * A string containing characters encoded in the native charset cannot
  56  * be safely passed to javascript via xpconnect.  Therefore, the "native
  57  * methods" are not scriptable.
  58  *
  59  * @status FROZEN
  60  */
  61 [scriptable, uuid(c8c0a080-0868-11d3-915f-d9d889d48e3c)]
  62 interface nsIFile : nsISupports
  63 {
  64     /**
  65      *  Create Types
  66      *
  67      *  NORMAL_FILE_TYPE - A normal file.
  68      *  DIRECTORY_TYPE   - A directory/folder.
  69      */
  70     const unsigned long NORMAL_FILE_TYPE = 0;
  71     const unsigned long DIRECTORY_TYPE   = 1;
  72
  73     /**
  74      *  append[Native]
  75      *
  76      *  This function is used for constructing a descendent of the
  77      *  current nsIFile.
  78      *
  79      *   @param node
  80      *       A string which is intended to be a child node of the nsIFile.
  81      *       For the |appendNative| method, the node must be in the native
  82      *       filesystem charset.
  83      */
  84     void append(in AString node);
  85     [noscript] void appendNative(in ACString node);
  86
  87     /**
  88      *  Normalize the pathName (e.g. removing .. and . components on Unix).
  89      */
  90     void normalize();
  91
  92     /**
  93      *  create
  94      *
  95      *  This function will create a new file or directory in the
  96      *  file system. Any nodes that have not been created or
  97      *  resolved, will be.  If the file or directory already
  98      *  exists create() will return NS_ERROR_FILE_ALREADY_EXISTS.
  99      *
 100      *   @param type
 101      *       This specifies the type of file system object
 102      *       to be made.  The only two types at this time
 103      *       are file and directory which are defined above.
 104      *       If the type is unrecongnized, we will return an
 105      *       error (NS_ERROR_FILE_UNKNOWN_TYPE).
 106      *
 107      *   @param permissions
 108      *       The unix style octal permissions.  This may
 109      *       be ignored on systems that do not need to do
 110      *       permissions.
 111      */
 112     void create(in unsigned long type, in unsigned long permissions);
 113
 114     /**
 115      *  Accessor to the leaf name of the file itself.
 116      *  For the |nativeLeafName| method, the nativeLeafName must
 117      *  be in the native filesystem charset.
 118      */
 119     attribute AString leafName;
 120     [noscript] attribute ACString nativeLeafName;
 121
 122     /**
 123      *  copyTo[Native]
 124      *
 125      *  This will copy this file to the specified newParentDir.
 126      *  If a newName is specified, the file will be renamed.
 127      *  If 'this' is not created we will return an error
 128      *  (NS_ERROR_FILE_TARGET_DOES_NOT_EXIST).
 129      *
 130      *  copyTo may fail if the file already exists in the destination
 131      *  directory.
 132      *
 133      *  copyTo will NOT resolve aliases/shortcuts during the copy.
 134      *
 135      *   @param newParentDir
 136      *       This param is the destination directory. If the
 137      *       newParentDir is null, copyTo() will use the parent
 138      *       directory of this file. If the newParentDir is not
 139      *       empty and is not a directory, an error will be
 140      *       returned (NS_ERROR_FILE_DESTINATION_NOT_DIR). For the
 141      *       |CopyToNative| method, the newName must be in the
 142      *       native filesystem charset.
 143      *
 144      *   @param newName
 145      *       This param allows you to specify a new name for
 146      *       the file to be copied. This param may be empty, in
 147      *       which case the current leaf name will be used.
 148      */
 149     void copyTo(in nsIFile newParentDir, in AString newName);
 150     [noscript] void CopyToNative(in nsIFile newParentDir, in ACString newName);
 151
 152     /**
 153      *  copyToFollowingLinks[Native]
 154      *
 155      *  This function is identical to copyTo with the exception that,
 156      *  as the name implies, it follows symbolic links.  The XP_UNIX
 157      *  implementation always follow symbolic links when copying.  For
 158      *  the |CopyToFollowingLinks| method, the newName must be in the
 159      *  native filesystem charset.
 160      */
 161     void copyToFollowingLinks(in nsIFile newParentDir, in AString newName);
 162     [noscript] void copyToFollowingLinksNative(in nsIFile newParentDir, in ACString newName);
 163
 164     /**
 165      *  moveTo[Native]
 166      *
 167      *  A method to move this file or directory to newParentDir.
 168      *  If a newName is specified, the file or directory will be renamed.
 169      *  If 'this' is not created we will return an error
 170      *  (NS_ERROR_FILE_TARGET_DOES_NOT_EXIST).
 171      *  If 'this' is a file, and the destination file already exists, moveTo
 172      *  will replace the old file.
 173      *
 174      *  moveTo will NOT resolve aliases/shortcuts during the copy.
 175      *  moveTo will do the right thing and allow copies across volumes.
 176      *  moveTo will return an error (NS_ERROR_FILE_DIR_NOT_EMPTY) if 'this' is
 177      *  a directory and the destination directory is not empty.
 178      *  moveTo will return an error (NS_ERROR_FILE_ACCESS_DENIED) if 'this' is
 179      *  a directory and the destination directory is not writable.
 180      *
 181      *   @param newParentDir
 182      *       This param is the destination directory. If the
 183      *       newParentDir is empty, moveTo() will rename the file
 184      *       within its current directory. If the newParentDir is
 185      *       not empty and does not name a directory, an error will
 186      *       be returned (NS_ERROR_FILE_DESTINATION_NOT_DIR).  For
 187      *       the |moveToNative| method, the newName must be in the
 188      *       native filesystem charset.
 189      *
 190      *   @param newName
 191      *       This param allows you to specify a new name for
 192      *       the file to be moved. This param may be empty, in
 193      *       which case the current leaf name will be used.
 194      */
 195     void moveTo(in nsIFile newParentDir, in AString newName);
 196     [noscript] void moveToNative(in nsIFile newParentDir, in ACString newName);
 197
 198     /**
 199      *  This will try to delete this file.  The 'recursive' flag
 200      *  must be PR_TRUE to delete directories which are not empty.
 201      *
 202      *  This will not resolve any symlinks.
 203      */
 204     void remove(in boolean recursive);
 205
 206     /**
 207      *  Attributes of nsIFile.
 208      */
 209
 210     attribute unsigned long permissions;
 211     attribute unsigned long permissionsOfLink;
 212
 213     /**
 214      *  File Times are to be in milliseconds from
 215      *  midnight (00:00:00), January 1, 1970 Greenwich Mean
 216      *  Time (GMT).
 217      */
 218     attribute PRInt64 lastModifiedTime;
 219     attribute PRInt64 lastModifiedTimeOfLink;
 220
 221     /**
 222      *  WARNING!  On the Mac, getting/setting the file size with nsIFile
 223      *  only deals with the size of the data fork.  If you need to
 224      *  know the size of the combined data and resource forks use the
 225      *  GetFileSizeWithResFork() method defined on nsILocalFileMac.
 226      */
 227     attribute PRInt64 fileSize;
 228     readonly attribute PRInt64 fileSizeOfLink;
 229
 230     /**
 231      *  target & path
 232      *
 233      *  Accessor to the string path.  The native version of these
 234      *  strings are not guaranteed to be a usable path to pass to
 235      *  NSPR or the C stdlib.  There are problems that affect
 236      *  platforms on which a path does not fully specify a file
 237      *  because two volumes can have the same name (e.g., mac).
 238      *  This is solved by holding "private", native data in the
 239      *  nsIFile implementation.  This native data is lost when
 240      *  you convert to a string.
 241      *
 242      *      DO NOT PASS TO USE WITH NSPR OR STDLIB!
 243      *
 244      *  target
 245      *      Find out what the symlink points at.  Will give error
 246      *      (NS_ERROR_FILE_INVALID_PATH) if not a symlink.
 247      *
 248      *  path
 249      *      Find out what the nsIFile points at.
 250      *
 251      *  Note that the ACString attributes are returned in the
 252      *  native filesystem charset.
 253      *
 254      */
 255     readonly attribute AString target;
 256     [noscript] readonly attribute ACString nativeTarget;
 257     readonly attribute AString path;
 258     [noscript] readonly attribute ACString nativePath;
 259
 260     boolean exists();
 261     boolean isWritable();
 262     boolean isReadable();
 263     boolean isExecutable();
 264     boolean isHidden();
 265     boolean isDirectory();
 266     boolean isFile();
 267     boolean isSymlink();
 268     /**
 269      * Not a regular file, not a directory, not a symlink.
 270      */
 271     boolean isSpecial();
 272
 273     /**
 274      *  createUnique
 275      *
 276      *  This function will create a new file or directory in the
 277      *  file system. Any nodes that have not been created or
 278      *  resolved, will be.  If this file already exists, we try
 279      *  variations on the leaf name "suggestedName" until we find
 280      *  one that did not already exist.
 281      *
 282      *  If the search for nonexistent files takes too long
 283      *  (thousands of the variants already exist), we give up and
 284      *  return NS_ERROR_FILE_TOO_BIG.
 285      *
 286      *   @param type
 287      *       This specifies the type of file system object
 288      *       to be made.  The only two types at this time
 289      *       are file and directory which are defined above.
 290      *       If the type is unrecongnized, we will return an
 291      *       error (NS_ERROR_FILE_UNKNOWN_TYPE).
 292      *
 293      *   @param permissions
 294      *       The unix style octal permissions.  This may
 295      *       be ignored on systems that do not need to do
 296      *       permissions.
 297      */
 298     void createUnique(in unsigned long type, in unsigned long permissions);
 299
 300     /**
 301       * clone()
 302       *
 303       * This function will allocate and initialize a nsIFile object to the
 304       * exact location of the |this| nsIFile.
 305       *
 306       *   @param file
 307       *          A nsIFile which this object will be initialize
 308       *          with.
 309       *
 310       */
 311     nsIFile clone();
 312
 313     /**
 314      *  Will determine if the inFile equals this.
 315      */
 316     boolean equals(in nsIFile inFile);
 317
 318     /**
 319      *  Will determine if inFile is a descendant of this file
 320      *  If |recur| is true, look in subdirectories too
 321      */
 322     boolean contains(in nsIFile inFile, in boolean recur);
 323
 324     /**
 325      *  Parent will be null when this is at the top of the volume.
 326      */
 327     readonly attribute nsIFile parent;
 328
 329     /**
 330      *  Returns an enumeration of the elements in a directory. Each
 331      *  element in the enumeration is an nsIFile.
 332      *
 333      *   @return NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does
 334      *           not specify a directory.
 335      */
 336     readonly attribute nsISimpleEnumerator directoryEntries;
 337 };
 338
 339 %{C++
 340 #ifdef MOZILLA_INTERNAL_API
 341 #include "nsDirectoryServiceUtils.h"
 342 #endif
 343 %}