xpcom/io/nsStreamUtils.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef nsStreamUtils_h__
   8 #define nsStreamUtils_h__
   9
  10 #include "nsCOMPtr.h"
  11 #include "nsStringFwd.h"
  12 #include "nsIInputStream.h"
  13 #include "nsTArray.h"
  14
  15 class nsIOutputStream;
  16 class nsIInputStreamCallback;
  17 class nsIOutputStreamCallback;
  18 class nsIEventTarget;
  19
  20 /**
  21  * A "one-shot" proxy of the OnInputStreamReady callback.  The resulting
  22  * proxy object's OnInputStreamReady function may only be called once!  The
  23  * proxy object ensures that the real notify object will be free'd on the
  24  * thread corresponding to the given event target regardless of what thread
  25  * the proxy object is destroyed on.
  26  *
  27  * This function is designed to be used to implement AsyncWait when the
  28  * aTarget parameter is non-null.
  29  */
  30 extern already_AddRefed<nsIInputStreamCallback>
  31 NS_NewInputStreamReadyEvent(nsIInputStreamCallback* aNotify,
  32                             nsIEventTarget* aTarget);
  33
  34 /**
  35  * A "one-shot" proxy of the OnOutputStreamReady callback.  The resulting
  36  * proxy object's OnOutputStreamReady function may only be called once!  The
  37  * proxy object ensures that the real notify object will be free'd on the
  38  * thread corresponding to the given event target regardless of what thread
  39  * the proxy object is destroyed on.
  40  *
  41  * This function is designed to be used to implement AsyncWait when the
  42  * aTarget parameter is non-null.
  43  */
  44 extern already_AddRefed<nsIOutputStreamCallback>
  45 NS_NewOutputStreamReadyEvent(nsIOutputStreamCallback* aNotify,
  46                              nsIEventTarget* aTarget);
  47
  48 /* ------------------------------------------------------------------------- */
  49
  50 enum nsAsyncCopyMode {
  51   NS_ASYNCCOPY_VIA_READSEGMENTS,
  52   NS_ASYNCCOPY_VIA_WRITESEGMENTS
  53 };
  54
  55 /**
  56  * This function is called when a new chunk of data has been copied.  The
  57  * reported count is the size of the current chunk.
  58  */
  59 typedef void (* nsAsyncCopyProgressFun)(void* closure, uint32_t count);
  60
  61 /**
  62  * This function is called when the async copy process completes.  The reported
  63  * status is NS_OK on success and some error code on failure.
  64  */
  65 typedef void (* nsAsyncCopyCallbackFun)(void* closure, nsresult status);
  66
  67 /**
  68  * This function asynchronously copies data from the source to the sink. All
  69  * data transfer occurs on the thread corresponding to the given event target.
  70  * A null event target is not permitted.
  71  *
  72  * The copier handles blocking or non-blocking streams transparently.  If a
  73  * stream operation returns NS_BASE_STREAM_WOULD_BLOCK, then the stream will
  74  * be QI'd to nsIAsync{In,Out}putStream and its AsyncWait method will be used
  75  * to determine when to resume copying.
  76  *
  77  * Source and sink are closed by default when copying finishes or when error
  78  * occurs. Caller can prevent closing source or sink by setting aCloseSource
  79  * or aCloseSink to false.
  80  *
  81  * Caller can obtain aCopierCtx to be able to cancel copying.
  82  */
  83 extern nsresult
  84 NS_AsyncCopy(nsIInputStream* aSource,
  85              nsIOutputStream* aSink,
  86              nsIEventTarget* aTarget,
  87              nsAsyncCopyMode aMode = NS_ASYNCCOPY_VIA_READSEGMENTS,
  88              uint32_t aChunkSize = 4096,
  89              nsAsyncCopyCallbackFun aCallbackFun = nullptr,
  90              void* aCallbackClosure = nullptr,
  91              bool aCloseSource = true,
  92              bool aCloseSink = true,
  93              nsISupports** aCopierCtx = nullptr,
  94              nsAsyncCopyProgressFun aProgressCallbackFun = nullptr);
  95
  96 /**
  97  * This function cancels copying started by function NS_AsyncCopy.
  98  *
  99  * @param aCopierCtx
 100  *        Copier context returned by NS_AsyncCopy.
 101  * @param aReason
 102  *        A failure code indicating why the operation is being canceled.
 103  *        It is an error to pass a success code.
 104  */
 105 extern nsresult
 106 NS_CancelAsyncCopy(nsISupports* aCopierCtx, nsresult aReason);
 107
 108 /**
 109  * This function copies all of the available data from the stream (up to at
 110  * most aMaxCount bytes) into the given buffer.  The buffer is truncated at
 111  * the start of the function.
 112  *
 113  * If an error occurs while reading from the stream or while attempting to
 114  * resize the buffer, then the corresponding error code is returned from this
 115  * function, and any data that has already been read will be returned in the
 116  * output buffer.  This allows one to use this function with a non-blocking
 117  * input stream that may return NS_BASE_STREAM_WOULD_BLOCK if it only has
 118  * partial data available.
 119  *
 120  * @param aSource
 121  *        The input stream to read.
 122  * @param aMaxCount
 123  *        The maximum number of bytes to consume from the stream.  Pass the
 124  *        value UINT32_MAX to consume the entire stream.  The number of
 125  *        bytes actually read is given by the length of aBuffer upon return.
 126  * @param aBuffer
 127  *        The string object that will contain the stream data upon return.
 128  *        Note: The data copied to the string may contain null bytes and may
 129  *        contain non-ASCII values.
 130  */
 131 extern nsresult
 132 NS_ConsumeStream(nsIInputStream* aSource, uint32_t aMaxCount,
 133                  nsACString& aBuffer);
 134
 135 /**
 136  * This function tests whether or not the input stream is buffered. A buffered
 137  * input stream is one that implements readSegments.  The test for this is to
 138  * 1/ check whether the input stream implements nsIBufferedInputStream;
 139  * 2/ if not, call readSegments, without actually consuming any data from the
 140  * stream, to verify that it functions.
 141  *
 142  * NOTE: If the stream is non-blocking and has no data available yet, then this
 143  * test will fail.  In that case, we return false even though the test is not
 144  * really conclusive.
 145  *
 146  * PERFORMANCE NOTE: If the stream does not implement nsIBufferedInputStream,
 147  * calling readSegments may cause I/O. Therefore, you should avoid calling
 148  * this function from the main thread.
 149  *
 150  * @param aInputStream
 151  *        The input stream to test.
 152  */
 153 extern bool
 154 NS_InputStreamIsBuffered(nsIInputStream* aInputStream);
 155
 156 /**
 157  * This function tests whether or not the output stream is buffered.  A
 158  * buffered output stream is one that implements writeSegments.  The test for
 159  * this is to:
 160  * 1/ check whether the output stream implements nsIBufferedOutputStream;
 161  * 2/ if not, call writeSegments, without actually writing any data into
 162  * the stream, to verify that it functions.
 163  *
 164  * NOTE: If the stream is non-blocking and has no available space yet, then
 165  * this test will fail.  In that case, we return false even though the test is
 166  * not really conclusive.
 167  *
 168  * PERFORMANCE NOTE: If the stream does not implement nsIBufferedOutputStream,
 169  * calling writeSegments may cause I/O. Therefore, you should avoid calling
 170  * this function from the main thread.
 171  *
 172  * @param aOutputStream
 173  *        The output stream to test.
 174  */
 175 extern bool
 176 NS_OutputStreamIsBuffered(nsIOutputStream* aOutputStream);
 177
 178 /**
 179  * This function is intended to be passed to nsIInputStream::ReadSegments to
 180  * copy data from the nsIInputStream into a nsIOutputStream passed as the
 181  * aClosure parameter to the ReadSegments function.
 182  *
 183  * @see nsIInputStream.idl for a description of this function's parameters.
 184  */
 185 extern NS_METHOD
 186 NS_CopySegmentToStream(nsIInputStream* aInputStream, void* aClosure,
 187                        const char* aFromSegment, uint32_t aToOffset,
 188                        uint32_t aCount, uint32_t* aWriteCount);
 189
 190 /**
 191  * This function is intended to be passed to nsIInputStream::ReadSegments to
 192  * copy data from the nsIInputStream into a character buffer passed as the
 193  * aClosure parameter to the ReadSegments function.  The character buffer
 194  * must be at least as large as the aCount parameter passed to ReadSegments.
 195  *
 196  * @see nsIInputStream.idl for a description of this function's parameters.
 197  */
 198 extern NS_METHOD
 199 NS_CopySegmentToBuffer(nsIInputStream* aInputStream, void* aClosure,
 200                        const char* aFromSegment, uint32_t aToOffset,
 201                        uint32_t aCount, uint32_t* aWriteCount);
 202
 203 /**
 204  * This function is intended to be passed to nsIOutputStream::WriteSegments to
 205  * copy data into the nsIOutputStream from a character buffer passed as the
 206  * aClosure parameter to the WriteSegments function.
 207  *
 208  * @see nsIOutputStream.idl for a description of this function's parameters.
 209  */
 210 extern NS_METHOD
 211 NS_CopySegmentToBuffer(nsIOutputStream* aOutputStream, void* aClosure,
 212                        char* aToSegment, uint32_t aFromOffset,
 213                        uint32_t aCount, uint32_t* aReadCount);
 214
 215 /**
 216  * This function is intended to be passed to nsIInputStream::ReadSegments to
 217  * discard data from the nsIInputStream.  This can be used to efficiently read
 218  * data from the stream without actually copying any bytes.
 219  *
 220  * @see nsIInputStream.idl for a description of this function's parameters.
 221  */
 222 extern NS_METHOD
 223 NS_DiscardSegment(nsIInputStream* aInputStream, void* aClosure,
 224                   const char* aFromSegment, uint32_t aToOffset,
 225                   uint32_t aCount, uint32_t* aWriteCount);
 226
 227 /**
 228  * This function is intended to be passed to nsIInputStream::ReadSegments to
 229  * adjust the aInputStream parameter passed to a consumer's WriteSegmentFun.
 230  * The aClosure parameter must be a pointer to a nsWriteSegmentThunk object.
 231  * The mStream and mClosure members of that object will be passed to the mFun
 232  * function, with the remainder of the parameters being what are passed to
 233  * NS_WriteSegmentThunk.
 234  *
 235  * This function comes in handy when implementing ReadSegments in terms of an
 236  * inner stream's ReadSegments.
 237  */
 238 extern NS_METHOD
 239 NS_WriteSegmentThunk(nsIInputStream* aInputStream, void* aClosure,
 240                      const char* aFromSegment, uint32_t aToOffset,
 241                      uint32_t aCount, uint32_t* aWriteCount);
 242
 243 struct nsWriteSegmentThunk
 244 {
 245   nsIInputStream* mStream;
 246   nsWriteSegmentFun mFun;
 247   void* mClosure;
 248 };
 249
 250 /**
 251  * Read data from aInput and store in aDest.  A non-zero aKeep will keep that
 252  * many bytes from aDest (from the end).  New data is appended after the kept
 253  * bytes (if any).  aDest's new length on returning from this function is
 254  * aKeep + aNewBytes and is guaranteed to be less than or equal to aDest's
 255  * current capacity.
 256  * @param aDest the array to fill
 257  * @param aInput the stream to read from
 258  * @param aKeep number of bytes to keep (0 <= aKeep <= aDest.Length())
 259  * @param aNewBytes (out) number of bytes read from aInput or zero if Read()
 260  *        failed
 261  * @return the result from aInput->Read(...)
 262  */
 263 extern NS_METHOD
 264 NS_FillArray(FallibleTArray<char>& aDest, nsIInputStream* aInput,
 265              uint32_t aKeep, uint32_t* aNewBytes);
 266
 267 #endif // !nsStreamUtils_h__