Source code

Revision control

Other Tools

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/. */
5
6
#include "nsISupports.idl"
7
#include "nsIDirectoryEnumerator.idl"
8
9
%{C++
10
struct PRFileDesc;
11
struct PRLibrary;
12
#include <stdio.h>
13
#include "mozilla/Path.h"
14
#include "nsCOMPtr.h"
15
#include "nsStringFwd.h"
16
namespace mozilla {
17
using PathString = nsTString<filesystem::Path::value_type>;
18
using PathSubstring = nsTSubstring<filesystem::Path::value_type>;
19
} // namespace mozilla
20
%}
21
22
[ptr] native PRFileDescStar(PRFileDesc);
23
[ptr] native PRLibraryStar(PRLibrary);
24
[ptr] native FILE(FILE);
25
native PathString(mozilla::PathString);
26
27
/**
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.
32
*
33
* This file has long introduced itself to new hackers with this opening
34
* paragraph:
35
*
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.
39
*
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
42
* experience.
43
*
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.
47
*
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.
51
*/
52
[scriptable, main_process_scriptable_only, uuid(2fa6884a-ae65-412a-9d4c-ce6e34544ba1), builtinclass]
53
interface nsIFile : nsISupports
54
{
55
/**
56
* Create Types
57
*
58
* NORMAL_FILE_TYPE - A normal file.
59
* DIRECTORY_TYPE - A directory/folder.
60
*/
61
const unsigned long NORMAL_FILE_TYPE = 0;
62
const unsigned long DIRECTORY_TYPE = 1;
63
64
/**
65
* append[Native]
66
*
67
* This function is used for constructing a descendent of the
68
* current nsIFile.
69
*
70
* @param node
71
* A string which is intended to be a child node of the nsIFile.
72
* For the |appendNative| method, the node must be in the native
73
* filesystem charset.
74
*/
75
void append(in AString node);
76
[noscript] void appendNative(in ACString node);
77
78
/**
79
* Normalize the pathName (e.g. removing .. and . components on Unix).
80
*/
81
void normalize();
82
83
/**
84
* create
85
*
86
* This function will create a new file or directory in the
87
* file system. Any nodes that have not been created or
88
* resolved, will be. If the file or directory already
89
* exists create() will return NS_ERROR_FILE_ALREADY_EXISTS.
90
*
91
* @param type
92
* This specifies the type of file system object
93
* to be made. The only two types at this time
94
* are file and directory which are defined above.
95
* If the type is unrecongnized, we will return an
96
* error (NS_ERROR_FILE_UNKNOWN_TYPE).
97
*
98
* @param permissions
99
* The unix style octal permissions. This may
100
* be ignored on systems that do not need to do
101
* permissions.
102
*/
103
[must_use] void create(in unsigned long type, in unsigned long permissions);
104
105
/**
106
* Accessor to the leaf name of the file itself.
107
* For the |nativeLeafName| method, the nativeLeafName must
108
* be in the native filesystem charset.
109
*/
110
attribute AString leafName;
111
[noscript] attribute ACString nativeLeafName;
112
113
/**
114
* copyTo[Native]
115
*
116
* This will copy this file to the specified newParentDir.
117
* If a newName is specified, the file will be renamed.
118
* If 'this' is not created we will return an error
119
* (NS_ERROR_FILE_TARGET_DOES_NOT_EXIST).
120
*
121
* copyTo may fail if the file already exists in the destination
122
* directory.
123
*
124
* copyTo will NOT resolve aliases/shortcuts during the copy.
125
*
126
* @param newParentDir
127
* This param is the destination directory. If the
128
* newParentDir is null, copyTo() will use the parent
129
* directory of this file. If the newParentDir is not
130
* empty and is not a directory, an error will be
131
* returned (NS_ERROR_FILE_DESTINATION_NOT_DIR). For the
132
* |CopyToNative| method, the newName must be in the
133
* native filesystem charset.
134
*
135
* @param newName
136
* This param allows you to specify a new name for
137
* the file to be copied. This param may be empty, in
138
* which case the current leaf name will be used.
139
*/
140
void copyTo(in nsIFile newParentDir, in AString newName);
141
[noscript] void CopyToNative(in nsIFile newParentDir, in ACString newName);
142
143
/**
144
* copyToFollowingLinks[Native]
145
*
146
* This function is identical to copyTo with the exception that,
147
* as the name implies, it follows symbolic links. The XP_UNIX
148
* implementation always follow symbolic links when copying. For
149
* the |CopyToFollowingLinks| method, the newName must be in the
150
* native filesystem charset.
151
*/
152
void copyToFollowingLinks(in nsIFile newParentDir, in AString newName);
153
[noscript] void copyToFollowingLinksNative(in nsIFile newParentDir, in ACString newName);
154
155
/**
156
* moveTo[Native]
157
*
158
* A method to move this file or directory to newParentDir.
159
* If a newName is specified, the file or directory will be renamed.
160
* If 'this' is not created we will return an error
161
* (NS_ERROR_FILE_TARGET_DOES_NOT_EXIST).
162
* If 'this' is a file, and the destination file already exists, moveTo
163
* will replace the old file.
164
* This object is updated to refer to the new file.
165
*
166
* moveTo will NOT resolve aliases/shortcuts during the copy.
167
* moveTo will do the right thing and allow copies across volumes.
168
* moveTo will return an error (NS_ERROR_FILE_DIR_NOT_EMPTY) if 'this' is
169
* a directory and the destination directory is not empty.
170
* moveTo will return an error (NS_ERROR_FILE_ACCESS_DENIED) if 'this' is
171
* a directory and the destination directory is not writable.
172
*
173
* @param newParentDir
174
* This param is the destination directory. If the
175
* newParentDir is empty, moveTo() will rename the file
176
* within its current directory. If the newParentDir is
177
* not empty and does not name a directory, an error will
178
* be returned (NS_ERROR_FILE_DESTINATION_NOT_DIR). For
179
* the |moveToNative| method, the newName must be in the
180
* native filesystem charset.
181
*
182
* @param newName
183
* This param allows you to specify a new name for
184
* the file to be moved. This param may be empty, in
185
* which case the current leaf name will be used.
186
*/
187
void moveTo(in nsIFile newParentDir, in AString newName);
188
[noscript] void moveToNative(in nsIFile newParentDir, in ACString newName);
189
190
/**
191
* renameTo
192
*
193
* This method is identical to moveTo except that if this file or directory
194
* is moved to a a different volume, it fails and returns an error
195
* (NS_ERROR_FILE_ACCESS_DENIED).
196
* This object will still point to the old location after renaming.
197
*/
198
void renameTo(in nsIFile newParentDir, in AString newName);
199
[noscript] void renameToNative(in nsIFile newParentDir, in ACString newName);
200
201
/**
202
* This will try to delete this file. The 'recursive' flag
203
* must be PR_TRUE to delete directories which are not empty.
204
*
205
* This will not resolve any symlinks.
206
*/
207
void remove(in boolean recursive);
208
209
/**
210
* Attributes of nsIFile.
211
*/
212
213
attribute unsigned long permissions;
214
attribute unsigned long permissionsOfLink;
215
216
/**
217
* File Times are to be in milliseconds from
218
* midnight (00:00:00), January 1, 1970 Greenwich Mean
219
* Time (GMT).
220
*/
221
attribute PRTime lastModifiedTime;
222
attribute PRTime lastModifiedTimeOfLink;
223
224
/**
225
* WARNING! On the Mac, getting/setting the file size with nsIFile
226
* only deals with the size of the data fork. If you need to
227
* know the size of the combined data and resource forks use the
228
* GetFileSizeWithResFork() method defined on nsILocalFileMac.
229
*/
230
attribute int64_t fileSize;
231
readonly attribute int64_t fileSizeOfLink;
232
233
/**
234
* target & path
235
*
236
* Accessor to the string path. The native version of these
237
* strings are not guaranteed to be a usable path to pass to
238
* NSPR or the C stdlib. There are problems that affect
239
* platforms on which a path does not fully specify a file
240
* because two volumes can have the same name (e.g., mac).
241
* This is solved by holding "private", native data in the
242
* nsIFile implementation. This native data is lost when
243
* you convert to a string.
244
*
245
* DO NOT PASS TO USE WITH NSPR OR STDLIB!
246
*
247
* target
248
* Find out what the symlink points at. Will give error
249
* (NS_ERROR_FILE_INVALID_PATH) if not a symlink.
250
*
251
* path
252
* Find out what the nsIFile points at.
253
*
254
* Note that the ACString attributes are returned in the
255
* native filesystem charset.
256
*
257
*/
258
readonly attribute AString target;
259
[noscript] readonly attribute ACString nativeTarget;
260
readonly attribute AString path;
261
[notxpcom,nostdcall,must_use] PathString nativePath();
262
%{C++
263
#ifndef XP_WIN
264
nsresult GetNativePath(nsACString& aPath);
265
#endif
266
/*
267
* Returns a human-readable path string.
268
*/
269
nsCString HumanReadablePath();
270
%}
271
272
boolean exists();
273
boolean isWritable();
274
boolean isReadable();
275
boolean isExecutable();
276
boolean isHidden();
277
boolean isDirectory();
278
boolean isFile();
279
boolean isSymlink();
280
/**
281
* Not a regular file, not a directory, not a symlink.
282
*/
283
boolean isSpecial();
284
285
/**
286
* createUnique
287
*
288
* This function will create a new file or directory in the
289
* file system. Any nodes that have not been created or
290
* resolved, will be. If this file already exists, we try
291
* variations on the leaf name "suggestedName" until we find
292
* one that did not already exist.
293
*
294
* If the search for nonexistent files takes too long
295
* (thousands of the variants already exist), we give up and
296
* return NS_ERROR_FILE_TOO_BIG.
297
*
298
* @param type
299
* This specifies the type of file system object
300
* to be made. The only two types at this time
301
* are file and directory which are defined above.
302
* If the type is unrecongnized, we will return an
303
* error (NS_ERROR_FILE_UNKNOWN_TYPE).
304
*
305
* @param permissions
306
* The unix style octal permissions. This may
307
* be ignored on systems that do not need to do
308
* permissions.
309
*/
310
[must_use]
311
void createUnique(in unsigned long type, in unsigned long permissions);
312
313
/**
314
* clone()
315
*
316
* This function will allocate and initialize a nsIFile object to the
317
* exact location of the |this| nsIFile.
318
*
319
* @param file
320
* A nsIFile which this object will be initialize
321
* with.
322
*
323
*/
324
nsIFile clone();
325
326
/**
327
* Will determine if the inFile equals this.
328
*/
329
boolean equals(in nsIFile inFile);
330
331
/**
332
* Will determine if inFile is a descendant of this file.
333
* This routine looks in subdirectories too.
334
*/
335
boolean contains(in nsIFile inFile);
336
337
/**
338
* Parent will be null when this is at the top of the volume.
339
*/
340
readonly attribute nsIFile parent;
341
342
/**
343
* Returns an enumeration of the elements in a directory. Each
344
* element in the enumeration is an nsIFile.
345
*
346
* @throws NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does
347
* not specify a directory.
348
*/
349
[binaryname(DirectoryEntriesImpl)]
350
readonly attribute nsIDirectoryEnumerator directoryEntries;
351
352
%{C++
353
nsresult GetDirectoryEntries(nsIDirectoryEnumerator** aOut)
354
{
355
return GetDirectoryEntriesImpl(aOut);
356
};
357
%}
358
359
/**
360
* initWith[Native]Path
361
*
362
* This function will initialize the nsIFile object. Any
363
* internal state information will be reset.
364
*
365
* @param filePath
366
* A string which specifies a full file path to a
367
* location. Relative paths will be treated as an
368
* error (NS_ERROR_FILE_UNRECOGNIZED_PATH). For
369
* initWithNativePath, the filePath must be in the native
370
* filesystem charset.
371
*/
372
void initWithPath(in AString filePath);
373
[noscript] void initWithNativePath(in ACString filePath);
374
375
/**
376
* initWithFile
377
*
378
* Initialize this object with another file
379
*
380
* @param aFile
381
* the file this becomes equivalent to
382
*/
383
void initWithFile(in nsIFile aFile);
384
385
/**
386
* followLinks
387
*
388
* This attribute will determine if the nsLocalFile will auto
389
* resolve symbolic links. By default, this value will be false
390
* on all non unix systems. On unix, this attribute is effectively
391
* a noop.
392
*/
393
attribute boolean followLinks;
394
395
/**
396
* Flag for openNSPRFileDesc(), to hint to the OS that the file will be
397
* read sequentially with agressive readahead.
398
*/
399
const unsigned long OS_READAHEAD = 0x40000000;
400
401
/**
402
* Flag for openNSPRFileDesc(). Deprecated and unreliable!
403
* Instead use NS_OpenAnonymousTemporaryFile() to create a temporary
404
* file which will be deleted upon close!
405
*/
406
const unsigned long DELETE_ON_CLOSE = 0x80000000;
407
408
/**
409
* Return the result of PR_Open on the file. The caller is
410
* responsible for calling PR_Close on the result. On success, the
411
* returned PRFileDescr must be non-null.
412
*
413
* @param flags the PR_Open flags from prio.h, plus optionally
414
* OS_READAHEAD or DELETE_ON_CLOSE. OS_READAHEAD is a hint to the
415
* OS that the file will be read sequentially with agressive
416
* readahead. DELETE_ON_CLOSE is unreliable on Windows and is deprecated.
417
* Instead use NS_OpenAnonymousTemporaryFile() to create a temporary
418
* file which will be deleted upon close.
419
*/
420
[noscript, must_use] PRFileDescStar openNSPRFileDesc(in long flags,
421
in long mode);
422
423
/**
424
* Return the result of fopen on the file. The caller is
425
* responsible for calling fclose on the result. On success, the
426
* returned FILE pointer must be non-null.
427
*/
428
[noscript, must_use] FILE openANSIFileDesc(in string mode);
429
430
/**
431
* Return the result of PR_LoadLibrary on the file. The caller is
432
* responsible for calling PR_UnloadLibrary on the result.
433
*/
434
[noscript, must_use] PRLibraryStar load();
435
436
// number of bytes available on disk to non-superuser
437
[must_use] readonly attribute int64_t diskSpaceAvailable;
438
439
/**
440
* appendRelative[Native]Path
441
*
442
* Append a relative path to the current path of the nsIFile object.
443
*
444
* @param relativeFilePath
445
* relativeFilePath is a native relative path. For security reasons,
446
* this cannot contain .. or cannot start with a directory separator.
447
* For the |appendRelativeNativePath| method, the relativeFilePath
448
* must be in the native filesystem charset.
449
*/
450
void appendRelativePath(in AString relativeFilePath);
451
[noscript] void appendRelativeNativePath(in ACString relativeFilePath);
452
453
/**
454
* Accessor to a null terminated string which will specify
455
* the file in a persistent manner for disk storage.
456
*
457
* The character set of this attribute is undefined. DO NOT TRY TO
458
* INTERPRET IT AS HUMAN READABLE TEXT!
459
*/
460
[must_use] attribute ACString persistentDescriptor;
461
462
/**
463
* reveal
464
*
465
* Ask the operating system to open the folder which contains
466
* this file or folder. This routine only works on platforms which
467
* support the ability to open a folder and is run async on Windows.
468
* This routine must be called on the main.
469
*/
470
[must_use] void reveal();
471
472
/**
473
* launch
474
*
475
* Ask the operating system to attempt to open the file.
476
* this really just simulates "double clicking" the file on your platform.
477
* This routine only works on platforms which support this functionality
478
* and is run async on Windows. This routine must be called on the
479
* main thread.
480
*/
481
[must_use] void launch();
482
483
/**
484
* getRelativeDescriptor
485
*
486
* Returns a relative file path in an opaque, XP format. It is therefore
487
* not a native path.
488
*
489
* The character set of the string returned from this function is
490
* undefined. DO NOT TRY TO INTERPRET IT AS HUMAN READABLE TEXT!
491
*
492
* @param fromFile
493
* the file from which the descriptor is relative.
494
* Throws if fromFile is null.
495
*/
496
[must_use] ACString getRelativeDescriptor(in nsIFile fromFile);
497
498
/**
499
* setRelativeDescriptor
500
*
501
* Initializes the file to the location relative to fromFile using
502
* a string returned by getRelativeDescriptor.
503
*
504
* @param fromFile
505
* the file to which the descriptor is relative
506
* @param relative
507
* the relative descriptor obtained from getRelativeDescriptor
508
*/
509
[must_use]
510
void setRelativeDescriptor(in nsIFile fromFile, in ACString relativeDesc);
511
512
/**
513
* getRelativePath
514
*
515
* Returns a relative file from 'fromFile' to this file as a UTF-8 string.
516
* Going up the directory tree is represented via "../". '/' is used as
517
* the path segment separator. This is not a native path, since it's UTF-8
518
* encoded.
519
*
520
* @param fromFile
521
* the file from which the path is relative.
522
* Throws if fromFile is null.
523
*/
524
[must_use] AUTF8String getRelativePath(in nsIFile fromFile);
525
526
/**
527
* setRelativePath
528
*
529
* Initializes the file to the location relative to fromFile using
530
* a string returned by getRelativePath.
531
*
532
* @param fromFile
533
* the file from which the path is relative
534
* @param relative
535
* the relative path obtained from getRelativePath
536
*/
537
[must_use]
538
void setRelativePath(in nsIFile fromFile, in AUTF8String relativeDesc);
539
};
540
541
%{C++
542
#ifdef MOZILLA_INTERNAL_API
543
#include "nsDirectoryServiceUtils.h"
544
#include "nsString.h"
545
546
inline std::ostream& operator<<(std::ostream& aOut, const nsIFile& aFile) {
547
nsIFile* file = const_cast<nsIFile*>(&aFile);
548
nsAutoString path;
549
file->GetPath(path);
550
return aOut << "nsIFile { " << path << " }";
551
}
552
#endif
553
%}