HaxeFoundation.haxe/libs/ziplib/zip.mli

(***********************************************************************)
(*                                                                     *)
(*                         The CamlZip library                         *)
(*                                                                     *)
(*            Xavier Leroy, projet Cristal, INRIA Rocquencourt         *)
(*                  adapted to Extc lib by Caue Waneck                 *)
(*                                                                     *)
(*  Copyright 2001 Institut National de Recherche en Informatique et   *)
(*  en Automatique.  All rights reserved.  This file is distributed    *)
(*  under the terms of the GNU Lesser General Public License, with     *)
(*  the special exception on linking described in file LICENSE.        *)
(*                                                                     *)
(***********************************************************************)
(* $Id: zip.mli,v 1.7 2008/12/07 09:23:08 xleroy Exp $ *)

(** Reading and writing ZIP archives

    This module provides functions for reading and writing ZIP archive
    files.  ZIP archives package one or more compressed files into
    a single ``ZIP file'' along with information about the files,
    including file name, date and time of last modification, user-provided
    comments, and a checksum to verify the integrity of each entry.
    The entries of a ZIP file are not necessarily actual files, and can
    actually consist of arbitrary data.

    The ZIP file format used in this module is identical to that
    implemented by the popular [pkzip] archiver under Windows,
    and by the Info-ZIP [zip] and [unzip] commands under Unix and Windows.
    This format is also identical to the JAR file format used by Java. *)

(** {6 Information on ZIP entries} *)

type compression_method =
    Stored                     (** data is stored without compression *)
  | Deflated                   (** data is compressed with the ``deflate'' algorithm *)
        (** Indicate whether the data in the entry is compressed or not. *)

type entry =
  { filename: string;          (** file name for entry *)
    extra: string;             (** extra information attached to entry *)
    comment: string;           (** comment attached to entry *)
    methd: compression_method; (** compression method *)
    mtime: float;              (** last modification time (seconds since epoch) *)
    crc: int32;                (** cyclic redundancy check for data *)
    uncompressed_size: int;    (** size of original data in bytes *)
    compressed_size: int;      (** size of compressed data *)
    is_directory: bool;        (** whether this entry represents a directory *)
    file_offset: int64         (** for internal use *)
  }
          (** Description of an entry in a ZIP file. *)

(** {6 Reading from ZIP files} *)

type in_file
          (** Abstract type representing a handle opened for reading from
              a ZIP file. *)
val open_in: string -> in_file
          (** Open the ZIP file with the given filename.  Return a
              handle opened for reading from this file. *)
val entries: in_file -> entry list
          (** Return a list of all entries in the given ZIP file. *)
val comment: in_file -> string
          (** Return the comment attached to the given ZIP file, or the
              empty string if none. *)
val find_entry: in_file -> string -> entry
          (** [Zip.find_entry zf filename] returns the description of the
              entry having name [filename] in the ZIP file [zf].
              Raises [Not_found] if no such entry exists.
              The file name must match exactly; in particular, case is
              significant.  File names must use [/] (slash) as the directory
              separator.  The name of a directory must end with a trailing 
              [/] (slash). *)
val read_entry: in_file -> entry -> string
          (** [Zip.read_entry zf e] reads and uncompresses the data
              (file contents) associated with entry [e] of ZIP file [zf].
              The data is returned as a character string. *)
val copy_entry_to_channel: in_file -> entry -> out_channel -> unit
          (** [Zip.copy_entry_to_channel zf e oc] reads and uncompresses
              the data associated with entry [e] of ZIP file [zf].
              It then writes this data to the output channel [oc]. *)
val copy_entry_to_file: in_file -> entry -> string -> unit
          (** [Zip.copy_entry_to_file zf e destfile] reads and uncompresses
              the data associated with entry [e] of ZIP file [zf].
              It then writes this data to the file named [destfile].
              The file [destfile] is created if it does not exist,
              and overwritten otherwise.  The last modification date of
              the file is set to that indicated in the ZIP entry [e],
              if possible. *)
val close_in: in_file -> unit
          (** Close the given ZIP file handle.  If the ZIP file handle was
              created by [open_in_channel], the underlying input channel
              is closed. *)

(** {6 Writing to ZIP files} *)

type out_file
          (** Abstract type representing a handle opened for writing to
              a ZIP file. *)
val open_out: ?comment: string -> string -> out_file
          (** Create (or truncate to zero length) the ZIP file with
              the given filename.  Return a handle opened for writing
              to this file.  The optional argument [comment] is a
              comment string that is attached to the ZIP file as a whole
              (as opposed to the comments that can be attached to individual
              ZIP entries). *) 
val add_entry:
  string -> out_file -> 
    ?extra: string -> ?comment: string -> ?level: int ->
    ?mtime: float -> string -> unit
          (** [Zip.add_entry data zf name] adds a new entry to the 
              ZIP file [zf].  The data (file contents) associated with
              the entry is taken from the string [data].  It is compressed
              and written to the ZIP file [zf].  [name] is the file name
              stored along with this entry.  Several optional arguments
              can be provided to control the format and attached information 
              of the entry:
              @param extra  extra data attached to the entry (a string).
                Default: empty.
              @param comment  attached to the entry (a string).
                Default: empty.
              @param level  compression level for the entry.  This is an
                integer between 0 and 9, with 0 meaning no compression (store
                as is), 1 lowest compression, 9 highest compression.  Higher
                levels result in smaller compressed data, but longer
                compression times.
                Default: 6 (moderate compression).
              @param mtime  last modification time (in seconds since the
                epoch).
                Default: the current time. *)
val copy_channel_to_entry:
  in_channel -> out_file -> 
    ?extra: string -> ?comment: string -> ?level: int ->
    ?mtime: float -> string -> unit
          (** Same as [Zip.add_entry], but the data associated with the
              entry is read from the input channel given as first argument.
              The channel is read up to end of file. *)
val copy_file_to_entry:
  string -> out_file -> 
    ?extra: string -> ?comment: string -> ?level: int ->
    ?mtime: float -> string -> unit
          (** Same as [Zip.add_entry], but the data associated with the
              entry is read from the file whose name is given as first
              argument.  Also, the default value for the [mtime]
              optional parameter is the time of last modification of the
              file. *)
val add_entry_generator:
  out_file ->
    ?extra: string -> ?comment: string -> ?level: int ->
    ?mtime: float -> string -> (string -> int -> int -> unit) * (unit -> unit)
          (** [Zip.add_entry_generator zf name] returns a pair of functions
              [(add, finish)].  It adds a new entry to the 
              ZIP file [zf].  The file name stored along with this entry
              is [name].  Initially, no data is stored in this entry.
              To store data in this entry, the program must repeatedly call
              the [add] function returned by [Zip.add_entry_generator].
              An invocation [add s ofs len] stores [len] characters of
              string [s] starting at offset [ofs] in the ZIP entry.
              When all the data forming the entry has been sent, the
              program must call the [finish] function returned by
              [Zip.add_entry_generator].  [finish] must be called exactly once.
              The optional arguments to [Zip.add_entry_generator]
              are as described in {!Zip.add_entry}. *)
val close_out: out_file -> unit
          (** Finish writing the ZIP archive by adding the table of
              contents, and close it. *)

(** {6 Error reporting} *)

exception Error of string * string * string
          (** Exception raised when an ill-formed ZIP archive is encountered,
              or illegal parameters are given to the functions in this
              module.  The exception is of the form
              [Error(ZIP_name, entry_name, message)] where [ZIP_name]
              is the name of the ZIP file, [entry_name] the name of
              the offending entry, and [message] an explanation of the
              error. *)