home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / packery / xpk_develop / autodocs / xpksub.doc < prev   
Text File  |  1996-10-19  |  7KB  |  239 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpksub.library/XpksPackerInfo
  4. xpksub.library/XpksPackChunk
  5. xpksub.library/XpksPackFree
  6. xpksub.library/XpksPackReset
  7. xpksub.library/XpksUnpackChunk
  8. xpksub.library/XpksUnpackFree
  9. xpksub.library/--sublibs--
  10.  
  11. xpksub.library/XpksPackerInfo
  12.  
  13.     NAME
  14.     XpksPackerInfo - Get information about a packer sub-library
  15.  
  16.     SYNOPSIS
  17.     info = XpkPackerInfo()
  18.      D0
  19.  
  20.     struct XpkInfo *XpkPackerInfo( void );
  21.  
  22.     FUNCTION
  23.     Returns all information about a packer sub-library for use
  24.     by the master library.
  25.  
  26.     RESULT
  27.     info - pointer to struct XpkPackerInfo. see xpk/xpksub.h
  28.            for the meaning of all the fields.
  29.  
  30.     SEE ALSO
  31.     XpksPackChunk()
  32.  
  33. xpksub.library/XpksPackChunk
  34.  
  35.     NAME
  36.     XpksPackChunk - Pack a chunk of data
  37.  
  38.     SYNOPSIS
  39.     err = XpksPackChunk( param )
  40.     D0              A0
  41.  
  42.     LONG XpksPackChunk(struct XpkSubParams *);
  43.  
  44.     FUNCTION
  45.     Packs one chunk of data from memory to memory. The size of the 
  46.     chunk will not surpass the MaxPkInChunk field of the packer info
  47.     structure. Chunks are numbered in case a library writes various
  48.     dictionaries at special places.
  49.  
  50.     INPUTS
  51.     struct XpkSubParams, where the fields mean:
  52.       InBuf     Pointer to the data to be compressed
  53.       InLen     The number of bytes to pack
  54.       OutBuf    Pointer to the memory area to write packed data to
  55.       OutBufLen Size of above memory area
  56.       OutLen    Will be set to compressed length by sublib
  57.       Number    The number of this chunk
  58.       Mode      The sub-mode to be used
  59.       Password  The password to be used for encryption
  60.       Sub[4]    Here the sub library stores its private data
  61.  
  62.     RESULTS
  63.     err    - global xpk error code
  64.     OutLen - Number of bytes written
  65.  
  66.     SEE ALSO
  67.     XpksPackReset(), XpksPackFree()
  68. xpksub.library/XpksPackFree
  69.  
  70.     NAME
  71.     XpksPackFree - Free buffers associated with packing process
  72.  
  73.     SYNOPSIS
  74.     XpksPackFree( param )
  75.                A0
  76.  
  77.     void XpksPackFree(struct XpkSubParams *)
  78.  
  79.     FUNCTION
  80.     Frees all buffers the sub-library has allocated privately
  81.     while doing some packing
  82.  
  83.     INPUTS
  84.     param - The XpkSubParams used for packing
  85.  
  86.     SEE ALSO
  87.     XpksPackChunk(), XpksPackReset()
  88.  
  89. xpksub.library/XpksPackReset
  90.  
  91.     NAME
  92.     XpksPackReset - Clears all state information
  93.  
  94.     SYNOPSIS
  95.     XpksPackReset( param )
  96.             A0
  97.  
  98.     LONG XpksPackReset(struct XpkSubParams *)
  99.  
  100.     FUNCTION
  101.     Clears all internal tables and any other state information of the
  102.     packer. This has the effect, to guarantee independent unpacking
  103.     of the chunk to come. The packers call this function automatically
  104.     before returning XPKERR_EXPANSION (data could not be compressed).
  105.  
  106.     Note:    packers have to store all of their state relevant to packing
  107.         in XpkSubParams to ensure reentrantness.
  108.  
  109.     INPUTS
  110.     param - The XpkSubParams used for packing
  111.  
  112.     SEE ALSO
  113.     XpksPackChunk(), XpksPackFree()
  114. xpksub.library/XpksUnpackChunk
  115.  
  116.     NAME
  117.     XpksUnpackChunk - Uncompress a chunk of data
  118.  
  119.     SYNOPSIS
  120.     err = XpksUnpackChunk( param )
  121.                 A0
  122.  
  123.     LONG XpksUnpackChunk(struct XpkSubParams *)
  124.  
  125.     FUNCTION
  126.     Decompresses one chunk of data.
  127.  
  128.     INPUTS
  129.     param - The XpkSubParams used for unpacking
  130.       InBuf     Pointer to the data to be uncompressed
  131.       InLen     The number of bytes to unpack
  132.       OutBuf    Pointer to the memory area to write unpacked data to
  133.       OutBufLen Size of above memory area
  134.       OutLen    Must contain the decompressed size of the data
  135.       Number    The number of this chunk
  136.       Password  The password to be used for decryption
  137.       Sub[4]    Here the sub library stores its private data
  138.     
  139.  
  140.     RESULT
  141.     err - global xpk error code
  142.  
  143.     SEE ALSO
  144.     XpksUnpackFree()
  145. xpksub.library/XpksUnpackFree
  146.  
  147.     NAME
  148.     XpksUnpackFree - Free all private data the sublib has allocated
  149.  
  150.     SYNOPSIS
  151.     XpksUnpackFree( param )
  152.               A0
  153.  
  154.     LONG XpksUnpackFree( struct XpkSubParams * )
  155.  
  156.     FUNCTION
  157.     Will free all memory the sub-library has allocated during the
  158.     decompression.
  159.  
  160.     INPUTS
  161.     param - The XpkSubParams used for unpacking
  162.  
  163.     SEE ALSO
  164.     XpksUnpackChunk()
  165. xpksub.library/--sublibs--
  166.  
  167. Some remarks for sublib writers
  168. -------------------------------
  169.  
  170. First of all, Read the documentation.  If you've got any further questions
  171. writing xpksublibraries, either contact one of the XPK maintainers.
  172.  
  173. How XpkPackChunk works:
  174. - Check xpar->Sub[0]. If it's 0, this is the first call. Allocate your tables
  175.   and store pointers to them in Sub[0] .. Sub[3].
  176. - Read xpar->InLen bytes from xpar->InBuf and pack them to xpar->OutBuf.
  177.   Don't exceed xpar->OutBufLen. Store packed len in xpar->OutLen.
  178.  
  179. How XpkUnpackChunk works:
  180. - Check xpar->Sub[0]. If it's 0, this is the first call. Allocate your tables
  181.   and store pointers to them in Sub[0] .. Sub[3].
  182. - Read xpar->InLen bytes from xpar->InBuf and unpack them to xpar->OutBuf.
  183.   Don't exceed xpar->OutBufLen. Maybe compare uncompressed len with 
  184.   xpar->OutLen.
  185.  
  186. Other notes:
  187. - Your library should, of course, be re-entrant. This means no PC-relative
  188.   addressing of writeable data. Whatever you have, store a pointer to it
  189.   somewhere in the XpkSubMessage. In short: All state information of the sublib
  190.   is in the XpkSubMessage. You can detect the first chunk of a file by the fact
  191.   that this pointer is still NULL. In case your lib is not re-entrant,
  192.   return XPKERR_LIBINUSE when required.
  193.  
  194. - There will be no larger chunks on (de)compression than the first one.
  195.  
  196. - On compression, you may expand the data by XPK_MARGIN bytes maximum. This
  197.   means the output buffer is as large as the input buffer plus XPK_MARGIN.
  198.   Compression libs would, of course, already return XPKERR_EXPANSION if
  199.   they exceed the input buffer.
  200.  
  201. - You must supply a function XpkPackReset, which clears all tables so
  202.   that the next chunk will be able to be unpacked independently. You also
  203.   have to reinitialize all state information [calling your XpkPackReset]
  204.   before returning XPKERR_EXPANSION!
  205.  
  206. - On decompression, you will also have a XPK_MARGIN byte saftey margin for
  207.   runaway unpacking. 
  208.  
  209. - Fill in one XpkInfo structure. See xpk/xpksub.h for the meanings of
  210.   the fields therein.
  211.  
  212. - If your packer has only one packing mode, fill in one XpkMode structure 
  213.   (see xpk.h). Set the 'Upto' field to 100, this means this struct handles 
  214.   all modes up to (and including) 100, which is the max packing mode. Place
  215.   a pointer to this struct in the XpkInfo structure.
  216.  
  217. - There must be at least one XpkMode structure, and the last XpkMode 
  218.   structure must have the Upto set to 100. It must!
  219.  
  220. - If your packer has several modes, create several XpkMode structures and
  221.   sort them by efficiency in ascending order. Place a pointer to them
  222.   in XpkInfo. Set the XPKIF_MODES flag in the Flag field of XpkInfo.
  223.  
  224. - Your packer will get the 0..100 number and is responsible of mapping
  225.   it to its own packing modes.
  226.  
  227. - Set the DefMode field to some 0...100 number.
  228.  
  229. - If XSF_STEPDOWN is set in the Flags field of the SubParams structure,
  230.   you are allowed to reduce packing efficiency in order to save mem.
  231.  
  232. - Encryption libraries should compute a cryptographic hash [that's a checksum]
  233.   while or after decryption and compare it with one stored in the encrypted
  234.   data.  If the hash of the decrypted text doesn't match the stored checksum,
  235.   return XPKERR_WRONGPW. Note, that this hash inevitably discloses information
  236.   applicable to breaking the code. Try to keep this information small, e.g.
  237.   by using a 16bit hash. Take care, that one has to decrypt the whole chunk
  238.   before it's possible to compute the hash of the decrypted data. 
  239.