A parser for VHIST files. More...

#include <vhistparser.h>

Inheritance diagram for vhist::VhistParser:

Public Member Functions
	VhistParser (ParseMode mode=MODE_ROBUST, QObject *pLogTarget=NULL)
	Creates a new parser for VHIST files.
virtual	~VhistParser ()
	Destroys a VHIST parser instance.
bool	open (const QString &filename)
	Opens a VHIST file and parses it.
SectionTagList	getSections ()
	Returns a list of all sections in the current VHIST file.
int	getNumSections ()
	Returns the number of sections in the current VHIST file.
FileTagList	getFiles ()
	Returns a list of all embedded files in the current VHIST file.
int	getNumFiles ()
	Returns the number of embedded files in the current VHIST file.
FileTagList	getFilesInSection (int sectionId)
	Returns a list of embedded files which are part of a specific section.
FileTagList	getSectionlessFiles ()
	Returns a list of embedded files, which are not part of any section.
MaybeSectionTag	getSection (int id)
	Returns the section with the given id.
MaybeFileTag	getFile (int id)
	Returnes the embedded file with the given id.
MaybeBytes	getFileContent (int id)
	Returns the content of a given embedded file.
bool	writeFileToDisk (int id, const QString &filename)
	Writes an embedded file from the current VHIST file to harddisk.
MD5Sums	calcChecksumsForFile (int id)
	Calculates the MD5 checksum for an embedded file.
QByteArray	getBytes (int startPos, int numBytes)
	Returns a part of the current VHIST file.

Detailed Description

A parser for VHIST files.

The parser can read all embedded files and sections in a time and memory efficient way, extract embedded files from the VHIST file and calculate checksums for them. The progress of the parsing and occuring errors are published via the log signal.

Examples:: parse_example1.cpp.

Constructor & Destructor Documentation

VhistParser::VhistParser	(	ParseMode	mode = `MODE_ROBUST`,
		QObject *	pLogTarget = `NULL`
	)

Creates a new parser for VHIST files.

Parameters:

[in]	mode	Specifies whether the parser should follow the vhist spec strictly or provide more robust parsing.
[in]	pLogTarget	An optional object with a void log(const QString, const vhist::LogType) slot. The parser will send it's output to this object.

Member Function Documentation

MD5Sums VhistParser::calcChecksumsForFile ( int id )

Calculates the MD5 checksum for an embedded file.

The method will calculate a pair of checksums, one checksum for the compressed and one for the uncompressed data. If the embedded file has not been compressed, the compressed MD5 will be empty. The checksums are returned as hex digests. In the case of an error, 2 empty checksums are returned.

Parameters:

[in] id The id of the embedded file, for which the checksums should be calculated.

Returns:: The checksums for the specified file.

Warning:: The method will load the complete file into memory at once. For large files, this is not a good idea. Additionally, the function will block until the checksums have been calculated. For more sophisticated purposes, using vhist::ValidationQueue is the better alternative.

See also:: vhist::ValidationQueue

QByteArray VhistParser::getBytes	(	int	startPos,
		int	numBytes
	)

Returns a part of the current VHIST file.

If the bytes could not be read, an array of length 0 is returned.

Parameters:

[in]	startPos	The index of the first byte, which is returned.
[in]	numBytes	The number of bytes to return.

Returns:: A bytearray containing the requested bytes.

MaybeFileTag VhistParser::getFile ( int id )

Returnes the embedded file with the given id.

If the id is not valid or no VHIST file is currently opened, a NULL pointer if returned.

Parameters:

[in] id The id of the requested file.

Returns:: The requested embedded file or NULL if and error occured.

MaybeBytes VhistParser::getFileContent ( int id )

Returns the content of a given embedded file.

The content is returned as a QByteArray. If the file is compressed, it is automatically inflated. In the case of an error, a NULL pointer is returned. This way, it's clear if the retrieval of a 0 bytes large file succeeded or failed.

Parameters:

[in] id The id of the requested file.

Returns:: The content of the requested file on success or a NULL pointer if an error occured.

FileTagList VhistParser::getFiles ( )

Returns a list of all embedded files in the current VHIST file.

Returns:: A list of all embedded files.

Examples:: parse_example1.cpp.

FileTagList VhistParser::getFilesInSection ( int sectionId )

Returns a list of embedded files which are part of a specific section.

If no VHIST file is currently open or the section does not exist, an empty list is returned.

Parameters:

[in] sectionId The id of the section, which's files should be returned.

Returns:: A list of all embedded files inside the given section.

int VhistParser::getNumFiles ( )

Returns the number of embedded files in the current VHIST file.

Returns:: The number of embedded files.

int VhistParser::getNumSections ( )

Returns the number of sections in the current VHIST file.

Returns:: The number of sections.

MaybeSectionTag VhistParser::getSection ( int id )

Returns the section with the given id.

If the id is not valid or no VHIST file is currently opened, a NULL pointer is returned.

Parameters:

[in] id The id of the section, which should be returned.

Returns:: The requested section or NULL if an error occured.

FileTagList VhistParser::getSectionlessFiles ( )

Returns a list of embedded files, which are not part of any section.

Note:: Sectionless files are not valid according to the VHIST standard, they may, however, appear in VHIST files, which are slightly corrupted.

Returns:: A list of all embedded sectionless files.

SectionTagList VhistParser::getSections ( )

Returns a list of all sections in the current VHIST file.

If no file has been opened yet or if opening and parsing the last VHIST file failed, an empty list is returned.

Returns:: A list of all sections.

Examples:: parse_example1.cpp.

bool VhistParser::open ( const QString & filename )

Opens a VHIST file and parses it.

If the file could not be opened or detecting the VHIST header failed, false is returned.

Parameters:

[in] filename The name of the file, which should be opened.

Returns:: true if opening and parsing the file succeeded and false otherwise.

Note:: The open function will parse the complete VHIST file. This operation is very time efficient and uses only a constant amount of memory, however, for large files, it still takes a noticable amount of time to complete. Therefore, opening the same VHIST file several times should be avoided.

Examples:: parse_example1.cpp.

bool VhistParser::writeFileToDisk	(	int	id,
		const QString &	filename
	)

Writes an embedded file from the current VHIST file to harddisk.

Parameters:

[in]	id	The id of the embedded file.
[in]	filename	The location on the harddisk, to which the file should be written.

Returns:: true if the operation succeeded and false otherwise.

Note:: Depending on the size of the embedded file, this operation may take a long time and block io during this period. In a GUI application, it's more favorable to use vhist::ExtractionQueue instead. The function only consumes a constant amount of memory.

See also:: vhist::ExtractionQueue

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

/daten/ahuesgen/projects/vhist/code/vhistlib/include/unvhistlib/vhistparser.h
/daten/ahuesgen/projects/vhist/code/vhistlib/src/unvhistlib/vhistparser.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation