From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- netwerk/base/nsIFileStreams.idl | 239 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 netwerk/base/nsIFileStreams.idl (limited to 'netwerk/base/nsIFileStreams.idl') diff --git a/netwerk/base/nsIFileStreams.idl b/netwerk/base/nsIFileStreams.idl new file mode 100644 index 0000000000..026fa41bcf --- /dev/null +++ b/netwerk/base/nsIFileStreams.idl @@ -0,0 +1,239 @@ +/* -*- 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" +#include "nsIRandomAccessStream.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, builtinclass, 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, builtinclass, 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, builtinclass, uuid(82cf605a-8393-4550-83ab-43cd5578e006)] +interface nsIFileRandomAccessStream : nsIRandomAccessStream +{ + /** + * @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, builtinclass, 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, builtinclass, 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); +}; -- cgit v1.2.3