1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/io/nsStreamUtils.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,264 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#ifndef nsStreamUtils_h__
1.9 +#define nsStreamUtils_h__
1.10 +
1.11 +#include "nsCOMPtr.h"
1.12 +#include "nsStringFwd.h"
1.13 +#include "nsIInputStream.h"
1.14 +#include "nsTArray.h"
1.15 +
1.16 +class nsIOutputStream;
1.17 +class nsIInputStreamCallback;
1.18 +class nsIOutputStreamCallback;
1.19 +class nsIEventTarget;
1.20 +
1.21 +/**
1.22 + * A "one-shot" proxy of the OnInputStreamReady callback. The resulting
1.23 + * proxy object's OnInputStreamReady function may only be called once! The
1.24 + * proxy object ensures that the real notify object will be free'd on the
1.25 + * thread corresponding to the given event target regardless of what thread
1.26 + * the proxy object is destroyed on.
1.27 + *
1.28 + * This function is designed to be used to implement AsyncWait when the
1.29 + * aTarget parameter is non-null.
1.30 + */
1.31 +extern already_AddRefed<nsIInputStreamCallback>
1.32 +NS_NewInputStreamReadyEvent(nsIInputStreamCallback *aNotify,
1.33 + nsIEventTarget *aTarget);
1.34 +
1.35 +/**
1.36 + * A "one-shot" proxy of the OnOutputStreamReady callback. The resulting
1.37 + * proxy object's OnOutputStreamReady function may only be called once! The
1.38 + * proxy object ensures that the real notify object will be free'd on the
1.39 + * thread corresponding to the given event target regardless of what thread
1.40 + * the proxy object is destroyed on.
1.41 + *
1.42 + * This function is designed to be used to implement AsyncWait when the
1.43 + * aTarget parameter is non-null.
1.44 + */
1.45 +extern already_AddRefed<nsIOutputStreamCallback>
1.46 +NS_NewOutputStreamReadyEvent(nsIOutputStreamCallback *aNotify,
1.47 + nsIEventTarget *aTarget);
1.48 +
1.49 +/* ------------------------------------------------------------------------- */
1.50 +
1.51 +enum nsAsyncCopyMode {
1.52 + NS_ASYNCCOPY_VIA_READSEGMENTS,
1.53 + NS_ASYNCCOPY_VIA_WRITESEGMENTS
1.54 +};
1.55 +
1.56 +/**
1.57 + * This function is called when a new chunk of data has been copied. The
1.58 + * reported count is the size of the current chunk.
1.59 + */
1.60 +typedef void (* nsAsyncCopyProgressFun)(void *closure, uint32_t count);
1.61 +
1.62 +/**
1.63 + * This function is called when the async copy process completes. The reported
1.64 + * status is NS_OK on success and some error code on failure.
1.65 + */
1.66 +typedef void (* nsAsyncCopyCallbackFun)(void *closure, nsresult status);
1.67 +
1.68 +/**
1.69 + * This function asynchronously copies data from the source to the sink. All
1.70 + * data transfer occurs on the thread corresponding to the given event target.
1.71 + * A null event target is not permitted.
1.72 + *
1.73 + * The copier handles blocking or non-blocking streams transparently. If a
1.74 + * stream operation returns NS_BASE_STREAM_WOULD_BLOCK, then the stream will
1.75 + * be QI'd to nsIAsync{In,Out}putStream and its AsyncWait method will be used
1.76 + * to determine when to resume copying.
1.77 + *
1.78 + * Source and sink are closed by default when copying finishes or when error
1.79 + * occurs. Caller can prevent closing source or sink by setting aCloseSource
1.80 + * or aCloseSink to false.
1.81 + *
1.82 + * Caller can obtain aCopierCtx to be able to cancel copying.
1.83 + */
1.84 +extern nsresult
1.85 +NS_AsyncCopy(nsIInputStream *aSource,
1.86 + nsIOutputStream *aSink,
1.87 + nsIEventTarget *aTarget,
1.88 + nsAsyncCopyMode aMode = NS_ASYNCCOPY_VIA_READSEGMENTS,
1.89 + uint32_t aChunkSize = 4096,
1.90 + nsAsyncCopyCallbackFun aCallbackFun = nullptr,
1.91 + void *aCallbackClosure = nullptr,
1.92 + bool aCloseSource = true,
1.93 + bool aCloseSink = true,
1.94 + nsISupports **aCopierCtx = nullptr,
1.95 + nsAsyncCopyProgressFun aProgressCallbackFun = nullptr);
1.96 +
1.97 +/**
1.98 + * This function cancels copying started by function NS_AsyncCopy.
1.99 + *
1.100 + * @param aCopierCtx
1.101 + * Copier context returned by NS_AsyncCopy.
1.102 + * @param aReason
1.103 + * A failure code indicating why the operation is being canceled.
1.104 + * It is an error to pass a success code.
1.105 + */
1.106 +extern nsresult
1.107 +NS_CancelAsyncCopy(nsISupports *aCopierCtx, nsresult aReason);
1.108 +
1.109 +/**
1.110 + * This function copies all of the available data from the stream (up to at
1.111 + * most aMaxCount bytes) into the given buffer. The buffer is truncated at
1.112 + * the start of the function.
1.113 + *
1.114 + * If an error occurs while reading from the stream or while attempting to
1.115 + * resize the buffer, then the corresponding error code is returned from this
1.116 + * function, and any data that has already been read will be returned in the
1.117 + * output buffer. This allows one to use this function with a non-blocking
1.118 + * input stream that may return NS_BASE_STREAM_WOULD_BLOCK if it only has
1.119 + * partial data available.
1.120 + *
1.121 + * @param aSource
1.122 + * The input stream to read.
1.123 + * @param aMaxCount
1.124 + * The maximum number of bytes to consume from the stream. Pass the
1.125 + * value UINT32_MAX to consume the entire stream. The number of
1.126 + * bytes actually read is given by the length of aBuffer upon return.
1.127 + * @param aBuffer
1.128 + * The string object that will contain the stream data upon return.
1.129 + * Note: The data copied to the string may contain null bytes and may
1.130 + * contain non-ASCII values.
1.131 + */
1.132 +extern nsresult
1.133 +NS_ConsumeStream(nsIInputStream *aSource, uint32_t aMaxCount,
1.134 + nsACString &aBuffer);
1.135 +
1.136 +/**
1.137 + * This function tests whether or not the input stream is buffered. A buffered
1.138 + * input stream is one that implements readSegments. The test for this is to
1.139 + * 1/ check whether the input stream implements nsIBufferedInputStream;
1.140 + * 2/ if not, call readSegments, without actually consuming any data from the
1.141 + * stream, to verify that it functions.
1.142 + *
1.143 + * NOTE: If the stream is non-blocking and has no data available yet, then this
1.144 + * test will fail. In that case, we return false even though the test is not
1.145 + * really conclusive.
1.146 + *
1.147 + * PERFORMANCE NOTE: If the stream does not implement nsIBufferedInputStream,
1.148 + * calling readSegments may cause I/O. Therefore, you should avoid calling
1.149 + * this function from the main thread.
1.150 + *
1.151 + * @param aInputStream
1.152 + * The input stream to test.
1.153 + */
1.154 +extern bool
1.155 +NS_InputStreamIsBuffered(nsIInputStream *aInputStream);
1.156 +
1.157 +/**
1.158 + * This function tests whether or not the output stream is buffered. A
1.159 + * buffered output stream is one that implements writeSegments. The test for
1.160 + * this is to:
1.161 + * 1/ check whether the output stream implements nsIBufferedOutputStream;
1.162 + * 2/ if not, call writeSegments, without actually writing any data into
1.163 + * the stream, to verify that it functions.
1.164 + *
1.165 + * NOTE: If the stream is non-blocking and has no available space yet, then
1.166 + * this test will fail. In that case, we return false even though the test is
1.167 + * not really conclusive.
1.168 + *
1.169 + * PERFORMANCE NOTE: If the stream does not implement nsIBufferedOutputStream,
1.170 + * calling writeSegments may cause I/O. Therefore, you should avoid calling
1.171 + * this function from the main thread.
1.172 + *
1.173 + * @param aOutputStream
1.174 + * The output stream to test.
1.175 + */
1.176 +extern bool
1.177 +NS_OutputStreamIsBuffered(nsIOutputStream *aOutputStream);
1.178 +
1.179 +/**
1.180 + * This function is intended to be passed to nsIInputStream::ReadSegments to
1.181 + * copy data from the nsIInputStream into a nsIOutputStream passed as the
1.182 + * aClosure parameter to the ReadSegments function.
1.183 + *
1.184 + * @see nsIInputStream.idl for a description of this function's parameters.
1.185 + */
1.186 +extern NS_METHOD
1.187 +NS_CopySegmentToStream(nsIInputStream *aInputStream, void *aClosure,
1.188 + const char *aFromSegment, uint32_t aToOffset,
1.189 + uint32_t aCount, uint32_t *aWriteCount);
1.190 +
1.191 +/**
1.192 + * This function is intended to be passed to nsIInputStream::ReadSegments to
1.193 + * copy data from the nsIInputStream into a character buffer passed as the
1.194 + * aClosure parameter to the ReadSegments function. The character buffer
1.195 + * must be at least as large as the aCount parameter passed to ReadSegments.
1.196 + *
1.197 + * @see nsIInputStream.idl for a description of this function's parameters.
1.198 + */
1.199 +extern NS_METHOD
1.200 +NS_CopySegmentToBuffer(nsIInputStream *aInputStream, void *aClosure,
1.201 + const char *aFromSegment, uint32_t aToOffset,
1.202 + uint32_t aCount, uint32_t *aWriteCount);
1.203 +
1.204 +/**
1.205 + * This function is intended to be passed to nsIOutputStream::WriteSegments to
1.206 + * copy data into the nsIOutputStream from a character buffer passed as the
1.207 + * aClosure parameter to the WriteSegments function.
1.208 + *
1.209 + * @see nsIOutputStream.idl for a description of this function's parameters.
1.210 + */
1.211 +extern NS_METHOD
1.212 +NS_CopySegmentToBuffer(nsIOutputStream *aOutputStream, void *aClosure,
1.213 + char *aToSegment, uint32_t aFromOffset,
1.214 + uint32_t aCount, uint32_t *aReadCount);
1.215 +
1.216 +/**
1.217 + * This function is intended to be passed to nsIInputStream::ReadSegments to
1.218 + * discard data from the nsIInputStream. This can be used to efficiently read
1.219 + * data from the stream without actually copying any bytes.
1.220 + *
1.221 + * @see nsIInputStream.idl for a description of this function's parameters.
1.222 + */
1.223 +extern NS_METHOD
1.224 +NS_DiscardSegment(nsIInputStream *aInputStream, void *aClosure,
1.225 + const char *aFromSegment, uint32_t aToOffset,
1.226 + uint32_t aCount, uint32_t *aWriteCount);
1.227 +
1.228 +/**
1.229 + * This function is intended to be passed to nsIInputStream::ReadSegments to
1.230 + * adjust the aInputStream parameter passed to a consumer's WriteSegmentFun.
1.231 + * The aClosure parameter must be a pointer to a nsWriteSegmentThunk object.
1.232 + * The mStream and mClosure members of that object will be passed to the mFun
1.233 + * function, with the remainder of the parameters being what are passed to
1.234 + * NS_WriteSegmentThunk.
1.235 + *
1.236 + * This function comes in handy when implementing ReadSegments in terms of an
1.237 + * inner stream's ReadSegments.
1.238 + */
1.239 +extern NS_METHOD
1.240 +NS_WriteSegmentThunk(nsIInputStream *aInputStream, void *aClosure,
1.241 + const char *aFromSegment, uint32_t aToOffset,
1.242 + uint32_t aCount, uint32_t *aWriteCount);
1.243 +
1.244 +struct nsWriteSegmentThunk {
1.245 + nsIInputStream *mStream;
1.246 + nsWriteSegmentFun mFun;
1.247 + void *mClosure;
1.248 +};
1.249 +
1.250 +/**
1.251 + * Read data from aInput and store in aDest. A non-zero aKeep will keep that
1.252 + * many bytes from aDest (from the end). New data is appended after the kept
1.253 + * bytes (if any). aDest's new length on returning from this function is
1.254 + * aKeep + aNewBytes and is guaranteed to be less than or equal to aDest's
1.255 + * current capacity.
1.256 + * @param aDest the array to fill
1.257 + * @param aInput the stream to read from
1.258 + * @param aKeep number of bytes to keep (0 <= aKeep <= aDest.Length())
1.259 + * @param aNewBytes (out) number of bytes read from aInput or zero if Read()
1.260 + * failed
1.261 + * @return the result from aInput->Read(...)
1.262 + */
1.263 +extern NS_METHOD
1.264 +NS_FillArray(FallibleTArray<char> &aDest, nsIInputStream *aInput,
1.265 + uint32_t aKeep, uint32_t *aNewBytes);
1.266 +
1.267 +#endif // !nsStreamUtils_h__
