Stream Class Reference

#include <stream.h>

Class Description

Streams are used to read information from a file, or to write it to a file.

In a Mudbox plug-in, you would typically use the Stream class when you override the Serialize method of a custom node that you have derived from the Node class. When you save or load a scene, Mudbox will call that method and pass you a stream object, which you can then use.

Typically, a stream object is used like this:

void myNode::Serialize( Stream& s )
{
    myParentClass::Serialize(s);
    s == myVariable1 == myVariable2 == myVariable3;
}

Here, the "==" operator will store the variables in the stream (if the stream is writing), or read them from the stream (if it is reading). So you can use the same code for both reading and writing. Since the "==" operator returns a stream reference, you can serialize multiple variables on the same line if you wish to do so, as shown above.

Examples:

Definition at line 39 of file stream.h.

Inheritance diagram for Stream:

Public Types
enum	{ chunk = 0x800000 }
Public Types inherited from Node
enum	DiagnosticLevel { dgnLevel1, dgnLevel2, dgnLevel3 }
	Indicates the level of validity checking that is performed in CheckValidity() More...

Public Member Functions
virtual	~Stream (void)
	Destructor. More...
virtual QString	FileName (void) const
	Returns the name of the file. More...
virtual bool	IsValid (void)
	Returns true if the stream has a valid version number. More...
virtual bool	IsOlderThan (int iVersion) const
	(Deprecated) Checks if the file is older than a specified version. More...
virtual bool	IsNewerThan (int iVersion) const
	(Deprecated) Checks if the file is newer than a specified version. More...
virtual int	ClassVersion (const class ClassDesc *pClass) const
	Returns the version for a class inside the current stream. More...
template<typename Type >
bool	IsOlderThan (int iVersion, Type *) const
	Checks if the file is older than a specified version for the given class. More...
template<typename Type >
bool	IsNewerThan (int iVersion, Type *) const
	Checks if the file is newer than a specified version for the given class. More...
virtual bool	IsStoring (void) const
	Returns true if the stream is in storing mode (i.e. More...
virtual void	SetError (bool bError)
	Use this method to inform Mudbox that there is an error in the stream you are trying to read or write. More...
virtual int	Version (void) const
	Returns the version number of the stream. More...
virtual uint64	CurrentPosition (void) const
	Returns the current position in the file. See also SetCurrentPosition(). More...
virtual void	SetCurrentPosition (uint64 iPosition)
	Sets the current position in the file. More...
virtual void	ReportCorruption (void)
	Call this function from your Serialize implementation, if you detect that the file content is corrupt. More...
virtual void	Open (const QString &sFileName, bool bStoring=false, int iProjectedFileSize=0, bool bProgressBar=true)
	Opens the file attached to this stream. More...
virtual void	Reopen (bool bStoring=false)
	Re-opens the file attached to this stream. More...
virtual bool	Close (void)
	Closes the file attached to this stream. More...
virtual bool	Eof (void)
	Returns true if you are reading the file, and you have reached the end of it. More...
virtual bool	ReadContents (void)
	This function reads the content of the stream into the memory, when the stream is opened for read. More...
virtual size_t	Read (void *pBuffer, size_t iSize)
	Reads data directly from the stream into a buffer you provide. More...
virtual size_t	Write (const void *pBuffer, size_t iSize)
	Writes data to the stream from a buffer you provide. More...
int	ReadInt (void)
	Reads a single integer from the stream, and returns it. More...
virtual void	ReadToFile (const QString &sFile)
	Takes the entire contents of the stream and writes it into the specified file. More...
virtual void	WriteFromFile (const QString &sFile)
	Fills the stream with the content of the specified file. More...
template<typename type >
Stream &	operator>> (type &v)
	Reads data from the stream to any data type. More...
template<typename type >
Stream &	operator<< (const type &v)
	Stores any data type into the stream. More...
virtual Node *	ReadPointer (void)
	Read/Writes node pointers. More...
virtual void	WritePointer (Node *pPointer)
template<typename type >
Stream &	operator>> (type *&p)
	Reads a pointer from the file. More...
template<typename type >
Stream &	operator<< (type *&p)
	Writes a pointer into the stream. More...
template<typename type >
Stream &	operator>> (Store< type > &s)
	Reads data from the stream to any Store (array) type. More...
template<typename type >
Stream &	operator<< (const Store< type > &s)
	Writes any store type (array) to the stream. More...
Stream &	operator>> (QString &s)
	Read/Writes QString. More...
Stream &	operator<< (const QString &s)
template<typename type >
Stream &	operator>> (QVector< type > &s)
	Reads data from the stream to a QVector object. More...
template<typename type >
Stream &	operator<< (const QVector< type > &s)
	Writes any store type (array) to the stream. More...
virtual void	WriteIntArray (const Store< unsigned int > &s)
virtual void	ReadIntArray (Store< unsigned int > &s)
template<>
Stream &	operator<< (const Store< unsigned int > &o)
template<>
Stream &	operator>> (Store< unsigned int > &o)
Public Member Functions inherited from Node
	Node (const QString &sStringID="", const QString &sDisplayName="")
	Standard constructor. More...
virtual	~Node (void)
virtual void	Initialize (void)
void	LoadTemplate (const QString &sFileName="", bool bStartEvent=false)
	Use an external XML file to initialize the attributes. More...
void	SaveTemplate (const QString &sFileName="", bool bSaveOnlyVisible=false)
	Save current attributes as an XML template. More...
unsigned int	Version (void) const
	Returns the current version of the node. This number increases when the content of the node changed (when ContentChanged() called). More...
void	SetVersion (unsigned int iVersion)
	Sets the current version number for the node. More...
unsigned int	ReferenceCount (void) const
	Returns the number of pointers referencing this node. More...
Attribute *	ReferencePointer (unsigned int iIndex) const
	Returns the address of an attribute which refers to this node. The type of the attribute is always aptr. More...
Node *	ReferenceNode (unsigned int iIndex) const
	Returns the address of a node referencing this node. More...
virtual QString	Name (const ClassDesc *pClass=0) const
	Deprecated. More...
virtual void	SetName (const QString &sName)
	Deprecated. More...
virtual QString	StringID (const ClassDesc *pClass=0) const
	Returns the string id of the node. More...
virtual void	SetStringID (const QString &sStringID)
	Sets the string id of the node. More...
virtual QString	DisplayName (void) const
	Returns the display name of the node. More...
virtual void	SetDisplayName (const QString &sDisplayName)
	Sets the display name of the node. More...
virtual QString	HelpID (void) const
	Returns the help entry id of the node. Can be overwritten in derived classes. More...
virtual void	SetHelpID (const QString &sHelpID)
	Sets the help entry id of the node. More...
void	Annex (Node *pSource, const QString &sCategory="")
	Relink all the attributes of the source node to this one. More...
virtual void	Serialize (Stream &s)
	Serializes the node. More...
bool	IsKindOf (const ClassDesc *pClass) const
	Returns true if this node is derived from the pClass class. More...
void	ContentChanged (void) const
	This function must be called if the content of the node is changed. More...
virtual void	CheckValidity (DiagnosticLevel iLevel=dgnLevel2) const
	Checks the validity of this node. More...
virtual void	CopyTo (Node *pNode) const
virtual Node *	Duplicate (void) const
virtual void	OnNodeEvent (const Attribute &cAttribute, NodeEventType cType)
	This function is called if an event occurs with any of the attributes of the node. More...
virtual void	OnEvent (const EventGate &cEvent)
	This function is called when a generic event occurs. See EventGate class. More...
void	RequestDeferredEvent (Attribute &cAttribute)
	Request for a deferred event, which will occur only in the main loop. More...
unsigned int	AttributeCount (void) const
	Returns the number of attributes owned by the node. More...
Attribute *	AttributeByIndex (int iIndex) const
	Returns a specified attribute (or 0 if iIndex is greater than the number of attributes). More...
Attribute *	AttributeByName (const QString &sName) const
	Returns a specified attribute by its name. Returns 0 if the attribute not found. More...
Attribute *	AttributeByID (const QString &sID) const
	Returns a specified attribute by its ID. Returns 0 if the attribute not found. More...
void	SetAttributeValue (const QString &sAttributeID, const QString &sNewValue)
	Set the value of an attribute from a string. More...
QString	AttributeValue (const QString &sAttributeID) const
	Returns the current value of an attribute as a string. More...
void	LogAttributes (void) const
	Write all attributes into the log file. More...
virtual QWidget *	CreatePropertiesWindow (QWidget *pParent)
	Create a window which displays the attributes of the node. Can be overriden to provide a custom interface. More...
Attribute *	AddAttribute (Attribute::AttributeType type, const QString &id)
	Allows SDK users to add attributes at runtime. More...
Node *	Next (void) const
	Returns the next node in the chain. Used to enumerate the current nodes. See also First(). More...
int	ID (void) const
	Returns an ID for the node. The ID is unique in the whole application life. More...
bool	SetID (int iID)
	Set ID for the node. More...

Protected Member Functions
	Stream (void)
	You cannot create a Stream object directly. Call CreateInstance<Stream>(), then use Stream::Open to specify parameters. More...

Additional Inherited Members
Static Public Member Functions inherited from Node
static void	StartHashing ()
	This is called once in main once static ctors are done. More...
static Node *	First (void)
	This function will return the first node in the memory. Used to enumerate all the current nodes. See also Next(). More...
static Node *	ByID (int iID)
	Returns the node with the specified ID, or zero if such a node does not exists. More...
static Node *	ByName (const QString &sClass, const QString &sName)
	Search for a node with the name sName. More...
Public Attributes inherited from Node
AttributeThisPointer	m_pThis
	DECLARE_CLASS

Member Enumeration Documentation

anonymous enum

Enumerator
chunk

Definition at line 47 of file stream.h.

{ chunk = 0x800000 };

Constructor & Destructor Documentation

Stream ( void  )

protected

You cannot create a Stream object directly. Call CreateInstance<Stream>(), then use Stream::Open to specify parameters.

virtual ~Stream ( void  )

virtual

Destructor.

Member Function Documentation

virtual QString FileName ( void  ) const

virtual

Returns the name of the file.

virtual bool IsValid ( void  )

virtual

Returns true if the stream has a valid version number.

When Mudbox creates a new stream for writing, it gives the stream its version number. Similarly, if a stream is opened for reading, it has a version number. This method checks to see if the number is valid.

The version number can be invalid if there is a problem with the file, or if the file was saved in a newer version of Mudbox, and you are trying to read it into an older version.

virtual bool IsOlderThan ( int  iVersion ) const

virtual

(Deprecated) Checks if the file is older than a specified version.

Returns true if it is.

Typically this method is used during Serialize to handle changes to the file format between versions of the software. This function is deprecated. Use the class specific one with the same name instead.

Parameters

[in]

iVersion

The version number you want to compare

virtual bool IsNewerThan ( int  iVersion ) const

virtual

(Deprecated) Checks if the file is newer than a specified version.

Returns true if it is, false if it is not. Typically this method is used during Serialize() to handle changes to the file format between versions of the software. This function is deprecated. Use the class specific one with the same name instead.

Parameters

[in]

iVersion

The version number you want to compare

virtual int ClassVersion ( const class ClassDesc *  pClass ) const

virtual

Returns the version for a class inside the current stream.

This function returns the version number which was used for a class when the stream was created. If the stream is a storing stream, then this number equals to the current version of the class.

bool IsOlderThan ( int  iVersion, Type *    ) const

inline

Checks if the file is older than a specified version for the given class.

Returns true if it is.

Typically this method is used during Serialize to handle changes to the file format between versions of the software.

Normally, you call this function within your Serialize implementation, something like this:

if ( s.IsOlderThan( 5, this );

In this example the specified version number (5) is a local version number to your class, while the second parameter just identifies the class where you are calling the function. See the macro IMPLEMENT_SCLASS for more details.

Parameters

[in]

iVersion

The version number you want to compare

Definition at line 103 of file stream.h.

                             { return ClassVersion( Type::StaticClass() ) < iVersion; };

bool IsNewerThan ( int  iVersion, Type *    ) const

inline

Checks if the file is newer than a specified version for the given class.

Returns true if it is, false if it is not. Typically this method is used during Serialize() to handle changes to the file format between versions of the software.

Normally, you call this function within your Serialize implementation, something like this:

if ( s.IsNewerThan( 4, this );

In this example the specified version number (4) is a local version number to your class, while the second parameter just identifies the class where you are calling the function. See the macro IMPLEMENT_SCLASS for more details.

Parameters

[in]

iVersion

The version number you want to compare

Definition at line 121 of file stream.h.

                             { return ClassVersion( Type::StaticClass() ) > iVersion; };

virtual bool IsStoring ( void  ) const

virtual

Returns true if the stream is in storing mode (i.e.

writing a file), and false if it is in reading mode.

virtual void SetError ( bool  bError )

virtual

Use this method to inform Mudbox that there is an error in the stream you are trying to read or write.

virtual int Version ( void  ) const

virtual

Returns the version number of the stream.

virtual uint64 CurrentPosition ( void  ) const

virtual

Returns the current position in the file. See also SetCurrentPosition().

virtual void SetCurrentPosition ( uint64  iPosition )

virtual

Sets the current position in the file.

Further calls to the stream will serialize from the new location. You can use this to skip over data in the file that you don't currently need.

Parameters

[in]

iPosition

The byte address to jump to

virtual void ReportCorruption ( void  )

virtual

Call this function from your Serialize implementation, if you detect that the file content is corrupt.

This function will throw an exception, so don't expect it to return. This call basically cancels the serialization of the current node and will try to step to the next one.

virtual void Open ( const QString &  sFileName, bool  bStoring = false, int  iProjectedFileSize = 0, bool  bProgressBar = true  )

virtual

Opens the file attached to this stream.

After creating a Stream object, this is the first function you normally call, which initializes the stream.

Parameters

[in]	sFileName	The name of the file to be opened
[in]	bStoring	Set this to true if you are storing data (i.e. writing the file), and false otherwise
[in]	iProjectedFileSize	If you know how big your file will be, you can optionally specify this argument to help display the status bar correctly
[in]	bProgressBar	If true, a progress bar will be displayed while reading and writing the file.

virtual void Reopen ( bool  bStoring = false )

virtual

Re-opens the file attached to this stream.

Parameters

[in]

bStoring

If true, open the file for writing. If false, open it for reading.

virtual bool Close ( void  )

virtual

Closes the file attached to this stream.

Returns true if the operation succeed.

This function is automatically called when the stream object is deleted. You can call this function directly before destructing the stream object, if you want to know about any corruption during writing, in which case this function returns false.

virtual bool Eof ( void  )

virtual

Returns true if you are reading the file, and you have reached the end of it.

virtual bool ReadContents ( void  )

virtual

This function reads the content of the stream into the memory, when the stream is opened for read.

This function is called automatically when the first pointer is serialized from the stream. You can directly call this function right after opening the stream, if you would like to know if the stream is loaded properly, or corruption was detected.

virtual size_t Read ( void *  pBuffer, size_t  iSize  )

virtual

Reads data directly from the stream into a buffer you provide.

This method returns the number of bytes that were successfully transferred to the buffer. (This number can be different if there is an error, or if you reach the end of the file– IS THIS TRUE?)

Parameters

[in]	pBuffer	A pointer to a block of memory to hold the data
[in]	iSize	The number of bytes to be read

virtual size_t Write ( const void *  pBuffer, size_t  iSize  )

virtual

Writes data to the stream from a buffer you provide.

Returns the number of bytes written.

Parameters

[in]	pBuffer	A pointer to a buffer of data you want to write
[in]	iSize	The number of bytes you want to write

int ReadInt ( void  )

inline

Reads a single integer from the stream, and returns it.

Definition at line 204 of file stream.h.

{ int i=0; operator >>( i ); return i; };

virtual void ReadToFile ( const QString &  sFile )

virtual

Takes the entire contents of the stream and writes it into the specified file.

Parameters

[in]

sFile

The name of the file that you want to store the stream data in

virtual void WriteFromFile ( const QString &  sFile )

virtual

Fills the stream with the content of the specified file.

Parameters

[in]

sFile

The name of the file that you want the stream to get its data from.

Stream& operator>> ( type &  v )

inline

Reads data from the stream to any data type.

Definition at line 219 of file stream.h.

{ MB_VERIFY_EQ( Read( &v, sizeof(type) ), sizeof(type) ); return *this; };

Stream& operator<< ( const type &  v )

inline

Stores any data type into the stream.

Definition at line 223 of file stream.h.

{ MB_VERIFY_EQ( Write( &v, sizeof(type) ), sizeof(type) ); return *this; };

virtual Node* ReadPointer ( void  )

virtual

Read/Writes node pointers.

virtual void WritePointer ( Node *  pPointer )

virtual

Stream& operator>> ( type *&  p )

inline

Reads a pointer from the file.

This function will serialize any pointer whose target is an object whose class was derived from the Node class. Other kind of pointers (like int*) cannot be serialized.

Definition at line 233 of file stream.h.

{ p = dynamic_cast<type *>( ReadPointer() ); return *this; }; 

Stream& operator<< ( type *&  p )

inline

Writes a pointer into the stream.

This function writes a pointer to the stream, if the pointer target is an object whose class was derived from the Node class. Other kind of pointers cannot be serialized.

Definition at line 240 of file stream.h.

{ WritePointer( p ); return *this; };

Stream & operator>> ( Store< type > &  s )

inline

Reads data from the stream to any Store (array) type.

Definition at line 307 of file stream.h.

{ unsigned int iSize; (*this) >> iSize; if ( o.SetItemCount( iSize ) && iSize ) Read( &(o[0]), sizeof(type)*iSize ); RegisterBlock( o.Name(), o.Size(), sizeof(type) ); return *this; };

Stream & operator<< ( const Store< type > &  s )

inline

Writes any store type (array) to the stream.

Definition at line 305 of file stream.h.

{ (*this) << o.ItemCount(); Write( &(o[0]), sizeof(type)*o.ItemCount() ); RegisterBlock( o.Name(), o.Size(), sizeof(type) ); return *this; };

Stream& operator>>

(

QString &

s

)

Read/Writes QString.

Stream& operator<<

(

const QString &

s

)

Stream& operator>> ( QVector< type > &  s )

inline

Reads data from the stream to a QVector object.

This function only works for arrays which contain simple objects only, which means the object has no pointers.

Definition at line 258 of file stream.h.

    {
        int iSize = ReadInt();
        s.resize( iSize );
        Read( s.data(), iSize*sizeof(type) );
        return *this;
    };

Stream& operator<< ( const QVector< type > &  s )

inline

Writes any store type (array) to the stream.

This function only works for arrays which contain simple objects only, which means the object has no pointers.

Definition at line 270 of file stream.h.

    {
        (*this) << s.size();
        Write( s.data(), s.size()*sizeof(type) );
        return *this;
    };

virtual void WriteIntArray ( const Store< unsigned int > &  s )

virtual

virtual void ReadIntArray ( Store< unsigned int > &  s )

virtual

Stream& operator<< ( const Store< unsigned int > &  o )

inline

Definition at line 311 of file stream.h.

{ WriteIntArray(o); return *this; };

Stream& operator>> ( Store< unsigned int > &  o )

inline

Definition at line 314 of file stream.h.

{ ReadIntArray(o); return *this; };

---

The documentation for this class was generated from the following file:

• Mudbox/stream.h