molib documentation

Languages Available: français español

CLASS

moIStream

NAME

Constructor - create an moIStream object
Destructor - destroys an moIStream object

VERSION

Version: 1.2.0

SYNOPSIS

moIStream(void);
virtual ~moIStream();

DESCRIPTION

An moIStream is a pure class. It is necessary to have an inherited version of it to instanciate an actual stream.

The moIStream is used for input. Please, use an moOStream for output purposes and an moIOStream for both input and output.

SEE ALSO

moOStream

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

Read - call this function to read some data from a file
RawRead - the implementation dependent read function

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Read(void *buffer, size_t length);

protected:
virtual int RawRead(void *buffer, size_t length) = 0;

PARAMETERS

buffer - a pointer where the data read will be saved
length - the number of bytes to read in buffer

DESCRIPTION

The Read() function will call the RawRead() and then pass the data to the current filter. It will then read the result out of the filter to the user buffer.

The RawRead() function is implementation dependent and thus is a pure virtual here. The moFile, for instance, defines the RawRead() as the fread() function in some input disk file or some other simple character stream.

If the Unread() function was succesfully called prior to a Read(), then the unread bytes are returned first. Note that Unread() can't "de-filter" data and thus the filter won't be run on data read from the internal buffer used to support the Unread() function.

Please, read the BUGS section of the Unread() function for more information about how to unread data previously read.

RETURN VALUE

the number of bytes read
0 when nothing can be read (eventually EOF was reached)
-1 when an error occurs

SEE ALSO

Get(), Unread(), Unget()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

Unread - write in the unget buffer

VERSION

Version: 1.2.0

SYNOPSIS

int Unread(const void *buffer, size_t length);

PARAMETERS

buffer - a pointer to the data to unread
length - the number of bytes to unread from buffer

DESCRIPTION

The Unread() function can be used to push bytes back in the stream. The next time the Read() function is called, these bytes are read first.

The function will throw an error if the number of bytes to be unread is too large for the internal buffer.

RETURN VALUE

the number of bytes unread

SEE ALSO

Get(), Read(), Unget()

BUGS

The bytes are copied as is in the internal buffer. This means if you unread a long, it is copied as four bytes as given in the buffer. Reading this value as two shorts may therefore not yield the expected result.

In other words, if you want to cancel a series of Get(char), you need to put the chars in reverse order in your buffer and then call the Unread() function at once:

myfunc(moIStream *stream) { char buf[32]; char *s;

s = buf + sizeof(buf) / sizeof(buf[0]); for(i = 0; i < 5; i++) { s--; // NOTE: we should handle errors too! stream->Get(s); } if(strcmp(s, "ABCDE") == 0) { // do something } else { // cancel these read stream->Unread(s, 5); } }

Note that this function can be used for chars but not for short, longs, etc.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

InputSize - the current size in bytes

VERSION

Version: 1.2.0

SYNOPSIS

virtual size_t InputSize(void) const;

DESCRIPTION

The InputSize() function retrieves the current size of this input stream.

RETURN VALUE

the size in bytes
-1 if an error occur

SEE ALSO

Read(), Get()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

Get - read a value from the input stream

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Get(<type>& c);

where <type> is any one of the C++ integer and floating point
type (bool, char, wchar_t, short, int, long, long long, float,
double, long double -- integers have signed and an unsigned
versions.)

PARAMETERS

c - a reference where the data read is written

DESCRIPTION

The Get() functions will read the necessary number of bytes from the input stream using the Read() function and return the resulting value. By default, the endian of the input stream is assumed to be the same as the system being used. It can be changed with the SetInputEndianess() function.

Though these are defined as virtual, they don't need to be overridden in your own stream declaration if it isn't to make it any faster.

RETURN VALUE

the number of bytes read (1, 2, 4 or 8 at this time)
-1 when an error occurs

SEE ALSO

Unget(), moOStream::Put(), SetInputEndianess()

BUGS

On some systems the size of some C++ types won't be properly recognized and thus an error will be thrown. This should never happen though.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

Unget - put a value back in the stream

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Unget(<type> c);

where <type> is any one of the C++ integer and floating point
type (bool, char, wchar_t, short, int, long, long long, float,
double, long double -- integers have signed and an unsigned
versions.)

PARAMETERS

c - the value to unget

DESCRIPTION

The Unget() functions will write the specified value back into the stream as if it had been read with the corresponding Get() function.

The endianness will be determined as the currently running processor endian or the one defined by the user with the SetInputEndian().

Though these are defined as virtual, they don't need to be overridden in your own stream declaration.

RETURN VALUE

the number of bytes written back (1, 2, 4 or 8 at this time)
-1 when an error occurs

SEE ALSO

Get(), moOStream::Put(), SetInputEndianess(), Unread()

BUGS

It is possible that these functions will throw an error if the size of a C++ type can't properly be determined.

You should Get() back the same way you Unget() data otherwise you may get an unexpected result due to the order in which bytes are re-read vs. unread. Please, see the BUGS section of the Unread() function for more information.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

InputFilename - get or change the input filename

VERSION

Version: 1.2.0

SYNOPSIS

virtual void InputFilename(const char *filename);
virtual const char *InputFilename(void) const;

PARAMETERS

filename - a UTF-8 filename

DESCRIPTION

A stream, by itself, doesn't require a name. If it is a named file, however, it can be given a name using this function.

RETURN VALUE

the current input stream filename

SEE ALSO

Get(), SetInputEndianess(), moOStream::SetOutputEndianess()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

SetInputEndianess - change the input endianess

VERSION

Version: 1.2.0

SYNOPSIS

virtual int SetInputEndianess(int endian);

PARAMETERS

endian - one of BIG_ENDIAN or LITTLE_ENDIAN

DESCRIPTION

The different Get() functions which read multi-byte values often require a specific endian to be used. This can easilly be archived by forcing the input stream to a specific endianess.

RETURN VALUE

the previous endianess

SEE ALSO

Get(), SetInputEndianess(), moOStream::SetOutputEndianess()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

SetInputFilter - change the input filter

VERSION

Version: 1.2.0

SYNOPSIS

virtual moFIFOSPtr SetInputFilter(moFIFO *filter);

PARAMETERS

filter - a FIFO to be used as a data filter

DESCRIPTION

This function accepts a FIFO which will be used as a filter to transform the raw data (read from the raw device) before to transfer them to the used of the stream.

You can stop the filtering by setting the filter pointer to 0.

NOTES

The default FIFO definition is transparent to the data (it isn't transformed) and this is isn't necessary to use such a FIFO on a stream.

RETURN VALUE

The previous filter or 0 when no filter was installed.

SEE ALSO

moOStream::SetOutputFilter()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

ReadPosition - get and set the position where data will be read next

VERSION

Version: 1.2.0

SYNOPSIS

virtual size_t ReadPosition(void) const;
virtual size_t ReadPosition(size_t position);

DESCRIPTION

The ReadPosition() functions will be used to seek the input file to the position where data needs to be read.

RETURN VALUE

the position where the pointer was before this call

SEE ALSO

Read(), Get()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIStream

NAME

Secret - mark the input stream as containing secret(s)

VERSION

Version: 1.2.0

SYNOPSIS

void Secret(void);

DESCRIPTION

The moIStream can hold some of the input in an unget buffer. When marked as secret, that buffer will be cleared before the moIStream is deleted. Note that is may not be necessary to set this flag if the input is encrypted.

Use this flag for security reasons.

This flag is set to false by default.

SEE ALSO

Unget(), Unread()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

Constructor - create an moOStream object
Destructor - destroys an moOStream object

VERSION

Version: 1.2.0

SYNOPSIS

moOStream(void);
virtual ~moOStream();

DESCRIPTION

An moOStream is a pure class. It is necessary to have an inherited version of it in order to instanciate such a stream.

The moOStream is used for output. Please, use an moIStream for input purposes and an moIOStream for both input and output.

SEE ALSO

moIStream

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

Write - call this function to write some data from a file
RawWrite - the implementation dependent write function

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Write(const void *buffer, size_t length);

protected:
virtual int RawWrite(const void *buffer, size_t length) = 0;

PARAMETERS

buffer - a pointer where the data read will be saved
length - the number of bytes to read in buffer

DESCRIPTION

The Write() function will call the RawWrite() after it passed the user data to the current output filter. The filter is in charge of transforming the user data in a raw format to be saved in the stream.

The RawWrite() function is implementation dependent and thus is a pure virtual here. The moFile, for instance, defines the RawWrite() as the fwrite() function in some input disk file or some other simple character stream.

NOTES

Because a filter may shrink (a compressor for instance) or enlarge (UTF8 to UTF32 for instance) the returned value could be interpreted in different ways. It was therefore decided that the number of bytes read from the user buffer pointer was the number we needed to return. This means more or less bytes may actually have been written to the final output stream.

RETURN VALUE

the number of bytes from buffer written
0 when nothing can be written
-1 when an error occurs

SEE ALSO

Put()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

Put - write a value to the output stream

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Put(<type> c);

where <type> is any one of the C++ integer and floating point
type (bool, char, wchar_t, short, int, long, long long, float,
double, long double -- integers have signed and an unsigned
versions.)

PARAMETERS

c - the value to write

DESCRIPTION

The Put() functions will write the necessary number of bytes from the given user parameter to the output using the Write() function. By default, the endian of the input stream is assumed to be the same as the system being used. It can be changed with the SetInputEndianess() function.

Though these are defined as virtual, they don't need to be defined in your own stream declaration.

RETURN VALUE

the number of bytes written (1, 2, 4 or 8 at this time)
-1 when an error occurs

SEE ALSO

moIStream::Get(), SetOututEndianess()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

OutputFilename - get or change the input filename

VERSION

Version: 1.2.0

SYNOPSIS

virtual void OutputFilename(const char *filename);
virtual const char *OutputFilename(void) const;

PARAMETERS

filename - a UTF-8 filename

DESCRIPTION

Changes the name of the output stream. By default, a stream is not specific to a file and thus isn't named. If you create a named file, set the name using this function.

RETURN VALUE

a pointer to the filename

SEE ALSO

moIStream::InputFilename()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

SetOutputEndianess - change the output endianess

VERSION

Version: 1.2.0

SYNOPSIS

virtual int SetOutputEndianess(int endian);

PARAMETERS

endian - one of BIG_ENDIAN or LITTLE_ENDIAN

DESCRIPTION

The different Put() functions which write multi-byte values often require a specific endian to be used. This can easilly be archived by forcing the output stream to a specific endianess.

RETURN VALUE

the previous endianess

SEE ALSO

Put(), moOStream::SetInputEndianess()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

SetOutputFilter - change the output endianess

VERSION

Version: 1.2.0

SYNOPSIS

virtual moFIFOSPtr SetOutputFilter(moFIFO *filter);

PARAMETERS

filter - a FIFO defined as a filter

DESCRIPTION

The data sent to a streams can automatically be filtered. This is done by using a FIFO that you install on an output stream with the SetOutputFilter() function.

Any data written to the stream will first be sent to the filter.

It is possible to stop the filtering by setting the filter pointer to 0.

NOTES

The default FIFO definition is transparent to the data (it isn't transformed) and this is isn't necessary to use such a FIFO on a stream.

RETURN VALUE

The previous filter pointer or 0 when none was defined.

SEE ALSO

moOStream::SetInputFilter()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

Flush - ensures all the data is written in the output

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Flush(void);

DESCRIPTION

The Flush() function will flush the data written to a disk, pipe, socket, etc. Any device which may bufferize data will derive the Flush() function so the user can ensure all the data was properly written in the output stream.

The default Flush() function does nothing.

RETURN VALUE

0 when no error occured
non zero if an error occurs

SEE ALSO

Write(), Put()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

OutputSize - the current size in bytes

VERSION

Version: 1.2.0

SYNOPSIS

virtual size_t OutputSize(void);

DESCRIPTION

The OutputSize() function retrieves the current size of this output stream.

RETURN VALUE

the size in bytes
-1 if an error occur

SEE ALSO

Write(), Put()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOStream

NAME

WritePosition - get and set the position where data will be written next

VERSION

Version: 1.2.0

SYNOPSIS

virtual size_t WritePosition(void) const;
virtual size_t WritePosition(size_t position);

DESCRIPTION

The WritePosition() functions will be used to seek the output file to the position where data needs to be written.

RETURN VALUE

the position where the pointer was before this call

SEE ALSO

Write(), Put()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIOStream

NAME

Constructor - create an I/O stream
Destructor - destroys an I/O stream

VERSION

Version: 1.2.0

SYNOPSIS

moIOStream(void);
virtual ~moIOStream();

DESCRIPTION

Create a stream which can be used for input and output.

SEE ALSO

moIStream, moOStream

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIOStream

NAME

Filename - get or change the I/O stream filename

VERSION

Version: 1.2.0

SYNOPSIS

virtual void Filename(const char *filename);
virtual const char *Filename(void);

PARAMETERS

filename - a UTF-8 filename

DESCRIPTION

A stream, by itself, doesn't require a name. If it is a named file, however, it can be given a name using this function.

Note that an I/O stream can receive two file names if the input and output specific functions are used to set the names.

RETURN VALUE

the current input and output stream filename

SEE ALSO

moIStream::InputFilename(), moOStream::OutputFilename()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moIOStream

NAME

AddRef - remove the moBase ambiguity
Release - remove the moBase ambiguity

VERSION

Version: 1.2.0

SYNOPSIS

unsigned long AddRef(void) const;
unsigned long Release(void);

DESCRIPTION

These two functions were created so the compiler can properly chose which AddRef/Release to use (the one from moIStream or moOStream.)

RETURN VALUE

the number of times the object was referenced

SEE ALSO

moBase::AddRef, moBase::Release

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox