source: GTP/trunk/Lib/Geom/OgreStuff/include/OgreDataStream.h @ 1809

Revision 1809, 15.5 KB checked in by gumbau, 18 years ago (diff)
Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4(Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25#ifndef __DataStream_H__
26#define __DataStream_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreString.h"
30#include "OgreSharedPtr.h"
31#include <istream>
32
33namespace Ogre {
34
35        /** General purpose class used for encapsulating the reading of data.
36        @remarks
37                This class performs basically the same tasks as std::basic_istream,
38                except that it does not have any formatting capabilities, and is
39                designed to be subclassed to receive data from multiple sources,
40                including libraries which have no compatiblity with the STL's
41                stream interfaces. As such, this is an abstraction of a set of
42                wrapper classes which pretend to be standard stream classes but
43                can actually be implemented quite differently.
44        @par
45                Generally, if a plugin or application provides an ArchiveFactory,
46                it should also provide a DataStream subclass which will be used
47                to stream data out of that Archive implementation, unless it can
48                use one of the common implementations included.
49        @note
50                Ogre makes no guarantees about thread safety, for performance reasons.
51                If you wish to access stream data asynchronously then you should
52                organise your own mutexes to avoid race conditions.
53        */
54        class _OgreExport DataStream
55        {
56        protected:
57                /// The name (e.g. resource name) that can be used to identify the source fot his data (optional)
58                String mName;           
59        /// Size of the data in the stream (may be 0 if size cannot be determined)
60        size_t mSize;
61        #define OGRE_STREAM_TEMP_SIZE 128
62        public:
63                /// Constructor for creating unnamed streams
64        DataStream() : mSize(0) {}
65                /// Constructor for creating named streams
66                DataStream(const String& name) : mName(name), mSize(0) {}
67                /// Returns the name of the stream, if it has one.
68                const String& getName(void) { return mName; }
69        virtual ~DataStream() {}
70                // Streaming operators
71        template<typename T> DataStream& operator>>(T& val);
72                /** Read the requisite number of bytes from the stream,
73                        stopping at the end of the file.
74                @param buf Reference to a buffer pointer
75                @param count Number of bytes to read
76                @returns The number of bytes read
77                */
78                virtual size_t read(void* buf, size_t count) = 0;
79                /** Get a single line from the stream.
80                @remarks
81                        The delimiter character is not included in the data
82                        returned, and it is skipped over so the next read will occur
83                        after it. The buffer contents will include a
84                        terminating character.
85        @note
86            If you used this function, you <b>must</b> open the stream in <b>binary mode</b>,
87            otherwise, it'll produce unexpected results.
88                @param buf Reference to a buffer pointer
89                @param maxCount The maximum length of data to be read, excluding the terminating character
90                @param delim The delimiter to stop at
91                @returns The number of bytes read, excluding the terminating character
92                */
93                virtual size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
94               
95            /** Returns a String containing the next line of data, optionally
96                    trimmed for whitespace.
97            @remarks
98                    This is a convenience method for text streams only, allowing you to
99                    retrieve a String object containing the next line of data. The data
100                    is read up to the next newline character and the result trimmed if
101                    required.
102        @note
103            If you used this function, you <b>must</b> open the stream in <b>binary mode</b>,
104            otherwise, it'll produce unexpected results.
105            @param
106                    trimAfter If true, the line is trimmed for whitespace (as in
107                    String.trim(true,true))
108            */
109            virtual String getLine( bool trimAfter = true );
110
111            /** Returns a String containing the entire stream.
112            @remarks
113                    This is a convenience method for text streams only, allowing you to
114                    retrieve a String object containing all the data in the stream.
115            */
116            virtual String getAsString(void);
117
118                /** Skip a single line from the stream.
119        @note
120            If you used this function, you <b>must</b> open the stream in <b>binary mode</b>,
121            otherwise, it'll produce unexpected results.
122                @param delim The delimiter(s) to stop at
123                @returns The number of bytes skipped
124                */
125                virtual size_t skipLine(const String& delim = "\n");
126
127                /** Skip a defined number of bytes. This can also be a negative value, in which case
128                the file pointer rewinds a defined number of bytes. */
129                virtual void skip(long count) = 0;
130       
131                /** Repositions the read point to a specified byte.
132            */
133            virtual void seek( size_t pos ) = 0;
134               
135                /** Returns the current byte offset from beginning */
136            virtual size_t tell(void) const = 0;
137
138                /** Returns true if the stream has reached the end.
139            */
140            virtual bool eof(void) const = 0;
141
142                /** Returns the total size of the data to be read from the stream,
143                        or 0 if this is indeterminate for this stream.
144                */
145        size_t size(void) const { return mSize; }
146
147        /** Close the stream; this makes further operations invalid. */
148        virtual void close(void) = 0;
149               
150
151        };
152
153        /** Shared pointer to allow data streams to be passed around without
154                worrying about deallocation
155        */
156        typedef SharedPtr<DataStream> DataStreamPtr;
157
158        /// List of DataStream items
159        typedef std::list<DataStreamPtr> DataStreamList;
160        /// Shared pointer to list of DataStream items
161        typedef SharedPtr<DataStreamList> DataStreamListPtr;
162
163        /** Common subclass of DataStream for handling data from chunks of memory.
164        */
165        class _OgreExport MemoryDataStream : public DataStream
166        {
167        protected:
168        /// Pointer to the start of the data area
169            uchar* mData;
170        /// Pointer to the current position in the memory
171            uchar* mPos;
172        /// Pointer to the end of the memory
173            uchar* mEnd;
174        /// Do we delete the memory on close
175                bool mFreeOnClose;                     
176        public:
177               
178                /** Wrap an existing memory chunk in a stream.
179                @param pMem Pointer to the exising memory
180                @param size The size of the memory chunk in bytes
181                @param freeOnClose If true, the memory associated will be destroyed
182                        when the stream is destroyed.
183                */
184                MemoryDataStream(void* pMem, size_t size, bool freeOnClose = false);
185               
186                /** Wrap an existing memory chunk in a named stream.
187                @param name The name to give the stream
188                @param pMem Pointer to the exising memory
189                @param size The size of the memory chunk in bytes
190                @param freeOnClose If true, the memory associated will be destroyed
191                        when the stream is destroyed.
192                */
193                MemoryDataStream(const String& name, void* pMem, size_t size,
194                                bool freeOnClose = false);
195
196                /** Create a stream which pre-buffers the contents of another stream.
197                @remarks
198                        This constructor can be used to intentionally read in the entire
199                        contents of another stream, copying them to the internal buffer
200                        and thus making them available in memory as a single unit.
201                @param sourceStream Another DataStream which will provide the source
202                        of data
203                @param freeOnClose If true, the memory associated will be destroyed
204                        when the stream is destroyed.
205                */
206                MemoryDataStream(DataStream& sourceStream,
207                                bool freeOnClose = true);
208               
209                /** Create a stream which pre-buffers the contents of another stream.
210                @remarks
211                        This constructor can be used to intentionally read in the entire
212                        contents of another stream, copying them to the internal buffer
213                        and thus making them available in memory as a single unit.
214                @param sourceStream Weak reference to another DataStream which will provide the source
215                        of data
216                @param freeOnClose If true, the memory associated will be destroyed
217                        when the stream is destroyed.
218                */
219                MemoryDataStream(DataStreamPtr& sourceStream,
220                                bool freeOnClose = true);
221
222                /** Create a named stream which pre-buffers the contents of
223                        another stream.
224                @remarks
225                        This constructor can be used to intentionally read in the entire
226                        contents of another stream, copying them to the internal buffer
227                        and thus making them available in memory as a single unit.
228                @param name The name to give the stream
229                @param sourceStream Another DataStream which will provide the source
230                        of data
231                @param freeOnClose If true, the memory associated will be destroyed
232                        when the stream is destroyed.
233                */
234                MemoryDataStream(const String& name, DataStream& sourceStream,
235                                bool freeOnClose = true);
236
237        /** Create a named stream which pre-buffers the contents of
238        another stream.
239        @remarks
240        This constructor can be used to intentionally read in the entire
241        contents of another stream, copying them to the internal buffer
242        and thus making them available in memory as a single unit.
243        @param name The name to give the stream
244        @param sourceStream Another DataStream which will provide the source
245        of data
246        @param freeOnClose If true, the memory associated will be destroyed
247        when the stream is destroyed.
248        */
249        MemoryDataStream(const String& name, const DataStreamPtr& sourceStream,
250            bool freeOnClose = true);
251
252        /** Create a stream with a brand new empty memory chunk.
253                @param size The size of the memory chunk to create in bytes
254                @param freeOnClose If true, the memory associated will be destroyed
255                        when the stream is destroyed.
256                */
257                MemoryDataStream(size_t size, bool freeOnClose = true);
258                /** Create a named stream with a brand new empty memory chunk.
259                @param name The name to give the stream
260                @param size The size of the memory chunk to create in bytes
261                @param freeOnClose If true, the memory associated will be destroyed
262                        when the stream is destroyed.
263                */
264                MemoryDataStream(const String& name, size_t size,
265                                bool freeOnClose = true);
266
267                ~MemoryDataStream();
268
269                /** Get a pointer to the start of the memory block this stream holds. */
270                uchar* getPtr(void) { return mData; }
271               
272                /** Get a pointer to the current position in the memory block this stream holds. */
273                uchar* getCurrentPtr(void) { return mPos; }
274               
275                /** @copydoc DataStream::read
276                */
277                size_t read(void* buf, size_t count);
278                /** @copydoc DataStream::readLine
279                */
280                size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
281               
282                /** @copydoc DataStream::skipLine
283                */
284                size_t skipLine(const String& delim = "\n");
285
286                /** @copydoc DataStream::skip
287                */
288                void skip(long count);
289       
290                /** @copydoc DataStream::seek
291                */
292            void seek( size_t pos );
293               
294                /** @copydoc DataStream::tell
295                */
296            size_t tell(void) const;
297
298                /** @copydoc DataStream::eof
299                */
300            bool eof(void) const;
301
302        /** @copydoc DataStream::close
303        */
304        void close(void);
305
306                /** Sets whether or not to free the encapsulated memory on close. */
307                void setFreeOnClose(bool free) { mFreeOnClose = free; }
308        };
309
310    /** Shared pointer to allow memory data streams to be passed around without
311    worrying about deallocation
312    */
313    typedef SharedPtr<MemoryDataStream> MemoryDataStreamPtr;
314
315    /** Common subclass of DataStream for handling data from
316                std::basic_istream.
317        */
318        class _OgreExport FileStreamDataStream : public DataStream
319        {
320        protected:
321                /// Reference to source stream
322                std::ifstream* mpStream;
323        bool mFreeOnClose;                     
324        public:
325                /** Construct stream from an STL stream
326        @param s Pointer to source stream
327        @param freeOnClose Whether to delete the underlying stream on
328            destruction of this class
329        */
330                FileStreamDataStream(std::ifstream* s,
331            bool freeOnClose = true);
332                /** Construct named stream from an STL stream
333        @param name The name to give this stream
334        @param s Pointer to source stream
335        @param freeOnClose Whether to delete the underlying stream on
336            destruction of this class
337        */
338                FileStreamDataStream(const String& name,
339            std::ifstream* s,
340            bool freeOnClose = true);
341
342                /** Construct named stream from an STL stream, and tell it the size
343        @remarks
344            This variant tells the class the size of the stream too, which
345            means this class does not need to seek to the end of the stream
346            to determine the size up-front. This can be beneficial if you have
347            metadata about the contents of the stream already.
348        @param name The name to give this stream
349        @param s Pointer to source stream
350        @param size Size of the stream contents in bytes
351        @param freeOnClose Whether to delete the underlying stream on
352            destruction of this class
353        */
354                FileStreamDataStream(const String& name,
355            std::ifstream* s,
356            size_t size,
357            bool freeOnClose = true);
358
359        ~FileStreamDataStream();
360
361                /** @copydoc DataStream::read
362                */
363                size_t read(void* buf, size_t count);
364                /** @copydoc DataStream::readLine
365                */
366        size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
367               
368                /** @copydoc DataStream::skip
369                */
370                void skip(long count);
371       
372                /** @copydoc DataStream::seek
373                */
374            void seek( size_t pos );
375
376                /** @copydoc DataStream::tell
377                */
378                size_t tell(void) const;
379
380                /** @copydoc DataStream::eof
381                */
382            bool eof(void) const;
383
384        /** @copydoc DataStream::close
385        */
386        void close(void);
387               
388               
389        };
390
391        /** Common subclass of DataStream for handling data from C-style file
392                handles.
393    @remarks
394        Use of this class is generally discouraged; if you want to wrap file
395        access in a DataStream, you should definitely be using the C++ friendly
396        FileStreamDataStream. However, since there are quite a few applications
397        and libraries still wedded to the old FILE handle access, this stream
398        wrapper provides some backwards compatibility.
399        */
400        class _OgreExport FileHandleDataStream : public DataStream
401        {
402        protected:
403                FILE* mFileHandle;
404        public:
405                /// Create stream from a C file handle
406                FileHandleDataStream(FILE* handle);
407                /// Create named stream from a C file handle
408                FileHandleDataStream(const String& name, FILE* handle);
409        ~FileHandleDataStream();
410
411                /** @copydoc DataStream::read
412                */
413                size_t read(void* buf, size_t count);
414
415                /** @copydoc DataStream::skip
416                */
417                void skip(long count);
418       
419                /** @copydoc DataStream::seek
420                */
421            void seek( size_t pos );
422
423                /** @copydoc DataStream::tell
424                */
425                size_t tell(void) const;
426
427                /** @copydoc DataStream::eof
428                */
429            bool eof(void) const;
430
431        /** @copydoc DataStream::close
432        */
433        void close(void);
434
435        };
436}
437#endif
438
Note: See TracBrowser for help on using the repository browser.