LArchiveFile

Description Component for maintaining a repository of tagged data blocks residing in a file
Header file LArchiveFile.h
Author Camil Demetrescu and Francesco Mungiguerra
Created Dec 12, 2001
Last updated Sep 7, 2002

 

Contents


Introduction

The component LArchiveFile provides support for maintaing archive files containing a collection of tagged data blocks. Each block has a logical index in the range [0,GetBlocksCount()-1] and is identified by a 32 bit integer tag (ui4 value). When a component LArchiveFile is created, it is associated to a corresponding file on disk. Member functions allow it to add new data blocks, remove existing data blocks, and browse the archive by logical index, retrieving block tag, and reading block data in the form of an LXPBlock object. Created archive file are written according to format described in archive file format. When the fragmentation of an archive file gets too high, the file is automatically compacted.


Interface

Constants

LArchiveFile_ID
LArchiveFile_MAGIC_NUMBER
LArchiveFile_VERSION
    
LArchiveFile_READ
LArchiveFile_WRITE
LArchiveFile_READ_WRITE
    
LArchiveFile_ILLEGAL_FILE_TYPE
LArchiveFile_CANT_OPEN_FILE
LArchiveFile_DAMAGED_FILE
LArchiveFile_NEWER_FILE_VERSION
LArchiveFile_IO_ERROR
LArchiveFile_OUT_OF_RANGE
LArchiveFile_READ_ONLY_ACCESS
LArchiveFile_WRITE_ONLY_ACCESS

Types

LArchiveFile
LArchiveFile_TOpenMode

Functions

LArchiveFile*   LArchiveFile_Open           (const i1* inFileName, LArchiveFile_TOpenMode inMode);
void            LArchiveFile_Close          (LArchiveFile** ThisA);

ui4             LArchiveFile_AddBlock       (LArchiveFile* This, ui4 inBlockTag, LXPBlock* inTagBlock);
void            LArchiveFile_RemoveBlock    (LArchiveFile* This, ui4 inBlockIdx); 

ui4             LArchiveFile_GetBlockTag    (LArchiveFile* This, ui4 inBlockIdx);
LXPBlock*       LArchiveFile_GetXPBlock     (LArchiveFile* This, ui4 inBlockIdx);
ui4             LArchiveFile_GetBlocksCount (LArchiveFile* This);


API Reference

Function Arguments Description Returns Throws
Open const i1* inFileName

Open archive file specified by the pathname inFileName. The created object provides access to the open file.The behavior is the following:

  READ WRITE READ_WRITE
File exists Provide access to the file. Throw ILLEGAL_FILE_TYPE if file has illegal magic number. Create empty archive file. Overwrite existing file.

Provide access to the file. Blocks can be added/removed. Throw ILLEGAL_FILE_TYPE if file has illegal magic number.

File does not exist Throw CANT_OPEN_FILE exception. Create empty archive file and provide access to it. Create empty archive file.

Caller is responsible of dellocating the created object using LArchiveFile_Close.

LArchiveFile*

Pointer to newly created object.

CANT_OPEN_FILE if disk operation fails.

ILLEGAL_FILE_TYPE if the file already exists, but has illegal magic number, and inMode==READ or inMode==READ_WRITE.

DAMAGED_FILE if archive fileinFileName is valid, but the file appears to be damaged.

NEWER_FILE_VERSION if archive fileinFileName has been created by an earlier version of the program.

TOpenMode inMode
Close LArchiveFile** ThisA Close the file associated to the object *ThisA. Release object memory. Compact archive if fragmentation gets too high. *ThisA is set to NULL. void -
AddBlock LArchiveFile* This Add to archive This new block with tag inBlockTag, and associated data inBlock.

ui4

index of new block

IO_ERROR if disk operation fails.

READ_ONLY_ACCESS if archive file is open in read only mode.

ui4 inBlockTag
LXPBlock* inBlock
RemoveBlock LArchiveFile* This Remove block with index inBlockIdx from archive file This. inTagIdx must be in the range [0, GetTagsCount()-1]. void OUT_OF_RANGE if index inBlockIdx is out of range.
ui4 inTagIdx
GetBlockTag LArchiveFile* This

Get tag of block with index inBlockIdx in archive This.inBlockIdx must be in the range [0, GetBlocksCount()-1].

ui4

Tag of the block with index inBlockIdx in the archive file.

OUT_OF_RANGE if index inBlockIdx is out of range.
ui4 inBlockIdx
GetXPBlock LArchiveFile* This Create new LXPBlock object starting from data in the tag with index inBlockIdx in archive This. The block should be deallocated by the caller. inBlockIdx must be in the range [0, GetTagsCount()-1]. Caller is responsible of deallocating the created LXPBlock object using LXPBlock_Delete.

LXPBlock*

Pointer to the newly created LXPBlock.

OUT_OF_MEMORY if memory allocation fails.

OUT_OF_RANGE if index inBlockIdx is out of range.

ui4 inBlockIdx
GetBlocksCount LArchiveFile* This -

ui4

Number of blocks in the archive file.

-


Archive file format

In this section we describe the format of archive files created by component LArchiveFile.

Section Size Offset Type Short description Notes
Header 10 0

ui4

Magic number 0x4C4E4456 Tag for file type identification (sequence of ASCII characters 'L', 'N', 'D', 'V', equal to LArchiveFile_MAGIC_NUMBER)
4 ui2 Version Version number of the format (equal to LArchiveFile_VERSION)
6 ui4 First block offset o1 Offset of the first block in the list of blocks (zero if archive file is empty)
... ... ... ... ... ...
Block
#1
4 o1 ui4 Block tag Tag number
4 ui4 Next block offset o2 Offset of the next block in the list of blocks (zero if last block)
4 ui4 Block size k1 Size in bytes of the block data
k1 ... Block data -
... ... ... ... ... ...
Block
#i
4 oi ui4 Block tag Tag number
4 ui4 Next block offset oi+1 Offset of the next block in the list of blocks (zero if last block)
4 ui4 Block size ki Size in bytes of the block data
ki ... Block data -


Revision history