Class AppSave
See Also: Class AppLoad, Class AppDataChunk, Character Strings.
class AppSave
Description:
This class is available in release 2.0 and later only.
This class is a general chunk-ifying code useful for writing hierarchical data structures to a linear stream, such as an AppData block.
All methods of this class are implemented by the system.
AppSave will write hierarchical chunks into a private buffer, enlarging it as needed. When completed, use the methods BufferPtr() and NBytesWritten() to get at this buffer. (AppSave will delete the buffer in its DeleteThis() method , so you need to copy the buffer to save the data.)
The chunk hierarchy should always have a single highest level chunk. Chunks can be nested to any depth.
A Chunk can contain either sub-chunks, or data, but not both.
Sample Code:
AppSave *asave = NewAppSave(1000);
asave->BeginChunk(MAIN_CHUNK);
asave->BeginChunk(CHUNK1);
// .. write data
asave->EndChunk();
asave->BeginChunk(CHUNK2);
// .. write data
asave->EndChunk();
asave->BeginChunk(CHUNK3);
// .. write data
asave->EndChunk();
asave->EndChunk(); // end MAIN_CHUNK
Prototype:
AppSave *NewAppSave(int initBufSize);
Remarks:
This global function create a new AppSave instance.
Parameters:
int initBufSize
Specifies the initial size the internal buffer is allocated to. It will be enlarged if necessary.
Methods:
Prototype:
virtual void DeleteThis()=0;
Remarks:
This method deletes the AppSave instance.
Prototype:
virtual BYTE *BufferPtr()=0;
Remarks:
This method is used after saving to get a pointer to the buffer created.
Prototype:
virtual int NBytesWritten()=0;
Remarks:
This method returns the number of bytes that were written in the buffer.
Prototype:
virtual void BeginChunk(USHORT id)=0;
Remarks:
This method is used to begin a chunk. The ID passed need only be unique within the plug-ins data itself.
Parameters:
USHORT id
The id for the chunk.
Prototype:
virtual void EndChunk()=0;
Remarks:
This method is used to end a chunk, and back-patch the length.
Prototype:
virtual int CurChunkDepth()=0;
Remarks:
This method is used internally for checking balanced BeginChunk/EndChunk.
Prototype:
virtual IOResult Write(const void *buf, ULONG nbytes, ULONG *nwrit)=0;
Remarks:
This method writes a block of bytes.
Parameters:
const void *buf
The buffer to write.
ULONG nbytes
The number of bytes to write.
ULONG *nwrit
The number of bytes actually written.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.
Prototype:
virtual IOResult WriteWString(const char *str)=0;
Remarks:
This method is used to write wide character strings.
Parameters:
const char *str
The string to write.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.
Prototype:
virtual IOResult WriteWString(const wchar_t *str)=0;
Remarks:
This method is used to write wide character strings.
Parameters:
const wchar_t *str
The string to write.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.
Prototype:
virtual IOResult WriteCString(const char *str)=0;
Remarks:
This method is used to write single byte character strings.
Parameters:
const char *str
The string to write.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.
Prototype:
virtual IOResult WriteCString(const wchar_t *str)=0;
Remarks:
This method is used to write single byte character strings.
Parameters:
const wchar_t *str
The string to write.
Return Value:
IO_OK - The write was acceptable - no errors.
IO_ERROR - This is returned if an error occurred.