toolkit/modules/FileUtils.jsm

   1 /* -*- indent-tabs-mode: nil; js-indent-level: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 var EXPORTED_SYMBOLS = ["FileUtils"];
   7
   8 const { XPCOMUtils } = ChromeUtils.import(
   9   "resource://gre/modules/XPCOMUtils.jsm"
  10 );
  11
  12 XPCOMUtils.defineLazyServiceGetter(
  13   this,
  14   "gDirService",
  15   "@mozilla.org/file/directory_service;1",
  16   "nsIProperties"
  17 );
  18
  19 var FileUtils = {
  20   MODE_RDONLY: 0x01,
  21   MODE_WRONLY: 0x02,
  22   MODE_RDWR: 0x04,
  23   MODE_CREATE: 0x08,
  24   MODE_APPEND: 0x10,
  25   MODE_TRUNCATE: 0x20,
  26
  27   PERMS_FILE: 0o644,
  28   PERMS_DIRECTORY: 0o755,
  29
  30   /**
  31    * Gets a file at the specified hierarchy under a nsIDirectoryService key.
  32    * @param   key
  33    *          The Directory Service Key to start from
  34    * @param   pathArray
  35    *          An array of path components to locate beneath the directory
  36    *          specified by |key|. The last item in this array must be the
  37    *          leaf name of a file.
  38    * @return  nsIFile object for the file specified. The file is NOT created
  39    *          if it does not exist, however all required directories along
  40    *          the way are if pathArray has more than one item.
  41    */
  42   getFile: function FileUtils_getFile(key, pathArray, followLinks) {
  43     var file = this.getDir(
  44       key,
  45       pathArray.slice(0, -1),
  46       pathArray.length > 1,
  47       followLinks
  48     );
  49     file.append(pathArray[pathArray.length - 1]);
  50     return file;
  51   },
  52
  53   /**
  54    * Gets a directory at the specified hierarchy under a nsIDirectoryService
  55    * key.
  56    * @param   key
  57    *          The Directory Service Key to start from
  58    * @param   pathArray
  59    *          An array of path components to locate beneath the directory
  60    *          specified by |key|
  61    * @param   shouldCreate
  62    *          true if the directory hierarchy specified in |pathArray|
  63    *          should be created if it does not exist, false otherwise.
  64    * @param   followLinks (optional)
  65    *          true if links should be followed, false otherwise.
  66    * @return  nsIFile object for the location specified.
  67    */
  68   getDir: function FileUtils_getDir(key, pathArray, shouldCreate, followLinks) {
  69     var dir = gDirService.get(key, Ci.nsIFile);
  70     for (var i = 0; i < pathArray.length; ++i) {
  71       dir.append(pathArray[i]);
  72     }
  73
  74     if (shouldCreate) {
  75       try {
  76         dir.create(Ci.nsIFile.DIRECTORY_TYPE, this.PERMS_DIRECTORY);
  77       } catch (ex) {
  78         if (ex.result != Cr.NS_ERROR_FILE_ALREADY_EXISTS) {
  79           throw ex;
  80         }
  81         // Ignore the exception due to a directory that already exists.
  82       }
  83     }
  84
  85     if (!followLinks) {
  86       dir.followLinks = false;
  87     }
  88     return dir;
  89   },
  90
  91   /**
  92    * Opens a file output stream for writing.
  93    * @param   file
  94    *          The file to write to.
  95    * @param   modeFlags
  96    *          (optional) File open flags. Can be undefined.
  97    * @returns nsIFileOutputStream to write to.
  98    * @note The stream is initialized with the DEFER_OPEN behavior flag.
  99    *       See nsIFileOutputStream.
 100    */
 101   openFileOutputStream: function FileUtils_openFileOutputStream(
 102     file,
 103     modeFlags
 104   ) {
 105     var fos = Cc["@mozilla.org/network/file-output-stream;1"].createInstance(
 106       Ci.nsIFileOutputStream
 107     );
 108     return this._initFileOutputStream(fos, file, modeFlags);
 109   },
 110
 111   /**
 112    * Opens an atomic file output stream for writing.
 113    * @param   file
 114    *          The file to write to.
 115    * @param   modeFlags
 116    *          (optional) File open flags. Can be undefined.
 117    * @returns nsIFileOutputStream to write to.
 118    * @note The stream is initialized with the DEFER_OPEN behavior flag.
 119    *       See nsIFileOutputStream.
 120    *       OpeanAtomicFileOutputStream is generally better than openSafeFileOutputStream
 121    *       baecause flushing is not needed in most of the issues.
 122    */
 123   openAtomicFileOutputStream: function FileUtils_openAtomicFileOutputStream(
 124     file,
 125     modeFlags
 126   ) {
 127     var fos = Cc[
 128       "@mozilla.org/network/atomic-file-output-stream;1"
 129     ].createInstance(Ci.nsIFileOutputStream);
 130     return this._initFileOutputStream(fos, file, modeFlags);
 131   },
 132
 133   /**
 134    * Opens a safe file output stream for writing.
 135    * @param   file
 136    *          The file to write to.
 137    * @param   modeFlags
 138    *          (optional) File open flags. Can be undefined.
 139    * @returns nsIFileOutputStream to write to.
 140    * @note The stream is initialized with the DEFER_OPEN behavior flag.
 141    *       See nsIFileOutputStream.
 142    */
 143   openSafeFileOutputStream: function FileUtils_openSafeFileOutputStream(
 144     file,
 145     modeFlags
 146   ) {
 147     var fos = Cc[
 148       "@mozilla.org/network/safe-file-output-stream;1"
 149     ].createInstance(Ci.nsIFileOutputStream);
 150     return this._initFileOutputStream(fos, file, modeFlags);
 151   },
 152
 153   _initFileOutputStream: function FileUtils__initFileOutputStream(
 154     fos,
 155     file,
 156     modeFlags
 157   ) {
 158     if (modeFlags === undefined) {
 159       modeFlags = this.MODE_WRONLY | this.MODE_CREATE | this.MODE_TRUNCATE;
 160     }
 161     fos.init(file, modeFlags, this.PERMS_FILE, fos.DEFER_OPEN);
 162     return fos;
 163   },
 164
 165   /**
 166    * Closes an atomic file output stream.
 167    * @param   stream
 168    *          The stream to close.
 169    */
 170   closeAtomicFileOutputStream: function FileUtils_closeAtomicFileOutputStream(
 171     stream
 172   ) {
 173     if (stream instanceof Ci.nsISafeOutputStream) {
 174       try {
 175         stream.finish();
 176         return;
 177       } catch (e) {}
 178     }
 179     stream.close();
 180   },
 181
 182   /**
 183    * Closes a safe file output stream.
 184    * @param   stream
 185    *          The stream to close.
 186    */
 187   closeSafeFileOutputStream: function FileUtils_closeSafeFileOutputStream(
 188     stream
 189   ) {
 190     if (stream instanceof Ci.nsISafeOutputStream) {
 191       try {
 192         stream.finish();
 193         return;
 194       } catch (e) {}
 195     }
 196     stream.close();
 197   },
 198
 199   File: Components.Constructor(
 200     "@mozilla.org/file/local;1",
 201     Ci.nsIFile,
 202     "initWithPath"
 203   ),
 204 };