The Tor Browser / file comparison
comparison: xpcom/io/nsIPipe.idl
xpcom/io/nsIPipe.idl
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
equal
deleted
inserted
replaced
| -1:000000000000 | 0:5838d589c4fe |
|---|---|
| 1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ | |
| 2 /* This Source Code Form is subject to the terms of the Mozilla Public | |
| 3 * License, v. 2.0. If a copy of the MPL was not distributed with this | |
| 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ | |
| 5 | |
| 6 #include "nsISupports.idl" | |
| 7 | |
| 8 interface nsIAsyncInputStream; | |
| 9 interface nsIAsyncOutputStream; | |
| 10 | |
| 11 /** | |
| 12 * nsIPipe represents an in-process buffer that can be read using nsIInputStream | |
| 13 * and written using nsIOutputStream. The reader and writer of a pipe do not | |
| 14 * have to be on the same thread. As a result, the pipe is an ideal mechanism | |
| 15 * to bridge data exchange between two threads. For example, a worker thread | |
| 16 * might write data to a pipe from which the main thread will read. | |
| 17 * | |
| 18 * Each end of the pipe can be either blocking or non-blocking. Recall that a | |
| 19 * non-blocking stream will return NS_BASE_STREAM_WOULD_BLOCK if it cannot be | |
| 20 * read or written to without blocking the calling thread. For example, if you | |
| 21 * try to read from an empty pipe that has not yet been closed, then if that | |
| 22 * pipe's input end is non-blocking, then the read call will fail immediately | |
| 23 * with NS_BASE_STREAM_WOULD_BLOCK as the error condition. However, if that | |
| 24 * pipe's input end is blocking, then the read call will not return until the | |
| 25 * pipe has data or until the pipe is closed. This example presumes that the | |
| 26 * pipe is being filled asynchronously on some background thread. | |
| 27 * | |
| 28 * The pipe supports nsIAsyncInputStream and nsIAsyncOutputStream, which give | |
| 29 * the user of a non-blocking pipe the ability to wait for the pipe to become | |
| 30 * ready again. For example, in the case of an empty non-blocking pipe, the | |
| 31 * user can call AsyncWait on the input end of the pipe to be notified when | |
| 32 * the pipe has data to read (or when the pipe becomes closed). | |
| 33 * | |
| 34 * NS_NewPipe2 and NS_NewPipe provide convenient pipe constructors. In most | |
| 35 * cases nsIPipe is not actually used. It is usually enough to just get | |
| 36 * references to the pipe's input and output end. In which case, the pipe is | |
| 37 * automatically closed when the respective pipe ends are released. | |
| 38 */ | |
| 39 [scriptable, uuid(25d0de93-685e-4ea4-95d3-d884e31df63c)] | |
| 40 interface nsIPipe : nsISupports | |
| 41 { | |
| 42 /** | |
| 43 * initialize this pipe | |
| 44 * | |
| 45 * @param nonBlockingInput | |
| 46 * true specifies non-blocking input stream behavior | |
| 47 * @param nonBlockingOutput | |
| 48 * true specifies non-blocking output stream behavior | |
| 49 * @param segmentSize | |
| 50 * specifies the segment size in bytes (pass 0 to use default value) | |
| 51 * @param segmentCount | |
| 52 * specifies the max number of segments (pass 0 to use default | |
| 53 * value). Passing UINT32_MAX here causes the pipe to have | |
| 54 * "infinite" space. This mode can be useful in some cases, but | |
| 55 * should always be used with caution. The default value for this | |
| 56 * parameter is a finite value. | |
| 57 */ | |
| 58 void init(in boolean nonBlockingInput, | |
| 59 in boolean nonBlockingOutput, | |
| 60 in unsigned long segmentSize, | |
| 61 in unsigned long segmentCount); | |
| 62 | |
| 63 /** | |
| 64 * The pipe's input end, which also implements nsISearchableInputStream. | |
| 65 */ | |
| 66 readonly attribute nsIAsyncInputStream inputStream; | |
| 67 | |
| 68 /** | |
| 69 * The pipe's output end. | |
| 70 */ | |
| 71 readonly attribute nsIAsyncOutputStream outputStream; | |
| 72 }; | |
| 73 | |
| 74 /** | |
| 75 * XXX this interface doesn't really belong in here. It is here because | |
| 76 * currently nsPipeInputStream is the only implementation of this interface. | |
| 77 */ | |
| 78 [scriptable, uuid(8C39EF62-F7C9-11d4-98F5-001083010E9B)] | |
| 79 interface nsISearchableInputStream : nsISupports | |
| 80 { | |
| 81 /** | |
| 82 * Searches for a string in the input stream. Since the stream has a notion | |
| 83 * of EOF, it is possible that the string may at some time be in the | |
| 84 * buffer, but is is not currently found up to some offset. Consequently, | |
| 85 * both the found and not found cases return an offset: | |
| 86 * if found, return offset where it was found | |
| 87 * if not found, return offset of the first byte not searched | |
| 88 * In the case the stream is at EOF and the string is not found, the first | |
| 89 * byte not searched will correspond to the length of the buffer. | |
| 90 */ | |
| 91 void search(in string forString, | |
| 92 in boolean ignoreCase, | |
| 93 out boolean found, | |
| 94 out unsigned long offsetSearchedTo); | |
| 95 }; | |
| 96 | |
| 97 %{C++ | |
| 98 | |
| 99 class nsIInputStream; | |
| 100 class nsIOutputStream; | |
| 101 | |
| 102 /** | |
| 103 * NS_NewPipe2 | |
| 104 * | |
| 105 * This function supersedes NS_NewPipe. It differs from NS_NewPipe in two | |
| 106 * major ways: | |
| 107 * (1) returns nsIAsyncInputStream and nsIAsyncOutputStream, so it is | |
| 108 * not necessary to QI in order to access these interfaces. | |
| 109 * (2) the size of the pipe is determined by the number of segments | |
| 110 * times the size of each segment. | |
| 111 * | |
| 112 * @param pipeIn | |
| 113 * resulting input end of the pipe | |
| 114 * @param pipeOut | |
| 115 * resulting output end of the pipe | |
| 116 * @param nonBlockingInput | |
| 117 * true specifies non-blocking input stream behavior | |
| 118 * @param nonBlockingOutput | |
| 119 * true specifies non-blocking output stream behavior | |
| 120 * @param segmentSize | |
| 121 * specifies the segment size in bytes (pass 0 to use default value) | |
| 122 * @param segmentCount | |
| 123 * specifies the max number of segments (pass 0 to use default value) | |
| 124 * passing UINT32_MAX here causes the pipe to have "infinite" space. | |
| 125 * this mode can be useful in some cases, but should always be used with | |
| 126 * caution. the default value for this parameter is a finite value. | |
| 127 */ | |
| 128 extern nsresult | |
| 129 NS_NewPipe2(nsIAsyncInputStream **pipeIn, | |
| 130 nsIAsyncOutputStream **pipeOut, | |
| 131 bool nonBlockingInput = false, | |
| 132 bool nonBlockingOutput = false, | |
| 133 uint32_t segmentSize = 0, | |
| 134 uint32_t segmentCount = 0); | |
| 135 | |
| 136 /** | |
| 137 * NS_NewPipe | |
| 138 * | |
| 139 * Preserved for backwards compatibility. Plus, this interface is more | |
| 140 * amiable in certain contexts (e.g., when you don't need the pipe's async | |
| 141 * capabilities). | |
| 142 * | |
| 143 * @param pipeIn | |
| 144 * resulting input end of the pipe | |
| 145 * @param pipeOut | |
| 146 * resulting output end of the pipe | |
| 147 * @param segmentSize | |
| 148 * specifies the segment size in bytes (pass 0 to use default value) | |
| 149 * @param maxSize | |
| 150 * specifies the max size of the pipe (pass 0 to use default value) | |
| 151 * number of segments is maxSize / segmentSize, and maxSize must be a | |
| 152 * multiple of segmentSize. passing UINT32_MAX here causes the | |
| 153 * pipe to have "infinite" space. this mode can be useful in some | |
| 154 * cases, but should always be used with caution. the default value | |
| 155 * for this parameter is a finite value. | |
| 156 * @param nonBlockingInput | |
| 157 * true specifies non-blocking input stream behavior | |
| 158 * @param nonBlockingOutput | |
| 159 * true specifies non-blocking output stream behavior | |
| 160 */ | |
| 161 extern nsresult | |
| 162 NS_NewPipe(nsIInputStream **pipeIn, | |
| 163 nsIOutputStream **pipeOut, | |
| 164 uint32_t segmentSize = 0, | |
| 165 uint32_t maxSize = 0, | |
| 166 bool nonBlockingInput = false, | |
| 167 bool nonBlockingOutput = false); | |
| 168 | |
| 169 %} |
