Overview |
Topics |
|
The VBD file manager class is responsible for handling all low-level file operations through the use of VBD file manager objects or by inheriting the VBD file manager class. Low-level file operations refer to functions such as: Create(), Open(), Read(), Write(), Alloc(), Delete(), and Close(). These functions contain all the routines needed to create and maintain VBD files in accordance with the VBD File Format.
Reference Counting:
VBD file manager objects are reference counted and must be created dynamically due to the way reference counting is implemented. Reference counting is a technique used to ensure the safe deletion or modification of an object. It works by storing a reference count with each object. Each time the object is used (referenced) by some other entity the counter is incremented. When the entity is finished with the object the counter is decremented. When the counter goes to zero, it means that no entities are referencing the object, so it can be safely deleted. Reference counting was implemented to ensure that only one copy of an object exists before closing an open file.
There are two versions of the Reference Count Class. A template class that can be used with any other data type is provided as part of the class library. In order to avoid any portability issues with template classes, a non-template version is provided with the VBD file manager. The template version will be used by default. Define the __USE_VBDREFCOUNT__ macro and the __NOT_USING_TEMPLATE_CLASS__ macro at compile time to disable the template version and use the VBD file manager's version.
Platform Independence:
VBD files created with the file manager class gain their platform independence by using INT32 class objects to represent file addresses. The INT32 class can produce platform independent 32-bit signed integers by manipulating long integer values in memory. It works by separating a 32-bit value into four separate byte values and reordering the bytes lowest-order to highest-order.
Exception Handling:
Two forms of exception handling are implemented in the file manager class. A global exception handler or C++ exceptions, denoted by the keyword throw, can be selected with the use of a pre-processor directive. Define the CPP_EXCEPTIONS macro at compile time to enable C++ exception handling. For more information see Exceptions and the EHandler class. If a program error occurs during a file operation and C++ exception handling is disabled, the global exception handler will flag you with an error message and terminate the program if necessary. If C++ exception handling is enabled and a program error occurs during a file operation, the function will throw an exception. The appropriate try and catch statements within the application must handle the exceptions or the program will terminate.
Several type definitions are used to create synonyms for existing types. Most of the type definitions are defined as part of the Platform Independent Data Types library. These type definitions are used to maintain compatibility between the size of built-in data types on various compilers. The VBD file manager uses several type definitions to clarify the meaning of the type being used:
typedef vbdRefCount VBDFilePtr - This type definition is used to dynamically create reference counted VBD file manager objects with the VBD file manager's version of the reference count class. NOTE: The __USE_VBDREFCOUNT__ macro and the __NOT_USING_TEMPLATE_CLASS__ macro must be defined at compile time to use this type definition.
typedef RefCount
typedef INT32 FAU - The File Address Unit type definition is used to create a synonym for the INT32 class. This type definition was created to separate file addresses from regular data. If a function returns an FAU or takes an FAU as an argument, you know that you're dealing with a file address.
typedef __LWORD__ StreamPos - This type definition is used to indicate the current position in the file stream.
typedef __UINT32__ vbChecksum - This type definition is used when calculating CRC-32 checksums used to detect bit errors.
The FileHeader data structure is used to represent the VBD file header in accordance with the VBD File Format.
struct FileHeader // VBD file header information (28 bytes total)
{
FAU FreeSpace; // First block of de-allocated heap space
FAU EndOfFile; // Address of the last byte in the file
FAU HeapStart; // Start of the dynamic storage area
FAU HighestVB; // Highest allocated block
__SBYTE__ Signature[8]; // Used to identify the file type
INT32 Version; // Used to identify the file version number
};
Free space field:
The "free space" pointer is used by the allocation function to reclaim deleted blocks. The number of deleted blocks is maintained in a non-contiguous list. Each block in the list points to the next block in the list starting at a specified address. The "free space" pointer is used to store the file address of the block where the list starts. In order to prevent VBD files from becoming extremely fragmented due to numerous deletions, blocks marked deleted or removed will be reused by the allocation function. The file manager's allocation function checks the "free space" field before allocating any blocks. If the "free space" field is not empty, the allocation function will walk through the free space list looking for a deleted or removed variable block of the size to be allocated. This includes the size of the block data plus the block header. One of two methods can be used to reclaim deleted or removed blocks, the best-fit method or the first-fit method. The best-fit method works by scanning the entire free space list until the best location to reuse a block is found. The first-fit method works by searching the free space list until the first block of the appropriate size is found. Both methods will reuse any unused portion of a reclaimed block. The unused portion is assigned a new block header (marked removed) and placed back on the free space list. NOTE: If the free space list becomes corrupt, the "free space" field will be marked corrupt by the FSListCorrupt integer constant and no longer be used.
End of file field:
The "end of file" pointer is used to mark the end of the file and locate where the file can be extended during block allocation. When an existing file is opened the file manager will compare this field to the true end of file. If the values do not match, this pointer will be adjusted if possible.
Start of heap field:
The "start of heap" pointer is used to store the address where the static storage area ends and the dynamic data area begins. The allocation of new blocks will always start at this address. The size of the static storage area is determined when the file is created. Any data stored in the static area will not be affected by any of the allocation routines.
Highest block field:
The "highest block" pointer is used to store the address of the highest allocated variable block. This ensures that the file manager will always know where the first and last blocks are located in the file.
Signature field:
The signature field is used to determine if the file is of the correct type when an existing file is opened. When a new file is created the VBD file manager writes the "VBDFILE" string to this field. The eighth byte is used for all revision changes. Version 1027 sets the revision letter to 'A' and performs a compatibility checks to ensure backward compatibility with previous releases. Revision 'A' adds a 32-bit CRC checksum routine and reserves space at the end of each block for an application to write 32-bit check-word.
Version field:
A version number is used to indicate that changes have been made to the file manager class itself. Version numbers are used to conditionally perform certain operations based on its numerical value. This will ensure backward compatibility with previous versions of the file manager class.
The VBD file manger stores a Variable Block (VB) header with each variable block that is allocated by the application. VB headers are used to keep track of the data blocks stored in the file. Applications can also use VB header info to obtain file locations and status information of its file data. When new blocks are allocated the file manager writes the block header and then reserves enough space to store the number of bytes requested. The application is responsible for writing the actual data in the block starting at the address immediately following the block header. The VBHeader data structure is used to represent variable block headers in accordance with the VBD File Format.
struct VBHeader // Marks each variable data block (16 bytes total)
{
UINT32 CkWord; // Check word for file integrity checks
UINT32 Length; // Block Length (Header + Object + CRC)
UINT32 Status; // Status of the data stored in this block
FAU NextDeletedVB; // Pointer to next deleted block
};
Check word field:
The "check word" field represents a 32-bit check word used for file integrity checks and to maintain synchronization between the file manager and the application. The VBD file manager sets the check word field to 0x00000FEFE using an UINT32 constant named CheckWord. Revision 'A' uses all 32 bits of the block check-word. In previous releases the upper 16 bits of the block check-word was reserved for a 16-bit CRC. Revision 'A' implements a 32-bit CRC routine and reserves four bytes at the end of each block for a 32-bit checksum. NOTE: If the check word value is changed, the file will no longer be compatible with previous releases.
Length field:
The "length" field stores the length of the object plus the size of the block header and the size of the block's CRC checksum value. The file manager uses this field to index the file block by block. The "check-word" field is used to ensure that the next block in sequence is a valid variable block. The length of the object can be calculated by subtracting the size of the block header and the size of the CRC checksum from the "length" field.
Status field:
The "status" field stores the status of the dynamic data in a block. Only one byte of the status field is used. The remaining three bytes of the status field is reserved for future use. The status of a variable data block can be determined by one of three byte values: 'N' for normal (ASCII 78), 'D' for deleted (ASCII 68), or 'R' for removed (ASCII 82.) The VBD file manager uses a signed byte constant named NormalVB to mark normal blocks, DeletedVB to mark deleted blocks, and RemovedVB to mark removed blocks. A block marked 'N' for normal indicates that the block is in use and cannot be reclaimed by the allocation function. A block marked 'D' for deleted means that the data in the block is still valid, but the block can be overwritten if needed. A block marked 'R' for removed means that the data in the block has been removed and the block can be overwritten. Once a block is removed it can never be restored. Marking them 'N' for normal can restore deleted blocks.
Next deleted block field:
The "next deleted block" pointer stores a pointer to the next deleted or removed variable block, only if this block has been deleted or removed. The total number of deleted blocks is maintained in a non-contiguous list. Each deleted or removed block in the list points to the next deleted or removed block in the list starting at the head of the list. The "free space" pointer in the VBD file header is used to store the file address where the head of the free space list is located. When a variable block is deleted or removed the next deleted block field is set to the VBD header's "free space" value to become the head of the free space list and the VBD header's "free space" pointer is set to the address of this deleted or remove block.
VBDFile::VBDFile
VBDFile::~VBDFile
VBDFile::Alloc
VBDFile::BlindOpen
VBDFile::CalcChecksum
VBDFile::ClearErr
VBDFile::Close
VBDFile::Create
VBDFile::Delete
VBDFile::Exists
VBDFile::FileHeaderSize
VBDFile::FilePosition
VBDFile::FileSize
VBDFile::FindFirstObject
VBDFile::FindFirstVB
VBDFile::FindNextObject
VBDFile::FindNextVB
VBDFile::Flush
VBDFile::GetEOF
VBDFile::GetFileStatus
VBDFile::GetFreeSpace
VBDFile::GetHeapStart
VBDFile::GetHighestVB
VBDFile::GetPosition
VBDFile::GetRevLetter
VBDFile::GetSignature
VBDFile::GetVBDFreeSpace
VBDFile::GetVersion
VBDFile::InitHdr
VBDFile::IsOK
VBDFile::IsOpen
VBDFile::ObjectLength
VBDFile::Open
VBDFile::Reclaim
VBDFile::ReadyForWriting
VBDFile::ReAlloc
VBDFile::Read
VBDFile::ReadOnly
VBDFile::ReadHdr
VBDFile::ReadVBHdr
VBDFile::ReadObjectChecksum
VBDFile::ReOpen
VBDFile::Rewind
VBDFile::Remove
VBDFile::Seek
VBDFile::SeekTo
VBDFile::SetPosition
VBDFile::StaticArea
VBDFile::TestVBDHeader
VBDFile::UnDelete
VBDFile::VBDeleted
VBDFile::VBDFileName
VBDFile::VBHeaderSize
VBDFile::VBLength
VBDFile::VBSearch
VBDFile::VBTotal
VBDFile::Write
VBDFile::WriteHdr
VBDFile::WriteObjectChecksum
VBDFile::WriteVBHdr
VBDFile::VBDFile() - Class constructor used to create a file object with a reference count of one.
VBDFile::~VBDFile() - Virtual class destructor responsible for closing the open file and flushing any disk buffers.
virtual int VBDFile::Create(const char *FName, FAU StaticSize = 0) - Virtual public member function that creates a new file named FName, overwriting it if it already exists. The StaticSize specifies the number of bytes to reserve for the static data. By default, no static area is created.
Exceptions, if not overridden in a derived class:
CFileCreationError
CEOFError
CFileWriteError
CFileNotWriteable
CDanglingPtr
CFileCloseError
CFileSeekError
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
virtual int VBDFile::Open(const char *FName, AccessMode Mode = READWRITE) - Virtual public member function that opens the FName file. The Mode can be set to either VBDFile::READWRITE or VBDFile::READONLY. The integer constants for the access modes are set in the VBDFile::AccessMode enumeration. The file's revision letter will be recorded each time the file is opened.
Exceptions, if not overridden in a derived class:
CFileOpenError
CWrongFileType
CAccessViolation
CFileReadError
CFileNotReady
CDanglingPtr
CFileCloseError
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable
CChecksumError
virtual void VBDFile::Close(int flush = 1) - Virtual public member function that closes the file if it is not already closed. By default, the file header and all internal buffers will be flushed to disk. This function does nothing if it detects an error state.
Exceptions, if not overridden in a derived class:
CDanglingPtr
CFileCloseError
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
virtual void VBDFile::Flush() - Virtual public member function used to write the file header to disk, and then flush any internal buffers the file might have.
Exceptions, if not overridden in a derived class:
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
FAU VBDFile::Alloc(unsigned Bytes) - Public member function used to allocate a variable block of the specified number of bytes from either the free space list or the end of the file. The number of bytes allocated is adjusted to hold a block header plus the data. Revision 'A' reserves four bytes at the end of the block to allow the application to store a 32-bit checksum with each block. Only the block header is written to the allocated space. The application is responsible for writing the data to the block at the file address returned by this function and for maintaining the optional 32-bit checksum. This function will return a zero if an allocation error occurs. NOTE: Version 1027 will position the file pointer to the file address where the next write operation should take place after allocating space for the object.
Exceptions:
CEOFError
CFileWriteError
CFileNotWriteable
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
CChecksumError
FAU VBDFile::ReAlloc(FAU Address, unsigned Bytes) - Public member function used to reallocate a specified number of bytes from either the free space list or the end of the file. This function returns the location of the space reallocated for the data, or returns a zero if an error occurred.
Exceptions:
CEOFError
CFileWriteError
CFileNotWriteable
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
CChecksumError
int VBDFile::Delete(FAU Address) - Public member function used to mark a block at the specified address deleted and leave the object unchanged, allowing it to be undeleted. The deleted block is placed at the front of the free space list. Return true if successful or returns false if an error occurred.
Exceptions:
CSyncError
CAccessViolation
CFileReadError
CFileNotReady
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CChecksumError
int VBDFile::Remove(FAU Address, int mem_alloc = 1) - Public member function used to delete a block at the specified address and permanently remove the data by setting all its bytes to zero. The block is marked removed, indicating that the data cannot be undeleted. Returns true if successful or returns false if an error occurred. If the mem_alloc variable is true, a buffer equal to the object length of the object will be created in memory. If the mem_alloc variable is false or memory allocation fails, a single byte value equal to zero, is written to the file byte by byte for the length of the object.
Exceptions:
CSyncError
CAccessViolation
CFileReadError
CFileNotReady
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CChecksumError
void VBDFile::Read(void *buf, unsigned Bytes, FAU Address = CurrAddress) - Public member function used to read a specified number of bytes, at a specified address, into a memory buffer. A read will start at the current stream position by default or from the beginning of the file if a file address is specified.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
void VBDFile::Write(const void *buf, unsigned Bytes, FAU Address = CurrAddress, int flush = 1, int bit_test = 1) - Public member function used to write a specified number of bytes, starting at a specified address, from a memory buffer. A write will start at the current stream position by default or from the beginning of the file if a file address is specified. If flush equals one, the file buffers will be flushed to disk with each write operation. If bit_test equals one, the CRC of the of the buffer will be compared to the CRC of the actual bytes written to disk.
Exceptions:
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
void VBDFile::Seek(FAU Offset, int SeekMode = SEEK_SET) - Public member function used to move the file pointer to a specified offset, using SeekMode, which should be either SEEK_SET, SEEK_CUR, or SEEK_END.
Exceptions:
CFileSeekError
CFileNotReady
int VBDFile::IsOpen() const - Public member function that returns true if the file is open.
int VBDFile::ReadOnly() const - Public member function that returns true if the file is open for reading only.
int VBDFile::ReadyForWriting() const - Public member function that returns true if the file is ready for writing.
int VBDFile::IsOK() const - Public member function that returns true if the file status is good.
void VBDFile::ClearErr() - Public member function used to clear any file errors.
unsigned VBDFile::ObjectLength(FAU Address) - Public member function that returns the object's length, in bytes, at a specified address.
Exceptions:
CSyncError
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
unsigned VBDFile::VBLength(FAU Address) - Public member function that returns the total length of a block, in bytes, at a specified address. The total length refers to the size of the block header plus the block data.
Exceptions:
CSyncError
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
StreamPos FilePosition() - Public member function that returns the current file position.
Exceptions:
CFileNotReady
char *VBDFile::GetSignature() - Public member function that returns the file signature stored in the file header.
const char *VBDFile::GetSignature() const - Public member function that returns the file signature stored in the file header.
INT32 VBDFile::GetVersion() - Public member function that returns the file version number stored in the file header.
INT32 VBDFile::GetVersion() const - Public member function that returns the file version number stored in the file header.
size_t VBDFile::FileHeaderSize() - Public member function that returns the size of the file header.
size_t VBDFile::FileHeaderSize() const - Public member function that returns the size of the file header.
size_t VBDFile::VBHeaderSize() - Public member function that returns the size of the block header.
size_t VBDFile::VBHeaderSize() const - Public member function that returns the size of the block header.
char *VBDFile::VBDFileName() - Public member function that returns the name of the open file.
const char *VBDFile::VBDFileName() const - Public member function that returns the name of the open file.
__SBYTE__ VBDFile::GetFileStatus() - Public member function that returns the file status byte.
__SBYTE__ VBDFile::GetFileStatus() const - Public member function that returns the file status byte.
__LWORD__ VBDFile::StaticArea() - Public member that returns the size of the pre-allocated static data area.
Exceptions:
CSyncError
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::Reclaim(unsigned Bytes) - Protected member function used by the VBDFile::Alloc() to find the first block on the free space list big enough to hold the data and two block headers. Define the __RECLAIM_BEST_FIT__ macro at compile time to use the best-fit method of reclaiming unused blocks or the __RECLAIM_FIRST_FIT__ macro to use the first-fit method. If neither macro is defined, the first-fit method is used by default. This function returns the address of the reclaimed space, or zero if a free block of the appropriate size was not found or the free space list is corrupt. NOTE: The byte size is adjusted by the VBDFile::Alloc() function to allocate space for the block header plus the data and the block CRC.
Exceptions:
CSyncError
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable
CChecksumError
void VBDFile::InitHdr() - Protected member function used to setup the header area of the file. If there is any statically allocated data beyond the header when a new file is created, a zero is stored at the end of the static data area to avoid any unexpected "end of file" exceptions. The file's revision letter will be recorded each time this function is called.
Exceptions:
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
void VBDFile::WriteHdr() - Protected member function used to write the file header to the open file.
Exceptions:
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
void VBDFile::ReadVBHdr(VBHeader &hdr, FAU Address) - Protected member function used to read a block header at the specified address. This function will test the block's check word to ensure that the file manager is still in sync with the open file, and that none of the variable blocks are corrupt.
Exceptions:
CSyncError
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
void VBDFile::WriteVBHdr(const VBHeader &hdr, FAU Address) - Protected member function used to write a block header at the specified address.
Exceptions:
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
void VBDFile::ReadHdr() - Public member function used to read a VBD file header from the open file.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
virtual int VBDFile::BlindOpen(const char *FName, AccessMode Mode = READONLY) - Virtual public member function used to open the FName file without checking the file type.
Exceptions, if not overridden in a derived class:
CFileOpenError
CAccessViolation
CFileReadError
CFileNotReady
CDanglingPtr
CFileCloseError
CFileSeekError
FAU VBDFile::VBSearch(FAU Offset = 0) - Public member used to search the file until a valid block is found. The search starts at the beginning of the file or the offset value. This function returns the address of the first block found or zero if no valid blocks are found.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::GetFreeSpace() - Public member function that returns the file address to the head of the free space list. This function returns zero if no blocks have been deleted or removed.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::GetVBDFreeSpace() - Public member function that returns the file address to the head of the free space list. This function returns zero if no blocks have been deleted or removed. Same as the VBDFile::GetFreeSpace() function.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::GetEOF() - Public member function that returns the "end of file" marker stored in the file header.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::GetHeapStart() - Public member function that returns the file address where the dynamic data area starts.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::GetHighestVB() - Public member function that returns the file address of the highest allocated block.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
int VBDFile::TestVBDHeader() - Public member function used to ensure that the in-memory copy of the file header and the disk copy stay in sync during multiple file access. This function will return zero if no errors are found, or return the number of errors encountered during the test. If any errors are encountered the file header will be re-read from disk.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
unsigned VBDFile::VBDeleted(__UWORD__ *d = 0, __UWORD__ *r = 0) - Public member function that returns the total number of removed and deleted blocks and passes back the number of delete and removed blocks in the "d" and "r" variables.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
unsigned VBDFile::VBTotal() - Public member function that returns the total number of normal, deleted, and removed blocks.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::FindFirstVB(FAU Offset = 0) - Public member function used to search through the file until a valid block is found. The search begins at the heap start or the offset value. This function will return zero if no valid blocks are found.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::FindNextVB(FAU Offset = 0) - Public member function used to search through the file until the next valid block after the first valid block is found. The search begins at the heap start or the offset value. This function will return zero if no valid blocks are found.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::FindFirstObject(FAU Offset = 0) - Public member function used to search through the file until a valid block is found and then return the object's address. If the block is marked deleted or removed, this function will continue searching until the first normal block is found. The search begins starts at the heap start or the offset value. This function will return zero if no valid blocks are found.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
FAU VBDFile::FindNextObject(FAU Offset = 0) - Public member function used to search through the file until the next valid block after the first valid block is found and then return the object's address. If the block is marked deleted or removed, this function will continue searching until the next normal block is found. The search begins at the heap start or the offset value. This function will return zero if no valid blocks are found.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
static int VBDFile::Exists(const char *FName) - Static public member function that returns true if the file FName exists.
static __LWORD__ VBDFile::FileSize(const char *FName) - Static public member function used to obtain the size of file FName. This function is used after the file has been closed and reopened to ensure that all the memory buffers were flushed to disk.
__ULWORD__ VBDFile::CalcChecksum(__UWORD__ Bytes, FAU Address, int mem_alloc = 1) - Calculate a 32-bit CRC checksum base on the Ethernet polynomial of 0x4C11DB7 for a given number of bytes starting at the specified address. Returns a 32-bit CRC value. If the mem_alloc variable is true, a buffer equal to the specified number of bytes will be created in memory. If the mem_alloc variable is false or memory allocation fails, the CRC will be calculated byte by byte starting at the specified address.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
fpos_t VBDFile::GetPosition() - Returns the current value of the file-position indicator. The VBDFile::SetPosition() function can later use information to reset the file pointer to its position at the time VBDFile::GetPosition() was called. The fpos_t type is an internal format and is intended for use only by the GetPosition() and SetPosition() functions to record information for uniquely specifying positions within a file.
Exceptions:
CFileSeekError
CFileNotReady
char VBDFile::GetRevLetter() - Returns the current VBD file revision letter which will be used to perform compatibility checks to ensure backward compatibility with previous releases.
int VBDFile::ReadObjectChecksum(FAU Address, __ULWORD__ *object_crc = 0, __ULWORD__ *calc_crc = 0) - Used by an application to test the object's CRC value stored on disk against the actual CRC of the bytes stored on disk. The Address variable must be set to the file address of the block data, not the block header. This function assumes that the data has already been written to the block. Returns true if the object's CRC test good or false if the CRC tests bad. Passes back the object's CRC stored on disk in the object_crc variable and the calculated CRC value in the calc_crc variable.
Exceptions:
CAccessViolation
CFileReadError
CFileNotReady
CFileSeekError
virtual int VBDFile::ReOpen(const char *FName, AccessMode Mode = READWRITE) - Reopens the FName file. File must exist and be a VBD file type or an exception will occur. This function will check the revsion letter when reopening an existing file.
Exceptions, if not overridden in a derived class:
CFileOpenError
CWrongFileType
CAccessViolation
CFileReadError
CFileNotReady
CDanglingPtr
CFileCloseError
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CChecksumError
void VBDFile::Rewind() - Repositions the file pointer to the beginning of the file.
FAU VBDFile::SeekTo(FAU Address) - Seek to the specified address, optimizing the seek operation by moving the file position indicator based on the current stream position. Returns the current file position after performing the seek operation.
Exceptions:
CFileSeekError
CFileNotReady
void VBDFile::SetPosition(const fpos_t fpos) - Returns the current value of the file-position indicator. The VBDFile::SetPosition() function can later use information to reset the file pointer to its position at the time VBDFile::GetPosition() was called. The fpos_t type is an internal format and is intended for use only by the GetPosition() and SetPosition() functions to record information for uniquely specifying positions within a file.
Exceptions:
CFileSeekError
CFileNotReady
UINT32 VBDFile::WriteObjectChecksum(FAU Address) - Used to by an application to write a 32-bit checksum for the object at the end of a block. The Address variable must be set to the file address of the block data, not the block header. This function assumes that the data has already been written to the block. Returns the 32-bit CRC checksum value for the object stored in the block.
Exceptions:
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
int VBDFile::UnDelete(FAU Address) - Undeletes the block if it has not been removed or reclaimed.
Exceptions:
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CChecksumError
CAccessViolation
CFileReadError
CFileNotReady
CSyncError
The VBD file manager's member functions can throw any of the following exceptions if the CPP_EXCEPTIONS macro is defined in the EHandler class at compile time. NOTE: The appropriate try and catch statements within the application must handle each exception or the program will terminate. Derived classes that override any of the file manager's virtual functions must handle any file I/O exceptions in its version of that function. If the CPP_EXCEPTIONS macro is not defined, the global error hander will signal that an exception has occurred and will terminate the program as defined in the Ehandler::Terminate() function.
CAccessViolation - this exception is thrown if an "end of file" error occurs during multiple file access. This exception was added to tell the application that the file has grown in size but the EOF marker has not.
CDanglingPtr - this exception is thrown if there are any dangling references to a reference counted pointer, indicating that a copy of this object is still being used by another object.
CEOFError - this exception is thrown if an "end of file" error is encountered.
CFileCloseError - this exception is thrown if the file cannot be closed.
CFileCreationError - this exception is thrown if the file cannot be created.
CFileNotReady - this exception is thrown if the file is not ready for reading.
CFileNotWriteable - this exception is thrown if the file cannot be written to.
CFileOpenError - this exception is thrown if the file cannot be opened because it does not exist or cannot be accessed in the specified file access mode.
CFileReadError - this exception is thrown if an error occurs while reading from the file.
CFileSeekError - this exception is thrown if an error is encountered during a seek operation.
CFileWriteError - this exception is thrown if the number of bytes written do not match the number of bytes requested to write.
CSyncError - this exception is thrown if the block header's check word cannot be read. This indicates a file synchronization error, meaning the file manager is not reading a valid block or the block is corrupt.
CWrongFileType - this exception is thrown if the file is not a VBD file type or the header is damaged and cannot be identified by the signature string stored in the file header.
CChecksumError - this exception is thrown if a bit error occurs when writing to disk. A 32-bit CRC checksum based on the Ethernet polynomial of 0x4C11DB7 is calculated when any data is written to the VBD file. The calculated checksum is then compared to data actually stored on disk. If the calculated checksum does not match the actual checksum, a bit error has occurred during data storage. All bit errors must be handled by the application since the type of data being stored is not known.