ZipIfstream Class Reference

Streaming reader for the single non-directory entry of a ZIP archive. More...

#include <OpenMS/FORMAT/ZipIfstream.h>

Collaboration diagram for ZipIfstream:

Public Member Functions
	ZipIfstream ()
	Default constructor; leaves the instance in a closed state (isOpen returns false, streamEnd returns true).
	ZipIfstream (const char *filename)
	Construct and open filename in one step; see open for the exact behaviour and exception set.
virtual	~ZipIfstream ()
	Destructor; closes the archive and the entry handle.
size_t	read (char *s, size_t n)
	Read up to n decompressed bytes from the open entry into s.
bool	streamEnd () const
	Whether the stream has been closed (end of entry reached or no archive opened).
bool	isOpen () const
	Whether an archive entry is currently open for reading.
void	open (const char *filename)
	Open filename and select its single non-directory entry for reading.
void	close ()
	Close the currently open archive (no-op if none is open). After the call, isOpen returns false and streamEnd returns true.
	ZipIfstream (const ZipIfstream &)=delete
ZipIfstream &	operator= (const ZipIfstream &)=delete
	ZipIfstream (ZipIfstream &&)=delete
ZipIfstream &	operator= (ZipIfstream &&)=delete

Protected Attributes
void *	zip_archive_ = nullptr
	Opaque libzip zip_t* handle; nullptr when no archive is open. Typed as void* to keep zip.h out of the header.
void *	zip_entry_ = nullptr
	Opaque libzip zip_file_t* handle for the currently streamed entry; nullptr when no entry is open.
bool	stream_at_end_ = true
	true once the stream has been closed (either explicitly via close or implicitly because the entry was fully consumed by read).

Detailed Description

Streaming reader for the single non-directory entry of a ZIP archive.

Backed by libzip. Directory entries (names ending in '/') are silently ignored when scanning the archive; the archive must contain exactly one non-directory entry, or open will throw. Bytes are then streamed lazily from that entry; the stream auto- closes once the entry has been fully consumed.

Note

When OpenMS is built without libzip, every call that actually touches an archive (open and consequently the single-argument constructor, plus read) throws Exception::NotImplemented. The default constructor, close, isOpen and streamEnd remain usable.

Copy and move are deliberately suppressed.

Constructor & Destructor Documentation

ZipIfstream() [1/4]

ZipIfstream

(

)

Default constructor; leaves the instance in a closed state (isOpen returns false, streamEnd returns true).

ZipIfstream() [2/4]

ZipIfstream ( const char *  filename )

explicit

Construct and open filename in one step; see open for the exact behaviour and exception set.

Parameters

[in]

filename

Path of the ZIP archive to open.

~ZipIfstream()

virtual ~ZipIfstream ( )

virtual

Destructor; closes the archive and the entry handle.

ZipIfstream() [3/4]

ZipIfstream ( const ZipIfstream &  )

delete

ZipIfstream() [4/4]

ZipIfstream ( ZipIfstream &&  )

delete

Member Function Documentation

close()

void close

(

)

Close the currently open archive (no-op if none is open). After the call, isOpen returns false and streamEnd returns true.

isOpen()

bool isOpen ( ) const

inline

Whether an archive entry is currently open for reading.

Returns

true if an entry is open, false otherwise.

References ZipIfstream::zip_entry_.

open()

void open

(

const char *

filename

)

Open filename and select its single non-directory entry for reading.

Closes any previously open archive first, scans the new archive for entries and selects the single non-directory one as the streaming source.

Parameters

[in]

filename

Path of the ZIP archive to open.

Exceptions

Exception::FileNotFound	when filename does not exist.
Exception::FileNotReadable	when filename exists but the archive cannot be opened (or the selected entry cannot be read).
Exception::FileEmpty	when the archive contains no non-directory entries.
Exception::ParseError	when the archive contains more than one non-directory entry. The exception message lists the conflicting entry names.
Exception::NotImplemented	when OpenMS was built without libzip.

operator=() [1/2]

ZipIfstream & operator= ( const ZipIfstream &  )

delete

operator=() [2/2]

ZipIfstream & operator= ( ZipIfstream &&  )

delete

read()

size_t read	(	char *	s,
		size_t	n
	)

Read up to n decompressed bytes from the open entry into s.

Returns the actual number of bytes written into s. A return value smaller than n indicates that the end of the entry was reached during this call and that the stream has been closed automatically (isOpen becomes false and streamEnd becomes true). Passing n == 0 is a no-op that returns 0 without touching the entry.

Parameters

[out]	s	Buffer that receives the decompressed bytes; must be at least n bytes long.
[in]	n	Number of bytes to attempt to read.

Returns

Number of decompressed bytes actually written into s.

Exceptions

Exception::ParseError	when zip_fread reports a decompression error.
Exception::IllegalArgument	when called on an instance that has no open entry (default-constructed, or already closed – including after a previous read drained the entry).
Exception::NotImplemented	when OpenMS was built without libzip.

streamEnd()

bool streamEnd ( ) const

inline

Whether the stream has been closed (end of entry reached or no archive opened).

Returns

true if no further read calls should be issued, false otherwise.

References ZipIfstream::stream_at_end_.

Member Data Documentation

stream_at_end_

bool stream_at_end_ = true

protected

true once the stream has been closed (either explicitly via close or implicitly because the entry was fully consumed by read).

Referenced by ZipIfstream::streamEnd().

zip_archive_

void* zip_archive_ = nullptr

protected

Opaque libzip zip_t* handle; nullptr when no archive is open. Typed as void* to keep zip.h out of the header.

zip_entry_

void* zip_entry_ = nullptr

protected

Opaque libzip zip_file_t* handle for the currently streamed entry; nullptr when no entry is open.

Referenced by ZipIfstream::isOpen().