/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #include "nsIInputStream.idl" #include "nsIOutputStream.idl" interface nsIEventTarget; interface nsIFile; interface nsIFileMetadataCallback; %{C++ struct PRFileDesc; %} [ptr] native PRFileDescPtr(PRFileDesc); /** * An input stream that allows you to read from a file. */ [scriptable, uuid(e3d56a20-c7ec-11d3-8cda-0060b0fc14a3)] interface nsIFileInputStream : nsIInputStream { /** * @param file file to read from * @param ioFlags file open flags listed in prio.h (see * PR_Open documentation) or -1 to open the * file in default mode (PR_RDONLY). * @param perm file mode bits listed in prio.h or -1 to * use the default value (0) * @param behaviorFlags flags specifying various behaviors of the class * (see enumerations in the class) */ void init(in nsIFile file, in long ioFlags, in long perm, in long behaviorFlags); /** * If this is set, the file will close automatically when the end of the * file is reached. */ const long CLOSE_ON_EOF = 1<<2; /** * If this is set, the file will be reopened whenever we reach the start of * the file, either by doing a Seek(0, NS_SEEK_CUR), or by doing a relative * seek that happen to reach the beginning of the file. If the file is * already open and the seek occurs, it will happen naturally. (The file * will only be reopened if it is closed for some reason.) */ const long REOPEN_ON_REWIND = 1<<3; /** * If this is set, the file will be opened (i.e., a call to * PR_Open done) only when we do an actual operation on the stream, * or more specifically, when one of the following is called: * - Seek * - Tell * - SetEOF * - Available * - Read * - ReadLine * * DEFER_OPEN is useful if we use the stream on a background * thread, so that the opening and possible |stat|ing of the file * happens there as well. * * @note Using this flag results in the file not being opened * during the call to Init. This means that any errors that might * happen when this flag is not set would happen during the * first read. Also, the file is not locked when Init is called, * so it might be deleted before we try to read from it. */ const long DEFER_OPEN = 1<<4; /** * This flag has no effect and is totally ignored on any platform except * Windows since this is the default behavior on POSIX systems. On Windows * if this flag is set then the stream is opened in a special mode that * allows the OS to delete the file from disk just like POSIX. */ const long SHARE_DELETE = 1<<5; }; /** * An output stream that lets you stream to a file. */ [scriptable, uuid(e734cac9-1295-4e6f-9684-3ac4e1f91063)] interface nsIFileOutputStream : nsIOutputStream { /** * @param file file to write to * @param ioFlags file open flags listed in prio.h (see * PR_Open documentation) or -1 to open the * file in default mode (PR_WRONLY | * PR_CREATE_FILE | PR_TRUNCATE) * @param perm file mode bits listed in prio.h or -1 to * use the default permissions (0664) * @param behaviorFlags flags specifying various behaviors of the class * (currently none supported) */ void init(in nsIFile file, in long ioFlags, in long perm, in long behaviorFlags); /** * @param length asks the operating system to allocate storage for * this file of at least |length| bytes long, and * set the file length to the corresponding size. * @throws NS_ERROR_FAILURE if the preallocation fails. * @throws NS_ERROR_NOT_INITIALIZED if the file is not opened. */ [noscript] void preallocate(in long long length); /** * See the same constant in nsIFileInputStream. The deferred open will * be performed when one of the following is called: * - Seek * - Tell * - SetEOF * - Write * - Flush * * @note Using this flag results in the file not being opened * during the call to Init. This means that any errors that might * happen when this flag is not set would happen during the * first write, and if the file is to be created, then it will not * appear on the disk until the first write. */ const long DEFER_OPEN = 1<<0; }; /** * A stream that allows you to read from a file or stream to a file. */ [scriptable, uuid(82cf605a-8393-4550-83ab-43cd5578e006)] interface nsIFileStream : nsISupports { /** * @param file file to read from or stream to * @param ioFlags file open flags listed in prio.h (see * PR_Open documentation) or -1 to open the * file in default mode (PR_RDWR). * @param perm file mode bits listed in prio.h or -1 to * use the default value (0) * @param behaviorFlags flags specifying various behaviors of the class * (see enumerations in the class) */ void init(in nsIFile file, in long ioFlags, in long perm, in long behaviorFlags); /** * See the same constant in nsIFileInputStream. The deferred open will * be performed when one of the following is called: * - Seek * - Tell * - SetEOF * - Available * - Read * - Flush * - Write * - GetSize * - GetLastModified * * @note Using this flag results in the file not being opened * during the call to Init. This means that any errors that might * happen when this flag is not set would happen during the * first read or write. The file is not locked when Init is called, * so it might be deleted before we try to read from it and if the * file is to be created, then it will not appear on the disk until * the first write. */ const long DEFER_OPEN = 1<<0; }; /** * An interface that allows you to get some metadata like file size and * file last modified time. These methods and attributes can throw * NS_BASE_STREAM_WOULD_BLOCK in case the informations are not available yet. * If this happens, consider the use of nsIAsyncFileMetadata. * * If using nsIAsyncFileMetadata, you should retrieve any data via this * interface before taking any action that might consume the underlying stream. * For example, once Available(), Read(), or nsIAsyncInputStream::AsyncWait() * are invoked, these methods may return NS_BASE_STREAM_CLOSED. This will * happen when using RemoteLazyInputStream with an underlying file stream, for * example. */ [scriptable, uuid(07f679e4-9601-4bd1-b510-cd3852edb881)] interface nsIFileMetadata : nsISupports { /** * File size in bytes. */ readonly attribute long long size; /** * File last modified time in milliseconds from midnight (00:00:00), * January 1, 1970 Greenwich Mean Time (GMT). */ readonly attribute long long lastModified; /** * The internal file descriptor. It can be used for memory mapping of the * underlying file. Please use carefully! If this returns * NS_BASE_STREAM_WOULD_BLOCK, consider the use of nsIAsyncFileMetadata. */ [noscript] PRFileDescPtr getFileDescriptor(); }; [scriptable, uuid(de15b80b-29ba-4b7f-9220-a3d75b17ae8c)] interface nsIAsyncFileMetadata : nsIFileMetadata { /** * Asynchronously wait for the object to be ready. * * @param aCallback The callback will be used when the stream is ready to * return File metadata. Use a nullptr to cancel a * previous operation. * * @param aEventTarget The event target where aCallback will be executed. * If aCallback is passed, aEventTarget cannot be null. */ void asyncFileMetadataWait(in nsIFileMetadataCallback aCallback, in nsIEventTarget aEventTarget); }; /** * This is a companion interface for * nsIAsyncFileMetadata::asyncFileMetadataWait. */ [function, scriptable, uuid(d01c7ead-7ba3-4726-b399-618ec8ec7057)] interface nsIFileMetadataCallback : nsISupports { /** * Called to indicate that the nsIFileMetadata object is ready. */ void onFileMetadataReady(in nsIAsyncFileMetadata aObject); };