nsIFile

IID:c8c0a080-0868-11d3-915f-d9d889d48e3c
Inherits From:nsISupports
Status:FROZEN

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.

This interface is implemented by the following components:


Constants

Create Types

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

PRUint32 NORMAL_FILE_TYPE = 0
PRUint32 DIRECTORY_TYPE = 1

Properties

readonly nsISimpleEnumerator directoryEntries

Returns an enumeration of the elements in a directory. Each element in the enumeration is an nsIFile.

PRInt64 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 PRInt64 fileSizeOfLink

PRInt64 lastModifiedTime

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

PRInt64 lastModifiedTimeOfLink

AString leafName

Accessor to the leaf name of the file itself. For the nativeLeafName method, the nativeLeafName must be in the native filesystem charset.

ACString nativeLeafName

readonly ACString nativePath

readonly ACString nativeTarget

readonly nsIFile parent

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

readonly AString path

PRUint32 permissions

Attributes of nsIFile.

PRUint32 permissionsOfLink

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


Methods

void append ( AString node ) [noscript] void appendNative ( ACString node ) nsIFile clone ( ) PRBool contains ( nsIFile inFile , PRBool recur ) void copyTo ( nsIFile newParentDir , AString newName ) void copyToFollowingLinks ( nsIFile newParentDir , AString newName ) [noscript] void copyToFollowingLinksNative ( nsIFile newParentDir , ACString newName ) [noscript] void CopyToNative ( nsIFile newParentDir , ACString newName ) void create ( PRUint32 type , PRUint32 permissions ) void createUnique ( PRUint32 type , PRUint32 permissions ) PRBool equals ( nsIFile inFile ) PRBool exists ( ) PRBool isDirectory ( ) PRBool isExecutable ( ) PRBool isFile ( ) PRBool isHidden ( ) PRBool isReadable ( ) PRBool isSpecial ( ) PRBool isSymlink ( ) PRBool isWritable ( ) void moveTo ( nsIFile newParentDir , AString newName ) [noscript] void moveToNative ( nsIFile newParentDir , ACString newName ) void normalize ( ) void remove ( PRBool recursive )

void append ( AString node )

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

Arguments:
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 appendNative ( ACString node )

Arguments:
node

nsIFile clone ( )

Clone()

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


PRBool contains ( nsIFile inFile , PRBool recur )

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

Arguments:
inFile
recur

void copyTo ( nsIFile newParentDir , AString newName )

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.

Arguments:
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 copyToFollowingLinks ( nsIFile newParentDir , AString newName )

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.

Arguments:
newParentDir
newName

void copyToFollowingLinksNative ( nsIFile newParentDir , ACString newName )

Arguments:
newParentDir
newName

void CopyToNative ( nsIFile newParentDir , ACString newName )

Arguments:
newParentDir
newName

void create ( PRUint32 type , PRUint32 permissions )

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.

Arguments:
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 createUnique ( PRUint32 type , PRUint32 permissions )

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.

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

PRBool equals ( nsIFile inFile )

Will determine if the inFile equals this.

Arguments:
inFile

PRBool exists ( )


PRBool isDirectory ( )


PRBool isExecutable ( )


PRBool isFile ( )


PRBool isHidden ( )


PRBool isReadable ( )


PRBool isSpecial ( )

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


PRBool isSymlink ( )


PRBool isWritable ( )


void moveTo ( nsIFile newParentDir , AString newName )

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.

Arguments:
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 moveToNative ( nsIFile newParentDir , ACString newName )

Arguments:
newParentDir
newName

void normalize ( )

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


void remove ( PRBool 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.

Arguments:
recursive

References

This interface is the type of the following properties:

inIFileSearch.currentDirectory, inIFileSearch.searchPath, nsICacheEntryDescriptor.file, nsICachingChannel.cacheFile, nsICommandLine.workingDirectory, nsIDirectoryEnumerator.nextFile, nsIFile.parent, nsIFileChannel.file, nsIFileURL.file, nsIHelperAppLauncher.targetFile, nsIIncrementalDownload.destination, nsIInstallLocation.location, nsIJVMConfig.mozillaPluginPath, nsIJVMConfig.path, nsIMIMEInfo.preferredApplicationHandler, nsIProcess.location, nsIProfileInternal.defaultProfileParentDir, nsIProfileStartup.directory, nsIZipReader.file

This interface is passed as an argument to the following methods:

imgIEncoder.encodeClipboardImage, inIFileSearch.getDirectoryDepth, inIFileSearch.getSubDirectories, nsIAddrDatabase.open, nsICommandLineRunner.init, nsIComponentLoader.autoRegisterComponent, nsIComponentLoader.autoRegisterComponents, nsIComponentLoader.autoUnregisterComponent, nsIComponentLoaderManager.getOptionalData, nsIComponentLoaderManager.hasFileChanged, nsIComponentLoaderManager.removeFileInfo, nsIComponentLoaderManager.saveFileInfo, nsIComponentLoaderManager.setOptionalData, nsIComponentManagerObsolete.autoRegister, nsIComponentManagerObsolete.autoRegisterComponent, nsIComponentManagerObsolete.autoUnregisterComponent, nsIComponentManagerObsolete.registerComponentSpec, nsIComponentManagerObsolete.registerComponentWithType, nsIComponentManagerObsolete.registryLocationForSpec, nsIComponentManagerObsolete.unregisterComponentSpec, nsIComponentRegistrar.autoRegister, nsIComponentRegistrar.autoUnregister, nsIComponentRegistrar.registerFactoryLocation, nsIComponentRegistrar.unregisterFactoryLocation, nsIDownloadObserver.onDownloadComplete, nsIDownloader.init, nsIEditorLogging.startLogging, nsIExtensionManager.installItemFromFile, nsIFastLoadService.addDependency, nsIFastLoadService.cacheChecksum, nsIFastLoadService.computeChecksum, nsIFastLoadWriteControl.addDependency, nsIFile.CopyToNative, nsIFile.contains, nsIFile.copyTo, nsIFile.copyToFollowingLinks, nsIFile.copyToFollowingLinksNative, nsIFile.equals, nsIFile.moveTo, nsIFile.moveToNative, nsIFileInputStream.init, nsIFileOutputStream.init, nsIFileProtocolHandler.getURLSpecFromFile, nsIFileProtocolHandler.newFileURI, nsIFileProtocolHandler.readURLFile, nsIFileView.setDirectory, nsIHelperAppLauncher.launchWithApplication, nsIHelperAppLauncher.saveToDisk, nsIIOService.newFileURI, nsIIncrementalDownload.init, nsIInstallLocation.getIDForLocation, nsIMIMEInfo.launchWithFile, nsIMIMEService.getTypeFromFile, nsIModule.registerSelf, nsIModule.unregisterSelf, nsIPasswordManagerInternal.readPasswords, nsIPref.readUserPrefs, nsIPref.savePrefFile, nsIPrefService.readUserPrefs, nsIPrefService.savePrefFile, nsIProcess.init, nsIProfileInternal.getCurrentProfileDir, nsIProfileInternal.updateRegistry, nsIRegistry.open, nsIZipReader.extract, nsIZipReader.init, nsIZipReaderCache.getZip, nsPIExternalAppLauncher.deleteTemporaryFileOnExit, nsPIXPIStubHook.StubInitialize

This interface is returned from the following methods:

inIFileSearch.getFileResultAt, nsICommandLine.resolveFile, nsIComponentManagerObsolete.specForRegistryLocation, nsIDirectoryServiceProvider.getFile, nsIFastLoadService.newFastLoadFile, nsIFile.clone, nsIFileProtocolHandler.getFileFromURLSpec, nsIInstallLocation.getItemFile, nsIInstallLocation.getItemLocation, nsIMsgMailSession.getDataFilesDir, nsIProfileInternal.getProfileDir

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
No comments available

Copyright © 1999 - 2005 XULPlanet.com