gecko/netwerk/base/nsIFileStreams.idl

217 lines
8.2 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"
interface nsIFile;
/**
* 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 be deleted by the time the stream is
* closed. It may be removed before the stream is closed if it is possible
* to delete it and still read from it.
*
* If OPEN_ON_READ is defined, and the file was recreated after the first
* delete, the file will be deleted again when it is closed again.
*/
const long DELETE_ON_CLOSE = 1<<1;
/**
* 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(e6f68040-c7ec-11d3-8cda-0060b0fc14a3)]
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);
/**
* 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;
};
/**
* An input stream that allows you to read from a slice of a file.
*/
[scriptable, uuid(3ce03a2f-97f7-4375-b6bb-1788a60cad3b)]
interface nsIPartialFileInputStream : nsISupports
{
/**
* Initialize with a file and new start/end positions. Both start and
* start+length must be smaller than the size of the file. Not doing so
* will lead to undefined behavior.
* You must initialize the stream, and only initialize it once, before it
* can be used.
*
* @param file file to read from
* @param start start offset of slice to read. Must be smaller
* than the size of the file.
* @param length length of slice to read. Must be small enough that
* start+length is smaller than the size of the file.
* @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 nsIFileInputStream)
*/
void init(in nsIFile file, in unsigned long long start,
in unsigned long long length,
in long ioFlags, in long perm, in long behaviorFlags);
};
/**
* 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.
*/
[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;
};