1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include
"nsISupports.idl"
7 #include
"nsIDirectoryEnumerator.idl"
13 #include
"mozilla/Path.h"
15 #include
"nsStringFwd.h"
17 using PathString
= nsTString
<filesystem
::Path
::value_type
>;
18 using PathSubstring
= nsTSubstring
<filesystem
::Path
::value_type
>;
19 } // namespace mozilla
22 [ptr] native PRFileDescStar
(PRFileDesc
);
23 [ptr] native PRLibraryStar
(PRLibrary
);
24 [ptr] native FILE
(FILE
);
25 native PathString
(mozilla
::PathString
);
28 * An nsIFile is an abstract representation of a filename. It manages
29 * filename encoding issues, pathname component separators ('/' vs. '\\'
30 * vs. ':') and weird stuff like differing volumes with identical names, as
31 * on pre-Darwin Macintoshes.
33 * This file has long introduced itself to new hackers with this opening
36 * This is the only correct cross-platform way to specify a file.
37 * Strings are not such a way. If you grew up on windows or unix, you
38 * may think they are. Welcome to reality.
40 * While taking the pose struck here to heart would be uncalled for, one
41 * may safely conclude that writing cross-platform code is an embittering
44 * All methods with string parameters have two forms. The preferred
45 * form operates on UCS-2 encoded characters strings. An alternate
46 * form operates on characters strings encoded in the "native" charset.
48 * A string containing characters encoded in the native charset cannot
49 * be safely passed to javascript via xpconnect. Therefore, the "native
50 * methods" are not scriptable.
52 [scriptable
, main_process_scriptable_only
, uuid(2fa6884a
-ae65
-412a
-9d4c
-ce6e34544ba1
), builtinclass
]
53 interface nsIFile
: nsISupports
58 * NORMAL_FILE_TYPE - A normal file.
59 * DIRECTORY_TYPE - A directory/folder.
61 const unsigned long NORMAL_FILE_TYPE
= 0;
62 const unsigned long DIRECTORY_TYPE
= 1;
67 * This function is used for constructing a descendent of the
71 * A string which is intended to be a child node of the nsIFile.
72 * For security reasons, this cannot contain .. and cannot start with
73 * a directory separator. For the |appendNative| method, the node must
74 * be in the native filesystem charset.
76 void append
(in AString node
);
77 [noscript
] void appendNative
(in ACString node
);
80 * Normalize the pathName (e.g. removing .. and . components on Unix).
87 * This function will create a new file or directory in the
88 * file system. Any nodes that have not been created or
89 * resolved, will be. If the file or directory already
90 * exists create() will return NS_ERROR_FILE_ALREADY_EXISTS.
93 * This specifies the type of file system object
94 * to be made. The only two types at this time
95 * are file and directory which are defined above.
96 * If the type is unrecongnized, we will return an
97 * error (NS_ERROR_FILE_UNKNOWN_TYPE).
100 * The unix style octal permissions. This may
101 * be ignored on systems that do not need to do
104 * @param skipAncestors
105 * Optional; if set to true, we'll skip creating
106 * ancestor directories (and return an error instead).
108 [must_use
] void create
(in unsigned long type
, in unsigned long permissions
,
109 [optional,default(false
)] in boolean skipAncestors
);
112 * Accessor to the leaf name of the file itself.
113 * For the |nativeLeafName| method, the nativeLeafName must
114 * be in the native filesystem charset.
116 attribute AString leafName
;
117 [noscript
] attribute ACString nativeLeafName
;
120 * The leaf name as displayed in OS-provided file pickers and similar UI.
121 * On Windows and macOS, 'real' leaf names of some directories can be
122 * in English, but the OS will show a different, translated name to users
123 * using a different locale. So folders like "Downloads", "Desktop" and
124 * "Documents" might not normally appear to users with that (English) name,
125 * but with an OS-localized translation. This API will return such a
126 * translation if it exists, or the leafName if it doesn't.
127 * On Linux, this will always be the same as `leafName`.
129 readonly attribute AString displayName
;
132 * Linux/Flatpak specific
133 * Returns path as exists on the host. Translates path provided by the document
134 * portal to the path it represents on the host.
135 * @returns {Promise<nsCString, nsresult>} that resolves with translated path
136 * if applicable or path as it is. Rejects when Firefox runs as Flatpak and we
137 * failed to translate the path.
145 * This will copy this file to the specified newParentDir.
146 * If a newName is specified, the file will be renamed.
147 * If 'this' is not created we will return an error
148 * (NS_ERROR_FILE_NOT_FOUND).
150 * copyTo may fail if the file already exists in the destination
153 * copyTo will NOT resolve aliases/shortcuts during the copy.
155 * @param newParentDir
156 * This param is the destination directory. If the
157 * newParentDir is null, copyTo() will use the parent
158 * directory of this file. If the newParentDir is not
159 * empty and is not a directory, an error will be
160 * returned (NS_ERROR_FILE_DESTINATION_NOT_DIR). For the
161 * |CopyToNative| method, the newName must be in the
162 * native filesystem charset.
165 * This param allows you to specify a new name for
166 * the file to be copied. This param may be empty, in
167 * which case the current leaf name will be used.
169 void copyTo
(in nsIFile newParentDir
, in AString newName
);
170 [noscript
] void CopyToNative
(in nsIFile newParentDir
, in ACString newName
);
173 * copyToFollowingLinks[Native]
175 * This function is identical to copyTo with the exception that,
176 * as the name implies, it follows symbolic links. The XP_UNIX
177 * implementation always follow symbolic links when copying. For
178 * the |CopyToFollowingLinks| method, the newName must be in the
179 * native filesystem charset.
181 void copyToFollowingLinks
(in nsIFile newParentDir
, in AString newName
);
182 [noscript
] void copyToFollowingLinksNative
(in nsIFile newParentDir
, in ACString newName
);
187 * A method to move this file or directory to newParentDir.
188 * If a newName is specified, the file or directory will be renamed.
189 * If 'this' is not created we will return an error
190 * (NS_ERROR_FILE_NOT_FOUND).
191 * If 'this' is a file, and the destination file already exists, moveTo
192 * will replace the old file.
193 * This object is updated to refer to the new file.
195 * moveTo will NOT resolve aliases/shortcuts during the copy.
196 * moveTo will do the right thing and allow copies across volumes.
197 * moveTo will return an error (NS_ERROR_FILE_DIR_NOT_EMPTY) if 'this' is
198 * a directory and the destination directory is not empty.
199 * moveTo will return an error (NS_ERROR_FILE_ACCESS_DENIED) if 'this' is
200 * a directory and the destination directory is not writable.
202 * @param newParentDir
203 * This param is the destination directory. If the
204 * newParentDir is empty, moveTo() will rename the file
205 * within its current directory. If the newParentDir is
206 * not empty and does not name a directory, an error will
207 * be returned (NS_ERROR_FILE_DESTINATION_NOT_DIR). For
208 * the |moveToNative| method, the newName must be in the
209 * native filesystem charset.
212 * This param allows you to specify a new name for
213 * the file to be moved. This param may be empty, in
214 * which case the current leaf name will be used.
216 void moveTo
(in nsIFile newParentDir
, in AString newName
);
217 [noscript
] void moveToNative
(in nsIFile newParentDir
, in ACString newName
);
220 * moveToFollowingLinks[Native]
222 * This function is identical to moveTo with the exception that,
223 * as the name implies, it follows symbolic links. The XP_UNIX
224 * implementation always follows symbolic links when moving. For
225 * the |MoveToFollowingLinks| method, the newName ust be in the native
226 * filesystem charset.
228 void moveToFollowingLinks
(in nsIFile newParentDir
, in AString newName
);
229 [noscript
] void moveToFollowingLinksNative
(in nsIFile newParentDir
, in ACString newName
);
234 * This method is identical to moveTo except that if this file or directory
235 * is moved to a a different volume, it fails and returns an error
236 * (NS_ERROR_FILE_ACCESS_DENIED).
237 * This object will still point to the old location after renaming.
239 void renameTo
(in nsIFile newParentDir
, in AString newName
);
240 [noscript
] void renameToNative
(in nsIFile newParentDir
, in ACString newName
);
243 * This will try to delete this file. The 'recursive' flag
244 * must be PR_TRUE to delete directories which are not empty.
246 * If passed, 'removeCount' will be incremented by the total number of files
247 * and/or directories removed. Will be 1 unless the 'recursive' flag is
248 * set. The parameter must be initialized beforehand.
250 * This will not resolve any symlinks.
252 void remove
(in boolean recursive
, [optional] inout uint32_t removeCount
);
255 * Attributes of nsIFile.
258 attribute
unsigned long permissions
;
259 attribute
unsigned long permissionsOfLink
;
262 * The last accesss time of the file in milliseconds from midnight, January
263 * 1, 1970 GMT, if available.
265 attribute PRTime lastAccessedTime
;
266 attribute PRTime lastAccessedTimeOfLink
;
269 * File Times are to be in milliseconds from
270 * midnight (00:00:00), January 1, 1970 Greenwich Mean
273 attribute PRTime lastModifiedTime
;
274 attribute PRTime lastModifiedTimeOfLink
;
277 * The creation time of file in milliseconds from midnight, January 1, 1970
280 * This attribute is only implemented on Windows and macOS. Accessing this
281 * on another platform will this will throw NS_ERROR_NOT_IMPLEMENTED.
283 readonly attribute PRTime creationTime
;
284 readonly attribute PRTime creationTimeOfLink
;
287 * WARNING! On the Mac, getting/setting the file size with nsIFile
288 * only deals with the size of the data fork. If you need to
289 * know the size of the combined data and resource forks use the
290 * GetFileSizeWithResFork() method defined on nsILocalFileMac.
292 attribute int64_t fileSize
;
293 readonly attribute int64_t fileSizeOfLink
;
298 * Accessor to the string path. The native version of these
299 * strings are not guaranteed to be a usable path to pass to
300 * NSPR or the C stdlib. There are problems that affect
301 * platforms on which a path does not fully specify a file
302 * because two volumes can have the same name (e.g., mac).
303 * This is solved by holding "private", native data in the
304 * nsIFile implementation. This native data is lost when
305 * you convert to a string.
307 * DO NOT PASS TO USE WITH NSPR OR STDLIB!
310 * Find out what the symlink points at. Will give error
311 * (NS_ERROR_FILE_INVALID_PATH) if not a symlink.
314 * Find out what the nsIFile points at.
316 * Note that the ACString attributes are returned in the
317 * native filesystem charset.
320 readonly attribute AString target
;
321 [noscript
] readonly attribute ACString nativeTarget
;
322 readonly attribute AString path
;
323 [notxpcom
,nostdcall
,must_use
] PathString nativePath
();
326 nsresult GetNativePath
(nsACString
& aPath
);
329 * Returns a human-readable path string.
331 nsCString HumanReadablePath
();
335 boolean isWritable
();
336 boolean isReadable
();
337 boolean isExecutable
();
339 boolean isDirectory
();
343 * Not a regular file, not a directory, not a symlink.
350 * This function will create a new file or directory in the
351 * file system. Any nodes that have not been created or
352 * resolved, will be. If this file already exists, we try
353 * variations on the leaf name "suggestedName" until we find
354 * one that did not already exist.
356 * If the search for nonexistent files takes too long
357 * (thousands of the variants already exist), we give up and
358 * return NS_ERROR_FILE_TOO_BIG.
361 * This specifies the type of file system object
362 * to be made. The only two types at this time
363 * are file and directory which are defined above.
364 * If the type is unrecongnized, we will return an
365 * error (NS_ERROR_FILE_UNKNOWN_TYPE).
368 * The unix style octal permissions. This may
369 * be ignored on systems that do not need to do
373 void createUnique
(in unsigned long type
, in unsigned long permissions
);
378 * This function will allocate and initialize a nsIFile object to the
379 * exact location of the |this| nsIFile.
382 * A nsIFile which this object will be initialize
389 * Will determine if the inFile equals this.
391 boolean equals
(in nsIFile inFile
);
394 * Will determine if inFile is a descendant of this file.
395 * This routine looks in subdirectories too.
397 boolean contains
(in nsIFile inFile
);
400 * Parent will be null when this is at the top of the volume.
402 readonly attribute nsIFile parent
;
405 * Returns an enumeration of the elements in a directory. Each
406 * element in the enumeration is an nsIFile.
408 * @throws NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does
409 * not specify a directory.
411 [binaryname
(DirectoryEntriesImpl
)]
412 readonly attribute nsIDirectoryEnumerator directoryEntries
;
415 nsresult GetDirectoryEntries
(nsIDirectoryEnumerator
** aOut
)
417 return GetDirectoryEntriesImpl
(aOut
);
422 * initWith[Native]Path
424 * This function will initialize the nsIFile object. Any
425 * internal state information will be reset.
428 * A string which specifies a full file path to a
429 * location. Relative paths will be treated as an
430 * error (NS_ERROR_FILE_UNRECOGNIZED_PATH). For
431 * initWithNativePath, the filePath must be in the native
432 * filesystem charset.
434 void initWithPath
(in AString filePath
);
435 [noscript
] void initWithNativePath
(in ACString filePath
);
440 * Initialize this object with another file
443 * the file this becomes equivalent to
445 void initWithFile
(in nsIFile aFile
);
448 * Flag for openNSPRFileDesc(), to hint to the OS that the file will be
449 * read sequentially with agressive readahead.
451 const unsigned long OS_READAHEAD
= 0x40000000;
454 * Flag for openNSPRFileDesc(). Deprecated and unreliable!
455 * Instead use NS_OpenAnonymousTemporaryFile() to create a temporary
456 * file which will be deleted upon close!
458 const unsigned long DELETE_ON_CLOSE
= 0x80000000;
461 * Return the result of PR_Open on the file. The caller is
462 * responsible for calling PR_Close on the result. On success, the
463 * returned PRFileDescr must be non-null.
465 * @param flags the PR_Open flags from prio.h, plus optionally
466 * OS_READAHEAD or DELETE_ON_CLOSE. OS_READAHEAD is a hint to the
467 * OS that the file will be read sequentially with agressive
468 * readahead. DELETE_ON_CLOSE is unreliable on Windows and is deprecated.
469 * Instead use NS_OpenAnonymousTemporaryFile() to create a temporary
470 * file which will be deleted upon close.
472 [noscript
, must_use
] PRFileDescStar openNSPRFileDesc
(in long flags
,
476 * Return the result of fopen on the file. The caller is
477 * responsible for calling fclose on the result. On success, the
478 * returned FILE pointer must be non-null.
480 [noscript
, must_use
] FILE openANSIFileDesc
(in string mode
);
483 * Return the result of PR_LoadLibrary on the file. The caller is
484 * responsible for calling PR_UnloadLibrary on the result.
486 [noscript
, must_use
] PRLibraryStar load
();
488 // number of bytes available on disk to non-superuser
489 [must_use
] readonly attribute int64_t diskSpaceAvailable
;
491 // disk capacity in bytes
492 [must_use
] readonly attribute int64_t diskCapacity
;
495 * appendRelative[Native]Path
497 * Append a relative path to the current path of the nsIFile object.
499 * @param relativeFilePath
500 * relativeFilePath is a native relative path. For security reasons,
501 * this cannot contain .. and cannot start with a directory separator.
502 * For the |appendRelativeNativePath| method, the relativeFilePath
503 * must be in the native filesystem charset.
505 void appendRelativePath
(in AString relativeFilePath
);
506 [noscript
] void appendRelativeNativePath
(in ACString relativeFilePath
);
509 * Accessor to a null terminated string which will specify
510 * the file in a persistent manner for disk storage.
512 * The character set of this attribute is undefined. DO NOT TRY TO
513 * INTERPRET IT AS HUMAN READABLE TEXT!
515 [must_use
] attribute ACString persistentDescriptor
;
520 * Ask the operating system to open the folder which contains
521 * this file or folder. This routine only works on platforms which
522 * support the ability to open a folder and is run async on Windows.
523 * This routine must be called on the main.
525 [must_use
] void reveal
();
530 * Ask the operating system to attempt to open the file.
531 * this really just simulates "double clicking" the file on your platform.
532 * This routine only works on platforms which support this functionality
533 * and is run async on Windows. This routine must be called on the
536 [must_use
] void launch
();
539 * getRelativeDescriptor
541 * Returns a relative file path in an opaque, XP format. It is therefore
544 * The character set of the string returned from this function is
545 * undefined. DO NOT TRY TO INTERPRET IT AS HUMAN READABLE TEXT!
548 * the file from which the descriptor is relative.
549 * Throws if fromFile is null.
551 [must_use
] ACString getRelativeDescriptor
(in nsIFile fromFile
);
554 * setRelativeDescriptor
556 * Initializes the file to the location relative to fromFile using
557 * a string returned by getRelativeDescriptor.
560 * the file to which the descriptor is relative
562 * the relative descriptor obtained from getRelativeDescriptor
565 void setRelativeDescriptor
(in nsIFile fromFile
, in ACString relativeDesc
);
570 * Returns a relative file from 'fromFile' to this file as a UTF-8 string.
571 * Going up the directory tree is represented via "../". '/' is used as
572 * the path segment separator. This is not a native path, since it's UTF-8
576 * the file from which the path is relative.
577 * Throws if fromFile is null.
579 [must_use
] AUTF8String getRelativePath
(in nsIFile fromFile
);
584 * Initializes the file to the location relative to fromFile using
585 * a string returned by getRelativePath.
588 * the file from which the path is relative
590 * the relative path obtained from getRelativePath
593 void setRelativePath
(in nsIFile fromFile
, in AUTF8String relativeDesc
);
597 #ifdef MOZILLA_INTERNAL_API
598 #include
"nsDirectoryServiceUtils.h"
599 #include
"nsString.h"
601 inline std
::ostream
& operator
<<(std
::ostream
& aOut
, const nsIFile
& aFile
) {
602 nsIFile
* file
= const_cast
<nsIFile
*>(&aFile
);
605 return aOut
<< "nsIFile { " << path
<< " }";