mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-01 00:32:11 +00:00
240 lines
8.9 KiB
Plaintext
240 lines
8.9 KiB
Plaintext
/* -*- 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);
|
|
};
|