home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 28 / amigaformatcd28.iso / -seriously_amiga- / archivers / xpk / xpk_develop / autodocs / xpkmaster.doc next >
Text File  |  1998-04-27  |  31KB  |  837 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpkmaster.library/XpkAllocObject
  4. xpkmaster.library/XpkClose
  5. xpkmaster.library/XpkExamine
  6. xpkmaster.library/XpkFault
  7. xpkmaster.library/XpkFreeObject
  8. xpkmaster.library/XpkOpen
  9. xpkmaster.library/XpkPack
  10. xpkmaster.library/XpkPassRequest
  11. xpkmaster.library/XpkPrintFault
  12. xpkmaster.library/XpkQuery
  13. xpkmaster.library/XpkRead
  14. xpkmaster.library/XpkUnpack
  15. xpkmaster.library/XpkWrite
  16. xpkmaster.library/--tags--
  17. xpkmaster.library/--progress--
  18. xpkmaster.library/--data hooks--
  19.  
  20. xpkmaster.library/XpkAllocObject             xpkmaster.library/XpkAllocObject
  21.  
  22.     NAME
  23.         XpkAllocObject - Allocate memory for xpk related structures (V4)
  24.  
  25.     SYNOPSIS
  26.         ptr = XpkAllocObject(type, tags)
  27.         D0                    D0    A0
  28.  
  29.         APTR  XpkAllocObject(ULONG , struct TagItem *)
  30.  
  31.         ptr = XpkAllocObjectTags(type, firsttag, ...)
  32.  
  33.         APTR  XpkAllocObjectTags(ULONG, Tag, ...)
  34.  
  35.     FUNCTION
  36.         This function allocates the memory of a needed xpk related
  37.         structure and initializes it. It should help to bring better
  38.         upwards compatibility in next versions. Use it always in newer code.
  39.  
  40.     INPUT
  41.         type    - in xpk/xpk.h defined XPKOBJ_... types.
  42.                   for example XPKOBJ_FIB alloctes XpkFib structure
  43.         tags    - Pointer to an array of struct TagItem. No tags defined
  44.                   at the moment.
  45.  
  46.     RESULT
  47.         ptr     - Pointer to allocated memory of needed size or 0 when an
  48.                   error occured.
  49.  
  50.     SEE ALSO
  51.         xpk/xpk.h, XpkFreeObject()
  52.  
  53. xpkmaster.library/XpkClose                         xpkmaster.library/XpkClose
  54.  
  55.     NAME
  56.         XpkClose - Close an XPK-File
  57.  
  58.     SYNOPSIS
  59.         err = XpkClose(xfh)
  60.         D0              A0
  61.  
  62.         LONG  XpkClose(struct XpkFib *)
  63.  
  64.     FUNCTION
  65.         Frees all resources associated with packing or unpacking an
  66.         XPK-File. Note that this may well fail, especially on packing,
  67.         since additional writes have to be made here.
  68.  
  69.     INPUT
  70.         xfh     - The Struct XpkFib obtained from XpkOpen()
  71.  
  72.     RESULT
  73.         err     - Global Xpk error code
  74.  
  75.     SEE ALSO
  76.         XpkOpen(), XpkRead(), XpkWrite()
  77.  
  78. xpkmaster.library/XpkExamine                     xpkmaster.library/XpkExamine
  79.  
  80.     NAME
  81.         XpkExamine - Get information about a compressed file
  82.  
  83.     SYNOPSIS
  84.         err = XpkExamine(fib, tags)
  85.         D0                A0   A1
  86.  
  87.         LONG  XpkExamine(struct XpkFib *, struct TagItem *)
  88.  
  89.         err = XpkExamineTags(fib, firsttag, ...)
  90.  
  91.         LONG  XpkExamineTags(struct XpkFib *, Tag, ...)
  92.  
  93.     FUNCTION
  94.         Returns information about compressed data. The output is written
  95.         to the XpkFib structure whose address is passed with the mandatory
  96.         XPK_FileExamine tag. You also have to specify an XPK_In* tag. Note
  97.         that the file position of the in hook will not be altered.
  98.     XPK_GetError is supported.
  99.         A tag field has to end with TAG_DONE.
  100.  
  101.     INPUT
  102.         tags    - Pointer to an array of struct TagItem. You may use 
  103.                   either a XPK_InBuf, a XPK_InName, XPK_InFH or XPK_InHook
  104.                   tag.
  105.  
  106.     RESULT
  107.         err     - Global Xpk error code
  108.  
  109.     SEE ALSO
  110.         xpk/xpk.h
  111.  
  112. xpkmaster.library/XpkFault                         xpkmaster.library/XpkFault
  113.  
  114.     NAME
  115.         XpkFault - Returns the text associated with a Xpk error code (V4)
  116.  
  117.     SYNOPSIS
  118.         len = XpkFault(code, header, buffer, bufsize)
  119.         D0              D0     A0      A1     D1
  120.  
  121.         LONG XpkFault(LONG, STRPTR, STRPTR, LONG)
  122.  
  123.     FUNCTION
  124.         This routine obtains the error message text for the given error code.
  125.         The header is prepended to the text of the error message, followed
  126.         by a colon. Puts a null-terminated string for the error message into
  127.         the buffer. At most len bytes are written to buffer.
  128.  
  129.     INPUTS
  130.         code    - Error code (negative value or 0)
  131.         header  - header to output before error text
  132.         buffer  - Buffer to receive error message.
  133.         bufsize - Length of the buffer.
  134.  
  135.     RESULT
  136.         len     - number of characters put into buffer (may be 0)
  137.  
  138.     SEE ALSO
  139.         XpkPrintFault()
  140.  
  141. xpkmaster.library/XpkFreeObject               xpkmaster.library/XpkFreeObject
  142.  
  143.     NAME
  144.         XpkFreeObject - Frees memory allocated with XpkAllocObject() (V4)
  145.  
  146.     SYNOPSIS
  147.         XpkFreeObject(type, object)
  148.                        D0     A0
  149.  
  150.         void XpkFreeObject(ULONG , APTR)
  151.  
  152.     FUNCTION
  153.         Frees object allocated by XpkAllocObject(). Do not call for objects
  154.         allocated in any other way.
  155.  
  156.     INPUTS
  157.         type    - type passed to XpkAllocObject()
  158.         object  - pointer returned by XpkAllocObject()
  159.  
  160.     SEE ALSO
  161.         xpk/xpk.h, XpkAllocObject()
  162.  
  163. xpkmaster.library/XpkOpen                           xpkmaster.library/XpkOpen
  164.  
  165.     NAME
  166.         XpkOpen - Open a compressed file for partial reading
  167.  
  168.     SYNOPSIS
  169.         err = XpkOpen(xfh, tags)
  170.         D0            A0    A1
  171.  
  172.         LONG  XpkOpen(struct XpkFib **, struct TagItem *)
  173.  
  174.     FUNCTION
  175.         Using XpkOpen you can read or write an XPK file without ever having
  176.         all of the file present in RAM. On reading, you cannot pick the 
  177.         size of the chunks. They are given by the file to be decompressed
  178.         and may be up to the whole size of the file.
  179.     XPK_GetError is supported.
  180.  
  181.     INPUT
  182.         xfh     - Address of a pointer to struct XpkFib
  183.         tags    - Specifying XPK_PackMethod will chose packing mode for
  184.                   this filehandle. Only In-tags are permitted in case
  185.                   of unpacking, and only Out-tags are in case of packing.
  186.                   Anything else will yield undefined results. Progress
  187.                   reports not supported. When packing, you must supply
  188.                   XPK_InLen as well.
  189.  
  190.     RESULT
  191.         xfh     - The filehandle. Consists of an XpkFib and some private
  192.                   information. The NLen field in the XpkFib indicates the
  193.                   length of the next chunk.
  194.         err     - Global Xpk error code. If nonzero, no XpkFib was allocated.
  195.  
  196.     SEE ALSO
  197.         XpkRead(), XpkWrite(), XpkClose(), xpkmaster.library/--tags--
  198.  
  199. xpkmaster.library/XpkPack                           xpkmaster.library/XpkPack
  200.  
  201.     NAME
  202.         XpkPack - Compress a data stream
  203.  
  204.     SYNOPSIS
  205.         err = XpkPack(tags)
  206.         D0             A0
  207.  
  208.         LONG  XpkPack(struct TagItem *)
  209.  
  210.         err = XpkPackTags(firsttag, ...)
  211.  
  212.         LONG  XpkPackTags(Tag, ...)
  213.  
  214.     FUNCTION
  215.         Compresses a file or a memory area to a different file or memory
  216.         area. You need to specify at least one XPK_In... tag, at least
  217.         one XPK_Out... tag, plus XPK_PackMethod.
  218.     XPK_GetError is supported.
  219.         A tag field has to end with TAG_DONE.
  220.  
  221.     INPUT
  222.         tags    - Pointer to an array of struct TagItem.
  223.  
  224.     RESULT
  225.         err     - Global Xpk error code.
  226.  
  227.     SEE ALSO
  228.         xpkmaster.library/--tags--, xpk/xpk.h
  229.  
  230. xpkmaster.library/XpkPassRequest             xpkmaster.library/XpkPassRequest
  231.  
  232.     NAME
  233.         XpkPassRequest - opens a password Requester (V4)
  234.  
  235.     SYNOPSIS
  236.         err = XpkPassRequest(tags)
  237.         D0                    A0
  238.  
  239.         LONG  XpkPassRequest(struct TagItem *)
  240.  
  241.         err = XpkPassRequestTags(firsttag, ...)
  242.  
  243.         LONG  XpkPassRequestTags(Tag, ...)
  244.  
  245.     FUNCTION
  246.         Opens a requester to ask the user for a password. The requester
  247.         can ask for a password or a 16/32 bit key. It has a tunable
  248.         timeout to allow batch work.
  249.  
  250.     This function needs at least 2 free signal bits for message ports.
  251.  
  252.     INPUT
  253.         tags    - Pointer to an array of struct TagItem.
  254.                   Either XPK_Preferences or one of the following:
  255.  
  256.     TAGS
  257.         XPK_PassChars   (ULONG)
  258.            Tell the requester which characters are allowed in the password.
  259.            Use XPKPASSFLG_... and XPKPASSFF_... defines.
  260.  
  261.         XPK_PasswordBuf (STRPTR)
  262.            Pointer to memory area, where the password should be stored.
  263.            Requires XPK_PassBuffSize tag.
  264.  
  265.         XPK_PassBufSize (ULONG)
  266.            Size of the buffer passed with XPK_PasswordBuf.
  267.  
  268.         XPK_Key16BitPtr (UWORD *)
  269.            Ask for an 16 bit key instead of a password. Data is a pointer
  270.            to a 16 bit (UWORD) variable. XPK_PassChars is ignored here, as
  271.            input is always hexadecimal.
  272.  
  273.         XPK_Key32BitPtr (ULONG *)
  274.            Ask for an 32 bit key. Data points to a 32 bit (ULONG) variable.
  275.        XPK_PassChars is ignored here, as input is always hexadecimal.
  276.  
  277.         XPK_PubScreen (struct Screen *)
  278.            Pointer of type struct Screen of the public screen, the
  279.            requester should open on. If not given, the requester opens on
  280.            default public screen. The screen must by locked by use of
  281.            LockPubScreen or garanted not to be closed during request!
  282.  
  283.         XPK_PassTitle (STRPTR)
  284.            Is the text, which is shown in the title line of the window. If
  285.            not given, the internal defaults are used.
  286.  
  287.         XPK_TimeOut (ULONG)
  288.            Time after which the requester should close automatically, when
  289.            no user action happend. 0 means no timeout.
  290.  
  291.     XPK_PassVerify (BOOL) (V4 REV25)
  292.        When this tag is specified, the user needs to enter the password
  293.        or passkey twice for verification. This option should be used
  294.        when password is needed for packing.
  295.  
  296.     XPK_PassWinLeft (UWORD) (V4 REV25)
  297.        This specifies the distance from left screen border to left
  298.        border of password requester. When not given, the window is
  299.        centered on screen.
  300.  
  301.     XPK_PassWinTop (UWORD) (V4 REV25)
  302.        This specifies the distance from top screen border to top
  303.        border of password requester. When not given, the window is
  304.        centered on screen.
  305.  
  306.     XPK_PassWinWidth (UWORD) (V4 REV25)
  307.        This specifies the width of the password requester. It must be
  308.        large enough (50 + borders) or the internal defaults are used.
  309.  
  310.     XPK_PassWinHeight (UWORD) (V4 REV25)
  311.        This specifies the height of the password requester. It must be
  312.        large enough (inner height a bit larger than font height) or the
  313.        internal defaults are used.
  314.  
  315.     XPK_PassCenter (BOOL) (V4 REV25)
  316.        When this is given, the above XPK_PassWinLeft and XPK_PassWinTop
  317.        are are interpreted as the center of the requester and not as
  318.        its upper left edge.
  319.  
  320.     RESULT
  321.         err     - Global Xpk error code.
  322.  
  323.     SEE ALSO
  324.         xpk/xpk.h
  325.  
  326. xpkmaster.library/XpkPrintFault               xpkmaster.library/XpkPrintFault
  327.  
  328.     NAME
  329.         XpkPrintFault - Prints the text associated with a Xpk error code (V4)
  330.  
  331.     SYNOPSIS
  332.         success = XpkPrintFault(code, header)
  333.         D0                       D0     A0
  334.  
  335.         BOOL XpkPrintFault(LONG, STRPTR)
  336.  
  337.     FUNCTION
  338.         This routine obtains and prints the error message text for the
  339.         given error code. This is similar to the XpkFault() function,
  340.         except that the output is written to the default output
  341.         channel with buffered output.
  342.  
  343.     INPUTS
  344.         code    - Error code (negative value or 0)
  345.         header  - header to output before error text
  346.  
  347.     RESULT
  348.         success - Success/failure code. Return of 0 means failure.
  349.  
  350.     SEE ALSO
  351.         XpkFault()
  352.  
  353. xpkmaster.library/XpkQuery                         xpkmaster.library/XpkQuery
  354.  
  355.     NAME
  356.         XpkQuery - Gain information about packers
  357.  
  358.     SYNOPSIS
  359.         err = XpkQuery(tags)
  360.         D0              A0
  361.  
  362.         LONG  XpkQuery(struct TagItem *)
  363.  
  364.         err = XpkQueryTags(firsttag, ...)
  365.  
  366.         LONG  XpkQueryTags(Tag, ... )
  367.  
  368.     FUNCTION
  369.         Finds out a list of available packers or various parameters of a
  370.         packer. When using the tag XPK_PackersQuery, you must supply a
  371.         XpkPackerList structure and will receive a list of available
  372.         packers. The second possibility, XPK_PackerQuery, expects a
  373.         pointer to a XpkPackerInfo structure which will be filled in with
  374.         information about a packer, and XPK_ModeQuery fills in a XpkMode
  375.         structure with information about some mode (or the default mode)
  376.         of a packer. XPK_PackMethod must be present when using the latter
  377.         two queries, and XPK_PackMode can be for ModeQuery.
  378.     XPK_GetError is supported. Every call only one query is allowed!
  379.  
  380.     The flag XPKIF_MODES does not mean, the library supports different
  381.     mode settings (as ALL libraries do that), but means there are
  382.     different XpkMode structures! So when XPKIF_MODES is not set, the
  383.     user still needs to be able to select all 100 modes!
  384.  
  385.     Pass {XPK_Preferences, FALSE} as tags to disable the dummy packer
  386.     USER, which implements the preferences packing. Then handle the
  387.     preferences mode internally, as the statistics passed with
  388.     XPK_ModeQuery and XPK_PackerQuery are not very useful.
  389.  
  390.     RESULT
  391.         err     - Global Xpk error code.
  392.  
  393.     SEE ALSO
  394.         xpk/xpk.h
  395.  
  396. xpkmaster.library/XpkRead                           xpkmaster.library/XpkRead
  397.  
  398.     NAME
  399.         XpkRead - Unpack one part of an XPK-File
  400.  
  401.     SYNOPSIS
  402.         read = XpkRead( xfh, buf, len )
  403.         D0              A0   A1   D0
  404.  
  405.         LONG  XpkRead(struct XpkFib *, UBYTE *, LONG)
  406.  
  407.     FUNCTION
  408.         Reads one chunk from an XPK-file and decompresses it to the
  409.         memory area indicated.
  410.  
  411.     INPUT
  412.         xfh     - The XpkFib obtained from XpkOpen(). It must be a read-
  413.                   handle, ie. there was no XPK_PackMethod tag among the
  414.                   tags passed to XpkOpen().
  415.         buf     - The memory area to write the destination to
  416.         len     - The number uncompressed bytes to output. Note that you
  417.                   cannot choose these freely but must take them from 
  418.                   the xf_NLen field in the XpkFib.
  419.  
  420.     RESULT
  421.         read    - The number of bytes read. 0 indicates EOF, negative
  422.                   numbers are global error codes. Long error messages 
  423.                   written to buffer passed through XPK_GetError in 
  424.                   XpkOpen(). This number of bytes read will usually be
  425.                   smaller than the number requested!
  426.  
  427.     SEE ALSO
  428.         XpkOpen(), XpkWrite(), XpkClose(), examples/
  429.  
  430. xpkmaster.library/XpkUnpack                       xpkmaster.library/XpkUnpack
  431.  
  432.     NAME
  433.         XpkUnpack - Decompress a data stream
  434.  
  435.     SYNOPSIS
  436.         err = XpkUnpack(tags)
  437.         D0             A0
  438.  
  439.         LONG  XpkUnpack(struct TagItem *)
  440.  
  441.         err = XpkUnpackTags(firsttag, ...)
  442.  
  443.         LONG  XpkUnpackTags(Tag, ...)
  444.  
  445.     FUNCTION
  446.         Decompresses a file or a memory area to a different file or memory
  447.         area. You need to specify at least one XPK_In... tag, at least
  448.         one XPK_Out... tag. A tag field has to end with TAG_DONE.
  449.     XPK_GetError is supported.
  450.  
  451.     INPUT
  452.         tags   - Pointer to an array of struct TagItem.
  453.  
  454.     RESULT
  455.         err    - Global Xpk error code.
  456.  
  457.     SEE ALSO
  458.         xpkmaster.library/--tags--
  459.  
  460. xpkmaster.library/XpkWrite                         xpkmaster.library/XpkWrite
  461.  
  462.     NAME
  463.         XpkWrite - Pack one part of an XPK-File
  464.  
  465.     SYNOPSIS
  466.         read = XpkWrite(xfh, buf, len)
  467.         D0              A0   A1   D0
  468.  
  469.         LONG  XpkWrite(struct XpkFib *, UBYTE *, LONG)
  470.  
  471.     FUNCTION
  472.         Compresses the memory area indicated and writes it to an
  473.         XPK-File.
  474.  
  475.     INPUT
  476.         xfh     - The XpkFib obtained from XpkOpen(). Must be a write-
  477.                   handle, ie. XPK_PackMethod must have been among the
  478.                   tags passed to XpkOpen().
  479.         buf     - The memory area to compress
  480.         len     - The number bytes to compress. Note you may not choose
  481.                   them freely, you must always deliver as many bytes
  482.                   as the NLen field of the XpkFib indicates. You may try
  483.                   to influence it by passing XPK_ChunkLen to XpkOpen().
  484.                   Important: The first chunk written *must* be the
  485.                   biggest!
  486.  
  487.     RESULT
  488.         written - The number of bytes written. 0 indicates EOF, negative
  489.                   numbers are global error codes. Error messages are 
  490.                   written to buffer passed through XPK_GetError in 
  491.                   XpkOpen().
  492.  
  493.     SEE ALSO
  494.         XpkOpen(), XpkRead(), XpkClose(), examples/
  495.  
  496. xpkmaster.library/--tags--                         xpkmaster.library/--tags--
  497.  
  498.     THE TAGS FOR XpkPack() AND XpkUnpack()
  499.  
  500.     THE INPUT TAGS. One of the four must be present.
  501.  
  502.         XPK_InName (STRPTR)
  503.             Name of file to (de)compress. On packing, XPK_InLen can be 
  504.             specified in order to pack only the first N bytes. On de-
  505.             compression, only one file will be decompressed, even if 
  506.             there is additional data at the end.
  507.  
  508.         XPK_InFH (BPTR)
  509.             File handle to (de)compress from. It is not necessary that
  510.             the handle is at the beginning of the file. Otherwise same
  511.             rules as in XPK_InName apply.
  512.  
  513.         XPK_InBuf (STRPTR)
  514.             Memory block to (de)compress. If you use this one, you 
  515.             have to specify InLen as well.
  516.  
  517.         XPK_InHook (struct Hook *)
  518.             Hookfunc to deliver data for (de)compression. See special
  519.             chapter on I/O hook functions. Must also supply XPK_InLen,
  520.             else the hook itself is asked for input filelength.
  521.  
  522.     IN ADDITION
  523.  
  524.         XPK_InLen (LONG)
  525.             Specifies the number of bytes to read when compressing.
  526.             ignored on decompression of normal xpk files. It should be
  527.             supplied for decompression to allow decrunching of non xpk
  528.             files.
  529.  
  530.     THE OUTPUT TAGS. One of the five must be present.
  531.  
  532.         XPK_OutName (STRPTR)
  533.             Name of file write (de)compressed data to.
  534.  
  535.         XPK_OutFH (BPTR)
  536.             File handle to append (de)compressed data to. This filehandle
  537.             must be writable, so MODE_OLDFILE filehandles may fail, as
  538.             these open a file in shared mode.
  539.  
  540.         XPK_OutBuf (APTR)
  541.             The memory block to write (de)compressed data to. Must also
  542.             supply XPK_OutBufLen. On packing, its size must be at least
  543.             inlen+inlen/32+2*XPK_MARGIN. On unpacking, it needs only be
  544.             outlen+XPK_MARGIN. Use XpkExamine() to find out outlen. Note
  545.             that this buffer must be word aligned.
  546.  
  547.         XPK_GetOutBuf (APTR *)
  548.             Allocates a block of appropriate size and stores a pointer to
  549.             it in the variable pointed to by ti_Data. Must also supply 
  550.             XPK_GetOutBufLen plus XPK_GetOutLen and can XPK_OutMemType.
  551.  
  552.         XPK_OutHook (struct Hook *)
  553.             Hookfunc to accept (de)compressed data. See special chapter
  554.             on I/O hook functions.
  555.  
  556.     IN ADDITION
  557.  
  558.         XPK_OutBufLen (LONG)
  559.             The length of the output buffer you supply using XPK_OutBuf.
  560.             For decompression, must be decompressed size (see XpkExamine())
  561.             plus XPK_MARGIN. For compression, inlen+inlen/32+2*XPK_MARGIN.
  562.  
  563.         XPK_GetOutLen (LONG *)
  564.             Stores the total length of the (de)compressed data in the
  565.             variable pointed to by ti_Data.
  566.  
  567.         XPK_GetOutBufLen (LONG *)
  568.             Stores the length of the buffer allocated for the data in the
  569.             variable pointed to by ti_Data. FreeMem() the buffer you get
  570.             from XPK_GetOutBuf with the length you get from XPK_GetOutBufLen.
  571.             Note: For the number of bytes written, refer to XPK_GetOutLen!
  572.  
  573.         XPK_OutMemType (LONG)
  574.             The type of memory to use for the output buffer.
  575.  
  576.     You have to specify different input and output streams always. So it
  577.     produces wrong results, when you supply same buffer for XPK_InBuf and
  578.     XPK_OutBuf or same filehandle for XPK_InFH and XPK_OutFH.
  579.     
  580.     PACKING TAGS
  581.  
  582.         XPK_PackMethod (STRPTR)
  583.             Use indicated method for packing. This would be a four
  584.             letter string of uppercase characters and numbers.
  585.  
  586.         XPK_PackMode (LONG)
  587.             Packing mode for sublib to use. Range is 0...100, where 100 is
  588.             most efficient.
  589.  
  590.         XPK_StepDown (BOOL)
  591.             Reduce packing efficiency to save mem if necessary.
  592.  
  593.         XPK_ChunkSize (LONG)
  594.             Chunk size to try to pack with. May be altered by the
  595.             master library.
  596.  
  597.     XPK_LossyOK (BOOL)
  598.         Some packers, like MPEG, reduce the file size by deleting some
  599.         information. These information cannot be restored. This tag
  600.         tells xpkmaster.library if it is ok for you, that some
  601.         information is deleted. It is FALSE by default. Use it with
  602.         care! Should be used only with sound or picture files.
  603.  
  604.     QUERY TAGS
  605.  
  606.         XPK_PackersQuery (struct XpkPackerList *)
  607.             Returns an array of available packers names in the XpkPackerList
  608.             structure whose address is stored in the ti_Data field of this
  609.             tag.
  610.  
  611.         XPK_PackerQuery (struct XpkPackerInfo *)
  612.             Returns information about one single packer in the XpkPackerInfo
  613.             structure whose address is stored in the ti_Data field of this
  614.             tag. See xpk/xpk.h for the meaning of the fields therein. You
  615.             must also supply XPK_PackMode.
  616.  
  617.         XPK_ModeQuery (struct XpkMode *)
  618.             Returns information about one single packer mode in the XpkMode
  619.             structure whose address is stored in the ti_Data field of this
  620.             tag. See xpk/xpk.h for the meaning of the fields therein. The
  621.             data of xm_Next field is illegal and must not be used. You
  622.             must also supply XPK_PackMethod and optionally XPK_PackMode,
  623.             otherwise the default mode will be used.
  624.  
  625.     OTHER TAGS
  626.  
  627.         XPK_GetError (STRPTR)
  628.             Write error msg to the buffer passed. The buffer must be of 
  629.             size XPKERRMSGSIZE. This tag calls XpkFault internally.
  630.             It is not recommended to use this tag any longer.
  631.  
  632.         XPK_Password (STRPTR)
  633.             Use password for en- or decoding. Passing a NULL pointer or
  634.             zero length string is equivalent to omitting this tag.
  635.  
  636.     XPK_Key16 (UWORD) (V4 REV25)
  637.         Supply a 16 bit key for decrunching of encrypted data. This
  638.         is only for decrunching of alien formats. XPK does not support
  639.         crunching with keys. Only know usage: crypted RNC files.
  640.  
  641.     XPK_Key32 (ULONG) (V4 REV25)
  642.         Supply a 32 bit key for decrunching of encrypted data. This
  643.         is only for decrunching of alien formats. XPK does not support
  644.         crunching with keys. Currently no know usage.
  645.  
  646.         XPK_ChunkHook (struct Hook *)
  647.             Hook function to call between chunks. Can print a progress
  648.             report, and if it returns a nonzero value, the (de)compression
  649.             will be aborted. See special chapter on chunk functions.
  650.  
  651.         XPK_PassThru (BOOL)
  652.             If true, data will just be handed trough on decompression if they
  653.             were not packed. Otherwise you get XPKERR_NOTPACKED.
  654.  
  655.         XPK_TaskPri (UBYTE)
  656.             The task priority to use during the (de)crunching. Use -1 for
  657.             background decompression.
  658.  
  659.         XPK_FileName (STRPTR)
  660.             The name to print in the progress report. If none is given, the
  661.             InName will be used when packing and the OutName when unpacking.
  662.  
  663.     PREFERENCES RELATED TAGS
  664.  
  665.         XPK_UseXfdMaster (BOOL) (V4)
  666.             If TRUE, xfdmaster.library will be used for checking unknown
  667.             files. Useable with XpkUnpack() and XpkExamine(). Is FALSE by
  668.             default, but depends on preference settings.
  669.  
  670.         XPK_UseExternals (BOOL) (V4)
  671.             If TRUE, xex libraries in LIBS:compressors/extern will be used
  672.             to check for crunched files. Useable with XpkUnpack() and
  673.             XpkExamine(). Default value is TRUE (depends on prefs!)
  674.  
  675.         XPK_PassRequest (BOOL) (V4)
  676.             If this is set a requester will be used to query the user for a
  677.             password, if none is given. Useable with XpkPack(). This is
  678.             disabled by default, but can be overridden using preferences
  679.             settings.
  680.  
  681.         XPK_Preferences (BOOL) (V4)
  682.             Tell xpkmaster.library whether to use its preferences system,
  683.             or not. This is enabled by default.
  684.  
  685.     XPK_ChunkReport (BOOL) (V4)
  686.         If this tag is set, xpkmaster.library brings an automatic chunk
  687.         report request (when the preferences semaphore has a valid
  688.         function for that). This is disabled by default.
  689.  
  690. xpkmaster.library/--progress--                 xpkmaster.library/--progress--
  691.  
  692.     THE PROGRESS REPORT HOOK
  693.         The progress report function is a standard hook function that will
  694.         be called after every chunk (de)compressed. This will be about 
  695.         every 30K, or just twice if the file format is not split in chunks.
  696.         If the field h_Entry in the hook is set, it will be called with 
  697.         the hook itself in A0 and the progress report structure in A1.
  698.         If the progress report function returns a nonzero value,
  699.         (de)compression aborts.
  700.         NOTE: Because hooks are not called in program environment, they
  701.         cannot be used in small data model of some compilers, as register
  702.         A4 is not passed through. So the hook either has to be compiled in
  703.         large data model or should use __saveds keyword of some compilers.
  704.  
  705. xpkmaster.library/--data hooks--             xpkmaster.library/--data hooks--
  706.  
  707.     GENERAL
  708.     You have four methods of passing data to xpkmaster.library: file-
  709.     names, filehandles, memory areas and hooks. The hooks are described
  710.     here. The hook field h_Entry has to be standard hook functions and
  711.     gets called with the hook itself in A0 and a pointer to a XpkIOMsg
  712.     in A1. Commands are stored in xiom_Type field, data in the other
  713.     fields. Return values are 0 or any of the XPKERR codes.
  714.     Commands XIO_FREE and XIO_ABORT may be ignored.
  715.  
  716.     Whenever an error occurs, you have to return an XPKERR code and
  717.     stop work. You get a XIO_ABORT call in this case later. When no
  718.     error occured, return 0.
  719.  
  720.     You may store private data in the free fields of XpkIOMsg structure.
  721.     You are always called with XIO_FREE or XIO_ABORT, so you can free
  722.     private stuff there. Buffers can be freed, when next time a buffer
  723.     allocation is required.
  724.  
  725.         NOTE: Because hooks are not called in program environment, they
  726.         cannot be used in small data model of some compilers, as register
  727.         A4 is not passed through. So the hook either has to be compiled in
  728.         large data model or should use __saveds keyword of some compilers.
  729.  
  730.     BUFFERS
  731.     Your hooks must be able to allocate buffers for read/write or pass
  732.     pointers to them, when they are already allocated. There are some
  733.     ways you have to handle this. First there is XIO_GETBUF. When getting
  734.     this command you have to pass a memory pointer pointing to a region
  735.     of at least xmm_Size size. For in hook there is another additionally
  736.     method. When XIO_READ is wanted and xiom_Ptr is zero, then you have
  737.     to pass (and allocate) a buf pointer and to fill it!
  738.     
  739.     The buffers must be valid until you are next time asked to allocate
  740.     a buffer (either with XIO_GETBUF or XIO_READ). Then you may return
  741.     old buffer pointer (when memory is large enough) or allocate a new
  742.     buffer and free the old buffer. When XIO_ABORT or XIO_FREE is send
  743.     all your buffers should be freed.
  744.  
  745.     NOTE: Your hooks do not get called only with your own buffers, but
  746.     also with xpkmaster internally buffers!
  747.  
  748.     When your input data is already in memory, you may pass pointers
  749.     to your memory regions and need not to allocate new memory for
  750.     XIO_READ when pointer is zero. When xiom_Ptr is not zero for
  751.     XIO_READ, you have to copy the data.
  752.  
  753.     Never expect, that you are called next time with buffer you
  754.     allocated. There may be write cycles of headers and other stuff
  755.     between XIO_GETBUF and XIO_WRITE. On reading it is equal.
  756.  
  757.     COMMANDS
  758.     XIO_READ    (in hooks only)
  759.       This command is called all time xpkmaster.library needs some data.
  760.       You have to fill the supplied memory area with input data of
  761.       needed size (not more!) When the input memory pointer is zero,
  762.       you have to allocate your own buffer and fill it. When you
  763.       allocated a buffer before (either by XIO_GETBUF or XIO_READ) you
  764.       can free it when pointer is zero.
  765.       Input:    xiom_Size    size of required data
  766.               xiom_Ptr    already allocated buffer or zero
  767.       Output:    xiom_Ptr    pointer to memory area of xiom_Size
  768.  
  769.     XIO_WRITE    (out hooks only)
  770.       This function is called, when some data was compressed and should
  771.       be stored now. Copy the contents of buffer to your data storing
  772.       system.
  773.       Input:    xiom_Size    size of data
  774.               xiom_Ptr    pointer to memory area of xiom_Size
  775.       Output:    none
  776.  
  777.     XIO_FREE    (both)
  778.       You get this when work is finished, free all your stuff now.
  779.       Input:    none
  780.       Output:    none
  781.  
  782.     XIO_ABORT    (both)
  783.       You get this when work was aborted, because an error occured.
  784.       Free all your stuff now.
  785.       Input:    none
  786.       Output:    none
  787.  
  788.     XIO_GETBUF    (both)
  789.       Asks you to pass a needed buffer. This buffer is not freed by
  790.       xpkmaster.library. Do this when getting XIO_FREE, XIO_ABORT or
  791.       the next XIO_GETBUF. Input buffers may be freed too, when
  792.       XIO_READ is called with no pointer.
  793.       Input:    xiom_Size    size of necessary buffer
  794.       Output:    xiom_Ptr    pointer to the buffer
  795.  
  796.     XIO_SEEK    (both)
  797.       Change the current position in your data (like dos.library Seek
  798.       command). When you are not able to handle seek, all better
  799.       functions will fail. Pass XPKERR_NOFUNC in this case as return
  800.       value. The offset you have to seek is always relative to current
  801.       position. It can be negative too. Return value (xiom_Size) is
  802.       same as for dos.library Seek command.
  803.       Input:    xiom_Size    offset you have to seek
  804.       Output:    xiom_Size    buffer position before seek
  805.  
  806.     XIO_TOTSIZE    (both)
  807.       You either have to tell the total input data size (in hook) or get
  808.       told the total output data size (out hook).
  809.  
  810.       OUT HOOK:
  811.       XIO_TOTSIZE may be ignored here. It tells you the maximum size
  812.       of output file (the real size may be shorter). This is for
  813.       example needed in memory hooks. This is only to inform you.
  814.       This command never needs to return an error code.
  815.       Input:    xiom_Size    total size of output data
  816.       Output:    none
  817.  
  818.       IN HOOK:
  819.       XIO_TOTSIZE cannot be ignored here. When your hook cannot
  820.       determine the total filesize, return any of the XPKERR values.
  821.       XIO_TOTSIZE is called only, when xpkmaster library really needs
  822.       filesize. Normal XPK files have size information in header and
  823.       XPK_InLen flags supplies information for input. In these cases
  824.       XIO_TOTSIZE is not used. But when returning an XPKERR, your hook
  825.       will not work in other cases, when size is required.
  826.       XIO_TOSIZE is used for following cases (when no XPK_InLen is
  827.       supplied!):
  828.       - decrunching of all non-xpk files
  829.       - crunching of files
  830.       NOTE: Only the size of the part, which should be processed, is
  831.       wanted. Most time this is from current position to end of file
  832.       (memory), but it may be shorter. But generally you have to
  833.       calculate size starting at current position.
  834.       Input:    none
  835.       Output:    xiom_Size    total size of input data
  836.  
  837.