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
9interface nsIEventTarget;
10interface nsIFile;
11interface nsIFileMetadataCallback;
12
13%{C++
14struct 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)]
23interface 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)]
89interface 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)]
136interface 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 RemoteLazyInputStream with an underlying file stream, for
186 * example.
187 */
188[scriptable, uuid(07f679e4-9601-4bd1-b510-cd3852edb881)]
189interface 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)]
211interface 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)]
232interface nsIFileMetadataCallback : nsISupports
233{
234    /**
235     * Called to indicate that the nsIFileMetadata object is ready.
236     */
237    void onFileMetadataReady(in nsIAsyncFileMetadata aObject);
238};
239