svn-gvsig-desktop / trunk / libraries / libjni-mrsid / include / support / lt_ioStreamInf.h @ 3539
History | View | Annotate | Download (6.41 KB)
1 |
/* $Id: lt_ioStreamInf.h 3539 2006-01-09 12:23:20Z nacho $ */
|
---|---|
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 |