libmspack

Data Fields
mscab_decompressor Struct Reference

A decompressor for .CAB (Microsoft Cabinet) files. More...

`#include <mspack.h>`

Collaboration diagram for mscab_decompressor:
[legend]

## Data Fields
struct mscabd_cabinet *(* | open )(struct mscab_decompressor *self, const char *filename)
| Opens a cabinet file and reads its contents. More...
void(* | close )(struct mscab_decompressor *self, struct mscabd_cabinet *cab)
| Closes a previously opened cabinet or cabinet set. More...
struct mscabd_cabinet *(* | search )(struct mscab_decompressor *self, const char *filename)
| Searches a regular file for embedded cabinets. More...
int(* | append )(struct mscab_decompressor *self, struct mscabd_cabinet *cab, struct mscabd_cabinet *nextcab)
| Appends one mscabd_cabinet to another, forming or extending a cabinet set. More...
int(* | prepend )(struct mscab_decompressor *self, struct mscabd_cabinet *cab, struct mscabd_cabinet *prevcab)
| Prepends one mscabd_cabinet to another, forming or extending a cabinet set. More...
int(* | extract )(struct mscab_decompressor *self, struct mscabd_file *file, const char *filename)
| Extracts a file from a cabinet or cabinet set. More...
int(* | set_param )(struct mscab_decompressor *self, int param, int value)
| Sets a CAB decompression engine parameter. More...
int(* | last_error )(struct mscab_decompressor *self)
| Returns the error code set by the most recently called method. More...

## Detailed Description

A decompressor for .CAB (Microsoft Cabinet) files.

All fields are READ ONLY.

See also
  mspack_create_cab_decompressor(), mspack_destroy_cab_decompressor()

## Field Documentation

## ◆ append

int(* mscab_decompressor::append) (struct mscab_decompressor *self, struct mscabd_cabinet *cab, struct mscabd_cabinet *nextcab)

Appends one mscabd_cabinet to another, forming or extending a cabinet set.

This will attempt to append one cabinet to another such that `(cab->nextcab == nextcab) && (nextcab->prevcab == cab)` and any folders split between the two cabinets are merged.

The cabinets MUST be part of a cabinet set – a cabinet set is a cabinet that spans more than one physical cabinet file on disk – and must be appropriately matched.

It can be determined if a cabinet has further parts to load by examining the mscabd_cabinet::flags field:

- if `(flags & MSCAB_HDR_PREVCAB)` is non-zero, there is a predecessor cabinet to open() and prepend(). Its MS-DOS case-insensitive filename is mscabd_cabinet::prevname
- if `(flags & MSCAB_HDR_NEXTCAB)` is non-zero, there is a successor cabinet to open() and append(). Its MS-DOS case-insensitive filename is mscabd_cabinet::nextname

If the cabinets do not match, an error code will be returned. Neither cabinet has been altered, and both should be closed seperately.

Files and folders in a cabinet set are a single entity. All cabinets in a set use the same file list, which is updated as cabinets in the set are added. All pointers to mscabd_folder and mscabd_file structures in either cabinet must be discarded and re-obtained after merging.

Parameters

  self | a self-referential pointer to the mscab_decompressor instance being called
  cab | the cabinet which will be appended to, predecessor of nextcab
  nextcab | the cabinet which will be appended, successor of cab

Returns
  an error code, or MSPACK_ERR_OK if successful

See also
  prepend(), open(), close()

## ◆ close

void(* mscab_decompressor::close) (struct mscab_decompressor *self, struct mscabd_cabinet *cab)

Closes a previously opened cabinet or cabinet set.

This closes a cabinet, all cabinets associated with it via the mscabd_cabinet::next, mscabd_cabinet::prevcab and mscabd_cabinet::nextcab pointers, and all folders and files. All memory used by these entities is freed.

The cabinet pointer is now invalid and cannot be used again. All mscabd_folder and mscabd_file pointers from that cabinet or cabinet set are also now invalid, and cannot be used again.

If the cabinet pointer given was created using search(), it MUST be the cabinet pointer returned by search() and not one of the later cabinet pointers further along the mscabd_cabinet::next chain.

If extra cabinets have been added using append() or prepend(), these will all be freed, even if the cabinet pointer given is not the first cabinet in the set. Do NOT close() more than one cabinet in the set.

The mscabd_cabinet::filename is not freed by the library, as it is not allocated by the library. The caller should free this itself if necessary, before it is lost forever.

Parameters

  self | a self-referential pointer to the mscab_decompressor instance being called
  cab | the cabinet to close

See also
  open(), search(), append(), prepend()

## ◆ extract

int(* mscab_decompressor::extract) (struct mscab_decompressor *self, struct mscabd_file *file, const char *filename)

Extracts a file from a cabinet or cabinet set.

This extracts a compressed file in a cabinet and writes it to the given filename.

The MS-DOS filename of the file, mscabd_file::filename, is NOT USED by extract(). The caller must examine this MS-DOS filename, copy and change it as necessary, create directories as necessary, and provide the correct filename as a parameter, which will be passed unchanged to the decompressor's mspack_system::open()

If the file belongs to a split folder in a multi-part cabinet set, and not enough parts of the cabinet set have been loaded and appended or prepended, an error will be returned immediately.

Parameters

  self | a self-referential pointer to the mscab_decompressor instance being called
  file | the file to be decompressed
  filename | the filename of the file being written to

Returns
  an error code, or MSPACK_ERR_OK if successful

## ◆ last_error

int(* mscab_decompressor::last_error) (struct mscab_decompressor *self)

Returns the error code set by the most recently called method.

This is useful for open() and search(), which do not return an error code directly.

Parameters

  self | a self-referential pointer to the mscab_decompressor instance being called

Returns
  the most recent error code

See also
  open(), search()

## ◆ open

struct mscabd_cabinet*(* mscab_decompressor::open) (struct mscab_decompressor *self, const char *filename)

Opens a cabinet file and reads its contents.

If the file opened is a valid cabinet file, all headers will be read and a mscabd_cabinet structure will be returned, with a full list of folders and files.

In the case of an error occuring, NULL is returned and the error code is available from last_error().

The filename pointer should be considered "in use" until close() is called on the cabinet.

Parameters

  self | a self-referential pointer to the mscab_decompressor instance being called
  filename | the filename of the cabinet file. This is passed directly to mspack_system::open().

Returns
  a pointer to a mscabd_cabinet structure, or NULL on failure

See also
  close(), search(), last_error()

## ◆ prepend

int(* mscab_decompressor::prepend) (struct mscab_decompressor *self, struct mscabd_cabinet *cab, struct mscabd_cabinet *prevcab)

Prepends one mscabd_cabinet to another, forming or extending a cabinet set.

This will attempt to prepend one cabinet to another, such that `(cab->prevcab == prevcab) && (prevcab->nextcab == cab)`. In all other respects, it is identical to append(). See append() for the full documentation.

Parameters

  self | a self-referential pointer to the mscab_decompressor instance being called
  cab | the cabinet which will be prepended to, successor of prevcab
  prevcab | the cabinet which will be prepended, predecessor of cab

Returns
  an error code, or MSPACK_ERR_OK if successful

See also
  append(), open(), close()

## ◆ search

struct mscabd_cabinet*(* mscab_decompressor::search) (struct mscab_decompressor *self, const char *filename)

Searches a regular file for embedded cabinets.

This opens a normal file with the given filename and will search the entire file for embedded cabinet files

If any cabinets are found, the equivalent of open() is called on each potential cabinet file at the offset it was found. All successfully open()ed cabinets are kept in a list.

The first cabinet found will be returned directly as the result of this method. Any further cabinets found will be chained in a list using the mscabd_cabinet::next field.

In the case of an error occuring anywhere other than the simulated open(), NULL is returned and the error code is available from last_error().

If no error occurs, but no cabinets can be found in the file, NULL is returned and last_error() returns MSPACK_ERR_OK.

The filename pointer should be considered in use until close() is called on the cabinet.

close() should only be called on the result of search(), not on any subsequent cabinets in the mscabd_cabinet::next chain.

Parameters

  self | a self-referential pointer to the mscab_decompressor instance being called
  filename | the filename of the file to search for cabinets. This is passed directly to mspack_system::open().

Returns
  a pointer to a mscabd_cabinet structure, or NULL

See also
  close(), open(), last_error()

## ◆ set_param

int(* mscab_decompressor::set_param) (struct mscab_decompressor *self, int param, int value)

Sets a CAB decompression engine parameter.

The following parameters are defined:

- MSCABD_PARAM_SEARCHBUF: How many bytes should be allocated as a buffer when using search()? The minimum value is 4. The default value is 32768.
- MSCABD_PARAM_FIXMSZIP: If non-zero, extract() will ignore bad checksums and recover from decompression errors in MS-ZIP compressed folders. The default value is 0 (don't recover).
- MSCABD_PARAM_DECOMPBUF: How many bytes should be used as an input bit buffer by decompressors? The minimum value is 4. The default value is 4096.

Parameters

  self | a self-referential pointer to the mscab_decompressor instance being called
  param | the parameter to set
  value | the value to set the parameter to

Returns
  MSPACK_ERR_OK if all is OK, or MSPACK_ERR_ARGS if there is a problem with either parameter or value.

See also
  search(), extract()

The documentation for this struct was generated from the following file:

- mspack.h