netwerk/base/nsIFileStreams.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsIInputStream.idl"
   7 #include "nsIOutputStream.idl"
   8 #include "nsIRandomAccessStream.idl"
   9
  10 interface nsIEventTarget;
  11 interface nsIFile;
  12 interface nsIFileMetadataCallback;
  13
  14 %{C++
  15 struct PRFileDesc;
  16 %}
  17
  18 [ptr] native PRFileDescPtr(PRFileDesc);
  19
  20 /**
  21  * An input stream that allows you to read from a file.
  22  */
  23 [scriptable, builtinclass, uuid(e3d56a20-c7ec-11d3-8cda-0060b0fc14a3)]
  24 interface nsIFileInputStream : nsIInputStream
  25 {
  26     /**
  27      * @param file          file to read from
  28      * @param ioFlags       file open flags listed in prio.h (see
  29      *                      PR_Open documentation) or -1 to open the
  30      *                      file in default mode (PR_RDONLY).
  31      * @param perm          file mode bits listed in prio.h or -1 to
  32      *                      use the default value (0)
  33      * @param behaviorFlags flags specifying various behaviors of the class
  34      *        (see enumerations in the class)
  35      */
  36     void init(in nsIFile file, in long ioFlags, in long perm,
  37               in long behaviorFlags);
  38
  39     /**
  40      * If this is set, the file will close automatically when the end of the
  41      * file is reached.
  42      */
  43     const long CLOSE_ON_EOF = 1<<2;
  44
  45     /**
  46      * If this is set, the file will be reopened whenever we reach the start of
  47      * the file, either by doing a Seek(0, NS_SEEK_CUR), or by doing a relative
  48      * seek that happen to reach the beginning of the file. If the file is
  49      * already open and the seek occurs, it will happen naturally.  (The file
  50      * will only be reopened if it is closed for some reason.)
  51      */
  52     const long REOPEN_ON_REWIND = 1<<3;
  53
  54     /**
  55      * If this is set, the file will be opened (i.e., a call to
  56      * PR_Open done) only when we do an actual operation on the stream,
  57      * or more specifically, when one of the following is called:
  58      *   - Seek
  59      *   - Tell
  60      *   - SetEOF
  61      *   - Available
  62      *   - Read
  63      *   - ReadLine
  64      *
  65      * DEFER_OPEN is useful if we use the stream on a background
  66      * thread, so that the opening and possible |stat|ing of the file
  67      * happens there as well.
  68      *
  69      * @note Using this flag results in the file not being opened
  70      *       during the call to Init.  This means that any errors that might
  71      *       happen when this flag is not set would happen during the
  72      *       first read.  Also, the file is not locked when Init is called,
  73      *       so it might be deleted before we try to read from it.
  74      */
  75     const long DEFER_OPEN = 1<<4;
  76
  77     /**
  78      * This flag has no effect and is totally ignored on any platform except
  79      * Windows since this is the default behavior on POSIX systems. On Windows
  80      * if this flag is set then the stream is opened in a special mode that
  81      * allows the OS to delete the file from disk just like POSIX.
  82      */
  83     const long SHARE_DELETE = 1<<5;
  84 };
  85
  86 /**
  87  * An output stream that lets you stream to a file.
  88  */
  89 [scriptable, builtinclass, uuid(e734cac9-1295-4e6f-9684-3ac4e1f91063)]
  90 interface nsIFileOutputStream : nsIOutputStream
  91 {
  92     /**
  93      * @param file          file to write to
  94      * @param ioFlags       file open flags listed in prio.h (see
  95      *                      PR_Open documentation) or -1 to open the
  96      *                      file in default mode (PR_WRONLY |
  97      *                      PR_CREATE_FILE | PR_TRUNCATE)
  98      * @param perm          file mode bits listed in prio.h or -1 to
  99      *                      use the default permissions (0664)
 100      * @param behaviorFlags flags specifying various behaviors of the class
 101      *        (currently none supported)
 102      */
 103     void init(in nsIFile file, in long ioFlags, in long perm,
 104               in long behaviorFlags);
 105
 106     /**
 107      * @param length        asks the operating system to allocate storage for
 108      *                      this file of at least |length| bytes long, and
 109      *                      set the file length to the corresponding size.
 110      * @throws NS_ERROR_FAILURE if the preallocation fails.
 111      * @throws NS_ERROR_NOT_INITIALIZED if the file is not opened.
 112      */
 113     [noscript] void preallocate(in long long length);
 114
 115     /**
 116      * See the same constant in nsIFileInputStream. The deferred open will
 117      * be performed when one of the following is called:
 118      *   - Seek
 119      *   - Tell
 120      *   - SetEOF
 121      *   - Write
 122      *   - Flush
 123      *
 124      * @note Using this flag results in the file not being opened
 125      *       during the call to Init.  This means that any errors that might
 126      *       happen when this flag is not set would happen during the
 127      *       first write, and if the file is to be created, then it will not
 128      *       appear on the disk until the first write.
 129      */
 130     const long DEFER_OPEN = 1<<0;
 131 };
 132
 133 /**
 134  * A stream that allows you to read from a file or stream to a file.
 135  */
 136 [scriptable, builtinclass, uuid(82cf605a-8393-4550-83ab-43cd5578e006)]
 137 interface nsIFileRandomAccessStream : nsIRandomAccessStream
 138 {
 139     /**
 140      * @param file          file to read from or stream to
 141      * @param ioFlags       file open flags listed in prio.h (see
 142      *                      PR_Open documentation) or -1 to open the
 143      *                      file in default mode (PR_RDWR).
 144      * @param perm          file mode bits listed in prio.h or -1 to
 145      *                      use the default value (0)
 146      * @param behaviorFlags flags specifying various behaviors of the class
 147      *        (see enumerations in the class)
 148      */
 149     void init(in nsIFile file, in long ioFlags, in long perm,
 150               in long behaviorFlags);
 151
 152     /**
 153      * See the same constant in nsIFileInputStream. The deferred open will
 154      * be performed when one of the following is called:
 155      *   - Seek
 156      *   - Tell
 157      *   - SetEOF
 158      *   - Available
 159      *   - Read
 160      *   - Flush
 161      *   - Write
 162      *   - GetSize
 163      *   - GetLastModified
 164      *
 165      * @note Using this flag results in the file not being opened
 166      *       during the call to Init.  This means that any errors that might
 167      *       happen when this flag is not set would happen during the
 168      *       first read or write. The file is not locked when Init is called,
 169      *       so it might be deleted before we try to read from it and if the
 170      *       file is to be created, then it will not appear on the disk until
 171      *       the first write.
 172      */
 173     const long DEFER_OPEN = 1<<0;
 174 };
 175
 176 /**
 177  * An interface that allows you to get some metadata like file size and
 178  * file last modified time. These methods and attributes can throw
 179  * NS_BASE_STREAM_WOULD_BLOCK in case the informations are not available yet.
 180  * If this happens, consider the use of nsIAsyncFileMetadata.
 181  *
 182  * If using nsIAsyncFileMetadata, you should retrieve any data via this
 183  * interface before taking any action that might consume the underlying stream.
 184  * For example, once Available(), Read(), or nsIAsyncInputStream::AsyncWait()
 185  * are invoked, these methods may return NS_BASE_STREAM_CLOSED.  This will
 186  * happen when using RemoteLazyInputStream with an underlying file stream, for
 187  * example.
 188  */
 189 [scriptable, builtinclass, uuid(07f679e4-9601-4bd1-b510-cd3852edb881)]
 190 interface nsIFileMetadata : nsISupports
 191 {
 192     /**
 193      * File size in bytes.
 194      */
 195     readonly attribute long long size;
 196
 197     /**
 198      * File last modified time in milliseconds from midnight (00:00:00),
 199      * January 1, 1970 Greenwich Mean Time (GMT).
 200      */
 201     readonly attribute long long lastModified;
 202
 203     /**
 204      * The internal file descriptor. It can be used for memory mapping of the
 205      * underlying file. Please use carefully! If this returns
 206      * NS_BASE_STREAM_WOULD_BLOCK, consider the use of nsIAsyncFileMetadata.
 207      */
 208     [noscript] PRFileDescPtr getFileDescriptor();
 209 };
 210
 211 [scriptable, builtinclass, uuid(de15b80b-29ba-4b7f-9220-a3d75b17ae8c)]
 212 interface nsIAsyncFileMetadata : nsIFileMetadata
 213 {
 214     /**
 215      * Asynchronously wait for the object to be ready.
 216      *
 217      * @param aCallback The callback will be used when the stream is ready to
 218      *                  return File metadata. Use a nullptr to cancel a
 219      *                  previous operation.
 220      *
 221      * @param aEventTarget The event target where aCallback will be executed.
 222      *                     If aCallback is passed, aEventTarget cannot be null.
 223      */
 224     void asyncFileMetadataWait(in nsIFileMetadataCallback aCallback,
 225                                in nsIEventTarget aEventTarget);
 226 };
 227
 228 /**
 229  * This is a companion interface for
 230  * nsIAsyncFileMetadata::asyncFileMetadataWait.
 231  */
 232 [function, scriptable, uuid(d01c7ead-7ba3-4726-b399-618ec8ec7057)]
 233 interface nsIFileMetadataCallback : nsISupports
 234 {
 235     /**
 236      * Called to indicate that the nsIFileMetadata object is ready.
 237      */
 238     void onFileMetadataReady(in nsIAsyncFileMetadata aObject);
 239 };