netwerk/base/public/nsITransport.idl@6474c204b198
netwerk/base/public/nsITransport.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 /* 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/. */
5 #include "nsISupports.idl"
7 interface nsIInputStream;
8 interface nsIOutputStream;
9 interface nsITransportEventSink;
10 interface nsIEventTarget;
12 /**
13 * nsITransport
14 *
15 * This interface provides a common way of accessing i/o streams connected
16 * to some resource. This interface does not in any way specify the resource.
17 * It provides methods to open blocking or non-blocking, buffered or unbuffered
18 * streams to the resource. The name "transport" is meant to connote the
19 * inherent data transfer implied by this interface (i.e., data is being
20 * transfered in some fashion via the streams exposed by this interface).
21 *
22 * A transport can have an event sink associated with it. The event sink
23 * receives transport-specific events as the transfer is occuring. For a
24 * socket transport, these events can include status about the connection.
25 * See nsISocketTransport for more info about socket transport specifics.
26 */
27 [scriptable, uuid(d8786c64-eb49-4a0b-b42c-0936a745fbe8)]
28 interface nsITransport : nsISupports
29 {
30 /**
31 * Open flags.
32 */
33 const unsigned long OPEN_BLOCKING = 1<<0;
34 const unsigned long OPEN_UNBUFFERED = 1<<1;
36 /**
37 * Open an input stream on this transport.
38 *
39 * Flags have the following meaning:
40 *
41 * OPEN_BLOCKING
42 * If specified, then the resulting stream will have blocking stream
43 * semantics. This means that if the stream has no data and is not
44 * closed, then reading from it will block the calling thread until
45 * at least one byte is available or until the stream is closed.
46 * If this flag is NOT specified, then the stream has non-blocking
47 * stream semantics. This means that if the stream has no data and is
48 * not closed, then reading from it returns NS_BASE_STREAM_WOULD_BLOCK.
49 * In addition, in non-blocking mode, the stream is guaranteed to
50 * support nsIAsyncInputStream. This interface allows the consumer of
51 * the stream to be notified when the stream can again be read.
52 *
53 * OPEN_UNBUFFERED
54 * If specified, the resulting stream may not support ReadSegments.
55 * ReadSegments is only gauranteed to be implemented when this flag is
56 * NOT specified.
57 *
58 * @param aFlags
59 * optional transport specific flags.
60 * @param aSegmentSize
61 * if OPEN_UNBUFFERED is not set, then this parameter specifies the
62 * size of each buffer segment (pass 0 to use default value).
63 * @param aSegmentCount
64 * if OPEN_UNBUFFERED is not set, then this parameter specifies the
65 * maximum number of buffer segments (pass 0 to use default value).
66 */
67 nsIInputStream openInputStream(in unsigned long aFlags,
68 in unsigned long aSegmentSize,
69 in unsigned long aSegmentCount);
71 /**
72 * Open an output stream on this transport.
73 *
74 * Flags have the following meaning:
75 *
76 * OPEN_BLOCKING
77 * If specified, then the resulting stream will have blocking stream
78 * semantics. This means that if the stream is full and is not closed,
79 * then writing to it will block the calling thread until ALL of the
80 * data can be written or until the stream is closed. If this flag is
81 * NOT specified, then the stream has non-blocking stream semantics.
82 * This means that if the stream is full and is not closed, then writing
83 * to it returns NS_BASE_STREAM_WOULD_BLOCK. In addition, in non-
84 * blocking mode, the stream is guaranteed to support
85 * nsIAsyncOutputStream. This interface allows the consumer of the
86 * stream to be notified when the stream can again accept more data.
87 *
88 * OPEN_UNBUFFERED
89 * If specified, the resulting stream may not support WriteSegments and
90 * WriteFrom. WriteSegments and WriteFrom are only guaranteed to be
91 * implemented when this flag is NOT specified.
92 *
93 * @param aFlags
94 * optional transport specific flags.
95 * @param aSegmentSize
96 * if OPEN_UNBUFFERED is not set, then this parameter specifies the
97 * size of each buffer segment (pass 0 to use default value).
98 * @param aSegmentCount
99 * if OPEN_UNBUFFERED is not set, then this parameter specifies the
100 * maximum number of buffer segments (pass 0 to use default value).
101 */
102 nsIOutputStream openOutputStream(in unsigned long aFlags,
103 in unsigned long aSegmentSize,
104 in unsigned long aSegmentCount);
106 /**
107 * Close the transport and any open streams.
108 *
109 * @param aReason
110 * the reason for closing the stream.
111 */
112 void close(in nsresult aReason);
114 /**
115 * Set the transport event sink.
116 *
117 * @param aSink
118 * receives transport layer notifications
119 * @param aEventTarget
120 * indicates the event target to which the notifications should
121 * be delivered. if NULL, then the notifications may occur on
122 * any thread.
123 */
124 void setEventSink(in nsITransportEventSink aSink,
125 in nsIEventTarget aEventTarget);
127 /**
128 * Generic nsITransportEventSink status codes. nsITransport
129 * implementations may override these status codes with their own more
130 * specific status codes (e.g., see nsISocketTransport).
131 *
132 * In C++, these constants have a type of uint32_t, so C++ callers must use
133 * the NS_NET_STATUS_* constants defined below, which have a type of
134 * nsresult.
135 */
136 const unsigned long STATUS_READING = 0x804b0008;
137 const unsigned long STATUS_WRITING = 0x804b0009;
138 };
140 [scriptable, uuid(EDA4F520-67F7-484b-A691-8C3226A5B0A6)]
141 interface nsITransportEventSink : nsISupports
142 {
143 /**
144 * Transport status notification.
145 *
146 * @param aTransport
147 * the transport sending this status notification.
148 * @param aStatus
149 * the transport status (resolvable to a string using
150 * nsIErrorService). See nsISocketTransport for socket specific
151 * status codes and more comments.
152 * @param aProgress
153 * the amount of data either read or written depending on the value
154 * of the status code. this value is relative to aProgressMax.
155 * @param aProgressMax
156 * the maximum amount of data that will be read or written. if
157 * unknown, 0xFFFFFFFF will be passed.
158 */
159 void onTransportStatus(in nsITransport aTransport,
160 in nsresult aStatus,
161 in unsigned long long aProgress,
162 in unsigned long long aProgressMax);
163 };
