Classic file stream capable of manipulating files in the file system. More...

Inheritance diagram for MStreamFile:

Public Types
enum	OpenFlags { FlagCreate = 0x10000, FlagNoReplace = 0x20000, FlagTruncate = 0x40000, FlagAppend = 0x80000 }
	These extra open mode flags are added to flags in MStream. More...

enum	SharingFlags { SharingAllowNone = 0, SharingAllowRead = 1, SharingAllowWrite = 2, SharingAllowAll = 3 }
	Sharing flags, relevant only to Windows operating system. More...

typedef HANDLE	StreamFileHandle
	Operating system dependent stream handle. More...

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

Public Member Functions
	MStreamFile ()
	Default constructor that creates an uninitialized file object. More...

	MStreamFile (const MStdString &fileName, unsigned flags=FlagReadOnly, unsigned sharing=SharingAllowAll)
	Create object and open a file stream by name. More...

	MStreamFile (StreamFileHandle handle, bool handleOwned, unsigned flags, MConstChars name, bool handleStandardConsole=false)
	Creates the file stream based on the given operating system handle that was opened previously. More...

virtual	~MStreamFile ()
	Destroy object, close the stream if it was opened previously. More...

void	Open (const MStdString &filename, unsigned flags=FlagReadOnly, unsigned sharing=SharingAllowAll)
	Open the file. More...

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

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

bool	IsOpen () const
	Whether the stream object is successfully open. 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...

Static Public Member Functions
static MStreamFile *	GetStdIn ()
	Standard input stream, analog of `stdin` that supports MStreamFile interface. More...

static MStreamFile *	GetStdOut ()
	Standard output stream, analog of `stdout` that supports MStreamFile interface. More...

static MStreamFile *	GetStdErr ()
	Standard error stream, analog of `stderr` that supports MStreamFile interface. More...

static MByteString	StaticReadAll (const MStdString &fileName)
	Convenience static method that reads the whole file at once and returns it as string. More...

static MStdStringVector	StaticReadAllLines (const MStdString &fileName)
	Convenience static method that reads the whole file at once and returns it as a collection of strings. More...

static MTime	GetModifyTime (const MStdString &fileName)
	Static method to access time when the given file was last modified. More...

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...

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

Protected Member Functions inherited from MStream
	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...

Detailed Description

Classic file stream capable of manipulating files in the file system.

The class inherits most of its power from the base MStream.

See also: MStream

Member Typedef Documentation

typedef HANDLE MStreamFile::StreamFileHandle

Operating system dependent stream handle.

For advanced uses, there is a way of accessing file handle directly. However caution should be taken by the developers, as the stream class can do its own buffering and data manipulation.

See also: MStreamFile(StreamFileHandle handle, bool handleOwned, unsigned flags, MConstChars name, bool handleStandardConsole)

Member Enumeration Documentation

enum MStreamFile::OpenFlags

These extra open mode flags are added to flags in MStream.

Enumerator
FlagCreate	Always create a new file. This is the analog of standard POSIX flag O_CREAT.
FlagNoReplace	Only effective with FlagCreate, which when set, throws an error if file exists. This is the analog of standard POSIX flag O_EXCL.
FlagTruncate	Open existing file and truncate it to an empty one. This is the analog of standard POSIX flag O_TRUNC.
FlagAppend	Set file pointer at the end.

enum MStreamFile::SharingFlags

Sharing flags, relevant only to Windows operating system.

For non-Windows operating systems, the flag has no effect.

Enumerator
SharingAllowNone	No sharing is allowed, an attempt to open the same file will fail.
SharingAllowRead	While this file is open, same or another process or user can open file for reading.
SharingAllowWrite	While this file is open, same or another process or user can open file for writing.
SharingAllowAll	While this file is open, same or another process or user can open file in any mode.

Constructor & Destructor Documentation

MStreamFile::MStreamFile ( )

Default constructor that creates an uninitialized file object.

The result file object is not open, no streaming operations are possible until Open is called.

See also: Open

MStreamFile::MStreamFile	(	const MStdString &	fileName,
		unsigned	flags = `FlagReadOnly`,
		unsigned	sharing = `SharingAllowAll`
	)

Create object and open a file stream by name.

Depending on the flags given, the file can be created.

fileName

File name, either relative or absolute.

When relative path is specified, current directory of the process is taken into consideration.
Absolute path will not depend on the current path of the process.
UNIX-style forward slashes can be used for directory separation on any operating system, including Windows.
On windows only, the Windows specific back slashes will work as usual.

flags

Flags applicable to file operation. Those are both, the generic stream specific flags, and flags relevant only to file stream. Bitwise OR operation can be used to apply many flags together.

See MStream::OpenFlags for details of generic stream flags
See MStreamFile::OpenFlags for details of file stream flags

sharing: This has effect only on Windows operating system, file sharing mode tells if the same file can be manipulated at the same time by this or other process or user. See MStreamFile::SharingFlags for possible values. This mode is a set of enumeration values, not a bit mask.

Many types of errors can be reported by this constructor to indicate impossibility of the operation. The exact precondition will depend on the presence of the file, flags supplied, and permissions of the user who runs the process. Typical uses:

// Open an existing text file for reading.
// File with such name shall exist in the current directory.
MStreamFile f1("myfile.txt", MStream::FlagReadOnly | MStream::FlagText);
// Open a new binary file for writing.
// This has to be a new file, and if such file is present already there will be an error.
MStreamFile f2("/tmp/myfile.db", MStream::FlagWriteOnly | MStreamFile::FlagNoReplace);
// Open a new binary file for reading and writing, truncate it to zero size if it exists already.
MStreamFile f3("/tmp/myfile.db", MStream::FlagReadWrite | MStreamFile::FlagTruncate);

See also: Open

MStreamFile::MStreamFile	(	StreamFileHandle	handle,
		bool	handleOwned,
		unsigned	flags,
		MConstChars	name,
		bool	handleStandardConsole = `false`
	)

Creates the file stream based on the given operating system handle that was opened previously.

Since by contract this constructor accepts an open handle, no system errors will be reported in this particular call, however those are possible when the object starts manipulating the handle. If the handle is owned, the stream will be closed at Close event or at object destruction, otherwise the stream will not be closed.

Parameters

handle	Handle that has to be open prior to calling this constructor. The particular type of the handle is operating system dependent.
handleOwned	Whether the handle will be owned by the stream. It only matters at the time stream destructor is called. If the handle is owned, it will be closed in stream destructor.
flags	Which flags to use on an opened handle.
name	Stream name, given so that the error messages that mention stream name can print it. For streams without a place in the file hierarchy, or for generic streams, any sort of artificial name can be given. For example, for `stdin` one can give "<stdin>". This parameter will only be used in error reporting.
handleStandardConsole	This parameter should only be true if this stream is created to handle standard console. Standard consoles have special behavior in the way their buffers are handled.

virtual MStreamFile::~MStreamFile ( )

virtual

Destroy object, close the stream if it was opened previously.

In certain cases, such as if this is a standard console input or output, the streams will not be closed.

Member Function Documentation

static MTime MStreamFile::GetModifyTime ( const MStdString & fileName )

static

Static method to access time when the given file was last modified.

This method is static, and it takes file name, as typically such operation does not have to open the file. The file shall exist for the operation to succeed and the path shall be accessible to user who shall have proper permissions, or an exception is thrown.

virtual MStdString MStreamFile::GetName ( ) const

virtual

Return a representative name of a stream.

This method overwrites the parent implementation and gives the file name as supplied at Open call.

Implements MStream.

static MStreamFile* MStreamFile::GetStdErr ( )

static

Standard error stream, analog of stderr that supports MStreamFile interface.

Some operating systems, such as Windows CE, do not support standard streams and they do not have this static property.

static MStreamFile* MStreamFile::GetStdIn ( )

static

Standard input stream, analog of stdin that supports MStreamFile interface.

Some operating systems, such as Windows CE, do not support standard streams and they do not have this static property.

static MStreamFile* MStreamFile::GetStdOut ( )

static

Standard output stream, analog of stdout that supports MStreamFile interface.

Some operating systems, such as Windows CE, do not support standard streams and they do not have this static property.

void MStreamFile::Open	(	const MStdString &	filename,
		unsigned	flags = `FlagReadOnly`,
		unsigned	sharing = `SharingAllowAll`
	)

Open the file.

If the object was an open file already, it will be closed first by this call. Depending on the flags given, the file can be created.

fileName

File name, either relative or absolute.

When relative path is specified, current directory of the process is taken into consideration.
Absolute path will not depend on the current path of the process.
UNIX-style forward slashes can be used for directory separation on any operating system, including Windows.
On windows only, the Windows specific back slashes will work as usual.

flags

Flags applicable to file operation. Those are both the generic stream specific flags, and flags relevant only to file stream. Bitwise OR operation can be used to apply many flags together.

See MStream::OpenFlags for details of generic stream flags
See MStreamFile::OpenFlags for details of file stream flags

sharing: This has effect only on Windows operating system, file sharing mode tells if the same file can be manipulated at the same time by this or other process or user. See MStreamFile::SharingFlags for possible values. This mode is a set of enumeration values, not a bit mask.

Many types of errors can be reported by this constructor to indicate impossibility of the operation. The exact precondition will depend on the presence of the file, flags supplied, and permissions of the user who runs the process. Typical uses:

// Open an existing text file for reading.
// File with such name shall exist in the current directory.
f1.Open("myfile.txt", MStream::FlagReadOnly | MStream::FlagText);
// Open a new binary file for writing.
// This has to be a new file, and if such file is present already there will be an error.
f2.Open("/tmp/myfile.db", MStream::FlagWriteOnly | MStreamFile::FlagNoReplace);
// Open a new binary file for reading and writing, truncate it to zero size if it exists already.
f3.Open("/tmp/myfile.db", MStream::FlagReadWrite | MStreamFile::FlagTruncate);

static MByteString MStreamFile::StaticReadAll ( const MStdString & fileName )

static

Convenience static method that reads the whole file at once and returns it as string.

This method is an equivalent of the following operations, but it does not expose the temporary file object:

MStreamFile(fileName, MStream::FlagReadOnly | MStream::FlagUseHeader).ReadAll();

The file with such name shall exist for the operation to succeed. Notice that the file is not open in text mode. If file is the text, and it shall be manipulated string by string, StaticReadAllLines can be more convenient.

See also: StaticReadAllLines - return the contents of a text file as a collection of strings

static MStdStringVector MStreamFile::StaticReadAllLines ( const MStdString & fileName )

static

Convenience static method that reads the whole file at once and returns it as a collection of strings.

This method is an equivalent of the following operations, but it does not expose the temporary file object:

MStreamFile(fileName, MStream::FlagReadOnly | MStream::FlagBuffered | MStream::FlagUseHeader).ReadAllLines();

The file with such name shall exist for the operation to succeed. It is assumed that the file is text, otherwise the behavior might be unexpected as the attempt to handle carriage return and line feed characters will be made. For binary streams StaticReadAll will be more appropriate.

See also: StaticReadAll - Returns the contents of the file as one single chunk of bytes.

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation