diff -r 000000000000 -r 6474c204b198 xpcom/io/nsStreamUtils.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xpcom/io/nsStreamUtils.h Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,264 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#ifndef nsStreamUtils_h__ +#define nsStreamUtils_h__ + +#include "nsCOMPtr.h" +#include "nsStringFwd.h" +#include "nsIInputStream.h" +#include "nsTArray.h" + +class nsIOutputStream; +class nsIInputStreamCallback; +class nsIOutputStreamCallback; +class nsIEventTarget; + +/** + * A "one-shot" proxy of the OnInputStreamReady callback. The resulting + * proxy object's OnInputStreamReady function may only be called once! The + * proxy object ensures that the real notify object will be free'd on the + * thread corresponding to the given event target regardless of what thread + * the proxy object is destroyed on. + * + * This function is designed to be used to implement AsyncWait when the + * aTarget parameter is non-null. + */ +extern already_AddRefed +NS_NewInputStreamReadyEvent(nsIInputStreamCallback *aNotify, + nsIEventTarget *aTarget); + +/** + * A "one-shot" proxy of the OnOutputStreamReady callback. The resulting + * proxy object's OnOutputStreamReady function may only be called once! The + * proxy object ensures that the real notify object will be free'd on the + * thread corresponding to the given event target regardless of what thread + * the proxy object is destroyed on. + * + * This function is designed to be used to implement AsyncWait when the + * aTarget parameter is non-null. + */ +extern already_AddRefed +NS_NewOutputStreamReadyEvent(nsIOutputStreamCallback *aNotify, + nsIEventTarget *aTarget); + +/* ------------------------------------------------------------------------- */ + +enum nsAsyncCopyMode { + NS_ASYNCCOPY_VIA_READSEGMENTS, + NS_ASYNCCOPY_VIA_WRITESEGMENTS +}; + +/** + * This function is called when a new chunk of data has been copied. The + * reported count is the size of the current chunk. + */ +typedef void (* nsAsyncCopyProgressFun)(void *closure, uint32_t count); + +/** + * This function is called when the async copy process completes. The reported + * status is NS_OK on success and some error code on failure. + */ +typedef void (* nsAsyncCopyCallbackFun)(void *closure, nsresult status); + +/** + * This function asynchronously copies data from the source to the sink. All + * data transfer occurs on the thread corresponding to the given event target. + * A null event target is not permitted. + * + * The copier handles blocking or non-blocking streams transparently. If a + * stream operation returns NS_BASE_STREAM_WOULD_BLOCK, then the stream will + * be QI'd to nsIAsync{In,Out}putStream and its AsyncWait method will be used + * to determine when to resume copying. + * + * Source and sink are closed by default when copying finishes or when error + * occurs. Caller can prevent closing source or sink by setting aCloseSource + * or aCloseSink to false. + * + * Caller can obtain aCopierCtx to be able to cancel copying. + */ +extern nsresult +NS_AsyncCopy(nsIInputStream *aSource, + nsIOutputStream *aSink, + nsIEventTarget *aTarget, + nsAsyncCopyMode aMode = NS_ASYNCCOPY_VIA_READSEGMENTS, + uint32_t aChunkSize = 4096, + nsAsyncCopyCallbackFun aCallbackFun = nullptr, + void *aCallbackClosure = nullptr, + bool aCloseSource = true, + bool aCloseSink = true, + nsISupports **aCopierCtx = nullptr, + nsAsyncCopyProgressFun aProgressCallbackFun = nullptr); + +/** + * This function cancels copying started by function NS_AsyncCopy. + * + * @param aCopierCtx + * Copier context returned by NS_AsyncCopy. + * @param aReason + * A failure code indicating why the operation is being canceled. + * It is an error to pass a success code. + */ +extern nsresult +NS_CancelAsyncCopy(nsISupports *aCopierCtx, nsresult aReason); + +/** + * This function copies all of the available data from the stream (up to at + * most aMaxCount bytes) into the given buffer. The buffer is truncated at + * the start of the function. + * + * If an error occurs while reading from the stream or while attempting to + * resize the buffer, then the corresponding error code is returned from this + * function, and any data that has already been read will be returned in the + * output buffer. This allows one to use this function with a non-blocking + * input stream that may return NS_BASE_STREAM_WOULD_BLOCK if it only has + * partial data available. + * + * @param aSource + * The input stream to read. + * @param aMaxCount + * The maximum number of bytes to consume from the stream. Pass the + * value UINT32_MAX to consume the entire stream. The number of + * bytes actually read is given by the length of aBuffer upon return. + * @param aBuffer + * The string object that will contain the stream data upon return. + * Note: The data copied to the string may contain null bytes and may + * contain non-ASCII values. + */ +extern nsresult +NS_ConsumeStream(nsIInputStream *aSource, uint32_t aMaxCount, + nsACString &aBuffer); + +/** + * This function tests whether or not the input stream is buffered. A buffered + * input stream is one that implements readSegments. The test for this is to + * 1/ check whether the input stream implements nsIBufferedInputStream; + * 2/ if not, call readSegments, without actually consuming any data from the + * stream, to verify that it functions. + * + * NOTE: If the stream is non-blocking and has no data available yet, then this + * test will fail. In that case, we return false even though the test is not + * really conclusive. + * + * PERFORMANCE NOTE: If the stream does not implement nsIBufferedInputStream, + * calling readSegments may cause I/O. Therefore, you should avoid calling + * this function from the main thread. + * + * @param aInputStream + * The input stream to test. + */ +extern bool +NS_InputStreamIsBuffered(nsIInputStream *aInputStream); + +/** + * This function tests whether or not the output stream is buffered. A + * buffered output stream is one that implements writeSegments. The test for + * this is to: + * 1/ check whether the output stream implements nsIBufferedOutputStream; + * 2/ if not, call writeSegments, without actually writing any data into + * the stream, to verify that it functions. + * + * NOTE: If the stream is non-blocking and has no available space yet, then + * this test will fail. In that case, we return false even though the test is + * not really conclusive. + * + * PERFORMANCE NOTE: If the stream does not implement nsIBufferedOutputStream, + * calling writeSegments may cause I/O. Therefore, you should avoid calling + * this function from the main thread. + * + * @param aOutputStream + * The output stream to test. + */ +extern bool +NS_OutputStreamIsBuffered(nsIOutputStream *aOutputStream); + +/** + * This function is intended to be passed to nsIInputStream::ReadSegments to + * copy data from the nsIInputStream into a nsIOutputStream passed as the + * aClosure parameter to the ReadSegments function. + * + * @see nsIInputStream.idl for a description of this function's parameters. + */ +extern NS_METHOD +NS_CopySegmentToStream(nsIInputStream *aInputStream, void *aClosure, + const char *aFromSegment, uint32_t aToOffset, + uint32_t aCount, uint32_t *aWriteCount); + +/** + * This function is intended to be passed to nsIInputStream::ReadSegments to + * copy data from the nsIInputStream into a character buffer passed as the + * aClosure parameter to the ReadSegments function. The character buffer + * must be at least as large as the aCount parameter passed to ReadSegments. + * + * @see nsIInputStream.idl for a description of this function's parameters. + */ +extern NS_METHOD +NS_CopySegmentToBuffer(nsIInputStream *aInputStream, void *aClosure, + const char *aFromSegment, uint32_t aToOffset, + uint32_t aCount, uint32_t *aWriteCount); + +/** + * This function is intended to be passed to nsIOutputStream::WriteSegments to + * copy data into the nsIOutputStream from a character buffer passed as the + * aClosure parameter to the WriteSegments function. + * + * @see nsIOutputStream.idl for a description of this function's parameters. + */ +extern NS_METHOD +NS_CopySegmentToBuffer(nsIOutputStream *aOutputStream, void *aClosure, + char *aToSegment, uint32_t aFromOffset, + uint32_t aCount, uint32_t *aReadCount); + +/** + * This function is intended to be passed to nsIInputStream::ReadSegments to + * discard data from the nsIInputStream. This can be used to efficiently read + * data from the stream without actually copying any bytes. + * + * @see nsIInputStream.idl for a description of this function's parameters. + */ +extern NS_METHOD +NS_DiscardSegment(nsIInputStream *aInputStream, void *aClosure, + const char *aFromSegment, uint32_t aToOffset, + uint32_t aCount, uint32_t *aWriteCount); + +/** + * This function is intended to be passed to nsIInputStream::ReadSegments to + * adjust the aInputStream parameter passed to a consumer's WriteSegmentFun. + * The aClosure parameter must be a pointer to a nsWriteSegmentThunk object. + * The mStream and mClosure members of that object will be passed to the mFun + * function, with the remainder of the parameters being what are passed to + * NS_WriteSegmentThunk. + * + * This function comes in handy when implementing ReadSegments in terms of an + * inner stream's ReadSegments. + */ +extern NS_METHOD +NS_WriteSegmentThunk(nsIInputStream *aInputStream, void *aClosure, + const char *aFromSegment, uint32_t aToOffset, + uint32_t aCount, uint32_t *aWriteCount); + +struct nsWriteSegmentThunk { + nsIInputStream *mStream; + nsWriteSegmentFun mFun; + void *mClosure; +}; + +/** + * Read data from aInput and store in aDest. A non-zero aKeep will keep that + * many bytes from aDest (from the end). New data is appended after the kept + * bytes (if any). aDest's new length on returning from this function is + * aKeep + aNewBytes and is guaranteed to be less than or equal to aDest's + * current capacity. + * @param aDest the array to fill + * @param aInput the stream to read from + * @param aKeep number of bytes to keep (0 <= aKeep <= aDest.Length()) + * @param aNewBytes (out) number of bytes read from aInput or zero if Read() + * failed + * @return the result from aInput->Read(...) + */ +extern NS_METHOD +NS_FillArray(FallibleTArray &aDest, nsIInputStream *aInput, + uint32_t aKeep, uint32_t *aNewBytes); + +#endif // !nsStreamUtils_h__