MozillaWiki

JSFileApi: Difference between revisions

Page Discussion

JSFileApi (view source)

Revision as of 14:33, 12 January 2013

213 bytes added ,  12 January 2013
no edit summary
No edit summary
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
This page details a proposal for [https://bugzilla.mozilla.org/show_bug.cgi?id=563742 Bug 563742 - Efficient ctypes API for file handling].
This page details a proposal for [https://bugzilla.mozilla.org/show_bug.cgi?id=563742 Bug 563742 - Efficient ctypes API for file handling].
'''Note''' This is an early draft. The final API is documented [https://developer.mozilla.org/en/JavaScript_OS.File on MDN].


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.


''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.
'''Conventions''' This document uses the conventions of [http://code.google.com/closure/compiler/docs/js-for-compiler.html the Google Closure Compiler] for  type annotations.


= Problems addressed by this API  =
= Problems addressed by this API  =
Line 36: Line 38:
== Access a file or a directory ==
== Access a file or a directory ==
   
   
 
     /**
     /**
       * Create a temporary directory.
       * Create a temporary file in the system-defined temporary directory (if it exists). This file is deleted when the process closes or when the file is closed, whichever happens first.
       *
       *
      * Note: For the time being, there is no guarantee *when* the temporary directory is cleaned
       * @param {string=} name An optional name that can be used for debugging purposes as a template for the name of the file created.
      *
       */
       * @returns {RawDir} a descriptor which may be used to access this directory
     createTempFile: function(name) {
       */  
  //Unix:       uses cached [nsIDirectoryService] to get temporary directoy, [mkstemp] and [this.openFile]
     createTempDirectory: function() {
  //Windows:     uses cached [nsIDirectoryService] to get temporary directory, [GetTempFileName] + [CreateFile] http://msdn.microsoft.com/en-us/library/windows/desktop/aa363875%28v=vs.85%29.aspx
  //Unix:   [Files.tmpdir] followed by [mkdtemp] and [Files.openDirectory]
  //Windows: [Files.tmpdir] followed by [GetTempFileName] and [Files.openDirectory]
     },
     },
 
   
   
== General utilities ==  
== General utilities ==  
Line 192: Line 192:


== Interfaces ==
== Interfaces ==
=== File Information ===
   
   
     /**
     /**
       * The kind of information that can be found by calling [RawFile.info] or [RawDir.forEachFile].
       * The kind of information that can be found by calling [RawFile.info] or [RawDir.contents].
       *
       *
       * Note that some or all fields may be computed lazily.
       * Note that some or all fields may be computed lazily.
Line 227: Line 228:
         }
         }
     },
     },
=== Directory entries ===
    DirEntry: {
        /**
        * The name of the file.
        *
        * Note that there is no guarantee that the file still exists by the time you attempt to open it.
        *
        * @return {string=}
        */
        get name(): { ...
        },
   
   
        /**
        * All the information that could be gathered about the file without opening it.
        *
        * @return {FileInfo}
        */
        get info(): { ...
            //Precomputed by [RawDir.contents]
        }
    },
=== Errors ===
     /**
     /**
       * An exception launched by this module.
       * An exception launched by this module.
Line 238: Line 262:
     Error: function(){}
     Error: function(){}


= Instances of RawFile =  
= Instances of <tt>RawFile</tt> =  


A <tt>RawFile</tt> is a low-level object wrapping a native file descriptor (under variants of Unix) or a file handle (under Windows).
A <tt>RawFile</tt> is a low-level object wrapping a native file descriptor (under variants of Unix) or a file handle (under Windows).
Line 353: Line 377:
  //Windows: [FlushFileBuffers] http://msdn.microsoft.com/en-us/library/windows/desktop/aa364439(v=VS.85).aspx
  //Windows: [FlushFileBuffers] http://msdn.microsoft.com/en-us/library/windows/desktop/aa364439(v=VS.85).aspx
     },
     },
= Instances of RawDir =


A <tt>RawDir</tt> is a slightly higher-level object wrapping a directory _name_ (for reasons of portability & iteration, this seemed more appropriate than _opening_ the directory during construction). On the Unix side, some of the methods rely upon (or have to reimplement) systems that obey recent versions of Posix, with functions such as <tt>openat</tt>.
= Instances of <tt>RawDir</tt> =
 
A <tt>RawDir</tt> is an object wrapping either a directory ''name'' or a directory descriptor, depending on the platform. On the Unix side, some of the methods rely upon (or have to reimplement) systems that obey recent versions of Posix, with functions such as <tt>openat</tt>.


== Opening/creating ==
== Opening/creating ==
Line 378: Line 402:
   
   
     /**
     /**
       * Create a temporary file in this directory. This file is deleted when the process closes, when the file is closed.
       * Create a temporary file in this directory. This file is deleted when the process closes or when the file is closed, whichever happens first.
       */
       */
     createTempFile: function() {
     createTempFile: function() {
Line 399: Line 423:
   
   
     /**
     /**
       * Create a temporary directory.
       * Create a temporary subdirectory.
       *
       *
       * 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 that the temporary directory will be cleaned
Line 421: Line 445:


== Browsing contents ==
== Browsing contents ==
This API provides three ways of browsing contents:
* using the directory as an iterator;
* using the more powerful function [forEachMap], which also provides fast filtering on platforms where it is possible.
   
   
     /**
     /**
       * Apply a treatment to all files in the directory.
       * Get the contents of the directory.
      *
      * Note: objects of type RawDir are iterable. Therefore, you can also loop through them using a standard [for..in].
       *
       *
       * @param {string=} filter. If provided, uses OS-accelerated, platform-specific, filtering, where available.
       * @param {string=} filter. If provided, uses OS-accelerated, platform-specific, filtering, where available.
       * @param {function(string, RawFile.FileInfo, number, function() RawFile)} onFile  A function called for each file in the directory, with the name of the file, a (lazy) file info for that file and a file number. If the function returns anything [null], the loop stops immediately and returns the value returned by that function.
       * @return {Array.<Files.DirEntry>} The list of files of the directory that match the filter.
      *
      * @returns The first value returned by [onFile], or [undefined] otherwise.
       */
       */
     forEachFile: function(filter, onFile) {
     contents: function(filter) {    
  //Unix:    maps to [opendir], [dfd], [readdir]/[readdir64], lazy calls to [stat], lazy calls to [openat]/[open], [closedir]
  //Unix:    maps to [opendir], [dfd], [readdir]/[readdir64], lazy calls to [stat], lazy calls to [openat]/[open], [closedir]
  //Windows: maps to [FindFirstFile], [FindNextFile], [Close]
  //Windows: maps to [FindFirstFile], [FindNextFile], [Close]
Yoric
184

edits

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