Source code

Revision control

Other Tools

1
/* -*- Mode: C++; tab-width: 2; 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 "nsIInputStream.idl"
7
#include "nsIOutputStream.idl"
8
9
interface nsIEventTarget;
10
interface nsIFile;
11
interface nsIFileMetadataCallback;
12
13
%{C++
14
struct PRFileDesc;
15
%}
16
17
[ptr] native PRFileDescPtr(PRFileDesc);
18
19
/**
20
* An input stream that allows you to read from a file.
21
*/
22
[scriptable, uuid(e3d56a20-c7ec-11d3-8cda-0060b0fc14a3)]
23
interface nsIFileInputStream : nsIInputStream
24
{
25
/**
26
* @param file file to read from
27
* @param ioFlags file open flags listed in prio.h (see
28
* PR_Open documentation) or -1 to open the
29
* file in default mode (PR_RDONLY).
30
* @param perm file mode bits listed in prio.h or -1 to
31
* use the default value (0)
32
* @param behaviorFlags flags specifying various behaviors of the class
33
* (see enumerations in the class)
34
*/
35
void init(in nsIFile file, in long ioFlags, in long perm,
36
in long behaviorFlags);
37
38
/**
39
* If this is set, the file will close automatically when the end of the
40
* file is reached.
41
*/
42
const long CLOSE_ON_EOF = 1<<2;
43
44
/**
45
* If this is set, the file will be reopened whenever we reach the start of
46
* the file, either by doing a Seek(0, NS_SEEK_CUR), or by doing a relative
47
* seek that happen to reach the beginning of the file. If the file is
48
* already open and the seek occurs, it will happen naturally. (The file
49
* will only be reopened if it is closed for some reason.)
50
*/
51
const long REOPEN_ON_REWIND = 1<<3;
52
53
/**
54
* If this is set, the file will be opened (i.e., a call to
55
* PR_Open done) only when we do an actual operation on the stream,
56
* or more specifically, when one of the following is called:
57
* - Seek
58
* - Tell
59
* - SetEOF
60
* - Available
61
* - Read
62
* - ReadLine
63
*
64
* DEFER_OPEN is useful if we use the stream on a background
65
* thread, so that the opening and possible |stat|ing of the file
66
* happens there as well.
67
*
68
* @note Using this flag results in the file not being opened
69
* during the call to Init. This means that any errors that might
70
* happen when this flag is not set would happen during the
71
* first read. Also, the file is not locked when Init is called,
72
* so it might be deleted before we try to read from it.
73
*/
74
const long DEFER_OPEN = 1<<4;
75
76
/**
77
* This flag has no effect and is totally ignored on any platform except
78
* Windows since this is the default behavior on POSIX systems. On Windows
79
* if this flag is set then the stream is opened in a special mode that
80
* allows the OS to delete the file from disk just like POSIX.
81
*/
82
const long SHARE_DELETE = 1<<5;
83
};
84
85
/**
86
* An output stream that lets you stream to a file.
87
*/
88
[scriptable, uuid(e734cac9-1295-4e6f-9684-3ac4e1f91063)]
89
interface nsIFileOutputStream : nsIOutputStream
90
{
91
/**
92
* @param file file to write to
93
* @param ioFlags file open flags listed in prio.h (see
94
* PR_Open documentation) or -1 to open the
95
* file in default mode (PR_WRONLY |
96
* PR_CREATE_FILE | PR_TRUNCATE)
97
* @param perm file mode bits listed in prio.h or -1 to
98
* use the default permissions (0664)
99
* @param behaviorFlags flags specifying various behaviors of the class
100
* (currently none supported)
101
*/
102
void init(in nsIFile file, in long ioFlags, in long perm,
103
in long behaviorFlags);
104
105
/**
106
* @param length asks the operating system to allocate storage for
107
* this file of at least |length| bytes long, and
108
* set the file length to the corresponding size.
109
* @throws NS_ERROR_FAILURE if the preallocation fails.
110
* @throws NS_ERROR_NOT_INITIALIZED if the file is not opened.
111
*/
112
[noscript] void preallocate(in long long length);
113
114
/**
115
* See the same constant in nsIFileInputStream. The deferred open will
116
* be performed when one of the following is called:
117
* - Seek
118
* - Tell
119
* - SetEOF
120
* - Write
121
* - Flush
122
*
123
* @note Using this flag results in the file not being opened
124
* during the call to Init. This means that any errors that might
125
* happen when this flag is not set would happen during the
126
* first write, and if the file is to be created, then it will not
127
* appear on the disk until the first write.
128
*/
129
const long DEFER_OPEN = 1<<0;
130
};
131
132
/**
133
* A stream that allows you to read from a file or stream to a file.
134
*/
135
[scriptable, uuid(82cf605a-8393-4550-83ab-43cd5578e006)]
136
interface nsIFileStream : nsISupports
137
{
138
/**
139
* @param file file to read from or stream to
140
* @param ioFlags file open flags listed in prio.h (see
141
* PR_Open documentation) or -1 to open the
142
* file in default mode (PR_RDWR).
143
* @param perm file mode bits listed in prio.h or -1 to
144
* use the default value (0)
145
* @param behaviorFlags flags specifying various behaviors of the class
146
* (see enumerations in the class)
147
*/
148
void init(in nsIFile file, in long ioFlags, in long perm,
149
in long behaviorFlags);
150
151
/**
152
* See the same constant in nsIFileInputStream. The deferred open will
153
* be performed when one of the following is called:
154
* - Seek
155
* - Tell
156
* - SetEOF
157
* - Available
158
* - Read
159
* - Flush
160
* - Write
161
* - GetSize
162
* - GetLastModified
163
*
164
* @note Using this flag results in the file not being opened
165
* during the call to Init. This means that any errors that might
166
* happen when this flag is not set would happen during the
167
* first read or write. The file is not locked when Init is called,
168
* so it might be deleted before we try to read from it and if the
169
* file is to be created, then it will not appear on the disk until
170
* the first write.
171
*/
172
const long DEFER_OPEN = 1<<0;
173
};
174
175
/**
176
* An interface that allows you to get some metadata like file size and
177
* file last modified time. These methods and attributes can throw
178
* NS_BASE_STREAM_WOULD_BLOCK in case the informations are not available yet.
179
* If this happens, consider the use of nsIAsyncFileMetadata.
180
*
181
* If using nsIAsyncFileMetadata, you should retrieve any data via this
182
* interface before taking any action that might consume the underlying stream.
183
* For example, once Available(), Read(), or nsIAsyncInputStream::AsyncWait()
184
* are invoked, these methods may return NS_BASE_STREAM_CLOSED. This will
185
* happen when using IPCBlobInputStream with an underlying file stream, for
186
* example.
187
*/
188
[scriptable, uuid(07f679e4-9601-4bd1-b510-cd3852edb881)]
189
interface nsIFileMetadata : nsISupports
190
{
191
/**
192
* File size in bytes.
193
*/
194
readonly attribute long long size;
195
196
/**
197
* File last modified time in milliseconds from midnight (00:00:00),
198
* January 1, 1970 Greenwich Mean Time (GMT).
199
*/
200
readonly attribute long long lastModified;
201
202
/**
203
* The internal file descriptor. It can be used for memory mapping of the
204
* underlying file. Please use carefully! If this returns
205
* NS_BASE_STREAM_WOULD_BLOCK, consider the use of nsIAsyncFileMetadata.
206
*/
207
[noscript] PRFileDescPtr getFileDescriptor();
208
};
209
210
[scriptable, uuid(de15b80b-29ba-4b7f-9220-a3d75b17ae8c)]
211
interface nsIAsyncFileMetadata : nsIFileMetadata
212
{
213
/**
214
* Asynchronously wait for the object to be ready.
215
*
216
* @param aCallback The callback will be used when the stream is ready to
217
* return File metadata. Use a nullptr to cancel a
218
* previous operation.
219
*
220
* @param aEventTarget The event target where aCallback will be executed.
221
* If aCallback is passed, aEventTarget cannot be null.
222
*/
223
void asyncFileMetadataWait(in nsIFileMetadataCallback aCallback,
224
in nsIEventTarget aEventTarget);
225
};
226
227
/**
228
* This is a companion interface for
229
* nsIAsyncFileMetadata::asyncFileMetadataWait.
230
*/
231
[function, scriptable, uuid(d01c7ead-7ba3-4726-b399-618ec8ec7057)]
232
interface nsIFileMetadataCallback : nsISupports
233
{
234
/**
235
* Called to indicate that the nsIFileMetadata object is ready.
236
*/
237
void onFileMetadataReady(in nsIAsyncFileMetadata aObject);
238
};