Lhasa: lha_reader.h File Reference

Lhasa

Loading...
Searching...
No Matches
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
LHAReader * | lha_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.
LHAFileHeader * | lha_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 (decompressed) 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

enum 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

  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.

## ◆ 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

  reader | The 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

  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).

## ◆ lha_reader_free()

void lha_reader_free | ( | LHAReader * | reader | ) |

Free a LHAReader structure.

Parameters

  reader | The LHAReader structure.

## ◆ lha_reader_new()

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.

## ◆ lha_reader_next_file()

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.

## ◆ lha_reader_read()

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

Read some of the (decompressed) 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.

## ◆ lha_reader_set_dir_policy()

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.