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