libCombine  0.1.0
C++ library for working with the COMBINE Archive format
CombineArchive Class Reference

Public Member Functions

 CombineArchive ()
 Constructs a new COMBINE archive. More...
 
 ~CombineArchive ()
 Desctructor, also clears all variables by calling cleanUp() More...
 
bool addFile (const std::string &fileName, const std::string &targetName, const std::string &format, bool isMaster=false)
 Adds a new file to the archive. More...
 
bool addFile (std::istream &stream, const std::string &targetName, const std::string &format, bool isMaster=false)
 Adds the contents of the stream to the archive. More...
 
void addMetadata (const std::string &targetName, const OmexDescription &description)
 Adds the given metadata to the list. More...
 
bool extractEntry (const std::string &name, const std::string &destination=std::string())
 extracts the content from the entry with the given name More...
 
bool extractEntryToStream (const std::string &name, std::ostream &stream)
 extracts the entry into the given outptu stream. More...
 
std::string extractEntryToString (const std::string &name)
 extracts the given entry and returns the contents as string. More...
 
bool extractTo (const std::string &directory)
 extracts all entries in this archive into the given directory. More...
 
bool initializeFromDirectory (const std::string &directory)
 initializes this archive with all the content from the given directory More...
 
bool initializeFromArchive (const std::string &archiveFile)
 initializes this instance from the given Combine archive More...
 
const CaOmexManifestgetManifest () const
 
CaOmexManifestgetManifest ()
 
const CaContentgetMasterFile () const
 
const CaContentgetMasterFile (const std::string &formatKey) const
 returns the first master file with given format key More...
 
const CaContentgetEntryByFormat (const std::string &formatKey) const
 returns the first entry with the given format key More...
 
const CaContentgetEntryByLocation (const std::string &location) const
 returns the first entry with the location More...
 
std::vector< std::string > getAllLocations () const
 
int getNumEntries () const
 
const CaContentgetEntry (int index) const
 returns the entry at the given index More...
 
OmexDescription getMetadataForLocation (const std::string &location) const
 returns the metadata for the given location if it does not exist an empty description will be returned. More...
 
void setManifest (CaOmexManifest *value)
 Sets the manifest to the given value. More...
 
bool cleanUp ()
 cleanUp resets this class (removes tempfiles, clears map and metadata) More...
 
bool writeToFile (const std::string &fileName)
 writes the archive to the file More...
 
bool getStream (const std::string &name, std::ifstream &stream)
 returns the stream for the given name More...
 

Protected Member Functions

std::string getNextFilename (const std::string &prefix, const std::string &suffix=".xml")
 returns the next filename that is not yet in the archive with the given prefix and suffix (defaults to .xml) More...
 
void addMetadataToArchive (OmexDescription &desc, zipper::Zipper *zipper)
 adds the given description to the zip archive (and the manifest). More...
 

Protected Attributes

CaOmexManifestmpManifest
 the manifest More...
 
std::map< std::string, std::string > mMap
 a map between the names of the files in this archive and the actual file names on the disc. More...
 
std::map< std::string, OmexDescriptionmMetadataMap
 a map between entries in this archive and metadata descriptions for them. More...
 
zipper::Unzipper * mpUnzipper
 an unzipper instance, that is used to extract data files. More...
 
std::vector< std::string > mTempFiles
 a vector of temporary files that have been created in the process of working on the archive. More...
 

Constructor & Destructor Documentation

§ CombineArchive()

CombineArchive::CombineArchive ( )

Constructs a new COMBINE archive.

§ ~CombineArchive()

CombineArchive::~CombineArchive ( )

Desctructor, also clears all variables by calling cleanUp()

Member Function Documentation

§ addFile() [1/2]

bool CombineArchive::addFile ( const std::string &  fileName,
const std::string &  targetName,
const std::string &  format,
bool  isMaster = false 
)

Adds a new file to the archive.

Parameters
fileNamethe file to be added
targetNamethe target name of the file in the archive
formatthe format that this file has
isMasterboolean indicating whether the file should be opened first if there are multiple ones.
Returns
boolean indicating success or failure

§ addFile() [2/2]

bool CombineArchive::addFile ( std::istream &  stream,
const std::string &  targetName,
const std::string &  format,
bool  isMaster = false 
)

Adds the contents of the stream to the archive.

Parameters
streaminput stream with the data.
targetNamethe target name of the file in the archive
formatthe format that this file has
isMasterboolean indicating whether the file should be opened first if there are multiple ones.
Returns
boolean indicating success or failure

§ addMetadata()

void CombineArchive::addMetadata ( const std::string &  targetName,
const OmexDescription description 
)

Adds the given metadata to the list.

Parameters
targetNamethe name of the entry that the metadata is about
descriptionthe metadata description

§ addMetadataToArchive()

void CombineArchive::addMetadataToArchive ( OmexDescription desc,
zipper::Zipper *  zipper 
)
protected

adds the given description to the zip archive (and the manifest).

the entry will be skipped if it is empty.

Parameters
descthe description to be added
zipperthe zipper to be used

§ cleanUp()

bool CombineArchive::cleanUp ( )

cleanUp resets this class (removes tempfiles, clears map and metadata)

Returns

§ extractEntry()

bool CombineArchive::extractEntry ( const std::string &  name,
const std::string &  destination = std::string() 
)

extracts the content from the entry with the given name

Parameters
namethe entry to be extracted
destinationoptional filename or folder to save the entry under. If a folder is given, the file will be saved as folder + "/" + name. If the argument is left blank the file will be written into "./" + name.
Returns
boolean indicating success or failure.

§ extractEntryToStream()

bool CombineArchive::extractEntryToStream ( const std::string &  name,
std::ostream &  stream 
)

extracts the entry into the given outptu stream.

Parameters
nameof the entry to be extracted
streamthe stream into which to write the contents of the file
Returns
boolean indicating success or failure.

§ extractEntryToString()

std::string CombineArchive::extractEntryToString ( const std::string &  name)

extracts the given entry and returns the contents as string.

Parameters
namethe entry to be extracted
Returns
the content of the entry, or empty if not found.

§ extractTo()

bool CombineArchive::extractTo ( const std::string &  directory)

extracts all entries in this archive into the given directory.

Parameters
directorythe directory into which to extract the archive.
Returns
boolean indicating success or failure.

§ getAllLocations()

std::vector<std::string> CombineArchive::getAllLocations ( ) const
Returns
a std::vector of all locations in this archive.

§ getEntry()

const CaContent* CombineArchive::getEntry ( int  index) const

returns the entry at the given index

Parameters
indexthe element to get
Returns
the entry with the given index, or NULL

§ getEntryByFormat()

const CaContent* CombineArchive::getEntryByFormat ( const std::string &  formatKey) const

returns the first entry with the given format key

Parameters
formatKeythe key
Returns
the entry with the given format, or NULL

§ getEntryByLocation()

const CaContent* CombineArchive::getEntryByLocation ( const std::string &  location) const

returns the first entry with the location

Parameters
locationthe location
Returns
the entry with the given location, or NULL

§ getManifest() [1/2]

const CaOmexManifest* CombineArchive::getManifest ( ) const
Returns
the manifest

§ getManifest() [2/2]

CaOmexManifest* CombineArchive::getManifest ( )
Returns
the manifest

§ getMasterFile() [1/2]

const CaContent* CombineArchive::getMasterFile ( ) const
Returns
returns the first master file or NULL

§ getMasterFile() [2/2]

const CaContent* CombineArchive::getMasterFile ( const std::string &  formatKey) const

returns the first master file with given format key

Parameters
formatKeythe format key
Returns
returns the first master file with the key or NULL

§ getMetadataForLocation()

OmexDescription CombineArchive::getMetadataForLocation ( const std::string &  location) const

returns the metadata for the given location if it does not exist an empty description will be returned.

Parameters
locationthe location
Returns
the metadata object if found (otherwise it will be empty)

§ getNextFilename()

std::string CombineArchive::getNextFilename ( const std::string &  prefix,
const std::string &  suffix = ".xml" 
)
protected

returns the next filename that is not yet in the archive with the given prefix and suffix (defaults to .xml)

Parameters
prefixthe prefix for the file
suffixthe suffix
Returns
the next filename that is not yet in the archive

§ getNumEntries()

int CombineArchive::getNumEntries ( ) const
Returns
number of entries in the archive

§ getStream()

bool CombineArchive::getStream ( const std::string &  name,
std::ifstream &  stream 
)

returns the stream for the given name

Parameters
namethe name that should be in the current map of files
streamthe stream for the found entry
Returns
true if the name is found, false otherwise

§ initializeFromArchive()

bool CombineArchive::initializeFromArchive ( const std::string &  archiveFile)

initializes this instance from the given Combine archive

Parameters
archiveFilethe combine archive file
Returns
boolean indicating success or failure

§ initializeFromDirectory()

bool CombineArchive::initializeFromDirectory ( const std::string &  directory)

initializes this archive with all the content from the given directory

Parameters
directorythe directory, from which all files will be added recursively to this archive. (excluding a file called "manifest.xml").
Returns
boolean indicating success or failure

§ setManifest()

void CombineArchive::setManifest ( CaOmexManifest value)

Sets the manifest to the given value.

Parameters
valuethe manifest

§ writeToFile()

bool CombineArchive::writeToFile ( const std::string &  fileName)

writes the archive to the file

Parameters
fileNamethe filename
Returns
true, in case of success

Field Documentation

§ mMap

std::map<std::string, std::string> CombineArchive::mMap
protected

a map between the names of the files in this archive and the actual file names on the disc.

In case a combine archive was opened, this filename will be prefixed with "unzipper://" to indicate that the file is to be read from the unzipper pointer.

§ mMetadataMap

std::map<std::string, OmexDescription> CombineArchive::mMetadataMap
protected

a map between entries in this archive and metadata descriptions for them.

§ mpManifest

CaOmexManifest* CombineArchive::mpManifest
protected

the manifest

§ mpUnzipper

zipper::Unzipper* CombineArchive::mpUnzipper
protected

an unzipper instance, that is used to extract data files.

§ mTempFiles

std::vector<std::string> CombineArchive::mTempFiles
protected

a vector of temporary files that have been created in the process of working on the archive.

They will be deleted automatically upon destruction of the instance.