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