ms_zip Class Reference [Mascot utilities and tools module]

Utility class for compressing and decompressing data in compress format, and compressing in gzip format. More...

#include <ms_zip.hpp>

Inheritance diagram for ms_zip:

Collaboration diagram for ms_zip:

List of all members.

Public Member Functions
	ms_zip (const bool isZipped, const unsigned char *buffer, const unsigned long len)
	Buffer mode constructor (only for C++).
	ms_zip (const bool isZipped, const std::string &buffer)
	Buffer mode constructor.
	ms_zip (const ms_zip &src)
	Copying constructor.
	ms_zip (const bool isZipped)
	Streaming mode constructor.
void	appendErrors (const ms_errors &src)
	Copies all errors from another instance and appends them at the end of own list.
void	clearAllErrors ()
	Remove all errors from the current list of errors.
std::string	compressMore (const std::string &dataIn)
	Feed more data to the compressor and retrieve the next chunk of compressed data.
void	compressMore (const unsigned char *dataIn, const unsigned long inputLen, unsigned char *dataOut, unsigned long *outputLen)
	Feed more data to the compressor and retrieve the next chunk of compressed data.
void	copyFrom (const ms_errors *right)
	Use this member to make a copy of another instance.
void	copyFrom (const ms_zip *right)
	Call this member to copy all the information from another instance.
const ms_errs *	getErrorHandler () const
	Retrive the error object using this function to get access to all errors and error parameters.
int	getLastError () const
	Return the error description of the last error that occurred.
std::string	getLastErrorString () const
	Return the error description of the last error that occurred.
unsigned long	getUnZipped (unsigned char *buffer, const unsigned long len) const
	Return the uncompressed buffer.
std::string	getUnZipped () const
	Return the uncompressed buffer.
unsigned long	getUnZippedLen () const
	Return the length of the uncompressed buffer.
unsigned long	getZipped (unsigned char *buffer, const unsigned long len) const
	Return the compressed buffer.
std::string	getZipped () const
	Return the compressed buffer.
unsigned long	getZippedLen () const
	Return the length of the compressed buffer.
bool	isValid () const
	Call this function to determine if there have been any errors.
ms_zip &	operator= (const ms_zip &right)
	C++ style assignment operator.

---

Detailed Description

Utility class for compressing and decompressing data in compress format, and compressing in gzip format.

---

Constructor & Destructor Documentation

ms_zip	(	const bool	isZipped,
		const unsigned char *	buffer,
		const unsigned long	len
	)

Buffer mode constructor (only for C++).

ms_zip can be used to compress and uncompress a small amount of data (less than 10 MB) in a buffer, or in streaming compression mode. When decompressing, the only supported data format is data compressed by ms_zip.

In buffer mode, the first four bytes of the compressed buffer are used to store the length of the uncompressed data as an unsigned 32 bit integer (little endian) format. No other headers are written. The object will hold a copy of both the compressed and uncompressed data, so it is not suitable for use with large amounts of data. After creating the object, call isValid() to determine if there are any errors. The errors can be retrieved using getLastErrorString().

Possible errors are:

• ms_errs::ERR_MSP_ZIP_ENDIAN
• ms_errs::ERR_MSP_ZIP_OUTOFMEMORY
• ms_errs::ERR_MSP_ZIP_BUFTOOSMALL
• ms_errs::ERR_MSP_ZIP_INVALIDDATA
• ms_errs::ERR_MSP_ZIP_UNKNOWN
• ms_errs::ERR_MSP_ZIP_LENGTHDIFFERS
• ms_errs::ERR_MSP_ZIP_UNCOMPRESSEDDATATOOLONG
• ms_errs::ERR_MSP_ZIP_ZEROLENGTH

Parameters:

isZipped	should be true if the passed buffer contains compressed data.
buffer	is a pointer to the compressed or uncompressed data. If it is uncompressed, there is no assumption that the data is null terminated.
len	is the length of the passed buffer.

ms_zip	(	const bool	isZipped,
		const std::string &	buffer
	)

Buffer mode constructor.

ms_zip can be used to compress and uncompress a small amount of data (less than 10 MB) in a buffer, or in streaming compression mode. When decompressing, the only supported data format is data compressed by ms_zip.

In buffer mode, the first four bytes of the compressed buffer are used to store the length of the uncompressed data as an unsigned 32 bit integer (little endian) format. No other headers are written. The object will hold a copy of both the compressed and uncompressed data, so it is not suitable for use with large amounts of data. After creating the object, call isValid() to determine if there are any errors. The errors can be retrieved using getLastErrorString().

Possible errors are:

• ms_errs::ERR_MSP_ZIP_ENDIAN
• ms_errs::ERR_MSP_ZIP_OUTOFMEMORY
• ms_errs::ERR_MSP_ZIP_BUFTOOSMALL
• ms_errs::ERR_MSP_ZIP_INVALIDDATA
• ms_errs::ERR_MSP_ZIP_UNKNOWN
• ms_errs::ERR_MSP_ZIP_LENGTHDIFFERS
• ms_errs::ERR_MSP_ZIP_UNCOMPRESSEDDATATOOLONG
• ms_errs::ERR_MSP_ZIP_ZEROLENGTH

Parameters:

isZipped	should be true if the passed buffer contains compressed data.
buffer	is a string that contains the compressed or uncompressed data. If it is uncompressed, there is no assumption that the data is null terminated. C++ programmers should be aware that a std::string constructor needs to be passed the length parameter when creating a std::string that contains binary data or a 'zero' in the data will be considered to be a null terminator for a string.

ms_zip

(

const bool

isZipped )

[explicit]

Streaming mode constructor.

ms_zip can be used to compress and uncompress a small amount of data (less than 10 MB) in a buffer, or in streaming compression mode. When decompressing, the only supported data format is data compressed by ms_zip.

In streaming compression mode, the compressed data stream will start with a minimal gzip header, followed by the compressed data. The constructor does not take any input data as a parameter, unlike in buffer mode. Instead, input data is fed to the object using ms_zip::compressMore(), which returns compressed data. End of input data is indicated by passing the empty string to ms_zip::compressMore().

No streaming decompression mode is supported in this version.

If the underlying zlib library cannot be initialised, the following errors are possible:

• ms_errs::ERR_MSP_ZIP_OUTOFMEMORY
• ms_errs::ERR_MSP_ZIP_VERSIONERROR

Parameters:

isZipped

must always be false for compression mode.

ms_zip

(

const ms_zip &

src )

Copying constructor.

Generally only used from C++, but will be called indirectly from other languages.

Parameters:

src	is the ms_zip to make a copy of.

---

Member Function Documentation

void appendErrors

(

const ms_errors &

src )

[inherited]

Copies all errors from another instance and appends them at the end of own list.

Parameters:

src	The object to copy the errors across from. See Maintaining object references: two rules of thumb.

void clearAllErrors

(

)

[inherited]

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also:

isValid(), getLastError(), getLastErrorString(), getErrorHandler()

Examples:

common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.

void compressMore	(	const unsigned char *	dataIn,
		const unsigned long	inputLen,
		unsigned char *	dataOut,
		unsigned long *	outputLen
	)

Feed more data to the compressor and retrieve the next chunk of compressed data.

You may need to call ms_zip::compressMore() a few times with more input data until the compressed stream starts, which is indicated by returning a non-empty string.

Both the input and output strings are bounded: inputLen and outputLen must not exceed 10 MB, and outputLen must always exceed 0. If any of these conditions fail, a corresponding error will be set.

End of input data is indicated by calling ms_zip::compressMore() with inputLen equal to 0 (dataIn can be NULL). The compressor will flush the output and return the last compressed bytes. If there are more bytes to return than outputLen, you must call the method again (with inputLen equal to 0). When there is no more data to be flushed, outputLen will equal 0.

If this method is called in non-streaming mode, outputLen will be set to 0 and the error ms_errs::ERR_MSP_ZIP_NOTSTREAMING set.

Other possible error conditions:

• ms_errs::ERR_MSP_ZIP_UNCOMPRESSEDDATATOOLONG
• ms_errs::ERR_MSP_ZIP_BUFTOOSMALL
• ms_errs::ERR_MSP_ZIP_STREAMERROR
• ms_errs::ERR_MSP_ZIP_UNKNOWN

Parameters:

dataIn	Pointer to raw binary data to append to the compressed stream. The data is not assumed to be null terminated.
inputLen	Length of data in dataIn.
dataOut	Pointer to the memory location where compressed data should be written.
outputLen	Maximum length of data to output. outputLen will be set to the actual length of dataOut on successful return.

std::string compressMore

(

const std::string &

dataIn )

Feed more data to the compressor and retrieve the next chunk of compressed data.

You may need to call ms_zip::compressMore() a few times with more input data until the compressed stream starts, which is indicated by returning a non-empty string.

Both the input and output strings are bounded: the input string length must not exceed 10 MB and the output string length will never exceed 10 MB.

End of input data is indicated by calling ms_zip::compressMore() with the empty string (length 0). The compressor will flush the output and return the last compressed bytes. If there are more bytes to return than the internal buffer allows, you must call the method again with the empty string. When there is no more data to be flushed, the returned string will be empty itself.

If this method is called in non-streaming mode, an empty string object will be returned and the error ms_errs::ERR_MSP_ZIP_NOTSTREAMING set.

Other possible error conditions:

• ms_errs::ERR_MSP_ZIP_UNCOMPRESSEDDATATOOLONG
• ms_errs::ERR_MSP_ZIP_STREAMERROR
• ms_errs::ERR_MSP_ZIP_UNKNOWN

Parameters:

dataIn

Raw binary data to append to the compressed stream. The data need not be null terminated. C++ programmers should be aware that a std::string constructor needs to be passed the length parameter when creating a std::string that contains binary data or a 'zero' in the data will be considered to be a null terminator for a string.

Returns:

A string (possibly empty) of raw compressed binary data.

void copyFrom

(

const ms_errors *

right )

[inherited]

Use this member to make a copy of another instance.

Parameters:

right

is the source to initialise from

void copyFrom

(

const ms_zip *

right )

Call this member to copy all the information from another instance.

Simply create an instance of the class using the default constructor and call this method.

Parameters:

right

is a pointer to another instance to copy from.

const ms_errs * getErrorHandler

(

)

const [inherited]

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns:

Constant pointer to the error handler

See also:

isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples:

common_error.cpp, and http_helper_getstring.cpp.

int getLastError

(

)

const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also:

isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Returns:

the error number of the last error, or 0 if there have been no errors.

Reimplemented in ms_mascotresfile.

std::string getLastErrorString

(

)

const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns:

Most recent error, warning, information or debug message

See Error Handling.

See also:

isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Reimplemented in ms_mascotresfile.

Examples:

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.

std::string getUnZipped

(

)

const

Return the uncompressed buffer.

In buffer mode, return the uncompressed data; in streaming compression mode, return the most recent input value to ms_zip::compressMore().

Note:

In C++, the string will not be null terminated, so you should use the std::string::length function to determing the length of the data.

Note:

In Perl, the length function can also be used on the returned string. The uncompressed data may be binary or text.

Returns:

uncompressed data as a string

unsigned long getUnZipped	(	unsigned char *	buffer,
		const unsigned long	len
	)		const

Return the uncompressed buffer.

In buffer mode, return the uncompressed data; in streaming compression mode, return the most recent input value to ms_zip::compressMore().

Parameters:

buffer	is the location where the uncompressed data will be copied to. The calling application should make sure that the buffer is long enough. Use getUnZippedLen() to find the length of the uncompressed data.
len	is the length of the passed buffer.

Returns:

The number of bytes copied to the buffer.

unsigned long getUnZippedLen

(

)

const

Return the length of the uncompressed buffer.

Returns:

The length, in bytes of the uncompressed data

std::string getZipped

(

)

const

Return the compressed buffer.

In buffer mode, return the compressed data; in streaming compression mode, return the most recent value from ms_zip::compressMore().

Note:

In C++, the string will not be null terminated, so you should use the std::string::length function to determing the length of the data.

Note:

In Perl, the length function can be used on the returned string.

Returns:

compressed data as a string

unsigned long getZipped	(	unsigned char *	buffer,
		const unsigned long	len
	)		const

Return the compressed buffer.

In buffer mode, return the compressed data; in streaming compression mode, return the most recent value from ms_zip::compressMore().

Parameters:

buffer	is the location where the compressed data will be copied to. The calling application should make sure that the buffer is long enough. Use getZippedLen() to find the length of the compressed data.
len	is the length of the passed buffer.

Returns:

The number of bytes copied to the buffer.

unsigned long getZippedLen

(

)

const

Return the length of the compressed buffer.

Returns:

The length, in bytes of the compressed data

bool isValid

(

)

const [inherited]

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns:

True if no fatal error occured

See also:

getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples:

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, resfile_summary.cpp, and tools_aahelper.cpp.

---

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

• ms_zip.hpp
• ms_zip.cpp