Mozilla

• About
• Developers
• Store
• Support
• Products

nsIFile

---

This interface is the only correct cross-platform way to specify a file. Strings are not such a way. Despite the fact that they work on Windows or Unix, they will not work here.

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 UCS-2 forms are scriptable, but the "native" methods are not.

Methods

append

appendNative

Makes a descendent of the current nsIFile.

Syntax:

void nsIFile::append(in AString node) 
[noscript] void nsIFile::appendNative(in ACString node) 

Parameters:

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.

nsresult:

NS_OK if successful.

normalize

Normalizes the pathName (e.g. removing .. and . components on Unix).

Syntax:

void nsIFile::normalize()  

Parameters:

None.

nsresult:

NS_OK if successful.

create

Creates 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 returns NS_ERROR_FILE_ALREADY_EXISTS.

Syntax:

void nsIFile::create(in unsigned long type,
	in unsigned long permissions)  

Parameters:

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 below. If the type is unrecognized, returns (NS_ERROR_FILE_UNKNOWN_TYPE).

permissions: Unix style octal permissions. This may be ignored on systems that do not need to do permissions.

nsresult:

NS_OK if successful.

copyTo

CopyToNative

Copies this file to the specified newParentDir. If a newName is specified, the file will be renamed. If 'this' is not created, returns the 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.

Syntax:

void nsIFile::copyTo(in nsIFile newParentDir, 
	in AString newName) 
[noscript] void nsIFile::CopyToNative(
	in nsIFile newParentDir, in ACString newName) 

Parameters:

newParentDir: The destination directory. If the newParentDir is empty, 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.

nsresult:

NS_OK if successful.

copyToFollowingLinks

copyToFollowingLinksNative

Is identical to copyTo except, as the name implies, it follows symbolic links. The XP_UNIX implementation always follows symbolic links when copying.

Syntax:

void nsIFile::copyToFollowingLinks(
	in nsIFile newParentDir, in AString newName) 
{noscript] void nsIFile::copyToFollowingLinksNative(
	in nsIFile newParentDir, in ACString newName) 

Parameters:

newParentDir: The destination directory. If the newParentDir is empty, 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).

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. For the copyToFollowingLinksNative method, the newName must be in the native filesystem charset.

nsresult:

NS_OK if successful.

moveTo

moveToNative

Moves this file to the specified newParentDir. If a newName is specified, the file will be renamed. If 'this' is not created, returns an error (NS_ERROR_FILE_TARGET_DOES_NOT_EXIST). moveTo will NOT resolve aliases/shortcuts during the copy. moveTo will do the right thing and allow copies across volumes.

Syntax:

void nsIFile::moveTo(in nsIFile newParentDir, 
	in AString newName) 
[noscript] void nsIFile::moveToNative(
	in nsIFile newParentDir, in ACString newName) 

Parameters:

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. For the moveToNative method, the newName must be in the native filesystem charset.

nsresult:

NS_OK if successful.

remove

Tries to delete this file. The 'recursive' flag must be PR_TRUE to delete directories which are not empty. It will not resolve any symlinks.

Syntax:

void nsIFile::remove(in boolean recursive)  

Parameters:

recursive: A boolean indicating whether or not to delete directories recursively.

nsresult:

NS_OK if successful.

exists

Determines if this file exists.

Syntax:

boolean nsIFile::exists()  

Parameters:

None.

Returns:

TRUE if it exists.

FALSE otherwise.

isWritable

Determines if this file is writable.

Syntax:

boolean nsIFile::isWritable()  

Parameters:

None.

Returns:

TRUE if it is writable.

FALSE otherwise.

isReadable

Determines if this file is readable.

Syntax:

boolean nsIFile::isReadable()  

Parameters:

None.

Returns:

TRUE if it is readable.

FALSE otherwise.

isExecutable

Determines if this file is executable.

Syntax:

boolean nsIFile::isExecutable()  

Parameters:

None.

Returns:

TRUE if it is executable.

FALSE otherwise.

isHidden

Determines if this file is hidden.

Syntax:

boolean nsIFile::isHidden()  

Parameters:

None.

Returns:

TRUE if it is hidden.

FALSE otherwise.

isDirectory

Determines if this file is a directory.

Syntax:

boolean nsIFile::isDirectory()  

Parameters:

None.

Returns:

TRUE if it is a directory.

FALSE otherwise.

isFile

Determines if this file is a file.

Syntax:

boolean nsIFile::isFile()  

Parameters:

None.

Returns:

TRUE if it is a file.

FALSE otherwise.

isSymlink

Determines if this file is a symbolic link.

Syntax:

boolean nsIFile::isSymlink()  

Parameters:

None.

Returns:

TRUE if it is a symlink.

FALSE otherwise.

isSpecial

Determines if this file is other than a regular file, a directory, or a symbolic link.

Syntax:

boolean nsIFile::isSpecial()  

Parameters:

None.

Returns:

TRUE if it is not a file, a directory, or a symlink.

FALSE otherwise.

createUnique

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, this method tries variations on the leaf name "suggestedName" until it finds one that does not already exist. If the search for nonexistent files takes too long (thousands of the variants already exist), it gives up and return NS_ERROR_FILE_TOO_BIG.

Syntax:

void nsIFile::createUnique(in unsigned long type, 
	in unsigned long permissions) 

Parameters:

type: The type of file system object to be made. The only two types at this time are file and directory which are defined below. If the type is unrecongnized, returns an error (NS_ERROR_FILE_UNKNOWN_TYPE).

permissions: Unix style octal permissions. This may be ignored on systems that do not need to do permissions.

nsresult:

NS_OK if successful.

clone

Allocates and initializes an nsIFile object to the exact location of this nsIFile

Syntax:

nsIFile nsIFile::clone() 

Parameters:

None.

Returns:

An nsIFile with which this object will be initialized.

equals

Determines if inFile equals a comparison object.

Syntax:

boolean nsIFile::equals(in nsIFile inFile)  

Parameters:

inFile: The comparison object.

Returns:

TRUE if the files are equal.

FALSE otherwise.

contains

Determines if inFile is a descendant of this file. If recur is TRUE, it will also look in subdirectories.

Syntax:

boolean nsIFile::contains(in nsIFile inFile, 
	in boolean recur) 

Parameters:

inFile: The file to be evaluated.

recur: A boolean indicating whether subdirectories should be searched.

Returns:

TRUE if infile is a descendent of this file.

FALSE otherwise.

Attributes and Constants

attribute AString nsIFile::leafName

[noscript] attribute ACString nsIFile::nativeLeafName

Gets and sets the leaf name of the file itself. nativeLeafName must be in the native filesystem charset.

attribute unsigned long nsIFile::permissions

Gets and sets permissions status.

attribute unsigned long nsIFile::permissionsOfLink

Gets and set permissions of link status.

attribute PRInt64 nsIFile::lastModifiedTime

Gets and sets time of the last file modification. Times are stored as milliseconds from midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).

attribute PRInt64 nsIFile::lastModifiedTimeOfLink

Gets and sets time of the last symlink modification.Times are stored as milliseconds from midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).

attribute PRInt64 nsIFile::fileSize

Gets and sets the file size.

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.

readonly attribute PRInt64 nsIFile::fileSizeOfLink

Gets the symlink size.

readonly attribute AString nsIFile::target

[noscript] readonly attribute ACString nsIFile::nativeTarget

.Gets the target, ie, what the symlink points at. Gives an error (NS_ERROR_FILE_INVALID_PATH) if not a symlink. Note that the ACString attribute is returned in the native filesystem charset.

Warning: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., XP_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 USE TO PASS TO NSPR OR STDLIB!

readonly attribute AString nsIFile::path

[noscript] readonly attribute ACString nsIFile::nativePath

Gets the path, ie, what the nsIFile points at. In the native version, the ACString is returned in the native filesystem charset.

Warning: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., XP_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 USE TO PASS TO NSPR OR STDLIB!

readonly attribute nsIFile nsIFile::parent

Gets the parent of this file. Parent will be null when this file is at the top of the volume.

readonly attribute nsISimpleEnumerator directoryEntries

Gets an enumeration of the elements in a directory. Each element in the enumerator is an nsIFile. If the current nsIFile does not specify a dirctory, returns an error NS_ERROR_FILE_NOT_DIRECTORY.

const unsigned long NORMAL_FILE_TYPE=0

const unsigned long DIRECTORY_TYPE=1

Constants for type parameters. NORMAL_FILE_TYPE is a normal file and DIRECTORY_TYPE is a directory/folder.

• Site Map
• Security Updates
• Contact Us
• Donate

Portions of this content are © 1998–2009 by individual mozilla.org contributors; content available under a Creative Commons license | Details.

Last modified May 7, 2003 Document History