The Tor Browser: xpcom/io/nsStreamUtils.h@6474c204b198 (annotated)

xpcom/io/nsStreamUtils.h@6474c204b198 (annotated)

xpcom/io/nsStreamUtils.h

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /* 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<nsIInputStreamCallback>
 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<nsIOutputStreamCallback>
 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<char> &aDest, nsIInputStream *aInput,
              uint32_t aKeep, uint32_t *aNewBytes);
 #endif // !nsStreamUtils_h__

The Tor Browser / annotate

xpcom/io/nsStreamUtils.h@6474c204b198 (annotated)

xpcom/io/nsStreamUtils.h