xpcom/io/nsIUnicharInputStream.idl@97036ab72558 (annotated)
xpcom/io/nsIUnicharInputStream.idl
Tue, 06 Jan 2015 21:39:09 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Tue, 06 Jan 2015 21:39:09 +0100
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
- permissions
- -rw-r--r--
Conditionally force memory storage according to privacy.thirdparty.isolate;
This solves Tor bug #9701, complying with disk avoidance documented in
https://www.torproject.org/projects/torbrowser/design/#disk-avoidance.
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #include "nsISupports.idl" |
| michael@0 | 7 | |
| michael@0 | 8 | interface nsIUnicharInputStream; |
| michael@0 | 9 | interface nsIInputStream; |
| michael@0 | 10 | |
| michael@0 | 11 | %{C++ |
| michael@0 | 12 | /** |
| michael@0 | 13 | * The signature of the writer function passed to ReadSegments. This |
| michael@0 | 14 | * is the "consumer" of data that gets read from the stream's buffer. |
| michael@0 | 15 | * |
| michael@0 | 16 | * @param aInStream stream being read |
| michael@0 | 17 | * @param aClosure opaque parameter passed to ReadSegments |
| michael@0 | 18 | * @param aFromSegment pointer to memory owned by the input stream |
| michael@0 | 19 | * @param aToOffset amount already read (since ReadSegments was called) |
| michael@0 | 20 | * @param aCount length of fromSegment |
| michael@0 | 21 | * @param aWriteCount number of bytes read |
| michael@0 | 22 | * |
| michael@0 | 23 | * Implementers should return the following: |
| michael@0 | 24 | * |
| michael@0 | 25 | * @throws <any-error> if not interested in consuming any data |
| michael@0 | 26 | * |
| michael@0 | 27 | * Errors are never passed to the caller of ReadSegments. |
| michael@0 | 28 | * |
| michael@0 | 29 | * NOTE: returning NS_OK and (*aWriteCount = 0) has undefined behavior. |
| michael@0 | 30 | */ |
| michael@0 | 31 | typedef NS_CALLBACK(nsWriteUnicharSegmentFun)(nsIUnicharInputStream *aInStream, |
| michael@0 | 32 | void *aClosure, |
| michael@0 | 33 | const char16_t *aFromSegment, |
| michael@0 | 34 | uint32_t aToOffset, |
| michael@0 | 35 | uint32_t aCount, |
| michael@0 | 36 | uint32_t *aWriteCount); |
| michael@0 | 37 | %} |
| michael@0 | 38 | native nsWriteUnicharSegmentFun(nsWriteUnicharSegmentFun); |
| michael@0 | 39 | |
| michael@0 | 40 | /** |
| michael@0 | 41 | * Abstract unicode character input stream |
| michael@0 | 42 | * @see nsIInputStream |
| michael@0 | 43 | */ |
| michael@0 | 44 | [scriptable, uuid(d5e3bd80-6723-4b92-b0c9-22f6162fd94f)] |
| michael@0 | 45 | interface nsIUnicharInputStream : nsISupports { |
| michael@0 | 46 | /** |
| michael@0 | 47 | * Reads into a caller-provided character array. |
| michael@0 | 48 | * |
| michael@0 | 49 | * @return The number of characters that were successfully read. May be less |
| michael@0 | 50 | * than aCount, even if there is more data in the input stream. |
| michael@0 | 51 | * A return value of 0 means EOF. |
| michael@0 | 52 | * |
| michael@0 | 53 | * @note To read more than 2^32 characters, call this method multiple times. |
| michael@0 | 54 | */ |
| michael@0 | 55 | [noscript] unsigned long read([array, size_is(aCount)] in char16_t aBuf, |
| michael@0 | 56 | in unsigned long aCount); |
| michael@0 | 57 | |
| michael@0 | 58 | /** |
| michael@0 | 59 | * Low-level read method that has access to the stream's underlying buffer. |
| michael@0 | 60 | * The writer function may be called multiple times for segmented buffers. |
| michael@0 | 61 | * ReadSegments is expected to keep calling the writer until either there is |
| michael@0 | 62 | * nothing left to read or the writer returns an error. ReadSegments should |
| michael@0 | 63 | * not call the writer with zero characters to consume. |
| michael@0 | 64 | * |
| michael@0 | 65 | * @param aWriter the "consumer" of the data to be read |
| michael@0 | 66 | * @param aClosure opaque parameter passed to writer |
| michael@0 | 67 | * @param aCount the maximum number of characters to be read |
| michael@0 | 68 | * |
| michael@0 | 69 | * @return number of characters read (may be less than aCount) |
| michael@0 | 70 | * @return 0 if reached end of file (or if aWriter refused to consume data) |
| michael@0 | 71 | * |
| michael@0 | 72 | * @throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would |
| michael@0 | 73 | * block the calling thread (non-blocking mode only) |
| michael@0 | 74 | * @throws <other-error> on failure |
| michael@0 | 75 | * |
| michael@0 | 76 | * NOTE: this function may be unimplemented if a stream has no underlying |
| michael@0 | 77 | * buffer |
| michael@0 | 78 | */ |
| michael@0 | 79 | [noscript] unsigned long readSegments(in nsWriteUnicharSegmentFun aWriter, |
| michael@0 | 80 | in voidPtr aClosure, |
| michael@0 | 81 | in unsigned long aCount); |
| michael@0 | 82 | |
| michael@0 | 83 | /** |
| michael@0 | 84 | * Read into a string object. |
| michael@0 | 85 | * @param aCount The number of characters that should be read |
| michael@0 | 86 | * @return The number of characters that were read. |
| michael@0 | 87 | */ |
| michael@0 | 88 | unsigned long readString(in unsigned long aCount, out AString aString); |
| michael@0 | 89 | |
| michael@0 | 90 | /** |
| michael@0 | 91 | * Close the stream and free associated resources. This also closes the |
| michael@0 | 92 | * underlying stream, if any. |
| michael@0 | 93 | */ |
| michael@0 | 94 | void close(); |
| michael@0 | 95 | }; |
