home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / Cruncher / XPK_D310.LZX / xpk_Develop / Autodocs / xpkmaster.doc next >
Encoding:
Text File  |  1996-10-20  |  14.1 KB  |  477 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpkmaster.library/XpkClose
  4. xpkmaster.library/XpkExamine
  5. xpkmaster.library/XpkExamineTags
  6. xpkmaster.library/XpkOpen
  7. xpkmaster.library/XpkOpenTags
  8. xpkmaster.library/XpkPack
  9. xpkmaster.library/XpkPackTags
  10. xpkmaster.library/XpkQuery
  11. xpkmaster.library/XpkQueryTags
  12. xpkmaster.library/XpkRead
  13. xpkmaster.library/XpkUnpack
  14. xpkmaster.library/XpkUnpackTags
  15. xpkmaster.library/XpkWrite
  16. xpkmaster.library/--tags--
  17. xpkmaster.library/--progress--
  18.  
  19. xpkmaster.library/XpkClose                         xpkmaster.library/XpkClose
  20.  
  21.     NAME
  22.     XpkClose - Close an XPK-File
  23.  
  24.     SYNOPSIS
  25.     err = XpkClose( xfh )
  26.     D0        A0
  27.  
  28.     LONG  XpkClose(struct XpkFib *)
  29.  
  30.     FUNCTION
  31.     Frees all resources associated with packing or unpacking an
  32.     XPK-File. Note that this may well fail, especially on packing,
  33.     since additional writes have to be made here.
  34.  
  35.     INPUT
  36.     xfh    - The Struct XpkFib obtained from XpkOpen()
  37.  
  38.     RESULT
  39.     err     - Global Xpk error code
  40.  
  41.     SEE ALSO
  42.     XpkOpen(), XpkRead(), XpkWrite()
  43. xpkmaster.library/XpkExamine                     xpkmaster.library/XpkExamine
  44.  
  45.     NAME
  46.     XpkExamine - Get information about a compressed file
  47.  
  48.     SYNOPSIS
  49.     err = XpkExamine(fib, tags)
  50.     D0          A0   A1
  51.  
  52.     LONG  XpkExamine(struct XpkFib *, struct TagItem *)
  53.  
  54.     FUNCTION
  55.     Returns information about compressed data. The output is written
  56.     to the XpkFib structure whose address is passed with the mandatory
  57.     XPK_FileExamine tag. You also have to specify an XPK_In* tag. Note
  58.     that the file position of the in hook will not be altered.
  59.     A tag field has to end with TAG_DONE.
  60.  
  61.     INPUT
  62.     tags    - Pointer to an array of struct TagItem. You may use 
  63.           either a XPK_InBuf, a XPK_InName, XPK_InFH or XPK_InHook
  64.           tag.
  65.  
  66.     RESULT
  67.     err    - Global Xpk error code
  68.  
  69.     SEE ALSO
  70.     xpk/xpk.h, xDir.c
  71.  
  72. xpkmaster.library/XpkExamineTags             xpkmaster.library/XpkExamineTags
  73.  
  74.     NAME
  75.     XpkExamineTags - Get information about a compressed file
  76.  
  77.     SYNOPSIS
  78.     err = XpkExamineTags(fib, tag1, val1, tag2, val2, .... , TAG_DONE )
  79.     D0
  80.  
  81.     LONG  XpkExamineTags(ULONG, ... );
  82.  
  83.     FUNCTION
  84.     Same as XpkExamine(), but tags passed on stack.
  85.  
  86.     SEE ALSO
  87.     XpkExamine()
  88. xpkmaster.library/XpkOpen                           xpkmaster.library/XpkOpen
  89.  
  90.     NAME
  91.     XpkOpen - Open a compressed file for partial reading
  92.  
  93.     SYNOPSIS
  94.     err = XpkOpen(xfh,tags)
  95.     D0          A0   A1
  96.  
  97.     LONG  XpkOpen(struct XpkFib **xfh, struct TagItem *)
  98.  
  99.     FUNCTION
  100.     Using XpkOpen you can read or write an XPK-File without ever having
  101.     all of the file present in RAM. On reading, you cannot pick the 
  102.     size of the chunks; they're given by the file to be decompressed
  103.     and may be up to the whole size of the file.
  104.  
  105.     INPUT
  106.     xfh    - Address of a pointer to struct XpkFib
  107.     tags    - Specifying XPK_PackMethod will chose packing mode for
  108.           this filehandle. Only In-tags are permitted in case
  109.           of unpacking, and only Out-tags are in case of packing.
  110.           Anything else will yield undefined results. Progress
  111.           reports not supported. When packing, you must supply
  112.           XPK_InLen as well.
  113.  
  114.     RESULT
  115.     xfh    - The filehandle. Consists of an XpkFib and some private
  116.           information. The NLen field in the XpkFib indicates the
  117.           length of the next chunk.
  118.     err    - Global Xpk error code. If nonzero, no XpkFib was allocated.
  119.           Check the XPK_GetError to see how to get a full err msg.
  120.  
  121.     SEE ALSO
  122.     XpkRead(), XpkWrite(), XpkClose(), xpkmaster.library/tags, examples/
  123.  
  124. xpkmaster.library/XpkPack                           xpkmaster.library/XpkPack
  125.  
  126.     NAME
  127.     XpkPack - Compress a data stream
  128.  
  129.     SYNOPSIS
  130.     err = XpkPack(tags)
  131.     D0           A0
  132.  
  133.     LONG  XpkPack(struct TagItem *);
  134.  
  135.     FUNCTION
  136.     Compresses a file or a memory area to a different file or memory
  137.     area. You need to specify at least one XPK_In... tag, at least
  138.     one XPK_Out... tag, plus XPK_PackMethod.
  139.     A tag field has to end with TAG_DONE.
  140.  
  141.     INPUT
  142.     tags    - Pointer to an array of struct TagItem. See xpkmaster/tags
  143.  
  144.     RESULT
  145.     err    - Global Xpk error code, see xpk.h. Check the XPK_GetError 
  146.           to see how to get a full err msg.
  147.  
  148.     SEE ALSO
  149.     xpkmaster.library/tags, xpk.c
  150.  
  151. xpkmaster.library/XpkPackTags                   xpkmaster.library/XpkPackTags
  152.  
  153.     NAME
  154.     XpkPackTags - Compress a data stream
  155.  
  156.     SYNOPSIS
  157.     err = XpkPackTags(tag1, val1, tag2, val2, .... , TAG_DONE )
  158.     D0
  159.  
  160.     LONG  XpkPackTags(ULONG, ... );
  161.  
  162.     FUNCTION
  163.     Same as XpkPack(), but tags passed on stack.
  164.  
  165.     SEE ALSO
  166.     XpkPack()
  167. xpkmaster.library/XpkQuery                         xpkmaster.library/XpkQuery
  168.  
  169.     NAME
  170.     XpkQuery - Gain information about packers
  171.  
  172.     SYNOPSIS
  173.     err = XpkQuery( tags )
  174.     D0         A0
  175.  
  176.     LONG  XpkQuery( tags );
  177.  
  178.     FUNCTION
  179.     Finds out a list of available packers or various parameters of a
  180.     packer. When using the tag XPK_PackersQuery, you must supply a
  181.     XpkPackerList structure and will receive a list of available
  182.     packers. The second possibility, XPK_PackerQuery, expects a
  183.     pointer to a XpkPackerInfo structure which will be filled in with
  184.     information about a packer, and XPK_ModeQuery fills in a XpkMode
  185.     structure with information about some mode (or the default mode)
  186.     of a packer. XPK_PackMethod must be present among the tags for
  187.     the latter two, and XPK_PackMode can be for ModeQuery.
  188.     A tag field has to end with TAG_DONE.
  189.  
  190.     RESULT
  191.     err     - Global Xpk error code. XPK_GetError also supported
  192.  
  193.     SEE ALSO
  194.     xpk/xpk.h
  195. xpkmaster.library/XpkQueryTags                 xpkmaster.library/XpkQueryTags
  196.  
  197.     NAME
  198.     XpkQueryTags - Gain information about packers
  199.  
  200.     SYNOPSIS
  201.     err = XpkQueryTags(tag1, val1, tag2, val2, .... , TAG_DONE )
  202.     D0
  203.  
  204.     LONG  XpkQueryTags(ULONG, ... );
  205.  
  206.     FUNCTION
  207.     Same as XpkQuery(), but tags passed on stack.
  208.  
  209.     SEE ALSO
  210.     XpkQuery()
  211. xpkmaster.library/XpkRead                           xpkmaster.library/XpkRead
  212.  
  213.     NAME
  214.     XpkRead - Unpack one part of an XPK-File
  215.  
  216.     SYNOPSIS
  217.     read = XpkRead( xfh, buf, len )
  218.     D0        A0   A1   D0
  219.  
  220.     LONG  XpkRead(struct XpkFib *, UBYTE *, LONG)
  221.  
  222.     FUNCTION
  223.     Reads one chunk from an XPK-file and decompresses it to the
  224.     memory area indicated.
  225.  
  226.     INPUT
  227.     xfh    - The XpkFib obtained from XpkOpen(). It must be a read-
  228.           handle, ie. there was no XPK_PackMethod tag among the
  229.           tags passed to XpkOpen().
  230.     buf    - The memory area to write the destination to
  231.     len    - The number uncompressed bytes to output. Note that you
  232.           can't choose these freely but must take them from 
  233.           the NLen field in the XpkFib.
  234.  
  235.     RESULT
  236.     read    - The number of bytes read. 0 indicates EOF, negative
  237.           numbers are global error codes. Long error messages 
  238.           written to buffer passed through XPK_GetError in 
  239.           XpkOpen(). This number of bytes read will usually be
  240.           smaller than the number requested!
  241.  
  242.     SEE ALSO
  243.     XpkOpen(), XpkWrite(), XpkClose(), examples/
  244. xpkmaster.library/XpkUnpack                       xpkmaster.library/XpkUnpack
  245.  
  246.     NAME
  247.     XpkUnpack - Decompress a data stream
  248.  
  249.     SYNOPSIS
  250.     err = XpkUnpack(tags)
  251.     D0           A0
  252.  
  253.     LONG  XpkUnpack(struct TagItem *);
  254.  
  255.     FUNCTION
  256.     Decompresses a file or a memory area to a different file or memory
  257.     area. You need to specify at least one XPK_In... tag, at least
  258.     one XPK_Out... tag.
  259.     A tag field has to end with TAG_DONE.
  260.  
  261.     INPUT
  262.     tags   - Pointer to an array of struct TagItem. See xpkmaster/tags
  263.  
  264.     RESULT
  265.     err    - Global Xpk error code.
  266.  
  267.     SEE ALSO
  268.     xpkmaster.library/tags
  269.  
  270. xpkmaster.library/XpkUnpackTags               xpkmaster.library/XpkUnpackTags
  271.  
  272.     NAME
  273.     XpkUnpackTags - Decompress a data stream
  274.  
  275.     SYNOPSIS
  276.     err = XpkUnpackTags(tag1, val1, tag2, val2, .... , TAG_DONE )
  277.     D0
  278.  
  279.     LONG  XpkUnpackTags(ULONG, ... );
  280.  
  281.     FUNCTION
  282.     Same as XpkUnpack(), but tags passed on stack.
  283.  
  284.     SEE ALSO
  285.     XpkUnpack()
  286. xpkmaster.library/XpkWrite                         xpkmaster.library/XpkWrite
  287.  
  288.     NAME
  289.     XpkWrite - Pack one part of an XPK-File
  290.  
  291.     SYNOPSIS
  292.     read = XpkWrite( xfh, buf, len )
  293.     D0         A0   A1   D0
  294.  
  295.     LONG  XpkWrite(struct XpkFib *, UBYTE *, LONG)
  296.  
  297.     FUNCTION
  298.     Compresses the memory area indicated and writes it to an
  299.     XPK-File.
  300.  
  301.     INPUT
  302.     xfh    - The XpkFib obtained from XpkOpen(). Must be a write-
  303.           handle, ie. XPK_PackMethod must have been among the
  304.           tags passed to XpkOpen().
  305.     buf    - The memory area to compress
  306.     len    - The number bytes to compress. Note you may not choose
  307.           them freely, you must always deliver as many bytes
  308.           as the NLen field of the XpkFib indicates. You may try
  309.           to influence it by passing XPK_ChunkLen to XpkOpen().
  310.           Important: The first chunk written *must* be the
  311.           biggest!
  312.  
  313.     RESULT
  314.     written    - The number of bytes written. 0 indicates EOF, negative
  315.           numbers are global error codes. Error messages are 
  316.           written to buffer passed through XPK_GetError in 
  317.           XpkOpen().
  318.  
  319.     SEE ALSO
  320.     XpkOpen(), XpkRead(), XpkClose(), examples/
  321. xpkmaster.library/--tags--                         xpkmaster.library/--tags--
  322.  
  323.     THE TAGS FOR XpkPack() AND XpkUnpack()
  324.  
  325.     THE INPUT TAGS. One of the four must be present.
  326.  
  327.     XPK_InName  (STRPTR)
  328.         Name of file to (de)compress. On packing, XPK_InLen can be 
  329.         specified in order to pack only the first N bytes. On de-
  330.         compression, only one file will be decompressed, even if 
  331.         there are additional data at the end.
  332.  
  333.     XPK_InFH    (BPTR)
  334.         File handle to (de)compress from. It is not necessary that
  335.         the handle is at the beginning of the file. Otherwise same
  336.         rules as in XPK_InName apply.
  337.  
  338.     XPK_InBuf   (STRPTR)
  339.         Memory block to (de)compress. If you use this one, you 
  340.         have to specify InLen as well.
  341.  
  342.     XPK_InHook  (struct Hook *)
  343.         Hookfunc to deliver data for (de)compression. See special
  344.         chapter on I/O hook functions. Must also supply XPK_InLen.
  345.  
  346.     IN ADDITION
  347.  
  348.     XPK_InLen   (LONG)
  349.         Specifies the number of bytes to read when compressing.
  350.         gnored on decompression.
  351.  
  352.  
  353.     THE OUTPUT TAGS. One of the five must be present.
  354.  
  355.     XPK_OutName      (STRPTR)
  356.         Name of file write (de)compressed data to.
  357.  
  358.     XPK_OutFH        (BPTR)
  359.         File handle to append (de)compressed data to.
  360.  
  361.     XPK_OutBuf       (APTR)
  362.         The memory block to write (de)compressed data to. Must also
  363.         supply XPK_OutBufLen. On packing, its size must be at least
  364.         inlen+inlen/32+2*XPK_MARGIN. On unpacking, it needs only be
  365.         outlen+XPK_MARGIN. Use XpkExamine() to find out outlen. Note
  366.         that this buffer must be word aligned.
  367.  
  368.     XPK_GetOutBuf    (APTR *)
  369.         Allocates a block of appropriate size and stores a pointer to
  370.         it in the variable pointed to by ti_Data. Must also supply 
  371.         XPK_GetOutBufLen plus XPK_GetOutLen and can XPK_OutMemType.
  372.  
  373.     XPK_OutHook      (struct Hook *)
  374.         Hookfunc to accept (de)compressed data. See special chapter
  375.         on I/O hook functions.
  376.  
  377.     IN ADDITION
  378.  
  379.     XPK_OutBufLen    (LONG)
  380.         The length of the output buffer you supply using XPK_OutBuf.
  381.         For decompression, must be decompressed size (see XpkExamine())
  382.         plus XPK_MARGIN. For compression, inlen+inlen/32+2*XPK_MARGIN.
  383.  
  384.     XPK_GetOutLen    (LONG *)
  385.         Stores the total length of the (de)compressed data in the variable
  386.         pointed to by ti_Data. Note: V2 of xpkmaster required for correct
  387.         operation on compression.
  388.  
  389.     XPK_GetOutBufLen (LONG *)
  390.         Stores the length of the buffer allocated for the data in the
  391.         variable pointed to by ti_Data. FreeMem() the buffer you  get
  392.         from XPK_GetOutBuf with the length you get from XPK_GetOutBufLen.
  393.         Note: For the number of bytes written, refer to XPK_GetOutLen!
  394.  
  395.     XPK_OutMemType   (LONG)
  396.         The type of memory to use for the output buffer.
  397.  
  398.  
  399.     PACKING TAGS
  400.  
  401.     XPK_PackMethod   (STRPTR)
  402.         Use indicated method for packing. This would be a four
  403.         letter string in most cases, plus an optional dot and 
  404.         a packing mode. See XPK_PackMode
  405.  
  406.     XPK_PackMode     (LONG)
  407.         Packing mode for sublib to use. Range is 0...100, where 100 is
  408.         most efficient.
  409.  
  410.     XPK_StepDown     (BOOL)
  411.         Reduce packing efficiency to save mem if necessary.
  412.  
  413.     XPK_ChunkSize    (LONG)
  414.         Chunk size to try to pack with. May be altered by the
  415.         master library.
  416.  
  417.     QUERY TAGS
  418.  
  419.     XPK_PackersQuery (struct XpkPackerList *)
  420.         Returns an array of available packers names in the XPLIST
  421.         structure whose address is stored in the ti_Data field
  422.         of this tag.
  423.  
  424.     XPK_PackerQuery  (struct XpkPackerInfo *)
  425.         Returns information about one single packer in the XPINFO
  426.         structure whose address is stored in the ti_Data field
  427.         of this tag. See xpk/xpk.h for the meaning of the
  428.         fields therein. You must also supply XPK_PackMode.
  429.  
  430.     XPK_ModeQuery    (struct XpkMode *)
  431.         Returns information about one single packer mode in the 
  432.         XPINFO structure whose address is stored in the ti_Data 
  433.         field of this tag. See xpk/xpk.h for the meaning of 
  434.         the fields therein. You must also supply XPK_PackMethod
  435.         and optionally XPK_PackMode (or a mode in the PackMethod
  436.         string), otherwise the default mode will be used.
  437.  
  438.     OTHER TAGS
  439.  
  440.     XPK_GetError     (STRPTR)
  441.         Write error msg to the buffer passed. The buffer must be of 
  442.         size XPKERRMSGSIZE.
  443.  
  444.     XPK_ShortError    (BOOL)
  445.         Don't include activity and file name in error messages.
  446.  
  447.     XPK_Password     (STRPTR)
  448.         Use password for en- or decoding. Passing a NULL pointer or
  449.         zero length string is equivalent to omitting this tag.
  450.  
  451.     XPK_ChunkHook    (struct Hook *)
  452.         Hook function to call between chunks. Can print a progress
  453.         report, and if it returns a nonzero value, the (de)compression
  454.         will be aborted. See special chapter on chunk functions.
  455.  
  456.     XPK_PassThru     (BOOL)
  457.         If true, data will just be handed trough on decompression if they
  458.         were not packed. Otherwise you get XPKERR_NOTPACKED.
  459.  
  460.     XPK_TaskPri      (UBYTE)
  461.         The task priority to use during the (de)crunching. Use -1 for
  462.         background decompression.
  463.  
  464.     XPK_FileName     (STRPTR)
  465.         The name to print in the progress report. If none is given, the
  466.         InName will be used when packing and the OutName when unpacking.
  467. xpkmaster.library/--progress--                 xpkmaster.library/--progress--
  468.  
  469.     THE PROGRESS REPORT HOOK
  470.     The progress report function is a standard hook function that will
  471.     be called after every chunk (de)compressed. This will be about 
  472.     every 30K, or just twice if the file format is not split in chunks.
  473.     If the field h_Entry in the hook is set, it will be called with 
  474.     the hook itself in a0 and the progress report structure in a1.
  475.     If the progress report function    returns a nonzero value,
  476.     (de)compression aborts.
  477.