nsIFile
From MDC
Contents |
[edit] Summary
An instance of nsIFile is a cross-platform representation of a location in the filesystem. With an nsIFile you can navigate to ancestors or descendants without having to deal with the different path separators used on different platforms, query the state of any file or directory at the position represented by the nsIFile and create, move or copy items in the filesystem.
An nsIFile can be retrieved by either instantiating an nsILocalFile using a platform specific path string or by using cross-platform locations retrieved from the directory service.
All methods with string parameters have two forms. The preferred form operates on UTF-16 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 UTF-16 forms are scriptable, but the "native methods" are not. In addition, the native form cannot deal with files whose name contain charcters outside the default system code page on Windows. Using the native form limits the ability of your code to deal with the full Unicode support on Windows 2000 or later where the OS itself does not have such a limitation. Therefore, you must not use the native form unless it is guaranteed that the path passed to a native form function is always ASCII.
#include "nsIFile.h"
[scriptable, uuid=(c8c0a080-0868-11d3-915f-d9d889d48e3c)]
interface nsIFile : nsISupports { ... };
[edit] Methods
-
append - This method is used for constructing a descendent of the current nsIFile.
-
appendNative - This method is used for constructing a descendent of the current nsIFile. [native character encoding variant]
-
normalize - This method is used to canonicalize the path represented by this nsIFile.
-
create - This method creates a new file or directory corresponding to the file path represented by this nsIFile.
-
createUnique - This method creates a new, unique file or directory corresponding to the file path represented by this nsIFile.
-
copyTo - This method copies this file to a new location.
-
copyToNative - This method copies this file to a new location. [native character encoding variant]
-
copyToFollowingLinks - This method copies this file to a new location.
-
copyToFollowingLinksNative - This method copies this file to a new location. [native character encoding variant]
-
moveTo - This method moves this file to a new location.
-
moveToNative - This method moves this file to a new location. [native character encoding variant]
-
remove - This method removes the file or directory corresponding to the file path represented by this nsIFile.
-
exists - This method tests whether or not this nsIFile exists.
-
isWritable - This method tests whether or not this nsIFile corresponds to a file or directory that may be modified by the user.
-
isReadable - This method tests whether or not this nsIFile corresponds to a file or directory that may be read by the user.
-
isExecutable - This method tests whether or not this nsIFile corresponds to a file that may be executed. Note: This function doesn't work on all platforms due to bug 322865.
-
isHidden - This method tests whether or not this nsIFile corresponds to a file or directory that is hidden. In Unix, hidden files start with a period. On Mac and Windows, they have an attribute bit set.
-
isDirectory - This method tests whether or not this nsIFile corresponds to a directory (same as a folder).
-
isFile - This method tests whether or not this nsIFile corresponds to a regular file, that is, a file that contains bytes.
-
isSymlink - This method tests whether or not this nsIFile corresponds to a symbolic link, shortcut, or alias, which in turn points to another filesystem object.
-
isSpecial - This method tests whether or not this nsIFile corresponds to a special system file, that is, a filesystem object that isn't a regular file, directory or symlink.
-
clone - This method creates a clone of this nsIFile object. (It does NOT clone the file itself; see the copy methods.)
-
equals - This method tests whether or not two nsIFile instances correspond to the same file or directory.
-
contains - This method tests whether or not a nsIFile instance is a descendent of the this nsIFile.
[edit] Attributes
-
leafName - This attribute exposes the name of the nsIFile without any directory components.
-
nativeLeafName - This attribute exposes the name of the nsIFile without any directory components. [native character encoding variant]
-
permissions - This attribute exposes UNIX-style permission bits for this nsIFile.
-
permissionsOfLink - This attribute exposes UNIX-style permission bits for the symbolic link referenced by this nsIFile.
-
lastModifiedTime - This attribute exposes the time when the file referenced by this nsIFile was last modified.
-
lastModifiedTimeOfLink - This attribute exposes the time when the symbolic link referenced by this nsIFile was last modified.
-
fileSize - This attribute exposes the size of the file referenced by this nsIFile.
-
fileSizeOfLink - This attribute exposes the size of the symbolic link referenced by this nsIFile.
-
target - This attribute exposes the full target of the nsIFile -- the full path with any symbolic links dereferenced.
-
nativeTarget - This attribute exposes the full target of the nsIFile -- the full path with any symbolic links dereferenced. [native character encoding variant]
-
path - This attribute exposes the full path of the nsIFile.
-
nativePath - This attribute exposes the full path of the nsIFile. [native character encoding variant]
-
parent - This attribute returns the parent nsIFile for this nsIFile.
-
directoryEntries - This attribute returns an enumeration of files in the directory specified by this nsIFile.
[edit] Remarks
All string-valued methods and attributes have two forms. The preferred form operates on UTF-16 (Unicode) encoded character strings. The alternate form operates on character strings encoded in the "native" multibyte character set. The native character encoding is defined as the single-byte character encoding used with the standard fopen function on the host system.
The native character encoding is determined using platform specific methods. As of Mozilla 1.7, it is UTF-8 on Mac OS X. On Linux and other UNIX platforms, it is the value returned from nl_langinfo (CODESET), which usually corresponds to the value of the LC_ALL, LC_CTYPE and LANG environment variables (with the precedence the same as the order they're enumerated). On Win32 platforms, it is the currently selected ANSI codepage (specified by CP_ACP).
The word "Native" appears in the name of methods that operate on or return strings encoded in the native character set.
A string containing characters encoded in the native character set cannot be safely passed to JavaScript via XPConnect. Therefore, the "native" methods and attributes are not scriptable.
XPCOM provides the string conversion functions NS_CStringToUTF16 and NS_UTF16ToCString, which can be used to convert a string between UTF-16 and the native character encoding.
[edit] History
This interface was frozen for Mozilla 1.0. See bug 129279 for details.