The Tor Browser / file comparison
comparison: xpcom/io/nsIAsyncInputStream.idl
xpcom/io/nsIAsyncInputStream.idl
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
equal
deleted
inserted
replaced
| -1:000000000000 | 0:c7615e885bb5 |
|---|---|
| 1 /* This Source Code Form is subject to the terms of the Mozilla Public | |
| 2 * License, v. 2.0. If a copy of the MPL was not distributed with this | |
| 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ | |
| 4 | |
| 5 #include "nsIInputStream.idl" | |
| 6 | |
| 7 interface nsIInputStreamCallback; | |
| 8 interface nsIEventTarget; | |
| 9 | |
| 10 /** | |
| 11 * If an input stream is non-blocking, it may return NS_BASE_STREAM_WOULD_BLOCK | |
| 12 * when read. The caller must then wait for the stream to have some data to | |
| 13 * read. If the stream implements nsIAsyncInputStream, then the caller can use | |
| 14 * this interface to request an asynchronous notification when the stream | |
| 15 * becomes readable or closed (via the AsyncWait method). | |
| 16 * | |
| 17 * While this interface is almost exclusively used with non-blocking streams, it | |
| 18 * is not necessary that nsIInputStream::isNonBlocking return true. Nor is it | |
| 19 * necessary that a non-blocking nsIInputStream implementation also implement | |
| 20 * nsIAsyncInputStream. | |
| 21 */ | |
| 22 [scriptable, uuid(a5f255ab-4801-4161-8816-277ac92f6ad1)] | |
| 23 interface nsIAsyncInputStream : nsIInputStream | |
| 24 { | |
| 25 /** | |
| 26 * This method closes the stream and sets its internal status. If the | |
| 27 * stream is already closed, then this method is ignored. Once the stream | |
| 28 * is closed, the stream's status cannot be changed. Any successful status | |
| 29 * code passed to this method is treated as NS_BASE_STREAM_CLOSED, which | |
| 30 * has an effect equivalent to nsIInputStream::close. | |
| 31 * | |
| 32 * NOTE: this method exists in part to support pipes, which have both an | |
| 33 * input end and an output end. If the input end of a pipe is closed, then | |
| 34 * writes to the output end of the pipe will fail. The error code returned | |
| 35 * when an attempt is made to write to a "broken" pipe corresponds to the | |
| 36 * status code passed in when the input end of the pipe was closed, which | |
| 37 * greatly simplifies working with pipes in some cases. | |
| 38 * | |
| 39 * @param aStatus | |
| 40 * The error that will be reported if this stream is accessed after | |
| 41 * it has been closed. | |
| 42 */ | |
| 43 void closeWithStatus(in nsresult aStatus); | |
| 44 | |
| 45 /** | |
| 46 * Asynchronously wait for the stream to be readable or closed. The | |
| 47 * notification is one-shot, meaning that each asyncWait call will result | |
| 48 * in exactly one notification callback. After the OnInputStreamReady event | |
| 49 * is dispatched, the stream releases its reference to the | |
| 50 * nsIInputStreamCallback object. It is safe to call asyncWait again from the | |
| 51 * notification handler. | |
| 52 * | |
| 53 * This method may be called at any time (even if read has not been called). | |
| 54 * In other words, this method may be called when the stream already has | |
| 55 * data to read. It may also be called when the stream is closed. If the | |
| 56 * stream is already readable or closed when AsyncWait is called, then the | |
| 57 * OnInputStreamReady event will be dispatched immediately. Otherwise, the | |
| 58 * event will be dispatched when the stream becomes readable or closed. | |
| 59 * | |
| 60 * @param aCallback | |
| 61 * This object is notified when the stream becomes ready. This | |
| 62 * parameter may be null to clear an existing callback. | |
| 63 * @param aFlags | |
| 64 * This parameter specifies optional flags passed in to configure | |
| 65 * the behavior of this method. Pass zero to specify no flags. | |
| 66 * @param aRequestedCount | |
| 67 * Wait until at least this many bytes can be read. This is only | |
| 68 * a suggestion to the underlying stream; it may be ignored. The | |
| 69 * caller may pass zero to indicate no preference. | |
| 70 * @param aEventTarget | |
| 71 * Specify NULL to receive notification on ANY thread (possibly even | |
| 72 * recursively on the calling thread -- i.e., synchronously), or | |
| 73 * specify that the notification be delivered to a specific event | |
| 74 * target. | |
| 75 */ | |
| 76 void asyncWait(in nsIInputStreamCallback aCallback, | |
| 77 in unsigned long aFlags, | |
| 78 in unsigned long aRequestedCount, | |
| 79 in nsIEventTarget aEventTarget); | |
| 80 | |
| 81 /** | |
| 82 * If passed to asyncWait, this flag overrides the default behavior, | |
| 83 * causing the OnInputStreamReady notification to be suppressed until the | |
| 84 * stream becomes closed (either as a result of closeWithStatus/close being | |
| 85 * called on the stream or possibly due to some error in the underlying | |
| 86 * stream). | |
| 87 */ | |
| 88 const unsigned long WAIT_CLOSURE_ONLY = (1<<0); | |
| 89 }; | |
| 90 | |
| 91 /** | |
| 92 * This is a companion interface for nsIAsyncInputStream::asyncWait. | |
| 93 */ | |
| 94 [function, scriptable, uuid(d1f28e94-3a6e-4050-a5f5-2e81b1fc2a43)] | |
| 95 interface nsIInputStreamCallback : nsISupports | |
| 96 { | |
| 97 /** | |
| 98 * Called to indicate that the stream is either readable or closed. | |
| 99 * | |
| 100 * @param aStream | |
| 101 * The stream whose asyncWait method was called. | |
| 102 */ | |
| 103 void onInputStreamReady(in nsIAsyncInputStream aStream); | |
| 104 }; |
