summaryrefslogtreecommitdiff
path: root/src/stream.h
diff options
context:
space:
mode:
authorMike Buland <eichlan@xagasoft.com>2012-03-25 20:00:08 +0000
committerMike Buland <eichlan@xagasoft.com>2012-03-25 20:00:08 +0000
commit469bbcf0701e1eb8a6670c23145b0da87357e178 (patch)
treeb5b062a16e46a6c5d3410b4e574cd0cc09057211 /src/stream.h
parentee1b79396076edc4e30aefb285fada03bb45e80d (diff)
downloadlibbu++-469bbcf0701e1eb8a6670c23145b0da87357e178.tar.gz
libbu++-469bbcf0701e1eb8a6670c23145b0da87357e178.tar.bz2
libbu++-469bbcf0701e1eb8a6670c23145b0da87357e178.tar.xz
libbu++-469bbcf0701e1eb8a6670c23145b0da87357e178.zip
Code is all reorganized. We're about ready to release. I should write up a
little explenation of the arrangement.
Diffstat (limited to 'src/stream.h')
-rw-r--r--src/stream.h205
1 files changed, 0 insertions, 205 deletions
diff --git a/src/stream.h b/src/stream.h
deleted file mode 100644
index b35f6ee..0000000
--- a/src/stream.h
+++ /dev/null
@@ -1,205 +0,0 @@
1/*
2 * Copyright (C) 2007-2011 Xagasoft, All rights reserved.
3 *
4 * This file is part of the libbu++ library and is released under the
5 * terms of the license contained in the file LICENSE.
6 */
7
8#ifndef BU_STREAM_H
9#define BU_STREAM_H
10
11#include "bu/config.h"
12
13#include <stdint.h>
14#include <stdio.h>
15
16#include "bu/string.h"
17
18namespace Bu
19{
20 /**
21 * The basis for a completely general data transport mechanism. Anything
22 * that inherits from this should provide at least the basic read and/or
23 * write functions, and very probably the close function. Any functions
24 * that aren't supported should throw an exception if called.
25 *
26 * The constructor of a child class should pretty much universally be used
27 * to open the stream. I can't think of anything that should require an
28 * exception.
29 *@ingroup Streams
30 */
31 class Stream
32 {
33 public:
34 Stream();
35 virtual ~Stream();
36
37 /**
38 * Close the stream.
39 */
40 virtual void close() = 0;
41
42 /**
43 * Read data from the stream into a buffer.
44 *@param pBuf (void *) Buffer which will be filled.
45 *@param nBytes (size_t) Max data to read.
46 *@returns (size_t) Amount of data read.
47 */
48 virtual size read( void *pBuf, size iBytes ) = 0;
49
50 /**
51 * Attempts to read a complete line from the stream. This will stop
52 * reading when it has reached the end of the stream, or runs out of
53 * data in a non-blocking stream.
54 *@returns The line read, not including newline character.
55 */
56 virtual Bu::String readLine();
57
58 /**
59 * Reads all data from the current position onward until isEos returns
60 * true and returns it as a Bu::String. This will also return if no
61 * data is available and the stream is in non-blocking mode. This
62 * function is intended for very particular circumstances and is often
63 * not the most efficient way to access the data that you would like.
64 *@returns The entire stream contents.
65 */
66 virtual Bu::String readAll();
67
68 /**
69 * Write data to the stream.
70 *@param pBuf (const void *) The data to be written.
71 *@param nBytes (size_t) Amount of data to write from pBuf.
72 *@returns (size_t) Amount of data actually written.
73 */
74 virtual size write( const void *pBuf, size iBytes ) = 0;
75
76 virtual size write( const Bu::String &sBuf );
77
78 /**
79 * Get the current position in the stream.
80 *@returns (long) The current position in the stream.
81 */
82 virtual size tell() = 0;
83
84 /**
85 * Seek to a position in the stream relative to the current position.
86 *@param offset (long) Offset from current position to seek to.
87 */
88 virtual void seek( size offset ) = 0;
89
90 /**
91 * Set position in the stream relative to the start of the stream.
92 *@param pos (long) The position.
93 */
94 virtual void setPos( size pos ) = 0;
95
96 /**
97 * Set position in the stream relative to the end of the stream.
98 *@param pos (long) The position.
99 */
100 virtual void setPosEnd( size pos ) = 0;
101
102 /**
103 * Are we at the end of the stream?
104 *@returns (bool) Are we at the end of the stream?
105 */
106 virtual bool isEos() = 0;
107
108 /**
109 * Is the stream open?
110 *@returns (bool) Is the stream open?
111 */
112 virtual bool isOpen() = 0;
113
114 /**
115 * Flush any data still held in buffers.
116 */
117 virtual void flush() = 0;
118
119 /**
120 * In non-blocking streams this indicates if a read operation will
121 * return data at the moment or not. In blocking streams this should
122 * return the same value as isEos().
123 */
124 virtual bool canRead() = 0;
125
126 /**
127 * In non-blocking streams this indicates if a write operation will
128 * actually write one or more bytes. In some cases writing is not
129 * allowed (e.g. internal buffers are full) temporarilly. In blocking
130 * streams this should return the same value as isWritable.
131 */
132 virtual bool canWrite() = 0;
133
134 /**
135 * Indicates if the stream is capable of read operations. This does not
136 * indicate if such operations will return useful data, see canRead for
137 * that.
138 */
139 virtual bool isReadable() = 0;
140
141 /**
142 * Indicates if the stream is capable of write operations. This does
143 * not indicate if such operations will succeed or fail, see canWrite
144 * for that.
145 */
146 virtual bool isWritable() = 0;
147
148 /**
149 * Indicates if the stream is capable of seek operations. This is
150 * generally false for non-blocking streams. Some buffered streams may
151 * support limited in-buffer seeking.
152 */
153 virtual bool isSeekable() = 0;
154
155 /**
156 * Are we currently set to block mode?
157 *@returns (bool)
158 */
159 virtual bool isBlocking() = 0;
160
161 /**
162 * Set stream to blocking or non-blocking mode.
163 *@param bBlocking (bool) Whether we should block or not.
164 */
165 virtual void setBlocking( bool bBlocking=true ) = 0;
166
167 /**
168 * Set the size of the stream, this does not apply to many types of
169 * streams. For those that it does apply to, data will be added or
170 * removed from the end of the stream, but the content of the added
171 * data is undefined.
172 */
173 virtual void setSize( size iSize ) = 0;
174
175 /**
176 * Returns the size of the stream if the stream can have a size. For
177 * streams that do not (sockets, pipes, etc.) this should throw an
178 * unsupported exception.
179 */
180 virtual size getSize() const = 0;
181
182 /**
183 * Returns the block-size of the stream, if it has one. This should
184 * throw an unsupported exception. In some cases the block size
185 * returned will not represent quite the same thing, for example,
186 * sockets will return their MTU, while files will return the
187 * filesystem's block size, and memory buffers will throw an exception.
188 */
189 virtual size getBlockSize() const = 0;
190
191 /**
192 * If possible, this returns a string that can be used to describe how
193 * to access the open stream. Not all streams support this, such as
194 * MemBuf, but for files it may give you a path to a file, for a socket
195 * it may give you an ip address, etc. If it isn't supported, an empty
196 * string may be returned.
197 */
198 virtual Bu::String getLocation() const = 0;
199
200 private:
201
202 };
203}
204
205#endif