MozillaWiki

JSFileApi: Difference between revisions

Page Discussion

JSFileApi (view source)

Revision as of 15:45, 30 September 2011

1,026 bytes removed ,  30 September 2011
no edit summary
No edit summary
No edit summary
Line 3: Line 3:
The general idea of this API is to provide a low-level, cross-platform, fast access to file management functions. For this reason, it does not implement some primitives that are very different between platforms, e.g. chmod, mmap, epoll.
The general idea of this API is to provide a low-level, cross-platform, fast access to file management functions. For this reason, it does not implement some primitives that are very different between platforms, e.g. chmod, mmap, epoll.


By the way, this document uses the conventions of [http://code.google.com/closure/compiler/docs/js-for-compiler.html|the Google Closure Compiler] for  type annotations.
*Conventions* By the way, this document uses the conventions of [http://code.google.com/closure/compiler/docs/js-for-compiler.html|the Google Closure Compiler] for  type annotations.
 


= Module FileUtilities =
= Module FileUtilities =
Line 11: Line 12:
== Access a file or a directory ==
== Access a file or a directory ==
   
   
    /**
      * Open a file
      *
      * @param {string} fileName A platform-dependent name. To create a file in a directory, use [DirectoryDescriptor.openFile].
      * @param {number} accessMode A or-ing of flags, as specified by [FileUtilities.Open.Access].
      * @param {number} contentMode A or-ing of flags, as specified by [FileUtilities.Open.Content]
      * @param {number} pragmaMode A or-ing of flags, as specified by [FileUtilities.Open.Pragma]
      * @return {FileDescriptor} a FileDescriptor
      *
      * @throws FileDescriptorError
      */
    openFile: function(fullName, accessMode, contentMode, pragmaMode) {
//Unix:    maps to [open]
//Windows: maps to [CreateFile]
//Windows note: we probably want flags FLAG_SHARE_READ, FLAG_SHARE_WRITE, FLAG_SHARE_DELETE to allow moving files that are currently open
    },
    /**
      * Create a temporary file. This file is deleted when the process closes, when the file is closed or when the FileDescriptor is garbage-collected.
      *
      * @return {FileDescriptor} a FileDescriptor
      */
    createTempFile: function() {
//Unix:    [FileUtilities.tmpdir] followed by [mkstemp] and [FileUtilities.openFile]
//Windows: [FileUtilities.tmpdir] followed by [GetTempFileName] and [FileUtilities.openFile]
//Alternative version:
//Unix minus Android: maps to [tmpfile]
//Android:            need to implement custom [tmpfile]
//Windows:            maps to [GetTempPath] + [GetTempFileName] + [CreateFile] http://msdn.microsoft.com/en-us/library/windows/desktop/aa363875%28v=vs.85%29.aspx
    },
    /**
      * @param {string} fullName The platform-specific name of the directory.
      * @param {number=} accessMode A or-ing of flags, as specified by [FileDescriptor.OpenDir.Access]
      *
      * @returns {DirectoryDescriptor} a descriptor which may be used to access this directory
      */
    openDirectory: function(fullName, accessMode) {
//Unix:    lazy
//Windows: lazy
    },
   
   
     /**
     /**
       * Create a temporary directory.
       * Create a temporary directory.
       *
       *
       * Note: For the time being, there is no guarantee that the temporary directory will be cleaned
       * Note: For the time being, there is no guarantee *when* the temporary directory is cleaned
       *
       *
       * @returns {DirectoryDescriptor} a descriptor which may be used to access this directory
       * @returns {DirectoryDescriptor} a descriptor which may be used to access this directory
Line 117: Line 76:
== Constants ==
== Constants ==
   
   
    get stdin:  function() {
 
//...
    },
    get stdout: function() {
//...
    },
    get stderr: function() {
//...
    },
     /**
     /**
       * Return the location of the directory/folder used to store temporary files.
       * Return the location of the directory/folder used to store temporary files.
Line 134: Line 84:
       * @return {DirectoryDescriptor}
       * @return {DirectoryDescriptor}
       */
       */
     get tmpdir: function () {
     get tmpdir() {
  //All platforms: use [nsIDirectoryService] [NS_OS_TEMP_DIR] to get the directory the first time
  //All platforms: use [nsIDirectoryService] [NS_OS_TEMP_DIR] to get the directory the first time
   
   
Line 143: Line 93:
    //Note: Perhaps we should check with nsIDirectoryServi
    //Note: Perhaps we should check with nsIDirectoryServi
     },
     },
    /**
      * Return a well-known directory, such as the user profile directory, etc.
      *
      * Results are cached.
      *
      * Note: for performance and usability reasons, we will probably progressively add functions such as [get tmpdir] for other well-known directories.
      *
      * @param The key of a well-known directory. The list of keys is only defined in http://lxr.mozilla.org/seamonkey/source/xpcom/io/nsDirectoryServiceDefs.h .
      */
    getDirectory: function(key) {
        //All platforms: use [nsIDirectoryService], cache result
    },
   
   
== Flags ==
== Flags ==
Line 387: Line 351:
       */
       */
     openFile: function(leafName, accessMode, contentMode, pragmaMode) {
     openFile: function(leafName, accessMode, contentMode, pragmaMode) {
  //Unix:    maps to [openat] (warning, this requires gnulib on non-Linux Unix platforms)
  //Linux:    [openat]
        //Unix:      decide between gnulib [openat] and simply [open]
  //Windows:  cf. [FileDescriptor.open]
  //Windows:  cf. [FileDescriptor.open]
     },
     },
Line 408: Line 373:
       */
       */
     openDirectory: function(leafName, accessMode) {
     openDirectory: function(leafName, accessMode) {
  //Unix:    lazy
  //Unix:    lazy -- may call [openat]
  //Windows: lazy
  //Windows: lazy
     },
     },
Line 438: Line 403:
  //Unix:    maps to [opendir], [dfd], [readdir]/[readdir64], lazy calls to [stat]
  //Unix:    maps to [opendir], [dfd], [readdir]/[readdir64], lazy calls to [stat]
  //Windows: maps to [FindFirstFile], [FindNextFile], [Close]
  //Windows: maps to [FindFirstFile], [FindNextFile], [Close]
 
    }


= Not implemented =
= Not implemented =
Line 448: Line 413:
* linking -- very different between platforms
* linking -- very different between platforms
* readString, writeString -- ArrayBuffer <-> String conversion most likely deserves its own API
* readString, writeString -- ArrayBuffer <-> String conversion most likely deserves its own API
* opening a file or directory from a full path -- error-prone, difficult to optimize, favors hardcoding non-portable paths
= Implementation notes =
* For the moment, the JS team does not recommend using js-ctypes for performance-critical code. Rather, they recommend using JS API, so this is probably the right way to go.
* This is JS code, so by definition not thread-safe.
* Depending on demands by API users, a C++ version may be produced. In this case, we will probably want to make it MT-safe.
Yoric
184

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/353512"