This is the only correct cross-platform way to specify a file. More...

import "nsIFile.idl";

Inheritance diagram for nsIFile:

Collaboration diagram for nsIFile:

Public Member Functions
void	append (in AString node)
	append[Native]
void	appendNative (in ACString node)
void	normalize ()
	Normalize the pathName (e.g.
void	create (in unsigned long type, in unsigned long permissions)
	create
void	copyTo (in nsIFile newParentDir, in AString newName)
	copyTo[Native]
void	CopyToNative (in nsIFile newParentDir, in ACString newName)
void	copyToFollowingLinks (in nsIFile newParentDir, in AString newName)
	copyToFollowingLinks[Native]
void	copyToFollowingLinksNative (in nsIFile newParentDir, in ACString newName)
void	moveTo (in nsIFile newParentDir, in AString newName)
	moveTo[Native]
void	moveToNative (in nsIFile newParentDir, in ACString newName)
void	remove (in boolean recursive)
	This will try to delete this file.
boolean	exists ()
boolean	isWritable ()
boolean	isReadable ()
boolean	isExecutable ()
boolean	isHidden ()
boolean	isDirectory ()
boolean	isFile ()
boolean	isSymlink ()
boolean	isSpecial ()
	Not a regular file, not a directory, not a symlink.
void	createUnique (in unsigned long type, in unsigned long permissions)
	createUnique
nsIFile	clone ()
	clone()
boolean	equals (in nsIFile inFile)
	Will determine if the inFile equals this.
boolean	contains (in nsIFile inFile, in boolean recur)
	Will determine if inFile is a descendant of this file If \|recur\| is true, look in subdirectories too.
Public Attributes
const unsigned long	NORMAL_FILE_TYPE = 0
	Create Types.
const unsigned long	DIRECTORY_TYPE = 1
attribute AString	leafName
	Accessor to the leaf name of the file itself.
attribute ACString	nativeLeafName
attribute unsigned long	permissions
	Attributes of nsIFile.
attribute unsigned long	permissionsOfLink
attribute PRInt64	lastModifiedTime
	File Times are to be in milliseconds from midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).
attribute PRInt64	lastModifiedTimeOfLink
attribute PRInt64	fileSize
	WARNING! On the Mac, getting/setting the file size with nsIFile only deals with the size of the data fork.
readonly attribute PRInt64	fileSizeOfLink
readonly attribute AString	target
	target & path
readonly attribute ACString	nativeTarget
readonly attribute AString	path
readonly attribute ACString	nativePath
readonly attribute nsIFile	parent
	Parent will be null when this is at the top of the volume.
readonly attribute nsISimpleEnumerator	directoryEntries
	Returns an enumeration of the elements in a directory.

Detailed Description

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.

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.

Member Function Documentation

void nsIFile::append ( in AString node )

append[Native]

This function is used for constructing a descendent of the current nsIFile.

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.

void nsIFile::appendNative ( in ACString node )

nsIFile nsIFile::clone ( )

clone()

This function will allocate and initialize a nsIFile object to the exact location of the |this| nsIFile.

Parameters:

file

A nsIFile which this object will be initialize with.

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

Will determine if inFile is a descendant of this file If |recur| is true, look in subdirectories too.

void nsIFile::copyTo	(	in nsIFile	newParentDir,
		in AString	newName
	)

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.

Parameters:

	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.

void nsIFile::copyToFollowingLinks	(	in nsIFile	newParentDir,
		in AString	newName
	)

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.

void nsIFile::copyToFollowingLinksNative	(	in nsIFile	newParentDir,
		in ACString	newName
	)

void nsIFile::CopyToNative	(	in nsIFile	newParentDir,
		in ACString	newName
	)

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

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.

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 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.

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

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.

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 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.

boolean nsIFile::equals ( in nsIFile inFile )

Will determine if the inFile equals this.

boolean nsIFile::exists ( )

boolean nsIFile::isDirectory ( )

boolean nsIFile::isExecutable ( )

boolean nsIFile::isFile ( )

boolean nsIFile::isHidden ( )

boolean nsIFile::isReadable ( )

boolean nsIFile::isSpecial ( )

Not a regular file, not a directory, not a symlink.

boolean nsIFile::isSymlink ( )

boolean nsIFile::isWritable ( )

void nsIFile::moveTo	(	in nsIFile	newParentDir,
		in AString	newName
	)

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.

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.

void nsIFile::moveToNative	(	in nsIFile	newParentDir,
		in ACString	newName
	)

void nsIFile::normalize ( )

Normalize the pathName (e.g.

removing .. and . components on Unix).

void nsIFile::remove ( in boolean recursive )

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.

Member Data Documentation

const unsigned long nsIFile::DIRECTORY_TYPE = 1

readonly attribute nsISimpleEnumerator nsIFile::directoryEntries

Returns an enumeration of the elements in a directory.

Each element in the enumeration is an nsIFile.

Returns:: NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does not specify a directory.

attribute PRInt64 nsIFile::fileSize

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

attribute PRInt64 nsIFile::lastModifiedTime

File Times are to be in milliseconds from midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).

attribute PRInt64 nsIFile::lastModifiedTimeOfLink

attribute AString nsIFile::leafName

Accessor to the leaf name of the file itself.

For the |nativeLeafName| method, the nativeLeafName must be in the native filesystem charset.

attribute ACString nsIFile::nativeLeafName

readonly attribute ACString nsIFile::nativePath

readonly attribute ACString nsIFile::nativeTarget

const unsigned long nsIFile::NORMAL_FILE_TYPE = 0

Create Types.

NORMAL_FILE_TYPE - A normal file. DIRECTORY_TYPE - A directory/folder.

readonly attribute nsIFile nsIFile::parent

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

readonly attribute AString nsIFile::path

attribute unsigned long nsIFile::permissions

Attributes of nsIFile.

attribute unsigned long nsIFile::permissionsOfLink

readonly attribute AString nsIFile::target

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.

The documentation for this interface was generated from the following file:

nsIFile.idl

nsIFile Interface Reference

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation