xpcom/io/nsStreamUtils.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is Mozilla.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 2002
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Darin Fisher <darin@netscape.com>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsStreamUtils_h__
  39 #define nsStreamUtils_h__
  40
  41 #include "nsStringFwd.h"
  42 #include "nsIInputStream.h"
  43
  44 class nsIOutputStream;
  45 class nsIInputStreamCallback;
  46 class nsIOutputStreamCallback;
  47 class nsIEventTarget;
  48
  49 /**
  50  * A "one-shot" proxy of the OnInputStreamReady callback.  The resulting
  51  * proxy object's OnInputStreamReady function may only be called once!  The
  52  * proxy object ensures that the real notify object will be free'd on the
  53  * thread corresponding to the given event target regardless of what thread
  54  * the proxy object is destroyed on.
  55  *
  56  * This function is designed to be used to implement AsyncWait when the
  57  * aTarget parameter is non-null.
  58  */
  59 extern NS_COM nsresult
  60 NS_NewInputStreamReadyEvent(nsIInputStreamCallback **aEvent,
  61                             nsIInputStreamCallback  *aNotify,
  62                             nsIEventTarget          *aTarget);
  63
  64 /**
  65  * A "one-shot" proxy of the OnOutputStreamReady callback.  The resulting
  66  * proxy object's OnOutputStreamReady function may only be called once!  The
  67  * proxy object ensures that the real notify object will be free'd on the
  68  * thread corresponding to the given event target regardless of what thread
  69  * the proxy object is destroyed on.
  70  *
  71  * This function is designed to be used to implement AsyncWait when the
  72  * aTarget parameter is non-null.
  73  */
  74 extern NS_COM nsresult
  75 NS_NewOutputStreamReadyEvent(nsIOutputStreamCallback **aEvent,
  76                              nsIOutputStreamCallback  *aNotify,
  77                              nsIEventTarget           *aTarget);
  78
  79 /* ------------------------------------------------------------------------- */
  80
  81 enum nsAsyncCopyMode {
  82     NS_ASYNCCOPY_VIA_READSEGMENTS,
  83     NS_ASYNCCOPY_VIA_WRITESEGMENTS
  84 };
  85
  86 /**
  87  * This function is called when the async copy process completes.  The reported
  88  * status is NS_OK on success and some error code on failure.
  89  */
  90 typedef void (* nsAsyncCopyCallbackFun)(void *closure, nsresult status);
  91
  92 /**
  93  * This function asynchronously copies data from the source to the sink. All
  94  * data transfer occurs on the thread corresponding to the given event target.
  95  * A null event target is not permitted.
  96  *
  97  * The copier handles blocking or non-blocking streams transparently.  If a
  98  * stream operation returns NS_BASE_STREAM_WOULD_BLOCK, then the stream will
  99  * be QI'd to nsIAsync{In,Out}putStream and its AsyncWait method will be used
 100  * to determine when to resume copying.
 101  */
 102 extern NS_COM nsresult
 103 NS_AsyncCopy(nsIInputStream         *aSource,
 104              nsIOutputStream        *aSink,
 105              nsIEventTarget         *aTarget,
 106              nsAsyncCopyMode         aMode = NS_ASYNCCOPY_VIA_READSEGMENTS,
 107              PRUint32                aChunkSize = 4096,
 108              nsAsyncCopyCallbackFun  aCallbackFun = nsnull,
 109              void                   *aCallbackClosure = nsnull);
 110
 111 /**
 112  * This function copies all of the available data from the stream (up to at
 113  * most aMaxCount bytes) into the given buffer.  The buffer is truncated at
 114  * the start of the function.
 115  *
 116  * If an error occurs while reading from the stream or while attempting to
 117  * resize the buffer, then the corresponding error code is returned from this
 118  * function, and any data that has already been read will be returned in the
 119  * output buffer.  This allows one to use this function with a non-blocking
 120  * input stream that may return NS_BASE_STREAM_WOULD_BLOCK if it only has
 121  * partial data available.
 122  *
 123  * @param aSource
 124  *        The input stream to read.
 125  * @param aMaxCount
 126  *        The maximum number of bytes to consume from the stream.  Pass the
 127  *        value PR_UINT32_MAX to consume the entire stream.  The number of
 128  *        bytes actually read is given by the length of aBuffer upon return.
 129  * @param aBuffer
 130  *        The string object that will contain the stream data upon return.
 131  *        Note: The data copied to the string may contain null bytes and may
 132  *        contain non-ASCII values.
 133  */
 134 extern NS_COM nsresult
 135 NS_ConsumeStream(nsIInputStream *aSource, PRUint32 aMaxCount,
 136                  nsACString &aBuffer);
 137
 138 /**
 139  * This function tests whether or not the input stream is buffered.  A buffered
 140  * input stream is one that implements readSegments.  The test for this is to
 141  * simply call readSegments, without actually consuming any data from the
 142  * stream, to verify that it functions.
 143  *
 144  * NOTE: If the stream is non-blocking and has no data available yet, then this
 145  * test will fail.  In that case, we return false even though the test is not
 146  * really conclusive.
 147  *
 148  * @param aInputStream
 149  *        The input stream to test.
 150  */
 151 extern NS_COM PRBool
 152 NS_InputStreamIsBuffered(nsIInputStream *aInputStream);
 153
 154 /**
 155  * This function tests whether or not the output stream is buffered.  A
 156  * buffered output stream is one that implements writeSegments.  The test for
 157  * this is to simply call writeSegments, without actually writing any data into
 158  * the stream, to verify that it functions.
 159  *
 160  * NOTE: If the stream is non-blocking and has no available space yet, then
 161  * this test will fail.  In that case, we return false even though the test is
 162  * not really conclusive.
 163  *
 164  * @param aOutputStream
 165  *        The output stream to test.
 166  */
 167 extern NS_COM PRBool
 168 NS_OutputStreamIsBuffered(nsIOutputStream *aOutputStream);
 169
 170 /**
 171  * This function is intended to be passed to nsIInputStream::ReadSegments to
 172  * copy data from the nsIInputStream into a nsIOutputStream passed as the
 173  * aClosure parameter to the ReadSegments function.
 174  *
 175  * @see nsIInputStream.idl for a description of this function's parameters.
 176  */
 177 extern NS_COM NS_METHOD
 178 NS_CopySegmentToStream(nsIInputStream *aInputStream, void *aClosure,
 179                        const char *aFromSegment, PRUint32 aToOffset,
 180                        PRUint32 aCount, PRUint32 *aWriteCount);
 181
 182 /**
 183  * This function is intended to be passed to nsIInputStream::ReadSegments to
 184  * copy data from the nsIInputStream into a character buffer passed as the
 185  * aClosure parameter to the ReadSegments function.  The character buffer
 186  * must be at least as large as the aCount parameter passed to ReadSegments.
 187  *
 188  * @see nsIInputStream.idl for a description of this function's parameters.
 189  */
 190 extern NS_COM NS_METHOD
 191 NS_CopySegmentToBuffer(nsIInputStream *aInputStream, void *aClosure,
 192                        const char *aFromSegment, PRUint32 aToOffset,
 193                        PRUint32 aCount, PRUint32 *aWriteCount);
 194
 195 /**
 196  * This function is intended to be passed to nsIInputStream::ReadSegments to
 197  * discard data from the nsIInputStream.  This can be used to efficiently read
 198  * data from the stream without actually copying any bytes.
 199  *
 200  * @see nsIInputStream.idl for a description of this function's parameters.
 201  */
 202 extern NS_COM NS_METHOD
 203 NS_DiscardSegment(nsIInputStream *aInputStream, void *aClosure,
 204                   const char *aFromSegment, PRUint32 aToOffset,
 205                   PRUint32 aCount, PRUint32 *aWriteCount);
 206
 207 /**
 208  * This function is intended to be passed to nsIInputStream::ReadSegments to
 209  * adjust the aInputStream parameter passed to a consumer's WriteSegmentFun.
 210  * The aClosure parameter must be a pointer to a nsWriteSegmentThunk object.
 211  * The mStream and mClosure members of that object will be passed to the mFun
 212  * function, with the remainder of the parameters being what are passed to
 213  * NS_WriteSegmentThunk.
 214  *
 215  * This function comes in handy when implementing ReadSegments in terms of an
 216  * inner stream's ReadSegments.
 217  */
 218 extern NS_COM NS_METHOD
 219 NS_WriteSegmentThunk(nsIInputStream *aInputStream, void *aClosure,
 220                      const char *aFromSegment, PRUint32 aToOffset,
 221                      PRUint32 aCount, PRUint32 *aWriteCount);
 222
 223 struct nsWriteSegmentThunk {
 224   nsIInputStream    *mStream;
 225   nsWriteSegmentFun  mFun;
 226   void              *mClosure;
 227 };
 228
 229 #endif // !nsStreamUtils_h__