pjs/netwerk/base/public/nsIFileStreams.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#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 (must QI to nsILocalFile)
     * @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 Seek(0) occurs.  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
     *   - 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;
};

/**
 * 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 (must QI to nsILocalFile)
     * @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
     *   - 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 (must QI to nsILocalFile)
     * @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);
};