/** Uniform access to zip, gzip, 7-zip, and RAR compressed archives \file */

/* File_Extractor 1.0.0 */
#ifndef FEX_H
#define FEX_H

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/** First parameter of most functions is fex_t*, or const fex_t* if nothing is
changed. Once one of these functions returns an error, the archive should not
be used any further, other than to close it. One exception is
fex_error_file_eof; the archive may still be used after this. */
typedef struct fex_t fex_t;

/** Pointer to error, or NULL if function was successful. See error functions
below. */
#ifndef fex_err_t /* (#ifndef allows better testing of library) */
typedef const char *fex_err_t;
#endif

/**** File types ****/

/** Archive file type identifier. Can also hold NULL. */
typedef const struct fex_type_t_ *fex_type_t;

/** Array of supported types, with NULL at end */
const fex_type_t *fex_type_list(void);

/** Name of this archive type, e.g. "ZIP archive", "file" */
const char *fex_type_name(fex_type_t);

/** Usual file extension for type, e.g. ".zip", ".7z". For binary file type,
returns "", since it can open any file. */
const char *fex_type_extension(fex_type_t);

/**** Wide-character file paths ****/

/** Converts wide-character path to form suitable for use with fex functions. */
char *fex_wide_to_path(const wchar_t *wide);

/** Frees converted path. OK to pass NULL. */
void fex_free_path(char *);

/**** Identification ****/

/** True if str ends in extension. If extension is "", always returns true.
Converts str to lowercase before comparison, so extension should ALREADY be
lowercase (i.e. pass ".zip", NOT ".ZIP"). */
int fex_has_extension(const char str[], const char extension[]);

/** Determines type based on first fex_identify_header_size bytes of file.
Returns usual file extension this should have (e.g. ".zip", ".gz", etc.).
Returns "" if file header is not recognized. */
const char *fex_identify_header(const void *header);
enum { fex_identify_header_size = 263 };

/** Determines type based on extension of a file path, or just a lone extension
(must include '.', e.g. ".zip", NOT just "zip"). Returns NULL if extension is
for an unsupported type (e.g. ".lzh"). */
fex_type_t fex_identify_extension(const char path_or_extension[]);

/** Determines type based on filename extension and/or file header. Sets *out
to determined type, or NULL if type is not supported. */
fex_err_t fex_identify_file(fex_type_t *out, const char path[]);

/** Type of an already-opened archive */
fex_type_t fex_type(const fex_t *);

/**** Open/close ****/

/** Initializes static tables used by library. Automatically called by
fex_open(). OK to call more than once. */
fex_err_t fex_init(void);

/** Opens archive and points *out at it. If error, sets *out to NULL. */
fex_err_t fex_open(fex_t **out, const char path[]);

/** Opens archive of specified type and sets *out. Returns error if file is not
of that archive type. If error, sets *out to NULL. */
fex_err_t fex_open_type(fex_t **out, const char path[], fex_type_t);

/** Closes archive and frees memory. OK to pass NULL. */
void fex_close(fex_t *);

/**** Scanning ****/

/** True if at end of archive. Must be called after fex_open() or fex_rewind(),
as an archive might contain no files. */
int fex_done(const fex_t *);

/** Goes to next file in archive. If there are no more files, fex_done() will
now return true. */
fex_err_t fex_next(fex_t *);

/** Goes back to first file in archive, as if it were just opened with
fex_open() */
fex_err_t fex_rewind(fex_t *);

/** Saved position in archive. Can also store zero. */
typedef int fex_pos_t;

/** Position of current file in archive. Never returns zero. */
fex_pos_t fex_tell_arc(const fex_t *);

/** Returns to file at previously-saved position */
fex_err_t fex_seek_arc(fex_t *, fex_pos_t);

/**** Info ****/

/** Name of current file */
const char *fex_name(const fex_t *);

/** Wide-character name of current file, or NULL if unavailable */
const wchar_t *fex_wname(const fex_t *);

/** Makes further information available for file */
fex_err_t fex_stat(fex_t *);

/** Size of current file. fex_stat() or fex_data() must have been called. */
int fex_size(const fex_t *);

/** Modification date of current file (MS-DOS format), or 0 if unavailable.
fex_stat() must have been called. */
unsigned int fex_dos_date(const fex_t *);

/** CRC-32 checksum of current file's contents, or 0 if unavailable. Doesn't
require calculation; simply gets it from file's header. fex_stat() must have
been called. */
unsigned int fex_crc32(const fex_t *);

/**** Extraction ****/

/** Reads n bytes from current file. Reading past end of file results in
fex_err_file_eof. */
fex_err_t fex_read(fex_t *, void *out, int n);

/** Number of bytes read from current file */
int fex_tell(const fex_t *);

/** Points *out at current file's data in memory. Pointer is valid until
fex_next(), fex_rewind(), fex_seek_arc(), or fex_close() is called. Pointer
must NOT be freed(); library frees it automatically. If error, sets *out to
NULL. */
fex_err_t fex_data(fex_t *, const void **out);

/**** Errors ****/

/** Error string associated with err. Returns "" if err is NULL. Returns err
unchanged if it isn't a fex_err_t returned by library. */
const char *fex_err_str(fex_err_t err);

/** Details of error beyond main cause, or "" if none or err is NULL. Returns
err unchanged if it isn't a fex_err_t returned by library. */
const char *fex_err_details(fex_err_t err);

/** Numeric code corresponding to err. Returns fex_ok if err is NULL. Returns
fex_err_generic if err isn't a fex_err_t returned by library. */
int fex_err_code(fex_err_t err);

enum { fex_ok = 0,                /**< Successful call. Guaranteed to be zero. */
       fex_err_generic = 0x01,    /**< Error of unspecified type */
       fex_err_memory = 0x02,     /**< Out of memory */
       fex_err_caller = 0x03,     /**< Caller called function with bad args */
       fex_err_internal = 0x04,   /**< Internal problem, bug, etc. */
       fex_err_limitation = 0x05, /**< Exceeded program limit */

       fex_err_file_missing = 0x20, /**< File not found at specified path */
       fex_err_file_read = 0x21,    /**< Couldn't open file for reading */
       fex_err_file_io = 0x23,      /**< Read/write error */
       fex_err_file_eof = 0x25,     /**< Tried to read past end of file */

       fex_err_file_type = 0x30,    /**< File is of wrong type */
       fex_err_file_feature = 0x32, /**< File requires unsupported feature */
       fex_err_file_corrupt = 0x33  /**< File is corrupt */
};

/** fex_err_t corresponding to numeric code. Note that this might not recover
the original fex_err_t before it was converted to a numeric code; in
particular, fex_err_details(fex_code_to_err(code)) will be "" in most cases. */
fex_err_t fex_code_to_err(int code);

/* Deprecated */
typedef fex_t File_Extractor;

#ifdef __cplusplus
}
#endif

#endif
