home *** CD-ROM | disk | FTP | other *** search
/ ANews 1 / AnewsCD01.iso / Indispensables / Compression / xad / Developer / Include / Autodocs / xadsub.doc < prev   
Text File  |  1999-08-09  |  11KB  |  260 lines
  1. TABLE OF CONTENTS
  2.  
  3. xadForeman/--Overview--
  4. xadClient/--Overview--
  5. xadClient/xcFree
  6. xadClient/xcGetInfo
  7. xadClient/xcRecogData
  8. xadClient/xcUnArchive
  9.  
  10. VERSION
  11.     $VER: xadsub.doc 2.1 (29.06.1999) by SDI
  12.  
  13. xadForeman/--Overview--                               xadForeman/--Overview--
  14.  
  15. The xadForeman structure is just some kind of header for external clients.
  16. It protects the clients from being executed accidentally by having a small
  17. piece of code (MOVEQ #-1,d0 : RTS) in the first 4 bytes.
  18. The master can identify a valid bunch of external clients by checking the
  19. first hunk of a file for the foreman identification.
  20. Finally, a foreman holds the pointer to a linked list of clients and thus
  21. enables the master to work with these clients.
  22.  
  23. xadClient/--Overview--                                 xadClient/--Overview--
  24.  
  25. The xadClient structure is the heart of the whole library system. Each
  26. client enables the master to recognize and unarchive files.
  27.  
  28. Therefore each client contains 4 routines that are called from the master.
  29. Pointers to these are stored in xc_RecogData, xc_GetInfo, xc_UnArchive and
  30. xc_Free.
  31.  
  32. All routines have one thing in common: the CPU registers D0/D1/A0/A1 are
  33. so-called scratch registers, they may change during execution, all other
  34. registers must remain unchanged. CPU register A6 holds a pointer to the
  35. xadMasterBase structure. See chapters below for a description of the client
  36. routines.
  37.  
  38. ALL CLIENT ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC
  39. MEMORY AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT
  40. THE ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME! DO
  41. NOT EXCEED STACK USAGE (1KB SHOULD BE THE MAXIMUM), AS PROGRAMS NORMALLY
  42. HAVE ONLY 4KB STACK.
  43.  
  44. The name of the archiver that is supported by the client and the flags that
  45. describe the packer are stored in xc_ArchiverName and xc_Flags. Internal
  46. clients all have an unique ID value stored in xc_Identifier. If you have
  47. written a client that should replace an internal one, because it is faster
  48. or otherwise enhanced, simply put the ID of the client to be replaced in
  49. xc_Identifier. The old client will then be taken out of the list of used
  50. clients. Normally this ID should be zero. There is one problem with this:
  51. When the user deactivates external clients the xadmaster system is missing
  52. this type completely as internal client is not activated in this case.
  53.  
  54. xcRecogData() usually only requires a quite small part of a file to
  55. recognize it properly. To avoid reading the whole file for recognition
  56. purposes, you need to set xc_RecogSize to the minimum amount of bytes
  57. that is required to recognize the crunched file correctly.
  58. Note that xadmaster uses this value internally to decide whether a file
  59. might be archived with a archiver or not, so you don't have to do an extra
  60. size comparison in your xc_RecogData function any more.
  61. For archiver headers with non-constant sizes, simply set xc_RecogSize
  62. to a value that will ensure correct recognition of all possible files.
  63.  
  64. Whenever you intend to use features of the xadmaster.library in your
  65. clients that are marked (V2) or higher, make sure to set xc_MasterVersion
  66. to the desired version number, otherwise an old library version might
  67. crash while using the new client.
  68.  
  69. Whenever a client calls a xadmaster function and gets a return code, the
  70. client needs to return this code! So whenever an error code is produced
  71. somewhere, it must reach the calling program. This is most important
  72. for progress report (automatically called by xadHookAccess), as the
  73. XADERR_SKIP can be checked by calling program.
  74.  
  75. ANY needed structure must be allocated with xadAllocObject! None of the
  76. XAD structures can be allocated any other way!
  77.  
  78. Multivolume support:
  79. This system also supports multivolume archives. A special multivolume
  80. input stream (XAD_INSPLITTED) allows to pass multiple input files as
  81. one stream to the clients. This means multivolume archiver files are
  82. passed as ONE stream to the related client. The client may check the
  83. ai->xai_MultiVolume entry. This is an ULONG array witch holds the start
  84. offset of every part and is finished with an zero value. The client may
  85. expect the parts to be in correct order, but must handle missing or
  86. defective parts (Handling of defective archives is necessary for normal
  87. archives as well!). Do not rely to much on part size information, as
  88. missing parts or defective parts normally will destroy the usefulness
  89. of that size information.
  90.  
  91. xadClient/xcFree                                             xadClient/xcFree
  92.  
  93.    NAME
  94.     xcFree -- Free all resources allocated by xcGetInfo
  95.  
  96.    SYNOPSIS
  97.     xcFree(ai, xadMasterBase)
  98.            A0       A6
  99.  
  100.     void xcFree(struct xadArchiveInfo *, struct xadMasterBase *)
  101.  
  102.    FUNCTION
  103.     This function frees all the stuff allocated by xcGetInfo. It is
  104.     called after unsuccessful xcGetInfo as well, so you need not to
  105.     call any freeing functions there. But be prepared for that case.
  106.     You must check all entries, as xcGetInfo may fail in the first
  107.     allocation stages (f.e. allocation of xadDiskInfo or xadFileInfo
  108.     structures).
  109.     Clear all entries you have freed! There should not be any pointers
  110.     left in xadArchiveInfo structure which do not point to valid
  111.     memory.
  112.  
  113.     Starting with (V2) the master library can do some stuff for you.
  114.     This is always done after calling this function, so you have the
  115.     chance to do private stuff before!
  116.     If you set the flag XADCF_FREEFILEINFO in xc_Flags, the master
  117.     library parses the xai_FileInfo list and frees every entry.
  118.     If you set the flag XADCF_FREEDISKINFO in xc_Flags, the master
  119.     library parses the xai_DiskInfo list and frees every entry.
  120.     If you set the flag XADCF_FREETEXTINFO in xc_Flags, the master
  121.     library parses the xdi_TextInfo list of every xadDiskInfo
  122.     structure and frees every entry.
  123.     If you set the flag XADCF_FREETEXTINFOTEXT in xc_Flags, the
  124.     master library frees xti_Text entry of xadTextInfo structures.
  125.     This requires these entries to be allocated with xadAllocVec()
  126.     function.
  127.  
  128.     If your free function is empty, because all can be done by master
  129.     library, then you may place a zero in xc_Free field of xadClient
  130.     structure and remove the function totally.
  131.  
  132.    INPUTS
  133.     ai    the master communication structure
  134.  
  135.    SEE ALSO
  136.     Example sourcecodes, xadmaster.library/xadFreeInfo()
  137.  
  138. xadClient/xcGetInfo                                       xadClient/xcGetInfo
  139.  
  140.    NAME
  141.     xcGetInfo -- create all information about an archive file
  142.  
  143.    SYNOPSIS
  144.     result = xcGetInfo(ai, xadMasterBase)
  145.       D0               A0        A6
  146.  
  147.     LONG xcGetInfo(struct xadArchiveInfo *, struct xadMasterBase *)
  148.  
  149.    FUNCTION
  150.     This function is the most important one. It creates a structure
  151.     list containing all necessary information. File archivers create
  152.     a linked list of xadFileInfo structures for every file/link/
  153.     directory which is stored in the archive. xadAllocObject helps
  154.     to store that information by providing 3 tags for getting special
  155.     memory. XAD_OBJNAMESIZE can be used to allocate a buffer for
  156.     storing (also multiple) names. The buffer is byte aligned. Do not
  157.     forget to count the 0-byte for every string you want to store there.
  158.     The buffer pointer is stored in xfi_FileName.
  159.     XAD_OBJCOMMENTSIZE is equal to this, but stored in xfi_Comment.
  160.     For file and disk archives there is the flag XAD_OBJPRIVINFOSIZE,
  161.     which returns a longword aligned buffer in xfi_PrivateInfo or
  162.     xdi_PrivateInfo.
  163.     Disk archivers create a linked list of xadDiskInfo structures.
  164.     Normal disk archivers do not allow to store more than one archive,
  165.     so linking is most time not necessary, but it is supported.
  166.     When storing information texts, they must be finished with a zero
  167.     byte, which is not counted in size field!
  168.     Every file or disk entry gets an entrynumber, which increases from
  169.     first to last entry. For mixed archivers this means that a
  170.     "file, disk, disk, file, file, disk" archive gets file entry
  171.     numbers 1,4,5 and disk entry numbers 2,3,6.
  172.     Most disk archivers are based on cylinder structure. These should
  173.     fill the xadDiskInfo fields correctly. If archivers are not based
  174.     on it (e.g. only sector based) they need to set XADDIF_NOCYLINDER
  175.     flag!
  176.     If the archiver format does not support file dates, set the
  177.     current date (XAD_DATECURRENTIME tag) and XADFIF_NODATE flag.
  178.     Protection bits default to zero (equals "rwed").
  179.     Archivers may store XADAIF_FILECORRUPT flag in xai_Flags, when 
  180.     archive is corrupt, but some entries are still usable. Unusable
  181.     entries must not appear in entry list. Do not return an error
  182.     code in that case, as an error code always means totally failure.
  183.     Starting with V2, an error code may be stored in xai_LastError,
  184.     when XADAIF_FILECORRUPT is used.
  185.  
  186.    INPUTS
  187.     ai    master communication structure
  188.  
  189.    RESULT
  190.         result    - any of the XADERR codes or zero when all is ok.
  191.  
  192.    SEE ALSO
  193.     Example sourcecodes, xadmaster.library/xadGetInfo()
  194.  
  195. xadClient/xcRecogData                                   xadClient/xcRecogData
  196.  
  197.    NAME
  198.     xcRecogData -- Scan input buffer for known archiver type
  199.  
  200.    SYNOPSIS
  201.     result = xcRecogData(size, buffer, xadMasterBase)
  202.       D0                  D0     A0         A6
  203.  
  204.     BOOL xcRecogData(ULONG, STRPTR, struct xadMasterBase *)
  205.  
  206.    FUNCTION
  207.     Returns non zero when this buffer is part of a archive file
  208.     supported by this client. The recognition should be very stable.
  209.     It should be tested with lots of files. One wrong recognition
  210.     for 100000 files is acceptable.
  211.  
  212.    INPUTS
  213.     size    size of passed buffer
  214.     buffer    buffer containing start of file to scan
  215.  
  216.    RESULT
  217.     result - TRUE if archiver is recogniced, FALSE if not
  218.  
  219.    SEE ALSO
  220.     Example sourcecodes, xadmaster.library/xadRecogFile(),
  221.     xadmaster.library/xadGetInfo()
  222.  
  223. xadClient/xcUnArchive                                   xadClient/xcUnArchive
  224.  
  225.    NAME
  226.     xcUnArchive -- write the required entry to destination
  227.  
  228.    SYNOPSIS
  229.     result = xcUnArchive(ai, xadMasterBase)
  230.       D0                 A0        A6
  231.  
  232.     LONG xcUnArchive(struct xadArchiveInfo *, struct xadMasterBase *)
  233.  
  234.    FUNCTION
  235.     This function dearchives one entry. The required entry is passed
  236.     in xai_CurFile or xai_CurDisk. A normal client will support only
  237.     one of the two possibilities, but clients using file and/or disk
  238.     archives are allowed as well. When writing disk data, the client
  239.     should write data in blocks with size of multiple sectorsize.
  240.     Although it should work, it is not recommended to write blocks
  241.     unequal to this.
  242.     Nearly all information you may need is stored in xadArchiveInfo
  243.     structure.
  244.     You may expect the entries to be unarchived in same order as they
  245.     are numbered, but it is not necessary!
  246.     Disk archivers may expect to be called again to dearchive an
  247.     entry, even if there is only one! So restore the file position
  248.     you need to unarchive.
  249.  
  250.    INPUTS
  251.     ai    master communication structure
  252.  
  253.    RESULT
  254.         result    - any of the XADERR codes or zero when all is ok.
  255.  
  256.    SEE ALSO
  257.     Example sourcecodes, xadmaster.library/xadDiskunArc(),
  258.     xadmaster.library/xadFileUnArc()
  259.  
  260.