The Tor Browser / file comparison

comparison: xpcom/io/nsStreamUtils.h

xpcom/io/nsStreamUtils.h

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

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial