Lhasa
lha_reader.h File Reference

LHA file reader. More...

Typedefs

typedef struct _LHAReader LHAReader
 Opaque structure used to decode the contents of an LZH file.

Enumerations

enum  LHAReaderDirPolicy { LHA_READER_DIR_PLAIN , LHA_READER_DIR_END_OF_DIR , LHA_READER_DIR_END_OF_FILE }
 Policy for extracting directories. More...

Functions

LHAReaderlha_reader_new (LHAInputStream *stream)
 Create a new LHAReader to read data from an LHAInputStream.
void lha_reader_free (LHAReader *reader)
 Free a LHAReader structure.
void lha_reader_set_dir_policy (LHAReader *reader, LHAReaderDirPolicy policy)
 Set the LHAReaderDirPolicy used to extract directories.
LHAFileHeaderlha_reader_next_file (LHAReader *reader)
 Read the header of the next archived file from the input stream.
size_t lha_reader_read (LHAReader *reader, void *buf, size_t buf_len)
 Read some of the (decompresed) data for the current archived file, decompressing as appropriate.
int lha_reader_check (LHAReader *reader, LHADecoderProgressCallback callback, void *callback_data)
 Decompress the contents of the current archived file, and check that the checksum matches correctly.
int lha_reader_extract (LHAReader *reader, char *filename, LHADecoderProgressCallback callback, void *callback_data)
 Extract the contents of the current archived file.
int lha_reader_current_is_fake (LHAReader *reader)
 Check if the current file (last returned by lha_reader_next_file) was generated internally by the extract process.

Detailed Description

LHA file reader.

This file contains the interface functions for the LHAReader structure, used to decode data from a compressed LZH file and extract compressed files.

Enumeration Type Documentation

◆ LHAReaderDirPolicy

Policy for extracting directories.

When extracting a directory, some of the metadata associated with it needs to be set after the contents of the directory have been extracted. This includes the modification time (which would otherwise be reset to the current time) and the permissions (which can affect the ability to extract files into the directory). To work around this problem there are several ways of handling directory extraction.

Enumerator
LHA_READER_DIR_PLAIN 

"Plain" policy.

In this mode, the metadata is set at the same time that the directory is created. This is the simplest to comprehend, and the files returned from lha_reader_next_file will match the files in the archive, but it is not recommended.

LHA_READER_DIR_END_OF_DIR 

"End of directory" policy.

In this mode, if a directory is extracted, the directory name will be saved. Once the contents of the directory appear to have been extracted (i.e. a file is found that is not within the directory), the directory will be returned again by lha_reader_next_file. This time, when the directory is "extracted" (via lha_reader_extract), the metadata will be set.

This method uses less memory than LHA_READER_DIR_END_OF_FILE, but there is the risk that a file will appear within the archive after the metadata has been set for the directory. However, this is not normally the case, as files and directories typically appear within an archive in order. GNU tar uses the same method to address this problem with tar files.

This is the default policy.

LHA_READER_DIR_END_OF_FILE 

"End of file" policy.

In this mode, each directory that is extracted is recorded in a list. When the end of the archive is reached, these directories are returned again by lha_reader_next_file. When the directories are "extracted" again (via lha_reader_extract), the metadata is set.

This avoids the problems that can potentially occur with LHA_READER_DIR_END_OF_DIR, but uses more memory.

Function Documentation

◆ lha_reader_check()

int lha_reader_check ( LHAReader * reader,
LHADecoderProgressCallback callback,
void * callback_data )

Decompress the contents of the current archived file, and check that the checksum matches correctly.

Parameters
readerThe LHAReader structure.
callbackCallback function to invoke to monitor progress (or NULL if progress does not need to be monitored).
callback_dataExtra data to pass to the callback function.
Returns
Non-zero if the checksum matches.

◆ lha_reader_current_is_fake()

int lha_reader_current_is_fake ( LHAReader * reader)

Check if the current file (last returned by lha_reader_next_file) was generated internally by the extract process.

This occurs when a directory or symbolic link must be created as a two-stage process, with some of the extraction process deferred to later in the stream.

These "fake" duplicates should usually be hidden in the user interface when a summary of extraction is presented.

Parameters
readerThe LHAReader structure.
Returns
Non-zero if the current file is a "fake", or zero for a normal file.

◆ lha_reader_extract()

int lha_reader_extract ( LHAReader * reader,
char * filename,
LHADecoderProgressCallback callback,
void * callback_data )

Extract the contents of the current archived file.

Parameters
readerThe LHAReader structure.
filenameFilename to extract the archived file to, or NULL to use the path and filename from the header.
callbackCallback function to invoke to monitor progress (or NULL if progress does not need to be monitored).
callback_dataExtra data to pass to the callback function.
Returns
Non-zero for success, or zero for failure (including CRC error).

◆ lha_reader_free()

void lha_reader_free ( LHAReader * reader)

Free a LHAReader structure.

Parameters
readerThe LHAReader structure.

◆ lha_reader_new()

LHAReader * lha_reader_new ( LHAInputStream * stream)

Create a new LHAReader to read data from an LHAInputStream.

Parameters
streamThe input stream to read data from.
Returns
Pointer to a new LHAReader structure, or NULL for error.

◆ lha_reader_next_file()

LHAFileHeader * lha_reader_next_file ( LHAReader * reader)

Read the header of the next archived file from the input stream.

Parameters
readerThe LHAReader structure.
Returns
Pointer to an LHAFileHeader structure, or NULL if an error occurred. This pointer is only valid until the next time that lha_reader_next_file is called.

◆ lha_reader_read()

size_t lha_reader_read ( LHAReader * reader,
void * buf,
size_t buf_len )

Read some of the (decompresed) data for the current archived file, decompressing as appropriate.

Parameters
readerThe LHAReader structure.
bufPointer to a buffer in which to store the data.
buf_lenSize of the buffer, in bytes.
Returns
Number of bytes stored in the buffer, or zero if there is no more data to decompress.

◆ lha_reader_set_dir_policy()

void lha_reader_set_dir_policy ( LHAReader * reader,
LHAReaderDirPolicy policy )

Set the LHAReaderDirPolicy used to extract directories.

Parameters
readerThe LHAReader structure.
policyThe policy to use for directories.