stream.h¶
#include <primo/platform/stream.h>
Includes¶
primo/platform/reference.h
Classes¶
Name |
Description |
|---|---|
The Stream interface can be used to implement a data source or sink. |
Namespaces¶
primo
Source¶
1//------------------------------------------------------------------------------
2// File: stream.h
3// (c) Copyright 2003-2012 Primo Software Corp. All rights reserved.
4//------------------------------------------------------------------------------
5
6#ifndef ___PRIMO_STREAM_H___
7#define ___PRIMO_STREAM_H___
8
9/** @file */
10
11#include <primo/platform/reference.h>
12
13#undef min
14
15namespace primo
16{
17
18/**
19 The Stream interface can be used to implement a data source or sink.
20 It can be used as an alternative to files when it is not convenient or possible to use files.
21
22 The default implementation of primo::Reference keeps a constant reference count of 1.
23 This can be used when the client code is the sole owner of the implemented stream and does not need
24 to manage it through the primo::Reference interface.
25*/
26class Stream: public primo::Reference
27{
28public:
29
30 /**
31 Empty destructor.
32 */
33 ~Stream() {}
34
35 /**
36 Opens the stream.
37
38 @return TRUE The stream is opened successfully. FALSE An error occurred.
39 */
40 virtual bool_t open() = 0;
41
42 /**
43 Closes the stream.
44 */
45 virtual void close() = 0;
46
47 /**
48 Checks whether the stream is open.
49
50 @return TRUE The stream is open, FALSE the stream is closed.
51 */
52 virtual bool_t isOpen() const = 0;
53
54 /**
55 Checks whether the stream supports reading.
56
57 @return TRUE It is possible to read form the stream.
58 FALSE It is not possible to read from the stream and the read method always returns FALSE.
59 */
60 virtual bool_t canRead() const = 0;
61
62 /**
63 Checks whether the stream supports writing.
64
65 @return TRUE It is possible to write to the stream.
66 FALSE It is not possible to write to the stream and the write method always returns FALSE.
67 */
68 virtual bool_t canWrite() const = 0;
69
70 /**
71 Checks whether the stream supports seeking.
72
73 @return TRUE It is possible to seek in the stream.
74 FALSE It is not possible to seek in the stream and the seek method always returns FALSE.
75 */
76 virtual bool_t canSeek() const = 0;
77
78 /**
79 Reads data from the stream.
80
81 @param buffer [in] A pointer to the buffer where the data shall be stored.
82 @param bufferSize [in] Buffer size in bytes. Specifies how many bytes shall be read from the stream.
83 @param totalRead [out] A pointer to a variable that stores the actual number of bytes read from the stream.
84 When the number of bytes returned (totalRead) is 0 then this is considered to be the end of the stream (EOS).
85 Reading at the end of the stream succeeds but 0 bytes are returned.
86 The number of bytes returned (totalRead) may be less than the requested bytes (bufferSize) even before the end of the stream is reached.
87
88 @remarks This function should block if no data is currently available in stream but more is expected to come:
89 from network, growing file, expandable buffer, etc.
90 The parameter totalRead should be set to 0 only when no more data is available in stream and no more data is expected to come.
91
92 @return TRUE The operation is successful. FALSE Could not read from the stream.
93
94 @see canRead
95 */
96 virtual bool_t read(void* buffer, int32_t bufferSize, int32_t* totalRead) = 0;
97
98 /**
99 Writes data to the stream.
100
101 @param buffer [in] A pointer to the data that shall be written to the stream.
102 @param dataSize [in] Specifies how many bytes to write.
103
104 @return TRUE the data has been written to the stream. FALSE an error occurred while writing to the stream.
105 @see canWrite
106 */
107 virtual bool_t write(const void* buffer, int32_t dataSize) = 0;
108
109 /**
110 Returns the current size of the stream.
111
112 @return Stream size in bytes. If the size is unknown -1 is returned.
113
114 @remarks The stream size may increase if more data is appended to the stream.
115 The stream size should never decrease.
116 */
117 virtual int64_t size() const = 0;
118
119 /**
120 Returns the current position in the stream.
121
122 @return Absolute position in stream or -1 if the stream cannot be seeked. The beginning of a seekable the stream is at position 0.
123
124 @see canSeek
125 */
126 virtual int64_t position() const = 0;
127
128 /**
129 Seeks to the specified position in the stream.
130
131 @param position [in] Specifies the absolute position from the beginning of the stream (which is at position 0).
132
133 @return TRUE if successful. FALSE if there's an error.
134
135 @see canSeek
136 */
137 virtual bool_t seek(int64_t position) = 0;
138
139 /**
140 The default implementation keeps a constant reference count of 1.
141
142 @return 1
143 */
144 int32_t retain() const { return 1; }
145
146 /**
147 The default implementation keeps a constant reference count of 1.
148
149 @return 1
150 */
151 int32_t release() const { return 1; }
152
153 /**
154 The default implementation keeps a constant reference count of 1.
155
156 @return 1
157 */
158 int32_t retainCount() const { return 1; }
159};
160
161
162}
163
164#endif // ___PRIMO_STREAM_H___