Typedefs | Enumerations | Functions

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.

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

Policy for extracting directories.

When extracting a directory, some of the metadata associated with it need 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 (ie. 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

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:
reader The LHAReader structure.
callback Callback function to invoke to monitor progress (or NULL if progress does not need to be monitored).
callback_data Extra data to pass to the callback function.
Returns:
Non-zero if the checksum matches.
int lha_reader_extract ( LHAReader reader,
char *  filename,
LHADecoderProgressCallback  callback,
void *  callback_data 
)

Extract the contents of the current archived file.

Parameters:
reader The LHAReader structure.
filename Filename to extract the archived file to, or NULL to use the path and filename from the header.
callback Callback function to invoke to monitor progress (or NULL if progress does not need to be monitored).
callback_data Extra data to pass to the callback function.
Returns:
Non-zero for success, or zero for failure (including CRC error).
void lha_reader_free ( LHAReader reader  ) 

Free a LHAReader structure.

Parameters:
reader The LHAReader structure.
LHAReader* lha_reader_new ( LHAInputStream stream  ) 

Create a new LHAReader to read data from an LHAInputStream.

Parameters:
stream The input stream to read data from.
Returns:
Pointer to a new LHAReader structure, or NULL for error.
LHAFileHeader* lha_reader_next_file ( LHAReader reader  ) 

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

Parameters:
reader The 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.
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:
reader The LHAReader structure.
buf Pointer to a buffer in which to store the data.
buf_len Size of the buffer, in bytes.
Returns:
Number of bytes stored in the buffer, or zero if there is no more data to decompress.
void lha_reader_set_dir_policy ( LHAReader reader,
LHAReaderDirPolicy  policy 
)

Set the LHAReaderDirPolicy used to extract directories.

Parameters:
reader The LHAReader structure.
policy The policy to use for directories.