MStream is the base class of all streams. More...

Inheritance diagram for MStream:

[legend]

Public Types
enum	OpenFlags { FlagReadOnly = 0x0001, FlagWriteOnly = 0x0002, FlagReadWrite = 0x0003, FlagText = 0x00010, FlagBuffered = 0x0020 }
	Flags that set modes of stream manipulation. More...

Public Member Functions
virtual	~MStream ()
	Closes the stream and destroys the object. More...

bool	IsOpen () const
	Whether the stream object is successfully open. More...

virtual MStdString	GetName () const =0
	Return a representative name of a stream. More...

unsigned	GetFlags () const
	Return flags associated with stream. More...

MByteString	Read (unsigned count)
	Reads a byte string of a given length from the stream. More...

MByteString	ReadAvailable (unsigned count)
	Reads a byte string up to a given length from the stream. More...

MByteString	ReadAll ()
	Reads all bytes available in stream. More...

void	ReadBytes (char *buffer, unsigned count)
	Reads a byte buffer of a given length from the stream. More...

unsigned	ReadAvailableBytes (char *buffer, unsigned count)
	Reads a byte buffer up to a given length from the stream. More...

MVariant	ReadLine ()
	Read one line from text file. More...

bool	ReadOneLine (MStdString &line)
	Read one line from text file, return false at end of file. More...

MStdStringVector	ReadAllLines ()
	Read all lines from text file. More...

void	Skip (unsigned count)
	Skips over and discards specified number of bytes of data from this stream. More...

void	WriteByte (Muint8 byte)
	Writes a byte to the current position in the stream and advances the position by one byte. More...

void	WriteChar (char c)
	Writes a char to the current position in the stream and advances the position by one byte. More...

void	Write (const MByteString &bytes)
	Writes a given byte string to the current position in the stream and advances the position. More...

void	WriteBytes (const char *bytes, unsigned count)
	Writes a given byte buffer to the current position in the stream and advances the position. More...

void	WriteChars (const char *chars)
	Writes a given zero terminated character string to the current position in the stream and advances the position. More...

void	WriteLine (const MStdString &str)
	Write a line into file. More...

void	WriteAllLines (const MStdStringVector &lines)
	Write given lines into file. More...

void	WriteFormat (MConstChars format,...)
	Write a formatted string into a file. More...

void	WriteFormatVA (MConstChars format, va_list args)
	Write a formatted string into a file using va_list. More...

void	Flush ()
	Causes any buffered data to be written into stream. More...

void	Close ()
	Flushes and closes the current stream and releases any resources. More...


MStdString	GetKey () const

void	SetKey (const MStdString &)


unsigned	GetPosition () const

void	SetPosition (unsigned)


unsigned	GetSize () const

void	SetSize (unsigned)


MVariant	ReadByte ()

Public Member Functions inherited from MObject
virtual	~MObject ()
	Object destructor.

virtual const MClass *	GetClass () const =0
	Get the final class of the object. More...

virtual unsigned	GetEmbeddedSizeof () const
	For embedded object types, return the size of the class. More...

bool	IsEmbeddedObject () const
	Tell if the object is of embedded kind. More...

SHOW_INTERNAL MVariant	Call (const MStdString &name, const MVariant &params)
	Call the object service with parameters, given as variant. More...

MVariant	Call0 (const MStdString &name)
	Call the object service with no parameters. More...

MVariant	Call1 (const MStdString &name, const MVariant &p1)
	Call the object service with one parameter. More...

MVariant	Call2 (const MStdString &name, const MVariant &p1, const MVariant &p2)
	Call the object service with two parameter. More...

MVariant	Call3 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3)
	Call the object service with three parameter. More...

MVariant	Call4 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4)
	Call the object service with four parameter. More...

MVariant	Call5 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5)
	Call the object service with five parameter. More...

MVariant	Call6 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5, const MVariant &p6)
	Call the object service with six parameter. More...

virtual MVariant	CallV (const MStdString &name, const MVariant::VariantVector &params)
	Call the object service with parameters, given as variant vector. More...

virtual bool	IsPropertyPresent (const MStdString &name) const
	Tell if the property with the given name exists.

virtual bool	IsServicePresent (const MStdString &name) const
	Tell if the service with the given name exists.

virtual MVariant	GetProperty (const MStdString &name) const
	Get the property value using name of the property. More...

virtual void	SetProperty (const MStdString &name, const MVariant &value)
	Set the property using name of the property, and value. More...

virtual MStdStringVector	GetAllPropertyNames () const
	Return the list of publicly available properties, persistent or not. More...

virtual MStdStringVector	GetAllPersistentPropertyNames () const
	Return the list of persistent properties. More...

virtual void	SetPersistentPropertiesToDefault ()
	Set the persistent properties of the object to their default values. More...

virtual MVariant	GetPersistentPropertyDefaultValue (const MStdString &name) const
	Get the default value of persistent property with the name given. More...

virtual void	SetPersistentPropertyToDefault (const MStdString &name)
	Set the persistent property with the name given to default value. More...

virtual const char *	GetType () const
	Get the name of the type for the object (could be the same as class name).

virtual void	SetType (const MStdString &)
	Intentionally, it will set the name of the type for the object, but the service will not allow setting the name to anything other than the current name. More...

virtual void	Validate ()
	Validate internal structures of the object. More...

Protected Member Functions
	MStream ()
	Default constructor, called from children of stream.

Protected Member Functions inherited from MObject
	MObject ()
	Object constructor, protected as the class is abstract.

void	DoSetPersistentPropertiesToDefault (const MClass *staticClass)
	Set the persistent properties to their default values for one object provided the class for that object. More...

Additional Inherited Members
Static Public Member Functions inherited from MObject
static const MClass *	GetStaticClass ()
	Get the declared class of this particular object. More...

static bool	IsClassPresent (const MStdString &name)
	Tells if the given class name is available. More...

Static Public Attributes inherited from MObject
static const MClass	s_class
	Class of MObject.

Detailed Description

MStream is the base class of all streams.

A stream is an abstraction of a sequence of bytes, such as a file, an input/output device, an interprocess communication pipe, or a TCP/IP socket. The MStream class and its derived classes provide a generic view of these different types of input and output, isolating the programmer from the specific details of the operating system and the underlying devices.

Some stream implementations perform local buffering of the underlying data to improve performance. For such streams, the Flush method can be used to clear any internal buffers and ensure that all data has been written to the underlying data source or repository.

Calling Close on a MStream flushes any buffered data, essentially calling Flush for you. Close also releases operating system resources such as file handles, network connections, or memory used for any internal buffering.

Member Enumeration Documentation

enum MStream::OpenFlags

Flags that set modes of stream manipulation.

They are given at stream open call.

Enumerator
FlagReadOnly	Only read operations are allowed by this stream.
FlagWriteOnly	Only write operations are allowed by this stream.
FlagReadWrite	Both reads and writes are allowed for this stream.
FlagText	On non-POSIX platforms, this flag will translate from new line character to carriage return and new line. Text streams can be buffered or not.
FlagBuffered	Real device read-write operations will be minimized, buffer used.

Constructor & Destructor Documentation

virtual MStream::~MStream ( )

virtual

Closes the stream and destroys the object.

This destructor never throws an exception at a close, even if during this operation any problems were encountered, such as IO error at flushing the buffer.

See also: Close This method will not silently swallow any exceptions during close operation.

Member Function Documentation

void MStream::Close ( )

Flushes and closes the current stream and releases any resources.

If a stream is not open, this method does nothing. Different from object destructor, this method can report any errors such as failure to flush a stream buffer. After such error, the file will remain closed

See also: IsOpen - tells if the stream is open

void MStream::Flush ( )

Causes any buffered data to be written into stream.

The behavior of this method depends on the particular stream. In some cases, the method has to do nothing until the stream is closed.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

unsigned MStream::GetFlags ( ) const

inline

Return flags associated with stream.

By convention, if the stream is not open, the returned value will be zero.

See also: IsOpen to check whether the stream is open.

MStdString MStream::GetKey ( ) const

Key to use in AES encrypted streams.

The key shall be a hexadecimal string that represents 16 binary bytes. Key can be set to the stream even if it is not open yet. In this case, it will affect the open operation.

See also: FlagAesEncrypted - flag that controls whether the stream is encrypted; FlagAesEncryptedCompressed - flag that controls whether the stream shall be compressed before encryption

virtual MStdString MStream::GetName ( ) const

pure virtual

Return a representative name of a stream.

This method is convenient for reporting the user recognized names in generic stream operations, for example it can be used for error reporting. The implementation of this method depends on the particular stream class. For files the file name will be returned.

Precondition: The stream shall be open for this operation to be successful.

Implemented in MStreamFile, MStreamSocket, MStreamExternalMemory, MStreamMemory, and MStreamSocketUdp.

unsigned MStream::GetPosition ( ) const

Position of the current stream pointer.

If the given position exceeds stream size the stream pointer will be moved to the end of stream.

Precondition: The stream must be opened for these operations to succeed. Also, the stream type and flags shall allow manipulation of its position.

unsigned MStream::GetSize ( ) const

Returns total size of the stream in bytes.

For compressed streams this size can be a lot bigger than the actual file size, as this size is whatever can be read from the stream. It is possible to truncate a stream that support such operation to a size that is smaller than its current size.

Precondition: The stream must be opened for these operations to succeed. The stream type and flags shall allow manipulation of its size. When set, the size given shall not be bigger than the current size of the stream.

bool MStream::IsOpen ( ) const

Whether the stream object is successfully open.

The implementation of this method depends on the particular stream class.

See also: Close - closing the stream

MByteString MStream::Read ( unsigned count )

Reads a byte string of a given length from the stream.

In case the stream does not have the given count of bytes, an end of stream exception is thrown.

Parameters

count The number of bytes to read from the stream.

Returns: Binary contents of exact specified size.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: ReadAvailable - a method that can return lesser amount of bytes than given.; ReadAll - return all bytes available, such as read the whole file into a byte buffer.

MByteString MStream::ReadAll ( )

Reads all bytes available in stream.

For a file it returns all bytes up to the end of the stream.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: Read - Reads a fixed count of bytes from stream.; ReadAvailable - A method that can return lesser amount of bytes than given.; ReadAllLines - Like ReadAll, but returns array of lines rather than one whole byte array.

MStdStringVector MStream::ReadAllLines ( )

Read all lines from text file.

A line is expected to be separated with new line character, while carriage return is ignored. The lines in collection end with line feed unless it is last in the file, and the last line does not end with line feed. When the file has no more lines an empty variant type is returned. The line is read from the current position.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: ReadLine - Returns next line in a file.

MByteString MStream::ReadAvailable ( unsigned count )

Reads a byte string up to a given length from the stream.

In case the stream does not have the given count of bytes, whatever is there is returned, therefore, the result number of bytes can be smaller than what is requested. When this operation is attempted at the end of the stream it will return an empty byte string.

Parameters

count The number of bytes to attempt to read from the stream.

Returns: Binary contents of specified size, or smaller.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: Read for reading a fixed count of bytes from stream; ReadAll - return all bytes available, such as read the whole file into a byte buffer.

unsigned MStream::ReadAvailableBytes	(	char *	buffer,
		unsigned	count
	)

Reads a byte buffer up to a given length from the stream.

This is a C++ only method. In case the stream does not have the given count of bytes, whatever is there is populated, therefore, the result number of bytes can be smaller than what is requested. When this operation is attempted at the end of the stream, it will populate an empty byte string.

Parameters

buffer	The buffer to hold the result, shall have at least count bytes.
count	The number of bytes to attempt to read from the stream.

Returns: Number of bytes read from the stream and set into buffer.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: ReadAvailable - Returns a byte string rather than fills buffer.; ReadBytes - A method that reads an exact count of bytes or throws an exception.

MVariant MStream::ReadByte ( )

Reads a byte from the stream and advances the position within the stream by one byte.

If a stream is at the end, return integer -1, otherwise, a byte with unsigned value 0 .. 255 is returned. Therefore, to check whether the stream is at the end, one verifies the variant type is an integer, in which case its value will be -1.

Returns

Byte in range 0 .. 225 for a read byte
Integer with value -1 if the stream is at the end

Precondition: The stream must be opened, and its access is possible.

void MStream::ReadBytes	(	char *	buffer,
		unsigned	count
	)

Reads a byte buffer of a given length from the stream.

This is a C++ only method. In case the stream does not have the given count of bytes, an end of stream exception is thrown.

Parameters

buffer	The buffer to hold the result, shall have at least count bytes.
count	The number of bytes to read from the stream.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: Read - Returns a byte string rather than fills buffer.; ReadAvailableBytes - A method that can populate lesser amount of bytes than given.

MVariant MStream::ReadLine ( )

Read one line from text file.

A line is expected to be separated with new line character, while carriage return is ignored. The returned line ends with line feed unless it is last in the file, and the last line does not end with line feed character. When the file has no more lines, an empty variant type is returned. The line is read from the current position.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: ReadAllLines - Returns all lines in a file in a collection.

bool MStream::ReadOneLine ( MStdString & line )

Read one line from text file, return false at end of file.

A line is expected to be separated with new line character, while carriage return is ignored. The returned line ends with line feed unless it is last in the file, and the last line does not end with line feed character. When the file has no more lines, an empty variant type is returned. The line is read from the current position.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: ReadAllLines - Returns all lines in a file in a collection.

void MStream::SetKey ( const MStdString & )

Key to use in AES encrypted streams.

The key shall be a hexadecimal string that represents 16 binary bytes. Key can be set to the stream even if it is not open yet. In this case, it will affect the open operation.

See also: FlagAesEncrypted - flag that controls whether the stream is encrypted; FlagAesEncryptedCompressed - flag that controls whether the stream shall be compressed before encryption

void MStream::SetPosition ( unsigned )

Position of the current stream pointer.

If the given position exceeds stream size the stream pointer will be moved to the end of stream.

Precondition: The stream must be opened for these operations to succeed. Also, the stream type and flags shall allow manipulation of its position.

void MStream::SetSize ( unsigned )

Returns total size of the stream in bytes.

For compressed streams this size can be a lot bigger than the actual file size, as this size is whatever can be read from the stream. It is possible to truncate a stream that support such operation to a size that is smaller than its current size.

Precondition: The stream must be opened for these operations to succeed. The stream type and flags shall allow manipulation of its size. When set, the size given shall not be bigger than the current size of the stream.

void MStream::Skip ( unsigned count )

Skips over and discards specified number of bytes of data from this stream.

The operation is performed by reading and ignoring whatever is read. If the specified number is zero, no bytes are skipped. If the stream does not have the specified number of bytes, an end of line exception is thrown.

Parameters

count How many bytes to skip.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

void MStream::Write ( const MByteString & bytes )

Writes a given byte string to the current position in the stream and advances the position.

Parameters

bytes Bytes to write into the stream.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

void MStream::WriteAllLines ( const MStdStringVector & lines )

Write given lines into file.

If any of the given lines do not end with line feed, the line feed is added to the stream. If the stream is open in text mode by having FlagText at open, and the platform is Windows, the carriage return is also added to comply with the text file rules on that platform.

Parameters

lines Lines to write into stream.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

void MStream::WriteByte ( Muint8 byte )

Writes a byte to the current position in the stream and advances the position by one byte.

Parameters

byte	A byte to place into stream.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

void MStream::WriteBytes	(	const char *	bytes,
		unsigned	count
	)

Writes a given byte buffer to the current position in the stream and advances the position.

This is a C++ only method.

Parameters

bytes	Pointer to the beginning of bytes buffer to write into the stream.
count	Number of bytes in the buffer that shall be written.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

void MStream::WriteChar ( char c )

inline

Writes a char to the current position in the stream and advances the position by one byte.

This method is exactly the same as WriteByte but for C++ type char, no UNICODE characters are processed.

Parameters

c	A character to place into stream.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

void MStream::WriteChars ( const char * chars )

Writes a given zero terminated character string to the current position in the stream and advances the position.

This is a C++ only method. The terminating zero character is not written to the stream.

Parameters

chars Pointer to the beginning of zero terminated string.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

void MStream::WriteFormat	(	MConstChars	format,
			...
	)

Write a formatted string into a file.

This is a C++ only method.

Parameters

format Format that shall comply to formatting rules defined by global function MFormat.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: MFormat for supported format specifiers.

void MStream::WriteFormatVA	(	MConstChars	format,
		va_list	args
	)

Write a formatted string into a file using va_list.

This is a C++ only method.

Parameters

format	Format that shall comply to formatting rules defined by global function MFormat.
args	Format arguments.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

See also: MFormat for supported format specifiers.

void MStream::WriteLine ( const MStdString & str )

Write a line into file.

If the given line does not end with line feed, the line feed is added to the stream. If the stream is open in text mode by having FlagText at open, and the platform is Windows, the carriage return is also added to comply with the text file rules on that platform.

Parameters

str	A line to write into stream.

Precondition: The stream must be opened for the operation to succeed, and the proper access rights are present.

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation