|
132
|
1 /*******************************************************************************
|
|
|
2
|
|
|
3 copyright: Copyright (c) 2004 Kris Bell. All rights reserved
|
|
|
4
|
|
|
5 license: BSD style: $(LICENSE)
|
|
|
6
|
|
|
7 version: Initial release: March 2004
|
|
|
8 Outback release: December 2006
|
|
|
9
|
|
|
10 author: Kris
|
|
|
11
|
|
|
12 *******************************************************************************/
|
|
|
13
|
|
|
14 module tango.io.model.IConduit;
|
|
|
15
|
|
|
16 public import tango.io.model.IBuffer;
|
|
|
17
|
|
|
18 /*******************************************************************************
|
|
|
19
|
|
|
20 Conduits provide virtualized access to external content, and
|
|
|
21 represent things like files or Internet connections. Conduits
|
|
|
22 expose a pair of streams, are modelled by tango.io.model.IConduit,
|
|
|
23 and are implemented via classes such as FileConduit & SocketConduit.
|
|
|
24
|
|
|
25 Additional kinds of conduit are easy to construct: one either
|
|
|
26 subclasses tango.io.Conduit, or implements tango.io.model.IConduit.
|
|
|
27 A conduit typically reads and writes from/to an IBuffer in large
|
|
|
28 chunks, typically the entire buffer. Alternatively, one can invoke
|
|
|
29 input.read(dst[]) and/or output.write(src[]) directly.
|
|
|
30
|
|
|
31 *******************************************************************************/
|
|
|
32
|
|
|
33 interface IConduit : InputStream, OutputStream
|
|
|
34 {
|
|
|
35 /***********************************************************************
|
|
|
36
|
|
|
37 Return the input stream
|
|
|
38
|
|
|
39 ***********************************************************************/
|
|
|
40
|
|
|
41 abstract InputStream input ();
|
|
|
42
|
|
|
43 /***********************************************************************
|
|
|
44
|
|
|
45 Return the output stream
|
|
|
46
|
|
|
47 ***********************************************************************/
|
|
|
48
|
|
|
49 abstract OutputStream output ();
|
|
|
50
|
|
|
51 /***********************************************************************
|
|
|
52
|
|
|
53 Return a preferred size for buffering conduit I/O
|
|
|
54
|
|
|
55 ***********************************************************************/
|
|
|
56
|
|
|
57 abstract uint bufferSize ();
|
|
|
58
|
|
|
59 /***********************************************************************
|
|
|
60
|
|
|
61 Return the name of this conduit
|
|
|
62
|
|
|
63 ***********************************************************************/
|
|
|
64
|
|
|
65 abstract char[] toString ();
|
|
|
66
|
|
|
67 /***********************************************************************
|
|
|
68
|
|
|
69 Is the conduit alive?
|
|
|
70
|
|
|
71 ***********************************************************************/
|
|
|
72
|
|
|
73 abstract bool isAlive ();
|
|
|
74
|
|
|
75 /***********************************************************************
|
|
|
76
|
|
|
77 Release external resources
|
|
|
78
|
|
|
79 ***********************************************************************/
|
|
|
80
|
|
|
81 abstract void detach ();
|
|
|
82
|
|
|
83 /***********************************************************************
|
|
|
84
|
|
|
85 Throw a generic IO exception with the provided msg
|
|
|
86
|
|
|
87 ***********************************************************************/
|
|
|
88
|
|
|
89 abstract void error (char[] msg);
|
|
|
90
|
|
|
91 /***********************************************************************
|
|
|
92
|
|
|
93 Models the ability to seek within a conduit
|
|
|
94
|
|
|
95 ***********************************************************************/
|
|
|
96
|
|
|
97 interface Seek
|
|
|
98 {
|
|
|
99 /***************************************************************
|
|
|
100
|
|
|
101 The anchor positions supported by seek()
|
|
|
102
|
|
|
103 ***************************************************************/
|
|
|
104
|
|
|
105 enum Anchor {
|
|
|
106 Begin = 0,
|
|
|
107 Current = 1,
|
|
|
108 End = 2,
|
|
|
109 };
|
|
|
110
|
|
|
111 /***************************************************************
|
|
|
112
|
|
|
113 Move the file position to the given offset from the
|
|
|
114 provided anchor point, and return adjusted position.
|
|
|
115
|
|
|
116 ***************************************************************/
|
|
|
117
|
|
|
118 long seek (long offset, Anchor anchor = Anchor.Begin);
|
|
|
119 }
|
|
|
120 }
|
|
|
121
|
|
|
122
|
|
|
123 /*******************************************************************************
|
|
|
124
|
|
|
125 Describes how to make an IO entity usable with selectors
|
|
|
126
|
|
|
127 *******************************************************************************/
|
|
|
128
|
|
|
129 interface ISelectable
|
|
|
130 {
|
|
|
131 typedef int Handle = -1; /// opaque OS file-handle
|
|
|
132
|
|
|
133 /***********************************************************************
|
|
|
134
|
|
|
135 Models a handle-oriented device.
|
|
|
136
|
|
|
137 TODO: figure out how to avoid exposing this in the general
|
|
|
138 case
|
|
|
139
|
|
|
140 ***********************************************************************/
|
|
|
141
|
|
|
142 Handle fileHandle ();
|
|
|
143 }
|
|
|
144
|
|
|
145
|
|
|
146 /*******************************************************************************
|
|
|
147
|
|
|
148 The common attributes of streams
|
|
|
149
|
|
|
150 *******************************************************************************/
|
|
|
151
|
|
|
152 interface IOStream
|
|
|
153 {
|
|
|
154 enum : uint
|
|
|
155 {
|
|
|
156 Eof = uint.max /// the End-of-Flow identifer
|
|
|
157 }
|
|
|
158
|
|
|
159 /***********************************************************************
|
|
|
160
|
|
|
161 Return the host conduit
|
|
|
162
|
|
|
163 ***********************************************************************/
|
|
|
164
|
|
|
165 IConduit conduit ();
|
|
|
166
|
|
|
167
|
|
|
168 /***********************************************************************
|
|
|
169
|
|
|
170 Close the input
|
|
|
171
|
|
|
172 ***********************************************************************/
|
|
|
173
|
|
|
174 void close ();
|
|
|
175 }
|
|
|
176
|
|
|
177
|
|
|
178 /*******************************************************************************
|
|
|
179
|
|
|
180 The Tango input stream
|
|
|
181
|
|
|
182 *******************************************************************************/
|
|
|
183
|
|
|
184 interface InputStream : IOStream
|
|
|
185 {
|
|
|
186 /***********************************************************************
|
|
|
187
|
|
|
188 Read from conduit into a target array. The provided dst
|
|
|
189 will be populated with content from the conduit.
|
|
|
190
|
|
|
191 Returns the number of bytes read, which may be less than
|
|
|
192 requested in dst. Eof is returned whenever an end-of-flow
|
|
|
193 condition arises.
|
|
|
194
|
|
|
195 ***********************************************************************/
|
|
|
196
|
|
|
197 uint read (void[] dst);
|
|
|
198
|
|
|
199 /***********************************************************************
|
|
|
200
|
|
|
201 Clear any buffered content
|
|
|
202
|
|
|
203 ***********************************************************************/
|
|
|
204
|
|
|
205 InputStream clear ();
|
|
|
206 }
|
|
|
207
|
|
|
208
|
|
|
209 /*******************************************************************************
|
|
|
210
|
|
|
211 The Tango output stream
|
|
|
212
|
|
|
213 *******************************************************************************/
|
|
|
214
|
|
|
215 interface OutputStream : IOStream
|
|
|
216 {
|
|
|
217 /***********************************************************************
|
|
|
218
|
|
|
219 Write to conduit from a source array. The provided src
|
|
|
220 content will be written to the conduit.
|
|
|
221
|
|
|
222 Returns the number of bytes written from src, which may
|
|
|
223 be less than the quantity provided. Eof is returned when
|
|
|
224 an end-of-flow condition arises.
|
|
|
225
|
|
|
226 ***********************************************************************/
|
|
|
227
|
|
|
228 uint write (void[] src);
|
|
|
229
|
|
|
230 /***********************************************************************
|
|
|
231
|
|
|
232 Transfer the content of another conduit to this one. Returns
|
|
|
233 a reference to this class, and throws IOException on failure.
|
|
|
234
|
|
|
235 ***********************************************************************/
|
|
|
236
|
|
|
237 OutputStream copy (InputStream src);
|
|
|
238
|
|
|
239 /***********************************************************************
|
|
|
240
|
|
|
241 Purge buffered content
|
|
|
242
|
|
|
243 ***********************************************************************/
|
|
|
244
|
|
|
245 OutputStream flush ();
|
|
|
246 }
|
|
|
247
|
|
|
248
|
