xpcom/io/nsIPipe.idl@6474c204b198
xpcom/io/nsIPipe.idl
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.
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/. */
6 #include "nsISupports.idl"
8 interface nsIAsyncInputStream;
9 interface nsIAsyncOutputStream;
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);
63 /**
64 * The pipe's input end, which also implements nsISearchableInputStream.
65 */
66 readonly attribute nsIAsyncInputStream inputStream;
68 /**
69 * The pipe's output end.
70 */
71 readonly attribute nsIAsyncOutputStream outputStream;
72 };
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 };
97 %{C++
99 class nsIInputStream;
100 class nsIOutputStream;
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);
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);
169 %}
