home *** CD-ROM | disk | FTP | other *** search
/ ANews 1 / AnewsCD01.iso / Indispensables / Compression / xad / Developer / Include / Autodocs / xadmaster.doc next >
Text File  |  1999-08-09  |  37KB  |  1,026 lines
  1. TABLE OF CONTENTS
  2.  
  3. xadmaster.library/--general--
  4. xadmaster.library/xadAllocObject
  5. xadmaster.library/xadAllocVec
  6. xadmaster.library/xadCalcCRC16
  7. xadmaster.library/xadCalcCRC32
  8. xadmaster.library/xadConvertDates
  9. xadmaster.library/xadCopyMem
  10. xadmaster.library/xadDiskUnArc
  11. xadmaster.library/xadFileUnArc
  12. xadmaster.library/xadFreeInfo
  13. xadmaster.library/xadFreeObject
  14. xadmaster.library/xadGetClientInfo
  15. xadmaster.library/xadGetErrorText
  16. xadmaster.library/xadGetInfo
  17. xadmaster.library/xadHookAccess
  18. xadmaster.library/xadRecogFile
  19. xadmaster.library/--tags--
  20. xadmaster.library/--data hooks--
  21. xadmaster.library/--progress hooks--
  22.  
  23. VERSION
  24.     $VER: xadmaster.doc 2.0 (21.06.1999) by SDI
  25.  
  26. xadmaster.library/--general--                   xadmaster.library/--general--
  27.  
  28.     This library gives you an interface to extract data from file or disk
  29.     archives.
  30.  
  31.     When unachiving a archive you need to do following steps always
  32.     1) Allocate a "struct xadArchiveInfo" with a call to
  33.        xadAllocObjectA(XADOBJ_ARCHIVEINFO, 0). This structure is the master
  34.        interface and must not by modified in any way. Nearly all other
  35.        functions you may use need to get the pointer this this structure.
  36.        All data is passed with tags!
  37.     1) Call xadGetInfo() to find out if the input data is archived. If it
  38.        is, the xadArchiveInfo structure is filled with lots of information
  39.        (but the structure may contain empty lists!).
  40.        See xadGetInfo() description to see what you may read and what stuff
  41.        not. One of the input tags must be specified here to specify one 
  42.        of the allowed 4 input stream methods.
  43.     2) For every file in a file archive or every disk call xadFileUnArc() or
  44.        xadDiskUnArc() with one tag XAD_ENTRYNUMBER set to wanted entry. One
  45.        of the output tags must be specified here. For xadFileUnArc() there are
  46.        4 streams methods like for input. The xadDiskUnArc() function allows a
  47.        fifth method called XAD_OUTDEVICE. This one writes directly to disks
  48.        like all the disk archivers do. It allows 2 ways to specify the
  49.        destination device.
  50.        Passwords and other stuff is additionally allowed and sometimes
  51.        required.
  52.     3) Call xadFreeInfo() to free the stuff allocated with xadGetInfo.
  53.     4) Use xadFreeObjectA() to free the xadArchiveInfo structure.
  54.     Do not use one xadArchiveInfo file structure for multiple input files!
  55.     
  56.     ANY needed structure must be allocated with xadAllocObject! None of
  57.     the xadmaster structures can be allocated any other way!
  58.  
  59.     There exist lots of tags, which can be passed to the functions of this
  60.     library. Some of these are repeated in the xadArchiveInfo communication
  61.     structure. Do NEVER set this flags or values directly, but always use
  62.     the corresponding tags. The handling of these elements possibly will
  63.     change, but the tags will stay valid always!
  64.  
  65.     I know there are lots of flags which have long and strange names. The
  66.     method is not so complicated as you may think. The always follow following
  67.     guideline: XADxxY_zzzzz
  68.     xx - short name of their structure (AI - xadArchiveInfo, DI - xadDiskInfo,
  69.          C - xadClient, ...)
  70.     Y  - F for flag or B for bit value
  71.     zz - The flag name itself
  72.     So XADPIF_OVERWRITE is a flag for xadProgressInfo, which is called
  73.     OVERWRITE and XADAIB_OVERWRITE is a bit value for xadArchiveInfo structure.
  74.     
  75.     Also all the structure elements cover a short prefix indicating the name
  76.     of the master structure (xfi for xadFileInfo, xc for xadClient, ...). So
  77.     you can always check if your code is valid by comparing the prefixes.
  78.  
  79. xadmaster.library/xadAllocObject             xadmaster.library/xadAllocObject
  80.  
  81.     NAME
  82.         xadAllocObject - Allocate memory for all xad related structures
  83.  
  84.     SYNOPSIS
  85.         ptr = xadAllocObjectA(type, tags)
  86.         D0                    D0    A0
  87.  
  88.         APTR xadAllocObjectA(ULONG, struct TagItem *)
  89.  
  90.         ptr = xadAllocObject(type, tag1, ...)
  91.  
  92.         APTR xadAllocObject(ULONG, Tag, ...)
  93.  
  94.     FUNCTION
  95.         This function allocates the memory of a needed xad related
  96.         structure and initializes it. You need to use this function to
  97.         allocate the structures. Any other way of allocating is not
  98.         allowed.
  99.  
  100.     INPUT
  101.         type    - in libraries/xadmaster.h defined XADOBJ_... types.
  102.                   For example XADOBJ_FILEINFO allocates xadFileInfo
  103.                   structure.
  104.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  105.           XAD_OBJNAMESIZE, XAD_OBJCOMMENTSIZE, XAD_OBJBLOCKENTRIES,
  106.           XAD_OBJPRIVINFOSIZE
  107.  
  108.     RESULT
  109.         ptr     - Pointer to required structure or 0 when an error occured.
  110.  
  111.     SEE ALSO
  112.         libraries/xadmaster.h, xadFreeObject(), tags section
  113.  
  114. xadmaster.library/xadAllocVec                   xadmaster.library/xadAllocVec
  115.  
  116.     NAME
  117.         xadAllocVec - Allocate memory for xad related stuff (V2)
  118.  
  119.     SYNOPSIS
  120.         ptr = xadAllocVec(size, flags)
  121.         D0                 D0     D1
  122.  
  123.         APTR xadAllocVec(ULONG, ULONG)
  124.  
  125.     FUNCTION
  126.         This function allocates memory for a stuff related to xad. It is like
  127.         exec.library AllocVec() function, but uses xadFreeObject() to free
  128.         stuff and reduces the need for SysBase in clients. It's the prefered
  129.         method to allocate memory in clients.
  130.  
  131.     INPUT
  132.         size    - The size in bytes.
  133.         flags   - Normal MEMF_... flags defined in exec/types.h
  134.  
  135.     RESULT
  136.         ptr     - Pointer to required memory or 0 when an error occured.
  137.  
  138.     SEE ALSO
  139.         libraries/xadmaster.h, exec/types.h, exec.doc/AllocMem(),
  140.         xadFreeObject(),
  141.  
  142. xadmaster.library/xadCalcCRC16                 xadmaster.library/xadCalcCRC16
  143.  
  144.     NAME
  145.         xadCalcCRC16 - calculate a 16 bit CRC
  146.  
  147.     SYNOPSIS
  148.         crc16 = xadCalcCRC16(id, init, size, buffer)
  149.         D0                   D0   D1    D2     A0
  150.  
  151.     UWORD xadCalcCRC16(UWORD, UWORD, ULONG, STRPTR)
  152.  
  153.     FUNCTION
  154.     This function calculates a 16 bit CRC. It is possibly to choose the
  155.     calculation method by parameter mode.
  156.  
  157.     The CRC calculation uses a table built with following function:
  158.     void MakeCRC16(UWORD *buf, ULONG ID)
  159.     {
  160.         UWORD i, j, k;
  161.  
  162.       for(i = 0; i < 256; ++i)
  163.       {
  164.         k = i;
  165.  
  166.         for(j = 0; j < 8; ++j)
  167.         {
  168.           if(k & 1)
  169.             k = (k >> 1) ^ ID;
  170.           else
  171.             k >>= 1;
  172.         }
  173.         buf[i] = k;
  174.       }
  175.     }
  176.  
  177.     The used calculation routine is like that:
  178.         crc = init;
  179.         while(size--)
  180.           crc = tab[(crc ^ *buffer++) & 0xFF] ^ (crc >> 8);
  181.  
  182.     ID's defined in xadmaster.h use a default table. All others build the
  183.     table on the fly.
  184.     XADCRC16_ID1: (0xA001) - Used by DMS, Arc, ...
  185.  
  186.     INPUT
  187.     id    - The table creation ID (maybe XADCR16_ID value)
  188.     init    - The initial value for CRC calculation.
  189.         size    - The input buffer size.
  190.         buffer  - A pointer to the input buffer.
  191.  
  192.     RESULT
  193.         crc16    - The calculated CRC value.
  194.  
  195.     SEE ALSO
  196.         libraries/xadmaster.h, xadCalcCRC32
  197.  
  198. xadmaster.library/xadCalcCRC32                 xadmaster.library/xadCalcCRC32
  199.  
  200.     NAME
  201.         xadCalcCRC32 - calculate a 32 bit CRC
  202.  
  203.     SYNOPSIS
  204.         crc32 = xadCalcCRC32(id, init, size, buffer)
  205.         D0                   D0   D1    D2     A0
  206.  
  207.     ULONG xadCalcCRC32(ULONG, ULONG, ULONG, STRPTR)
  208.  
  209.     FUNCTION
  210.     This function calculates a 32 bit CRC. It is possibly to choose the
  211.     calculation method by parameter mode.
  212.  
  213.     The CRC calculation uses a table built with following function:
  214.     void MakeCRC32(ULONG *buf, ULONG ID)
  215.     {
  216.         ULONG i, j, k;
  217.  
  218.       for(i = 0; i < 256; ++i)
  219.       {
  220.         k = i;
  221.  
  222.         for(j = 0; j < 8; ++j)
  223.         {
  224.           if(k & 1)
  225.             k = (k >> 1) ^ ID;
  226.           else
  227.             k >>= 1;
  228.         }
  229.         buf[i] = k;
  230.       }
  231.     }
  232.  
  233.     The used calculation routine is like that:
  234.         crc = init;
  235.         while(size--)
  236.           crc = tab[(crc ^ *buffer++) & 0xFF] ^ (crc >> 8);
  237.  
  238.     ID's defined in xadmaster.h use a default table. All others build the
  239.     table on the fly.
  240.     XADCRC32_ID2: (0xEDB88320) - Used by Zoom, Zip, LZX, ...
  241.  
  242.     INPUT
  243.     id    - The table creation ID (maybe XADCR32_ID value)
  244.     init    - The initial value for CRC calculation.
  245.         size    - The input buffer size.
  246.         buffer  - A pointer to the input buffer.
  247.  
  248.     RESULT
  249.         crc32    - The calculated CRC value.
  250.  
  251.     SEE ALSO
  252.         libraries/xadmaster.h, xadCalcCRC16
  253.  
  254. xadmaster.library/xadConvertDates           xadmaster.library/xadConvertDates
  255.  
  256.     NAME
  257.         xadConvertDates - convert between date storage methods
  258.  
  259.     SYNOPSIS
  260.         result = xadConvertDatesA(tags)
  261.         D0                         A0
  262.  
  263.     LONG xadConvertDates(struct TagItem *)
  264.  
  265.         result = xadConvertDates(tag1, ...)
  266.  
  267.     LONG xadConvertDates(Tag, ...)
  268.  
  269.     FUNCTION
  270.     This function can be used to transfrom date and time between
  271.     different storage systems. One of the input tags must be specified.
  272.     Output tags may be specified multiple. The date information is
  273.     based on Gregorian calendar. Some systems can store a wider range
  274.     of dates than others. If a date produces an overflow or an
  275.     underflow for a special date, the highest/lowest valid date is used
  276.     (e.g. for timevalues 0x00000000 or 0xFFFFFFFF).
  277.  
  278.     The XAD_MAKEGMTDATE and XAD_MAKELOCALDATE tags need locale.library
  279.     to get the offset to local time. If locale.library cannot be opened
  280.     the offset is set to 0.
  281.  
  282.     XAD_DATECURRENTTIME can be used to get the current system date and
  283.     time.
  284.  
  285.     WeekDay information is ignored for input and always recalculated.
  286.     The calculation routines use full range of available variable space,
  287.     so f.e. a Unix date 1.1.1970 00:00:00 (value 0x00000000) with a
  288.     UTC offset of -30 min produces 31.12.1968 23:30:00 (which cannot be
  289.     stored as UNIX time value, but only as xadDate structure)!.
  290.  
  291.     INPUT
  292.     ai    - the master communication structure
  293.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  294.           XAD_DATEUNIX, XAD_DATEAMIGA, XAD_DATEDATESTAMP,
  295.               XAD_DATEXADDATE, XAD_DATECLOCKDATA, XAD_DATECURRENTTIME,
  296.               XAD_DATEMSDOS, XAD_GETDATEUNIX, XAD_GETDATEAMIGA,
  297.               XAD_GETDATEDATESTAMP, XAD_GETDATEXADDATE,
  298.               XAD_GETDATECLOCKDATA, XAD_GETDATEMSDOS, XAD_MAKEGMTDATA,
  299.               XAD_MAKELOCALDATE
  300.  
  301.     RESULT
  302.         result    - any of the XADERR codes or zero when all is ok.
  303.  
  304.     SEE ALSO
  305.         libraries/xadmaster.h, tags section
  306.  
  307. xadmaster.library/xadCopyMem                     xadmaster.library/xadCopyMem
  308.  
  309.     NAME
  310.         xadCopyMem - copies one data block to another position
  311.  
  312.     SYNOPSIS
  313.         xadCopyMem(src, dest, size)
  314.                     A0   A1    D0
  315.  
  316.     void xadCopyMem(APTR, APTR, ULONG)
  317.  
  318.     FUNCTION
  319.     CopyMem is a general purpose memory copy function. It can deal with
  320.     any length and its pointers on any alignment. It tries to optimize
  321.     the copy operation, when alignment and size allow longword copies.
  322.  
  323.     Overlapping copies are supported in both directions.
  324.  
  325.     The internal implementation of this function will change from
  326.     system to system and version to version.
  327.     This copy function is not highly optimized, but should fit any needs
  328.     around xadmaster.library!
  329.  
  330.     INPUT
  331.     src    - the source buffer
  332.         dest    - the destination buffer
  333.     size    - the size to copy
  334.  
  335.     RESULT
  336.         none
  337.  
  338.     SEE ALSO
  339.         libraries/xadmaster.h, exec.library/CopyMem()
  340.  
  341. xadmaster.library/xadDiskUnArc                 xadmaster.library/xadDiskUnArc
  342.  
  343.     NAME
  344.         xadDiskUnArc - the master function for unarchiving disks
  345.  
  346.     SYNOPSIS
  347.         result = xadDiskUnArcA(ai, tags)
  348.         D0                    A0   A1
  349.  
  350.     LONG xadDiskUnArc(struct xadArchiveInfo *, struct TagItem *)
  351.  
  352.         result = xadDiskUnArc(ai, tag1, ...)
  353.  
  354.     LONG xadDiskUnArc(struct xadArchiveInfo *, Tag, ...)
  355.  
  356.     FUNCTION
  357.     This function dearchives a disk archive. It can be called after
  358.     a succesful call to xadGetInfo. At least the tag XAD_ENTRYNUMBER
  359.     and one of the output tags needs to be supplied. When a progress
  360.     hook is supplied, this can be used for questioning for overwriting
  361.     and ignoring of drive geometry and for status displays.
  362.     Normally disk archivers will have only one entry, but there may
  363.     be multiple disk archives.
  364.  
  365.     When this function returns, the supplied output data streams may
  366.     be used in any way (files, memory). The library does not even know
  367.     that they exist! The xadmaster.library cannot be used to rename,
  368.     protect, comment or delete that stuff!
  369.  
  370.     INPUT
  371.     ai    - the master communication structure
  372.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  373.                 XAD_ENTRYNUMBER, XAD_OUTFILEHANDLE, XAD_OUTFILENAME,
  374.           XAD_OUTHOOK, XAD_OUTMEMORY, XAD_OUTSIZE, XAD_OVERWRITE,
  375.           XAD_PROGRESSHOOK, XAD_IGNOREGEOMETRY, XAD_HIGHCYLINDER,
  376.           XAD_LOWCYLINDER, XAD_OUTDEVICE, XAD_VERIFY, XAD_PASSWORD
  377.  
  378.     RESULT
  379.         result    - any of the XADERR codes or zero when all is ok.
  380.  
  381.     SEE ALSO
  382.         libraries/xadmaster.h, xadFileUnArc(), xadGetInfo(), tags section
  383.  
  384. xadmaster.library/xadFileUnArc                 xadmaster.library/xadFileUnArc
  385.  
  386.     NAME
  387.         xadFileUnArc - the master function for unarchiving disks
  388.  
  389.     SYNOPSIS
  390.         result = xadFileUnArcA(ai, tags)
  391.         D0                    A0   A1
  392.  
  393.     LONG xadFileUnArc(struct xadArchiveInfo *, struct TagItem *)
  394.  
  395.         result = xadFileUnArc(ai, tag1, ...)
  396.  
  397.     LONG xadFileUnArc(struct xadArchiveInfo *, Tag, ...)
  398.  
  399.     FUNCTION
  400.     This function dearchives a file archive entry. It can be called
  401.     after a succesful call to xadGetInfo. At least the tag
  402.     XAD_ENTRYNUMBER and one of the output tags needs to be supplied.
  403.     When a progress hook is supplied, this can be used for questioning
  404.     for overwriting and for status displays.
  405.     This function needs to be called for every file, which should be
  406.     unarchived. Best is to do unarchiving in direction giving by
  407.     info structure, because some archivers crunch multiple files in one
  408.     pass and the unarchiver needs to compress and buffer the whole
  409.     pass to get one file.
  410.  
  411.     When this function returns, the supplied output data streams may
  412.     be used in any way (files, memory). The library does not even know
  413.     that they exist! The xadmaster.library cannot be used to rename,
  414.     protect, comment or delete that stuff!
  415.  
  416.     INPUT
  417.     ai    - the master communication structure
  418.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  419.                 XAD_ENTRYNUMBER, XAD_OUTFILEHANDLE, XAD_OUTFILENAME,
  420.           XAD_OUTHOOK, XAD_OUTMEMORY, XAD_OUTSIZE, XAD_OVERWRITE,
  421.           XAD_PROGRESSHOOK, XAD_PASSWORD
  422.  
  423.     RESULT
  424.         result    - any of the XADERR codes or zero when all is ok.
  425.  
  426.     SEE ALSO
  427.         libraries/xadmaster.h, xadDiskUnArc(), xadGetInfo(), tags section
  428.  
  429. xadmaster.library/xadFreeInfo                   xadmaster.library/xadFreeInfo
  430.  
  431.     NAME
  432.         xadFreeInfo - free stuff built and allocated with xadGetInfo()
  433.  
  434.     SYNOPSIS
  435.         xadFreeInfo(ai)
  436.                     A0
  437.  
  438.         void xadFreeInfo(struct xadArchiveInfo *)
  439.  
  440.     FUNCTION
  441.         Frees all the stuff built and allocated by a call to xadGetInfo().
  442.     You always need to call this after your work with a certain input
  443.     file is finished.
  444.  
  445.     INPUTS
  446.         ai    - the master communication structure
  447.  
  448.     SEE ALSO
  449.         libraries/xadmaster.h, xadGetInfo(), tags section
  450.  
  451. xadmaster.library/xadFreeObject               xadmaster.library/xadFreeObject
  452.  
  453.     NAME
  454.         xadFreeObject - Frees structures allocated with xadAllocObject() or
  455.                 xadAllocVec()
  456.  
  457.     SYNOPSIS
  458.         xadFreeObjectA(object, tags)
  459.                          A0      A1
  460.  
  461.         void xadFreeObjectA(APTR, struct TagItem *)
  462.  
  463.         xadFreeObject(object, tag1, ...)
  464.  
  465.         void xadFreeObject(APTR, Tag, ...)
  466.  
  467.     FUNCTION
  468.         Frees object allocated by xadAllocObject() or AllocVec(). Do not call
  469.         for objects allocated in any other way.
  470.         This function frees ALL memory which was allocated by xadAllocObject(),
  471.         but only this memory. This means all name buffers and other related
  472.         structures are freed, but if you replace pointers, your replacements
  473.         get not freed. This function does not need the original pointers to be
  474.         in the related positions, as the buffer size is stored elsewhere.
  475.  
  476.     INPUTS
  477.         object    - object allocated with xadAllocObject() or xadAllocVec()
  478.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  479.           currently none
  480.  
  481.     SEE ALSO
  482.         libraries/xadmaster.h, xadAllocObject(), xadAllocVec(), tags section
  483.  
  484. xadmaster.library/xadGetClientInfo         xadmaster.library/xadGetClientInfo
  485.  
  486.     NAME
  487.         xadGetClientInfo - Get list of active clients
  488.  
  489.     SYNOPSIS
  490.         ptr = xadGetClientInfo()
  491.         D0
  492.  
  493.         struct xadClient *xadGetClientInfo(void)
  494.  
  495.     FUNCTION
  496.     This function returns a list of all active clients. It can be used
  497.     to show information about the library. The list is read only and
  498.     cannot be modified!
  499.  
  500.     RESULT
  501.         ptr    - Pointer to first client in the list.
  502.  
  503.     SEE ALSO
  504.         libraries/xadmaster.h
  505.  
  506. xadmaster.library/xadGetErrorText           xadmaster.library/xadGetErrorText
  507.  
  508.     NAME
  509.         xadGetErrorText - Get error string from an error number
  510.  
  511.     SYNOPSIS
  512.         ptr = xadGetErrorText(errnum)
  513.         D0                    D0
  514.  
  515.         STRPTR xadGetErrorText(ULONG)
  516.  
  517.     FUNCTION
  518.     This function returns the error string related to the supplied
  519.     error number. This string is valid as long as xadmaster.library
  520.     is opened, so when needed any longer time it must be copied.
  521.  
  522.     INPUT
  523.         errnum    - in libraries/xadmaster.h defined XADERR_... numbers.
  524.  
  525.     RESULT
  526.         ptr    - Pointer to required string.
  527.  
  528.     SEE ALSO
  529.         libraries/xadmaster.h
  530.  
  531. xadmaster.library/xadGetInfo                     xadmaster.library/xadGetInfo
  532.  
  533.     NAME
  534.         xadGetInfo - get information about an archive
  535.  
  536.     SYNOPSIS
  537.         result = xadGetInfoA(ai, tags)
  538.         D0                    A0   A1
  539.  
  540.     LONG xadGetInfo(struct xadArchiveInfo *, struct TagItem *)
  541.  
  542.         result = xadGetInfo(ai, tag1, ...)
  543.  
  544.     LONG xadGetInfo(struct xadArchiveInfo *, Tag, ...)
  545.  
  546.     FUNCTION
  547.     This function returns all useful information about a specified
  548.     archive. It opens the archive for working. You may call
  549.     xadFileUnArc() or xadDiskUnArc() for the included entries
  550.     after a successful call to xadGetInfo. The data must be freed
  551.     by a call to xadFreeInfo(). After that the xadArchiveInfo structure
  552.     must be freed and NEVER be used again! For archives encrypting
  553.     the information parts as well, you need to specify XAD_PASSWORD.
  554.     This password can be used for all calls to a unarchiving function,
  555.     but is overwritten by XAD_PASSWORD tag argument (only for the
  556.     entry XAD_PASSWORD is specified). Check and parse the elements
  557.     xai_FileInfo and xai_DiskInfo. You may expect both lists to have
  558.     valid entries or also both to be empty. Parsing the lists is the
  559.     normal way to do anything.
  560.  
  561.     The supplied input stream is used and must be valid and unmodified
  562.     until xadFreeInfo() is called. Only the current client is allowed to
  563.     access the stream, but it is guaranteed to be unmodified!
  564.  
  565.     INPUT
  566.     ai    - the master communication structure
  567.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  568.           XAD_INSIZE, XAD_INFILENAME, XAD_INFILEHANDLE,
  569.           XAD_INMEMORY, XAD_INHOOK, XAD_PASSWORD
  570.  
  571.     RESULT
  572.         result    - any of the XADERR codes or zero when all is ok.
  573.  
  574.     SEE ALSO
  575.         libraries/xadmaster.h, xadFreeInfo(), xadDiskUnArc(),
  576.         xadFileUnArc(), tags section
  577.  
  578. xadmaster.library/xadHookAccess               xadmaster.library/xadHookAccess
  579.  
  580.     NAME
  581.         xadHookAccess - a client only function to get/store data
  582.  
  583.     SYNOPSIS
  584.         result = xadHookAccess(command, data, buffer, ai)
  585.         D0                       D0      D1     A0    A1
  586.  
  587.     LONG xadHookAccess(ULONG, LONG, APTR, struct xadArchiveInfo *)
  588.  
  589.     FUNCTION
  590.     This function is for external clients only. It is needed to get
  591.     data, store results and seek in input or output. There are 5
  592.     commands XADAC_READ, XADAC_WRITE, XADAC_COPY, XADAC_INPUTSEEK,
  593.     XADAC_OUTPUTSEEK to do that. This function updates the xai_InPos,
  594.     xai_OutPos and xai_OutSize fields in xadArchiveInfo structure. The
  595.     seek commands and the copy command should set buffer parameter to
  596.     zero. Seek's and reads should not exceed the file borders! The
  597.     client knows position and size, so checks are possible before doing
  598.     wrong commands.
  599.  
  600.     INPUT
  601.         command - one of the XADAC command to control hook
  602.         data    - the required data, mostly a size value
  603.         buffer    - the input/output buffer for read and write
  604.     ai    - the master communication structure
  605.  
  606.     RESULT
  607.         result    - any of the XADERR codes or zero when all is ok.
  608.  
  609.     SEE ALSO
  610.         libraries/xadmaster.h
  611.  
  612. xadmaster.library/xadRecogFile                 xadmaster.library/xadRecogFile
  613.  
  614.     NAME
  615.         xadRecogFile - check if a file is an archive file or not
  616.  
  617.     SYNOPSIS
  618.         client = xadRecogFileA(size, memory, tags)
  619.         D0                     D0     A0     A1
  620.  
  621.         struct xadClient *xadRecogFileA(ULONG, APTR, struct TagItem *)
  622.  
  623.         client = xadRecogFileA(size, memory, tag1, ...)
  624.  
  625.         struct xadClient *xadRecogFileA(ULONG, APTR, Tag, ...)
  626.  
  627.     FUNCTION
  628.     This function can be used to check if a file is a archive or not.
  629.     It has only limited abilities! You need to pass a pointer to
  630.     memory of recogsize. The recogsize value can be found in
  631.     xadMasterBase. If the file is shorter, use the complete file as
  632.     buffer. Longer buffers are allowed as well. When the file is
  633.     archived, you get back a pointer to the client which detected the
  634.     file. If not, the return is zero. The only usable information
  635.     should be the name of the client. To get more information and all
  636.     archive related data you have to use xadGetInfo, which calls
  637.     xadRecogFile internal itself.
  638.  
  639.     Normally this function is not needed by application programs. It
  640.     is used in xadList utility. This function is useful for tools
  641.     only detecting and displaying the archiver type.
  642.  
  643.     INPUT
  644.         size    - size of the memory region
  645.     memory    - pointer to the memory holding the file
  646.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  647.           XAD_NOEXTERN
  648.  
  649.     RESULT
  650.         client    - pointer to client structure or zero when no archive
  651.  
  652.     SEE ALSO
  653.         libraries/xadmaster.h, xadGetInfo(), tags section
  654.  
  655. xadmaster.library/--tags--                         xadmaster.library/--tags--
  656.  
  657.     TAGS FOR xadAllocObject
  658.  
  659.       XAD_OBJBLOCKENTRIES    (ULONG)
  660.     Can be specified together with XADOBJ_DISKINFO. This allocates
  661.     memory for xdi_BlockInfo. Data field of tag item contains number
  662.     of required blocks. Memory gets freed automatically, when object
  663.     is freed.
  664.  
  665.       XAD_OBJCOMMENTSIZE    (ULONG)
  666.     Like XAD_OBJNAMESIZE, but allocates memory for xfi_Comment entry.
  667.  
  668.       XAD_OBJNAMESIZE        (ULONG)
  669.     Can be specified together with XADOBJ_FILEINFO. This allocates
  670.     memory for storing file name. The required size has to be stored
  671.     in data field of tag item. The allocated memory pointer is stored
  672.     in xfi_FileName field of returned structure. Memory gets freed
  673.     automatically, when object is freed.
  674.  
  675.       XAD_OBJPRIVINFOSIZE    (ULONG)
  676.     Can be specified together with XADOBJ_FILEINFO and XADOBJ_DISKINFO.
  677.     This allocates longword aligned client private buffer, which is
  678.     stored in xfi_PrivateInfo or xdi_PrivateInfo field. The required
  679.     size has to be stored in data field of tag item. Memory gets freed
  680.     automatically, when object is freed.
  681.  
  682.     TAGS FOR xadGetInfo
  683.  
  684.       XAD_INFILEHANDLE        (BPTR)
  685.     FileHandle to get data from. It is not necessary that the handle
  686.     is at the beginning of the file.
  687.  
  688.       XAD_INFILENAME        (STRPTR)
  689.     Name of the input file.
  690.  
  691.       XAD_INHOOK        (struct Hook *)
  692.     This enables any other way of data delivering. See special
  693.     chapter on I/O hook functions.
  694.  
  695.       XAD_INMEMORY        (STRPTR)
  696.         Pointer to a memory buffer holding the input data. You need to
  697.         specify XAD_INSIZE when using this.
  698.  
  699.       XAD_INSIZE        (ULONG)
  700.     Specify the size of input data. Must be used together with
  701.     XAD_INMEMORY. Can be used together with other hooks.
  702.  
  703.       XAD_INSPLITTED        (struct xadSplitFile *)
  704.     For multivolume archives it is necessary to supply multiple files.
  705.     This tag allows to pass multiple input streams of any type in a
  706.     linked list of xadSplitFile structures. The clients see that as
  707.     one single continous stream (except that ai->xai_MultiVolume
  708.     contains a field with size information for every part).
  709.     Each entry must contain one of the other input types and the
  710.     corresponding data. Also the size can be or must be (XAD_INMEMORY)
  711.     passed in xadSplitFile structure.
  712.     Clients could expect the parts in it correct order, but should be
  713.     able to handle missing or corrupted part.
  714.  
  715.     TAGS FOR xadFileUnArc and xadDiskUnArc
  716.  
  717.       XAD_ENTRYNUMBER        (ULONG)
  718.     This flag specifies the wanted entry. You must not specify more
  719.     or less than one of that flag every call. Normally this flag equals
  720.     the element xdi_EntryNumber for currently parsed xadDiskInfo
  721.     structure and xfi_EntryNumber for currently parsed xadFileInfo
  722.     structure.
  723.  
  724.       XAD_MAKEDIRECTORY        (BOOL)
  725.     Create missing directory tree when necessary. If not set the
  726.     progress hook may get asked if directory should be created or
  727.     not (if there is one).
  728.  
  729.       XAD_OUTFILEHANDLE        (BPTR)
  730.     FileHandle to send data to. It is not necessary that the handle
  731.     is at the beginning of the file.
  732.  
  733.       XAD_OUTFILENAME        (STRPTR)
  734.     Name of the output file.
  735.  
  736.       XAD_OUTHOOK        (struct Hook *)
  737.     This enables any other way of data storing. See special chapter
  738.     on I/O hook functions.
  739.  
  740.       XAD_OUTMEMORY        (STRPTR)
  741.         Pointer to a memory buffer to store data in. You need to specify
  742.         XAD_OUTSIZE when using this.
  743.  
  744.       XAD_OUTSIZE        (ULONG)
  745.     Specify the maximum size of output data. Must be used together with
  746.     XAD_OUTMEMORY.
  747.  
  748.       XAD_OVERWRITE        (BOOL)
  749.     This forces the file hook to overwrite existing destination files.
  750.     If not set the progress hook may get asked if files should be
  751.     overwritten or not (if there is one).
  752.  
  753.       XAD_PROGRESSHOOK        (struct Hook *)
  754.     The progress hook for status displays. See special progress hook
  755.     chapter for more information.
  756.  
  757.     TAGS FOR xadDiskUnArc
  758.  
  759.       XAD_IGNOREGEOMETRY    (BOOL)
  760.     This forces the device hook to use devices with different drive
  761.     geometry than the one on disk archive. Most time this will produce
  762.     useless disks. If not set the progress hook may get asked if
  763.     geometry should be ignored or not (if there is one).
  764.  
  765.       XAD_HIGHCYLINDER        (ULONG)
  766.     It specifies the highest cylinder which should be unarchived.
  767.  
  768.       XAD_LOWCYLINDER        (ULONG)
  769.     It specifies the lowest cylinder which should be unarchived.
  770.  
  771.       XAD_OUTDEVICE        (struct xadDeviceInfo *)
  772.     For disk archives it is useful to store data directly on a disk.
  773.     Use this tag to specify the device where data should be stored.
  774.         In xdi_DOSName the DOS device must be stored, which must not be
  775.         terminated with a ':' character.
  776.         Alternatively in fields xdi_DeviceName and xdi_Unit the wanted
  777.         device must be specified. The device must support TD_GETGEOMETRY
  778.         command, even if XAD_IGNOREGEOMETRY is turned on, as the hook
  779.         needs at least the blocksize for internal buffering.
  780.         NOTE: When xdi_DeviceName and xdi_Unit is used, the hook cannot
  781.         perform an Inhibit operation and thus it cannot prevent other
  782.         tasks from accessing the device. Also a DOS device is not updated,
  783.         so a DiskChange becomes necessary.
  784.         I suggest always using xdi_DOSName field!
  785.       
  786.       XAD_VERIFY        (BOOL)
  787.         Turns on verify for device output. This is turned off by default.
  788.  
  789.     TAGS FOR xadConvertDates
  790.  
  791.       XAD_DATEUNIX        (ULONG)
  792.     Input is an UNIX date value (seconds starting with 01.01.1970).
  793.  
  794.       XAD_DATEAMIGA        (ULONG)
  795.     Input as an Amiga date value (seconds starting with 01.01.1978).
  796.  
  797.       XAD_DATEDATESTAMP        (struct DateStamp *)
  798.     Input is a pointer to an Amiga DateStamp structure.
  799.  
  800.       XAD_DATEXADDATE        (struct xadDate *)
  801.     Input is a pointer to a xadmaster date structure.
  802.  
  803.       XAD_DATECLOCKDATA        (struct ClockData *)
  804.     Input is a pointer to a ClockData structure.
  805.  
  806.       XAD_DATECURRENTTIME    (void)
  807.     Current system time value should be used as input.
  808.  
  809.       XAD_DATEMSDOS        (ULONG)
  810.     Input is an 32 bit packed date format used by MS-DOS. This means:
  811.     Bit 0..4 is half second (25 = second 49 or 50), 5..10 is minute,
  812.     11..15 is hour, 16..20 is day, 21..24 is month (1 = january) and
  813.     25..31 is year (0 = year 1980). This format is used for archivers
  814.     like RAR or Zip.
  815.  
  816.       XAD_GETDATEUNIX        (ULONG *)
  817.     An UNIX time value should be stored in the ULONG variable, the
  818.     supplied pointer points to.
  819.  
  820.       XAD_GETDATEAMIGA        (ULONG *)
  821.     An Amiga time value should be stored in the ULONG variable, the
  822.     supplied pointer points to.
  823.  
  824.       XAD_GETDATEDATESTAMP    (struct DateStamp *)
  825.     The date should be stored in DateStamp structure the supplied
  826.     pointer points to.
  827.  
  828.       XAD_GETDATEXADDATE    (struct xadDate *)
  829.     The date should be stored in xadmaster date structure the supplied
  830.     pointer points to.
  831.  
  832.       XAD_GETDATECLOCKDATA    (struct ClockData *)
  833.     The date should be stored in ClockData structure the supplied
  834.     pointer points to.
  835.  
  836.       XAD_GETDATEMSDOS        (ULONG *)
  837.     An MS-DOS packed date value should be stored in the ULONG variable,
  838.     the supplied pointer points to.
  839.  
  840.       XAD_MAKEGMTDATE        (BOOL)
  841.     This forces the function to subtract the GMT offset supplied by
  842.     locale.library to convert a local date to GMT date. Opening
  843.     locale.library is required for that. When it cannot be openend or
  844.     the offset would cause a overrun or underrun in the xd_Year field,
  845.     no offset will be used. 
  846.       
  847.       XAD_MAKELOCALDATE        (BOOL)
  848.     This forces the function to ad the GMT offset supplied by
  849.     locale.library to convert a GMT date to a local date. Opening
  850.     locale.library is required for that. When it cannot be openend or
  851.     the offset would cause a overrun or underrun in the xd_Year field,
  852.     no offset will be used.
  853.  
  854.     TAGS FOR different functions
  855.  
  856.       XAD_NOEXTERN        (BOOL)
  857.     When this is specified for xadGetInfo or xadRecogFile, the library
  858.     skips any external clients. Normally this should not be necessary.
  859.     Some of the main clients are external as well (for legal reasons).
  860.  
  861.       XAD_PASSWORD        (STRPTR)
  862.     You may supply a password for xadGetInfo, xadFileUnArc and
  863.     xadDiskUnArc functions.
  864.  
  865. xadmaster.library/-- data hooks--            xadmaster.library/--data hooks--
  866.  
  867.     GENERAL
  868.     You have four methods of passing data to xadmaster.library: file-
  869.     names, filehandles, memory areas and hooks. The hooks are described
  870.     here. The hook field h_Entry has to be standard hook functions and
  871.     gets called with the hook itself in A0 and a pointer to a
  872.     xadHookParam in A1. Commands are stored in xhp_Command field, data
  873.     in the other fields. Return values are 0 or any of the XADERR codes.
  874.     Unsupported commands are returned with XADERR_NOTSUPPORTED.
  875.  
  876.     You may store a pointer to private data in the field xhp_PrivatePtr.
  877.     You always get a XADHC_FREE after work to enable you freeing your
  878.     resources.
  879.  
  880.     Whenever an error occured, the hook gets called with XADHC_ABORT.
  881.     Use this to delete partial file, free useless memory or whatever
  882.     you used. You must not do cleanup stuff on XADHC_ABORT call, as 
  883.     XADHC_FREE call follows after it.
  884.     
  885.         NOTE: Because hooks are not called in program environment, they
  886.         cannot be used in small data model of some compilers, as register
  887.         A4 is not passed through. So the hook either has to be compiled in
  888.         large data model or should use __saveds keyword of some compilers.
  889.  
  890.     COMMANDS
  891.       XADHC_READ        (input hooks only)
  892.     This command is called all time xadmaster.library needs some data.
  893.     Fill the supplied memory area with input data of needed size.
  894.     Input:    xhp_BufferSize    size of required data
  895.         xhp_BufferPtr    buffer to fill
  896.     Output:    xhp_DataPos    buffer position after read
  897.  
  898.       XADHC_WRITE        (output hooks only)
  899.     This function is called, when some data should be stored. Copy
  900.     the contents of buffer to your data storing system.
  901.     Input:    xhp_BufferSize    size of data
  902.         xhp_BufferPtr    pointer to memory area
  903.     Output:    xhp_DataPos    buffer position after write
  904.  
  905.       XADHC_SEEK        (both)
  906.     Change the current position in your data (like dos.library Seek
  907.     command). The offset you have to seek is always relative to
  908.     current position. It can be negative too. Seek's with size 0 can
  909.     be used to get current file position.
  910.     Input:    xhp_CommandData    offset you have to seek
  911.     Output:    xhp_DataPos    buffer position after seek
  912.  
  913.       XADHC_INIT        (both)
  914.     The work starts. Allocate needed structures and initialize your
  915.     stuff. Clear xhp_BufferPos.
  916.     Input:    none
  917.     Output:    none
  918.  
  919.       XADHC_FREE        (both)
  920.     You get this when work is finished, free all your stuff now. You
  921.     need to clear all pointers you use for checking, as it may happen
  922.     that you get multiple XADHC_FREE commands.
  923.     Input:    none
  924.     Output:    none
  925.  
  926.       XADHC_ABORT        (output hooks only)
  927.     You get this when work was aborted, because an error occured.
  928.     Free all work stuff. Buffers must be freed by later XADHC_FREE call.
  929.     Be prepared to get multiple XADHC_ABORT commands.
  930.     Input:    none
  931.     Output:    none
  932.  
  933.       XADHC_FULLSIZE        (input hooks only)
  934.     The hook should return complete size of input data which should be
  935.     processed.
  936.     Input:    none
  937.     Output:    xhp_CommandData    size of input file
  938.  
  939. xadmaster.library/-- progress hooks--    xadmaster.library/--progress hooks--
  940.  
  941.     GENERAL
  942.     This hook can be used to do display completion reports or ask the
  943.     user. It gets a pointer to a xadProgressInfo structure. The hook
  944.     returns a combination of XADPIF flags. A return value without
  945.     XADPIF_OK (mostly 0) means a break command. Normally a hook should
  946.     check for <CTRL>-<C> presses (or any other break condition) and add a
  947.     XADPIF_OK to return value when no break condition exists.
  948.  
  949.     A progress hook must not support all possibilities! For example hooks
  950.     from file unarchiving utilities never need an XADPIF_IGNOREGEOMETRY
  951.     check. Also they need not support renaming or any other stuff. But
  952.     the more they support, the better the user can work with the tool!
  953.  
  954.     MODES
  955.       XADPMODE_ASK
  956.     The master library has some problems, which need user interaction.
  957.     The implementation of the user interaction depends on the
  958.     application. The xpi_Status holds information what question needs to
  959.     be answered. When XADPIF_OVERWRITE is set, the hook must determine if
  960.     the file should be overwritten, renamed or not. The return flags
  961.     must be set corresponding to this decision. Same is for
  962.     XADPIF_IGNORGEGEOMETRY and XADPIF_MAKEDIRECTORY flag.
  963.  
  964.     XADPIF_IGNOREGEOEMTRY
  965.       The hook either returns XADPIK_OK|XADPIF_IGNOREGEOMETRY or only
  966.       XADPIF_OK, when user doesn't think geometry can be ignored.
  967.  
  968.     XADPIF_MAKEDIRECTORY
  969.       The hook either returns XADPIK_OK|XADPIF_MAKEDIRECTORY or only
  970.       XADPIF_OK, when user doesn't want to make directory.
  971.  
  972.     XADPIF_OVERWRITE
  973.       The destination file already exists. The user should get 6 chances
  974.       now (named with some standard letters).
  975.       N - Do not do anything. The hook returns XADPIF_OK.
  976.       Y - Turn overwrite on. The hook returns XADPIF_OK|XADPIF_OVERWRITE.
  977.       A - Turn overwrite on for all files. The hook stores this
  978.           information and returns XADPIF_OK|XADPIF_OVERWRITE. All
  979.           following XADPIF_OVERWRITE requests are automatically answered
  980.           with this return.
  981.       S - Skip that file. The hook returns XADPIF_OK|XADPIF_SKIP.
  982.       Q - Quit the program. The hook returns XADPIF_OK and the program
  983.           quits before next call.
  984.       R - The user wants to rename the file. The hook calls xadAllocVec()
  985.           to get some memory for the name and passes this in xpi_NewName.
  986.           This memory is freed by xadmaster.library afterwards!
  987.           The return value is XADPIF_OK|XADPIF_RENAME.
  988.  
  989.       XADPMODE_END
  990.         This is the last progress display with final results.
  991.  
  992.       XADPMODE_ERROR
  993.         An error occured. The error value is in xpi_Error field.
  994.  
  995.       XADPMODE_PROGRESS
  996.         Normal progress display. Depending on data type (disk/file), some
  997.         progress information can be displayed.
  998.  
  999.     RETURN VALUES
  1000.       0 or anything without XADPIF_OK
  1001.     The work should be aborted. The master library returns XADERR_BREAK.
  1002.  
  1003.       XADPIF_OK
  1004.     No break condition occured. The normal return value for progress
  1005.     display. Also used when user choosed to answer NO to XADPMODE_ASK
  1006.     questions.
  1007.  
  1008.       XADPIF_OK|XADPIF_IGNOREGEOMETRY
  1009.     User choosed that drive geometry can be ignored.
  1010.  
  1011.       XADPIF_OK|XADPIF_MAKEDIRECTORY
  1012.     User choosed that directory should be created.
  1013.  
  1014.       XADPIK_OK|XADPIF_OVERWRITE
  1015.     User choosed that file should be overwritten.
  1016.  
  1017.       XADPIF_OK|XADPIF_RENAME
  1018.     User choosed that file should be renamed. The field xpi_NewName must
  1019.     contain a memory block allocated with xadAllocVec() which holds a new
  1020.     file name. This block is freed by xadmaster.library afterwards!
  1021.  
  1022.       XADPIF_OK|XADPIF_SKIP
  1023.     User choosed to skip that file. The master library returns XADERR_SKIP
  1024.     in that case.
  1025.  
  1026.