In Gecko 14 this Interface was merged into the nsIFile
interface.
nsIFile
that are particular to a file that is accessible via the local file system.
nsIFile
Last changed in Gecko 1.0 Implemented by: @mozilla.org/file/local;1
. To create an instance, use:
var localFile = Components.classes["@mozilla.org/file/local;1"] .createInstance(Components.interfaces.nsILocalFile);
Method overview
void appendRelativeNativePath(in ACString relativeFilePath); Native code only! |
void appendRelativePath(in AString relativeFilePath); |
ACString getRelativeDescriptor(in nsILocalFile fromFile); |
void initWithFile(in nsILocalFile aFile); |
void initWithNativePath(in ACString filePath); Native code only! |
void initWithPath(in AString filePath); |
void launch(); |
PRLibraryStar load(); Native code only! |
FILE openANSIFileDesc(in string mode); Native code only! |
PRFileDescStar openNSPRFileDesc(in long flags, in long mode); Native code only! |
void reveal(); |
void setRelativeDescriptor(in nsILocalFile fromFile, in ACString relativeDesc); |
Attributes
Attribute | Type | Description |
diskSpaceAvailable |
PRInt64 |
The number of bytes available to non-superuser on the disk volume containing the nsILocalFile . Read only. |
followLinks |
PRBool |
Determines whether or not the false on all non-UNIX systems. As of Mozilla 1.7, this attribute is ignored on UNIX systems. |
persistentDescriptor |
ACString |
On some platforms, the value of nsIFile.path may be insufficient to uniquely identify the file on the local file system. The persistent descriptor is intended to be used whenever a Note: The value of the followLinks attribute is not encoded in the persistent descriptor. |
Constants
Constant | Value | Description |
DELETE_ON_CLOSE |
0x80000000 |
Optional parameter used by openNSPRFileDesc() . |
Methods
appendRelativeNativePath
Appends a relative, native character encoding, path to the current path of the nsILocalFile
object.
void appendRelativeNativePath( in ACString relativeFilePath );
Parameters
relativeFilePath
- A native relative path. For security reasons, this cannot contain '..' or cannot start with a directory separator '/'. Must be in the native file system character set.
Exceptions thrown
NS_ERROR_FILE_UNRECOGNIZED_PATH
- Indicates that
relativeFilePath
incorrectly begins with a path separator character or otherwise contains invalid characters.
appendRelativePath()
Appends a relative native path to the current path of the nsILocalFile
object.
void appendRelativePath( in AString relativeFilePath );
Parameters
relativeFilePath
- A native relative path. For security reasons, this cannot contain '..' or cannot start with a directory separator '/' .
Exceptions thrown
NS_ERROR_FILE_UNRECOGNIZED_PATH
- Indicates that
relativeFilePath
incorrectly begins with a path separator character or otherwise contains invalid characters.
getRelativeDescriptor()
Returns a relative file path in an opaque, cross platform format. It is therefore not a native path.
ACString getRelativeDescriptor( in nsILocalFile fromFile );
Parameters
fromFile
- The file from which the descriptor is relative. There is no defined result if this parameter is
null
.
Return value
An opaque string value with undefined character encoding. This string is not intended for display to users.
The result returned from this method may be used with setRelativeDescriptor()
to initialize a nsILocalFile
instance.
initWithFile()
Initializes this object with another file.
void initWithFile( in nsILocalFile aFile );
Parameters
aFile
- The file this becomes equivalent to.
initWithNativePath()
Used to set the full path that this nsILocalFile
references. All current settings will be reset.
void initWithNativePath( in ACString filePath );
Parameters
filePath
- A string that specifies a platform-specific, full path to a file or directory. Must be in the native file system character set.
Exceptions thrown
NS_ERROR_FILE_UNRECOGNIZED_PATH
- Indicates that FilePath is not an absolute file path.
initWithPath()
Used to set the full path that this nsILocalFile
references. All current settings will be reset.
void initWithPath( in AString filePath );
Parameters
filePath
- A string that specifies a platform-specific, full path to a file or directory.
Exceptions thrown
NS_ERROR_FILE_UNRECOGNIZED_PATH
- Indicates that FilePath is not an absolute file path.
launch()
Requests that the operating system attempt to open this file.
void launch();
Parameters
None.
load
Returns the result of PR_LoadLibrary()
on the file. The caller is responsible for calling PR_UnloadLibrary()
on the result.
PRLibraryStar load();
Parameters
None.
Return value
A pointer to a PRLibrary
.
Example
#include "prlink.h" #include "nsError.h" #include "nsILocalFile.h" // Load the DLL corresponding to the given nsILocalFile... nsresult LoadDLL(nsILocalFile *aLocalFile) { PRLibrary *dll; nsresult rv = aLocalFile->Load(&dll); if (NS_FAILED(rv)) return rv; // Do something with the library now that it is open... PR_FreeLibrary(dll); return NS_OK; }
openANSIFileDesc
Returns the result of fopen()
on the file. The caller is responsible for calling fclose()
on the result.
FILE openANSIFileDesc( in string mode );
Parameters
mode
- An ANSI file open mode string, which will be passed to
fopen()
.
Return value
A pointer to an ANSI FILE
type.
Example
#include <stdio.h> #include "nsError.h" #include "nsILocalFile.h" // Read the contents of a nsILocalFile... nsresult ReadLocalFile(nsILocalFile *aLocalFile) { FILE *fp; nsresult rv = aLocalFile->OpenANSIFileDesc("r", &fp); if (NS_FAILED(rv)) return rv; char buf[512]; size_t n; while ((n = fread(buf, sizeof(buf), 1, fp)) > 0) { // Do something with n-byte block of data from file... } if (ferror(fp) != 0) rv = NS_ERROR_UNEXPECTED; fclose(fp); return rv; }
openNSPRFileDesc
Returns the result of PR_Open()
on the file. The caller is responsible for calling PR_Close()
on the result.
PRFileDescStar openNSPRFileDesc( in long flags, in long mode );
Parameters
flags
-
The
PR_Open()
flags fromnsprpub/pr/include/prio.h
, plus optionallyDELETE_ON_CLOSE
.DELETE_ON_CLOSE
may be implemented by removing the file (by path name) immediately after opening it, so beware of possible races; the file should be exclusively owned by this process.A bitwise combination of the following open flags:
PR_RDONLY
Open for reading only.PR_WRONLY
Open for writing only.PR_RDWR
Open for reading and writing.PR_CREATE_FILE
If the file does not exist, the file is created. If the file exists, this flag has no effect.PR_APPEND
The file pointer is set to the end of the file prior to each write.PR_TRUNCATE
If the file exists, its length is truncated to 0.PR_SYNC
If set, each write will wait for both the file data and file status to be physically updated.PR_EXCL
WithPR_CREATE_FILE
, if the file does not exist, the file is created. If the file already exists, no action and null is returned.DELETE_ON_CLOSE
File will be deleted when closed.
mode
- A UNIX-style file permissions value. For example, the octal value 0600 may be used to limit read and write access to the current user of the system. This parameter may be ignored on systems that do not support file permissions.
Return value
If the file is successfully opened, returns a pointer to the PRFileDesc
created for the newly opened file. Returns a null pointer if the open failed.
Example
#include "prio.h" #include "nsError.h" #include "nsILocalFile.h" // Read the contents of a nsILocalFile... nsresult ReadLocalFile(nsILocalFile *aLocalFile) { PRFileDesc *fd; nsresult rv = aLocalFile->OpenNSPRFileDesc(PR_RDONLY, 0, &fd); if (NS_FAILED(rv)) return rv; char buf[512]; PRInt32 n; while ((n = PR_Read(fd, buf, sizeof(buf))) > 0) { // Do something with n-byte block of data from file... } if (n < 0) rv = NS_ERROR_UNEXPECTED; PR_Close(fd); return rv; }
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. See the note in the remarks below.
void reveal();
Parameters
None.
setRelativeDescriptor()
Initializes the file to the location relative to fromFile
using a string returned by getRelativeDescriptor()
.
void setRelativeDescriptor( in nsILocalFile fromFile, in ACString relativeDesc );
Parameters
fromFile
- The file to which the descriptor is relative.
relativeDesc
- The relative descriptor obtained from
getRelativeDescriptor()
.
Remarks
The methods initWithNativePath()
and appendRelativeNativePath()
take string valued parameters that are encoded using the native character encoding. That means, you cannot deal with files whose name contain characters outside the default code page on Windows even though Windows 2000 or later has no problem with them. Therefore, never use these functions unless you are absolutely sure that the path passed to them is always ASCII-only. See nsIFile
for more information on the native character encoding.