nsIFileStreams.idl (9130B)
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 };