An nsIFile is an abstract representation of a filename. It manages
filename encoding issues, pathname component separators (‘/’ vs. ‘\’
vs. ‘:’) and weird stuff like differing volumes with identical names, as
on pre-Darwin Macintoshes.
This file has long introduced itself to new hackers with this opening
paragraph:
This is the only correct cross-platform way to specify a file.
Strings are not such a way. If you grew up on windows or unix, you
may think they are. Welcome to reality.
While taking the pose struck here to heart would be uncalled for, one
may safely conclude that writing cross-platform code is an embittering
experience.
All methods with string parameters have two forms. The preferred
form operates on UCS-2 encoded characters strings. An alternate
form operates on characters strings encoded in the “native” charset.
A string containing characters encoded in the native charset cannot
be safely passed to javascript via xpconnect. Therefore, the “native
methods” are not scriptable.
append[Native]
This function is used for constructing a descendent of the
current nsIFile.
| node | A string which is intended to be a child node of the nsIFile. For the |appendNative| method, the node must be in the native filesystem charset. |
Normalize the pathName (e.g. removing .. and . components on Unix).
create
This function will create a new file or directory in the
file system. Any nodes that have not been created or
resolved, will be. If the file or directory already
exists create() will return NS_ERROR_FILE_ALREADY_EXISTS.
| type | This specifies the type of file system object to be made. The only two types at this time are file and directory which are defined above. If the type is unrecongnized, we will return an error (NS_ERROR_FILE_UNKNOWN_TYPE). |
| permissions | The unix style octal permissions. This may be ignored on systems that do not need to do permissions. |
copyTo[Native]
This will copy this file to the specified newParentDir.
If a newName is specified, the file will be renamed.
If ‘this’ is not created we will return an error
(NS_ERROR_FILE_TARGET_DOES_NOT_EXIST).
copyTo may fail if the file already exists in the destination
directory.
copyTo will NOT resolve aliases/shortcuts during the copy.
| newParentDir | This param is the destination directory. If the newParentDir is null, copyTo() will use the parent directory of this file. If the newParentDir is not empty and is not a directory, an error will be returned (NS_ERROR_FILE_DESTINATION_NOT_DIR). For the |CopyToNative| method, the newName must be in the native filesystem charset. |
| newName | This param allows you to specify a new name for the file to be copied. This param may be empty, in which case the current leaf name will be used. |
copyToFollowingLinks[Native]
This function is identical to copyTo with the exception that,
as the name implies, it follows symbolic links. The XP_UNIX
implementation always follow symbolic links when copying. For
the |CopyToFollowingLinks| method, the newName must be in the
native filesystem charset.
moveTo[Native]
A method to move this file or directory to newParentDir.
If a newName is specified, the file or directory will be renamed.
If ‘this’ is not created we will return an error
(NS_ERROR_FILE_TARGET_DOES_NOT_EXIST).
If ‘this’ is a file, and the destination file already exists, moveTo
will replace the old file.
This object is updated to refer to the new file.
moveTo will NOT resolve aliases/shortcuts during the copy.
moveTo will do the right thing and allow copies across volumes.
moveTo will return an error (NS_ERROR_FILE_DIR_NOT_EMPTY) if ‘this’ is
a directory and the destination directory is not empty.
moveTo will return an error (NS_ERROR_FILE_ACCESS_DENIED) if ‘this’ is
a directory and the destination directory is not writable.
| newParentDir | This param is the destination directory. If the newParentDir is empty, moveTo() will rename the file within its current directory. If the newParentDir is not empty and does not name a directory, an error will be returned (NS_ERROR_FILE_DESTINATION_NOT_DIR). For the |moveToNative| method, the newName must be in the native filesystem charset. |
| newName | This param allows you to specify a new name for the file to be moved. This param may be empty, in which case the current leaf name will be used. |
renameTo
This method is identical to moveTo except that if this file or directory
is moved to a a different volume, it fails and returns an error
(NS_ERROR_FILE_ACCESS_DENIED).
This object will still point to the old location after renaming.
This will try to delete this file. The ‘recursive’ flag
must be PR_TRUE to delete directories which are not empty.
This will not resolve any symlinks.
Not a regular file, not a directory, not a symlink.
createUnique
This function will create a new file or directory in the
file system. Any nodes that have not been created or
resolved, will be. If this file already exists, we try
variations on the leaf name “suggestedName” until we find
one that did not already exist.
If the search for nonexistent files takes too long
(thousands of the variants already exist), we give up and
return NS_ERROR_FILE_TOO_BIG.
| type | This specifies the type of file system object to be made. The only two types at this time are file and directory which are defined above. If the type is unrecongnized, we will return an error (NS_ERROR_FILE_UNKNOWN_TYPE). |
| permissions | The unix style octal permissions. This may be ignored on systems that do not need to do permissions. |
clone()
This function will allocate and initialize a nsIFile object to the
exact location of the |this| nsIFile.
| file | A nsIFile which this object will be initialize with. |
Will determine if the inFile equals this.
Will determine if inFile is a descendant of this file.
This routine looks in subdirectories too.
initWith[Native]Path
This function will initialize the nsIFile object. Any
internal state information will be reset.
| filePath | A string which specifies a full file path to a location. Relative paths will be treated as an error (NS_ERROR_FILE_UNRECOGNIZED_PATH). For initWithNativePath, the filePath must be in the native filesystem charset. |
initWithFile
Initialize this object with another file
| aFile | the file this becomes equivalent to |
Return the result of PR_Open on the file. The caller is
responsible for calling PR_Close on the result.
| flags | the PR_Open flags from prio.h, plus optionally OS_READAHEAD or DELETE_ON_CLOSE. OS_READAHEAD is a hint to the OS that the file will be read sequentially with agressive readahead. DELETE_ON_CLOSE is unreliable on Windows and is deprecated. Instead use NS_OpenAnonymousTemporaryFile() to create a temporary file which will be deleted upon close. |
Return the result of fopen on the file. The caller is
responsible for calling fclose on the result.
Return the result of PR_LoadLibrary on the file. The caller is
responsible for calling PR_UnloadLibrary on the result.
appendRelative[Native]Path
Append a relative path to the current path of the nsIFile object.
| relativeFilePath | relativeFilePath is a native relative path. For security reasons, this cannot contain .. or cannot start with a directory separator. For the |appendRelativeNativePath| method, the relativeFilePath must be in the native filesystem charset. |
reveal
Ask the operating system to open the folder which contains
this file or folder. This routine only works on platforms which
support the ability to open a folder and is run async on Windows.
This routine must be called on the main.
launch
Ask the operating system to attempt to open the file.
this really just simulates “double clicking” the file on your platform.
This routine only works on platforms which support this functionality
and is run async on Windows. This routine must be called on the
main thread.
getRelativeDescriptor
Returns a relative file path in an opaque, XP format. It is therefore
not a native path.
The character set of the string returned from this function is
undefined. DO NOT TRY TO INTERPRET IT AS HUMAN READABLE TEXT!
| fromFile | the file from which the descriptor is relative. There is no defined result if this param is null. |
setRelativeDescriptor
Initializes the file to the location relative to fromFile using
a string returned by getRelativeDescriptor.
| fromFile | the file to which the descriptor is relative |
| relative | the relative descriptor obtained from getRelativeDescriptor |
Accessor to the leaf name of the file itself.
For the |nativeLeafName| method, the nativeLeafName must
be in the native filesystem charset.
Attributes of nsIFile.
File Times are to be in milliseconds from
midnight (00:00:00), January 1, 1970 Greenwich Mean
Time (GMT).
WARNING! On the Mac, getting/setting the file size with nsIFile
only deals with the size of the data fork. If you need to
know the size of the combined data and resource forks use the
GetFileSizeWithResFork() method defined on nsILocalFileMac.
target & path
Accessor to the string path. The native version of these
strings are not guaranteed to be a usable path to pass to
NSPR or the C stdlib. There are problems that affect
platforms on which a path does not fully specify a file
because two volumes can have the same name (e.g., mac).
This is solved by holding “private”, native data in the
nsIFile implementation. This native data is lost when
you convert to a string.
DO NOT PASS TO USE WITH NSPR OR STDLIB!
target
Find out what the symlink points at. Will give error
(NS_ERROR_FILE_INVALID_PATH) if not a symlink.
path
Find out what the nsIFile points at.
Note that the ACString attributes are returned in the
native filesystem charset.
Parent will be null when this is at the top of the volume.
Returns an enumeration of the elements in a directory. Each
element in the enumeration is an nsIFile.
@throws NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does
not specify a directory.
followLinks
This attribute will determine if the nsLocalFile will auto
resolve symbolic links. By default, this value will be false
on all non unix systems. On unix, this attribute is effectively
a noop.
Accessor to a null terminated string which will specify
the file in a persistent manner for disk storage.
The character set of this attribute is undefined. DO NOT TRY TO
INTERPRET IT AS HUMAN READABLE TEXT!
Create Types
NORMAL_FILE_TYPE - A normal file.
DIRECTORY_TYPE - A directory/folder.
Flag for openNSPRFileDesc(), to hint to the OS that the file will be
read sequentially with agressive readahead.
Flag for openNSPRFileDesc(). Deprecated and unreliable!
Instead use NS_OpenAnonymousTemporaryFile() to create a temporary
file which will be deleted upon close!