PTypes: streams: iobase

#include <pstreams.h>

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

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

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 an object. Close() calls flush() for output streams. To simplify error handling in user programs, this method never throws exceptions. If you want to check for errors during the last write operation, call flush() explicitly before closing the stream.

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.

large iobase::tellx() 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::tell() left for compatibility; returns a 32-bit file offset or raises an exception if the value doesn't fit the int type.

large iobase::seekx(large 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, seekx() 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.

int iobase::seek(int newpos, ioseekmode mode = IO_BEGIN) left for compatibility; tries to seek in 32-bit mode and return a 32-bit file offset. Raises an exception if the return value doesn't fir the int type.

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(bool) indicates whether the stream is active. Setting this property to true or false opens or closes the stream respectively.

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

int iobase::get/set_bufsize(int) 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(int) 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(iostatusevent) -- sets or returns user-defined callback function. The callback function is called whenever the status of the stream is changed (see also get_status()).