svn-gvsig-desktop / trunk / libraries / libjni-mrsid / include / support / lt_ioStreamInf.h @ 3539
History | View | Annotate | Download (6.41 KB)
1 | 662 | igbrotru | /* $Id$ */
|
---|---|---|---|
2 | /* //////////////////////////////////////////////////////////////////////////
|
||
3 | // //
|
||
4 | // This code is Copyright (c) 2004 LizardTech, Inc, 1008 Western Avenue, //
|
||
5 | // Suite 200, Seattle, WA 98104. Unauthorized use or distribution //
|
||
6 | // prohibited. Access to and use of this code is permitted only under //
|
||
7 | // license from LizardTech, Inc. Portions of the code are protected by //
|
||
8 | // US and foreign patents and other filings. All Rights Reserved. //
|
||
9 | // //
|
||
10 | ////////////////////////////////////////////////////////////////////////// */
|
||
11 | /* PUBLIC */
|
||
12 | |||
13 | #ifndef LT_STREAMINF_H
|
||
14 | #define LT_STREAMINF_H
|
||
15 | |||
16 | #include "lt_lib_io.h" |
||
17 | |||
18 | |||
19 | LT_BEGIN_NAMESPACE( LizardTech ) |
||
20 | |||
21 | |||
22 | |||
23 | /**
|
||
24 | * Abstract definition of a stream.
|
||
25 | *
|
||
26 | * This class is intentionally very sparse, and completely abstract to
|
||
27 | * facilitate COM usage. The semantics of the LTIOStreamInf class are
|
||
28 | * very similar to the unix stdio model.
|
||
29 | */
|
||
30 | class LTIOStreamInf |
||
31 | { |
||
32 | public:
|
||
33 | // The following is a pure virtual destructor with an empty definition.
|
||
34 | // It might look broken to you, but this is a well-known practice and
|
||
35 | // is explicitly allowed by the standard for very good, technical reasons.
|
||
36 | // (Do a google search for "pure virtual destructor" for details.)
|
||
37 | #if defined(LT_COMPILER_GNU) || defined(LT_COMPILER_SUN)
|
||
38 | // gcc doesn't allow the declaration to be in the class body,
|
||
39 | // so we put the member function "definition" in lt_ioStreamInf.cpp
|
||
40 | virtual ~LTIOStreamInf() =0;
|
||
41 | #else
|
||
42 | virtual ~LTIOStreamInf() =0 {}
|
||
43 | #endif
|
||
44 | |||
45 | /**
|
||
46 | * @name Status accessors
|
||
47 | */
|
||
48 | //@{
|
||
49 | |||
50 | /**
|
||
51 | * Test for end-of-stream
|
||
52 | *
|
||
53 | * Returns true after the first read operation that attempts to
|
||
54 | * read past the end of the stream. It returns false if the current
|
||
55 | * position is not end of stream.
|
||
56 | *
|
||
57 | * @retval true end of stream
|
||
58 | * @retval false otherwise
|
||
59 | */
|
||
60 | virtual bool isEOF() =0; |
||
61 | |||
62 | /**
|
||
63 | * Test for stream openness.
|
||
64 | *
|
||
65 | * @retval true The stream is open
|
||
66 | * @retval false otherwise
|
||
67 | */
|
||
68 | virtual bool isOpen() =0; |
||
69 | |||
70 | //@}
|
||
71 | |||
72 | |||
73 | /**
|
||
74 | * @name Opening and closing
|
||
75 | */
|
||
76 | //@{
|
||
77 | |||
78 | /**
|
||
79 | * Opens the stream.
|
||
80 | *
|
||
81 | * Opening a stream puts it in a state that allows data access based on cached
|
||
82 | * initialization parameters.
|
||
83 | *
|
||
84 | * @retval LT_STS_IOStreamUninitialized The stream has not been initialized with enough
|
||
85 | * information to open the stream
|
||
86 | * @retval LT_STS_IOStreamInvalidState The stream is already open
|
||
87 | * @retval LT_STS_Success On success.
|
||
88 | * @retval LT_STS_Failure Failure.
|
||
89 | * @retval other Implementations may return other codes
|
||
90 | */
|
||
91 | virtual LT_STATUS open() =0;
|
||
92 | |||
93 | /**
|
||
94 | * Closes the stream.
|
||
95 | *
|
||
96 | * Puts the stream in a state that does not allow data access. May
|
||
97 | * free up resources, but only in such a way that doesn't inhibit
|
||
98 | * successful future calls to open()
|
||
99 | *
|
||
100 | * @retval LT_STS_Success On success, or if the stream is already closed.
|
||
101 | * @retval LT_STS_Failure Otherwise.
|
||
102 | */
|
||
103 | virtual LT_STATUS close() =0;
|
||
104 | |||
105 | //@}
|
||
106 | |||
107 | |||
108 | /**
|
||
109 | * @name Data access
|
||
110 | */
|
||
111 | //@{
|
||
112 | |||
113 | /**
|
||
114 | * Retrieve the specified number of bytes from the data source and
|
||
115 | * place them in pDest.
|
||
116 | *
|
||
117 | * @param pDest buffer in which to store read data
|
||
118 | * @param numBytes number of bytes to read from stream
|
||
119 | *
|
||
120 | * @retval numBytes The number of bytes actually read
|
||
121 | */
|
||
122 | virtual lt_uint32 read( lt_uint8 *pDest, lt_uint32 numBytes ) = 0;
|
||
123 | |||
124 | /**
|
||
125 | * Store the specified number of bytes in the data source.
|
||
126 | *
|
||
127 | * @param pSrc buffer from which to store data
|
||
128 | * @param numBytes number of bytes to write to stream
|
||
129 | *
|
||
130 | * @retval numBytes number of bytes actually written
|
||
131 | */
|
||
132 | virtual lt_uint32 write( const lt_uint8 *pSrc, lt_uint32 numBytes ) = 0; |
||
133 | |||
134 | //@}
|
||
135 | |||
136 | /**
|
||
137 | * @name Positioning
|
||
138 | */
|
||
139 | //@{
|
||
140 | |||
141 | /**
|
||
142 | * Moves the data access position to origin + offset
|
||
143 | *
|
||
144 | * @param offset number of bytes from origin at which to the next read or write will take place
|
||
145 | * @param origin place in stream from which to seek
|
||
146 | *
|
||
147 | * @retval LT_STS_IOStreamUnsupported The stream is not seekable
|
||
148 | * @retval LT_STS_IOStreamInvalidArgs The offset and origin do not specify a valid location in the stream
|
||
149 | * @retval LT_STS_Success On success
|
||
150 | * @retval LT_STS_Failure Otherwise
|
||
151 | * @retval other Implementations may return other codes
|
||
152 | */
|
||
153 | virtual LT_STATUS seek( lt_int64 offset, LTIOSeekDir origin ) =0;
|
||
154 | |||
155 | /**
|
||
156 | * Returns the current data access position as an offset from the start of the data
|
||
157 | *
|
||
158 | * @retval postion Number of bytes from the start of the data
|
||
159 | * @retval -1 On error.
|
||
160 | * @retval other Implementations may return other codes
|
||
161 | */
|
||
162 | virtual lt_int64 tell() =0;
|
||
163 | |||
164 | //@}
|
||
165 | |||
166 | /**
|
||
167 | * @name Other operations
|
||
168 | */
|
||
169 | //@{
|
||
170 | |||
171 | /**
|
||
172 | * @brief Clone the stream
|
||
173 | *
|
||
174 | * Create new stream of the same type with the same initialization parameters.
|
||
175 | * The transmission of these parameters is the responsibility of the derived type.
|
||
176 | * The new stream should initially return false for isOpen().
|
||
177 | *
|
||
178 | * @retval NULL the stream could not be duplicated; valid LTIOStreamInf* otherwise.
|
||
179 | */
|
||
180 | virtual LTIOStreamInf* duplicate() =0;
|
||
181 | |||
182 | |||
183 | /**
|
||
184 | * @brief Get status code of last error event.
|
||
185 | *
|
||
186 | * read(), write(), tell(), and duplicate() do not explicitly return status codes
|
||
187 | * in the event of an error. When an error has occurred, this function returns
|
||
188 | * the appropriate status code. Note calling this function after a successful
|
||
189 | * I/O operation will return an undefined value.
|
||
190 | *
|
||
191 | * @retval status the error code
|
||
192 | */
|
||
193 | virtual LT_STATUS getLastError() const =0; |
||
194 | |||
195 | |||
196 | /**
|
||
197 | * @brief Get a URI describing the stream object.
|
||
198 | *
|
||
199 | * This function returns a UTF-8, null-terminated string which is a
|
||
200 | * URI describing the origin of the stream object -- for example,
|
||
201 | * "file://foo.txt" or "lt_memstream:". This string is only intended
|
||
202 | * for diagnostic purposes, i.e. it may not be valid to pass it
|
||
203 | * to the ctor in an attempt to reopen the stream.
|
||
204 | *
|
||
205 | * @retval uri the uri string
|
||
206 | */
|
||
207 | virtual const char* getID() const =0; |
||
208 | |||
209 | //@}
|
||
210 | |||
211 | }; |
||
212 | |||
213 | |||
214 | |||
215 | LT_END_NAMESPACE( LizardTech ) |
||
216 | |||
217 | |||
218 | #endif // LT_STREAMINF_H |