PTypes: streams: iobase

#include <pstreams.h>

typedef void (*iostatusevent)(iobase* sender, int code);

void   iobase::open();
void   iobase::close();
void   iobase::cancel();
int    iobase::tell();
int    iobase::seek(int newpos, ioseekmode mode = IO_BEGIN);
string iobase::get_streamname();
bool   iobase::get/set_active();
bool   iobase::get/set_cancelled();
int    iobase::get/set_bufsize();
int    iobase::get_status();
iostatusevent iobase::get/set_onstatus();

The methods and properties of this abstract class are common to all stream interfaces in PTypes.

void iobase::open() opens (activates) the stream.

void iobase::close() closes (deactivates) the stream. This method is called automatically during destruction of the object. Close() calls flush() for output streams.

void iobase::cancel() closes the stream and sets the cancelled property to true. In communication streams this method may close the connection immediately, unlike close(), which always tries to flush data buffers and then close the stream gracefully.

int iobase::tell() returns either the current position in the target media (usually file) or, for communication channels, the number of bytes transfered from the beginning of the session.

int iobase::seek(int newpos, ioseekmode mode = IO_BEGIN) changes the media pointer (e.g. file pointer). Possible values for mode are: IO_BEGIN, IO_CURRENT and IO_END. This function first tries to position the stream pointer within the scope of the I/O buffer. If the new pointer is out of buffer's range, seek() then tries to change the physical pointer of the target media. Note that physical positioning is not supported by some stream types, e.g. by ipstream.

string iobase::get_streamname() returns a string containing either a file name, an URL, or some other string describing the underlying media or object. Useful for diagnostics messages.

bool iobase::get/set_active() indicates whether the stream is active. Setting this property to true or false opens or closes the stream respectively.

bool iobase::get/set_cancelled() returns true if the stream was closed using cancel().

int iobase::get/set_bufsize() sets the buffer size for the stream. Setting this property to -1 will assign some reasonable default value, which may vary depending on the operating environment, available memory, etc. Note: text input routines require buffering (see instm).

int iobase::get_status() returns the current status of the stream. The value of this property can be one of the following: IO_CREATED, IO_OPENING, IO_OPENED, IO_READING, IO_WRITING, IO_EOF, IO_CLOSING, IO_CLOSED. Derivative classes may add other status codes, e.g. see ipstream.

iostatusevent iobase::get/set_onstatus() -- sets or returns user-defined callback function. The callback function is called whenever the status of the stream is being changed (see also get_status()).