1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/io/nsIStreamBufferAccess.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,88 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +/**
1.12 + * An interface for access to a buffering stream implementation's underlying
1.13 + * memory buffer.
1.14 + *
1.15 + * Stream implementations that QueryInterface to nsIStreamBufferAccess must
1.16 + * ensure that all buffers are aligned on the most restrictive type size for
1.17 + * the current architecture (e.g., sizeof(double) for RISCy CPUs). malloc(3)
1.18 + * satisfies this requirement.
1.19 + */
1.20 +[scriptable, uuid(ac923b72-ac87-4892-ac7a-ca385d429435)]
1.21 +interface nsIStreamBufferAccess : nsISupports
1.22 +{
1.23 + /**
1.24 + * Get access to a contiguous, aligned run of bytes in the stream's buffer.
1.25 + * Exactly one successful getBuffer call must occur before a putBuffer call
1.26 + * taking the non-null pointer returned by the successful getBuffer.
1.27 + *
1.28 + * The run of bytes are the next bytes (modulo alignment padding) to read
1.29 + * for an input stream, and the next bytes (modulo alignment padding) to
1.30 + * store before (eventually) writing buffered data to an output stream.
1.31 + * There can be space beyond this run of bytes in the buffer for further
1.32 + * accesses before the fill or flush point is reached.
1.33 + *
1.34 + * @param aLength
1.35 + * Count of contiguous bytes requested at the address A that satisfies
1.36 + * (A & aAlignMask) == 0 in the buffer, starting from the current stream
1.37 + * position, mapped to a buffer address B. The stream implementation
1.38 + * must pad from B to A by skipping bytes (if input stream) or storing
1.39 + * zero bytes (if output stream).
1.40 + *
1.41 + * @param aAlignMask
1.42 + * Bit-mask computed by subtracting 1 from the power-of-two alignment
1.43 + * modulus (e.g., 3 or sizeof(uint32_t)-1 for uint32_t alignment).
1.44 + *
1.45 + * @return
1.46 + * The aligned pointer to aLength bytes in the buffer, or null if the
1.47 + * buffer has no room for aLength bytes starting at the next address A
1.48 + * after the current position that satisfies (A & aAlignMask) == 0.
1.49 + */
1.50 + [notxpcom,noscript] charPtr getBuffer(in uint32_t aLength, in uint32_t aAlignMask);
1.51 +
1.52 + /**
1.53 + * Relinquish access to the stream's buffer, filling if at end of an input
1.54 + * buffer, flushing if completing an output buffer. After a getBuffer call
1.55 + * that returns non-null, putBuffer must be called.
1.56 + *
1.57 + * @param aBuffer
1.58 + * A non-null pointer returned by getBuffer on the same stream buffer
1.59 + * access object.
1.60 + *
1.61 + * @param aLength
1.62 + * The same count of contiguous bytes passed to the getBuffer call that
1.63 + * returned aBuffer.
1.64 + */
1.65 + [notxpcom,noscript] void putBuffer(in charPtr aBuffer, in uint32_t aLength);
1.66 +
1.67 + /**
1.68 + * Disable and enable buffering on the stream implementing this interface.
1.69 + * DisableBuffering flushes an output stream's buffer, and invalidates an
1.70 + * input stream's buffer.
1.71 + */
1.72 + void disableBuffering();
1.73 + void enableBuffering();
1.74 +
1.75 + /**
1.76 + * The underlying, unbuffered input or output stream.
1.77 + */
1.78 + readonly attribute nsISupports unbufferedStream;
1.79 +};
1.80 +
1.81 +%{C++
1.82 +
1.83 +/**
1.84 + * These macros get and put a buffer given either an sba parameter that may
1.85 + * point to an object implementing nsIStreamBufferAccess, nsIObjectInputStream,
1.86 + * or nsIObjectOutputStream.
1.87 + */
1.88 +#define NS_GET_BUFFER(sba,n,a) ((sba)->GetBuffer(n, a))
1.89 +#define NS_PUT_BUFFER(sba,p,n) ((sba)->PutBuffer(p, n))
1.90 +
1.91 +%}
