xpcom/io/nsIStreamBufferAccess.idl@97036ab72558 (annotated)
xpcom/io/nsIStreamBufferAccess.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: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| 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 | /** |
| michael@0 | 9 | * An interface for access to a buffering stream implementation's underlying |
| michael@0 | 10 | * memory buffer. |
| michael@0 | 11 | * |
| michael@0 | 12 | * Stream implementations that QueryInterface to nsIStreamBufferAccess must |
| michael@0 | 13 | * ensure that all buffers are aligned on the most restrictive type size for |
| michael@0 | 14 | * the current architecture (e.g., sizeof(double) for RISCy CPUs). malloc(3) |
| michael@0 | 15 | * satisfies this requirement. |
| michael@0 | 16 | */ |
| michael@0 | 17 | [scriptable, uuid(ac923b72-ac87-4892-ac7a-ca385d429435)] |
| michael@0 | 18 | interface nsIStreamBufferAccess : nsISupports |
| michael@0 | 19 | { |
| michael@0 | 20 | /** |
| michael@0 | 21 | * Get access to a contiguous, aligned run of bytes in the stream's buffer. |
| michael@0 | 22 | * Exactly one successful getBuffer call must occur before a putBuffer call |
| michael@0 | 23 | * taking the non-null pointer returned by the successful getBuffer. |
| michael@0 | 24 | * |
| michael@0 | 25 | * The run of bytes are the next bytes (modulo alignment padding) to read |
| michael@0 | 26 | * for an input stream, and the next bytes (modulo alignment padding) to |
| michael@0 | 27 | * store before (eventually) writing buffered data to an output stream. |
| michael@0 | 28 | * There can be space beyond this run of bytes in the buffer for further |
| michael@0 | 29 | * accesses before the fill or flush point is reached. |
| michael@0 | 30 | * |
| michael@0 | 31 | * @param aLength |
| michael@0 | 32 | * Count of contiguous bytes requested at the address A that satisfies |
| michael@0 | 33 | * (A & aAlignMask) == 0 in the buffer, starting from the current stream |
| michael@0 | 34 | * position, mapped to a buffer address B. The stream implementation |
| michael@0 | 35 | * must pad from B to A by skipping bytes (if input stream) or storing |
| michael@0 | 36 | * zero bytes (if output stream). |
| michael@0 | 37 | * |
| michael@0 | 38 | * @param aAlignMask |
| michael@0 | 39 | * Bit-mask computed by subtracting 1 from the power-of-two alignment |
| michael@0 | 40 | * modulus (e.g., 3 or sizeof(uint32_t)-1 for uint32_t alignment). |
| michael@0 | 41 | * |
| michael@0 | 42 | * @return |
| michael@0 | 43 | * The aligned pointer to aLength bytes in the buffer, or null if the |
| michael@0 | 44 | * buffer has no room for aLength bytes starting at the next address A |
| michael@0 | 45 | * after the current position that satisfies (A & aAlignMask) == 0. |
| michael@0 | 46 | */ |
| michael@0 | 47 | [notxpcom,noscript] charPtr getBuffer(in uint32_t aLength, in uint32_t aAlignMask); |
| michael@0 | 48 | |
| michael@0 | 49 | /** |
| michael@0 | 50 | * Relinquish access to the stream's buffer, filling if at end of an input |
| michael@0 | 51 | * buffer, flushing if completing an output buffer. After a getBuffer call |
| michael@0 | 52 | * that returns non-null, putBuffer must be called. |
| michael@0 | 53 | * |
| michael@0 | 54 | * @param aBuffer |
| michael@0 | 55 | * A non-null pointer returned by getBuffer on the same stream buffer |
| michael@0 | 56 | * access object. |
| michael@0 | 57 | * |
| michael@0 | 58 | * @param aLength |
| michael@0 | 59 | * The same count of contiguous bytes passed to the getBuffer call that |
| michael@0 | 60 | * returned aBuffer. |
| michael@0 | 61 | */ |
| michael@0 | 62 | [notxpcom,noscript] void putBuffer(in charPtr aBuffer, in uint32_t aLength); |
| michael@0 | 63 | |
| michael@0 | 64 | /** |
| michael@0 | 65 | * Disable and enable buffering on the stream implementing this interface. |
| michael@0 | 66 | * DisableBuffering flushes an output stream's buffer, and invalidates an |
| michael@0 | 67 | * input stream's buffer. |
| michael@0 | 68 | */ |
| michael@0 | 69 | void disableBuffering(); |
| michael@0 | 70 | void enableBuffering(); |
| michael@0 | 71 | |
| michael@0 | 72 | /** |
| michael@0 | 73 | * The underlying, unbuffered input or output stream. |
| michael@0 | 74 | */ |
| michael@0 | 75 | readonly attribute nsISupports unbufferedStream; |
| michael@0 | 76 | }; |
| michael@0 | 77 | |
| michael@0 | 78 | %{C++ |
| michael@0 | 79 | |
| michael@0 | 80 | /** |
| michael@0 | 81 | * These macros get and put a buffer given either an sba parameter that may |
| michael@0 | 82 | * point to an object implementing nsIStreamBufferAccess, nsIObjectInputStream, |
| michael@0 | 83 | * or nsIObjectOutputStream. |
| michael@0 | 84 | */ |
| michael@0 | 85 | #define NS_GET_BUFFER(sba,n,a) ((sba)->GetBuffer(n, a)) |
| michael@0 | 86 | #define NS_PUT_BUFFER(sba,p,n) ((sba)->PutBuffer(p, n)) |
| michael@0 | 87 | |
| michael@0 | 88 | %} |
