Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes
nsIFile Interface Reference

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

import "nsIFile.idl";

Inheritance diagram for nsIFile:
Inheritance graph
[legend]
Collaboration diagram for nsIFile:
Collaboration graph
[legend]

List of all members.

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.

FROZEN

Definition at line 62 of file nsIFile.idl.


Member Function Documentation

void nsIFile::append ( in AString  node)

append[Native]

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

Parameters:
nodeA 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)

clone()

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

Parameters:
fileA 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:
newParentDirThis 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.
newNameThis 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 
)

Here is the caller graph for this function:

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:
typeThis 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).
permissionsThe 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:
typeThis 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).
permissionsThe unix style octal permissions. This may be ignored on systems that do not need to do permissions.

Will determine if the inFile equals this.

Here is the caller graph for this function:

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

Here is the caller graph for this function:

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.

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:
newParentDirThis 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.
newNameThis 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 
)

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

Definition at line 71 of file nsIFile.idl.

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.

Definition at line 336 of file nsIFile.idl.

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.

Definition at line 227 of file nsIFile.idl.

Definition at line 228 of file nsIFile.idl.

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

Definition at line 218 of file nsIFile.idl.

Definition at line 219 of file nsIFile.idl.

Accessor to the leaf name of the file itself.

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

Definition at line 119 of file nsIFile.idl.

Definition at line 120 of file nsIFile.idl.

readonly attribute ACString nsIFile::nativePath

Definition at line 258 of file nsIFile.idl.

readonly attribute ACString nsIFile::nativeTarget

Definition at line 256 of file nsIFile.idl.

Create Types.

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

Definition at line 70 of file nsIFile.idl.

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

Definition at line 327 of file nsIFile.idl.

readonly attribute AString nsIFile::path

Definition at line 257 of file nsIFile.idl.

Attributes of nsIFile.

Definition at line 210 of file nsIFile.idl.

Definition at line 211 of file nsIFile.idl.

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

Definition at line 255 of file nsIFile.idl.


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