home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / util / pplib-1.6.lha / PPlib / doc / pplib.doc
Text File  |  1993-12-21  |  23KB  |  679 lines
  1. TABLE OF CONTENTS
  2.  
  3. powerpacker.library/ppAllocCrunchInfo
  4. powerpacker.library/ppCalcChecksum
  5. powerpacker.library/ppCalcPasskey
  6. powerpacker.library/ppCrunchBuffer
  7. powerpacker.library/ppCrunchBufferDest
  8. powerpacker.library/ppDecrunchBuffer
  9. powerpacker.library/ppDecrypt
  10. powerpacker.library/ppEnterPassword
  11. powerpacker.library/ppErrorMessage
  12. powerpacker.library/ppFreeCrunchInfo
  13. powerpacker.library/ppGetPassword
  14. powerpacker.library/ppLoadData
  15. powerpacker.library/ppWriteDataHeader
  16. powerpacker.library/ppAllocCrunchInfo   powerpacker.library/ppAllocCrunchInfo
  17.  
  18.   NAME  ppAllocCrunchInfo()  (V35)
  19.  
  20.     crunchinfo = ppAllocCrunchInfo (efficiency, speedup, function, userdata);
  21.  
  22.     APTR ppAllocCrunchInfo (ULONG, ULONG, BOOL (*)(), APTR);
  23.     D0                      D0     D1     A0          A1
  24.  
  25.   DESCRIPTION
  26.     Allocate all the necessary memory needed to crunch a buffer. This
  27.     function must be called before using ppCrunchBuffer.  You must pass
  28.     the crunching efficiency and the size of the speedup buffer.
  29.  
  30.     You can pass a callback function to be called during crunching. Use this
  31.     type of function:
  32.  
  33.     BOOL __stdargs myFunction (ULONG lensofar, ULONG crunlen,
  34.                                ULONG totlen, APTR userdata);
  35.  
  36.     If you do not wish to use this feature pass a NULL. The function can be
  37.     used for two things:
  38.  
  39.       o to display the percentage crunched and gain so far.
  40.       o to allow the user to abort crunching.
  41.  
  42.     Your function will be passed four arguments (on the stack, normal C
  43.     conventions):
  44.  
  45.       lensofar - length of part crunched so far.
  46.       crunlen  - crunched length of lensofar.
  47.       totlen   - total length of buffer.
  48.       userdata - the userdata you provided to ppAllocCrunchInfo().
  49.  
  50.     If your function returns a non-zero value the crunching will continue,
  51.     returning zero will abort crunching.
  52.  
  53.     SAS/C users shouldn't forget __saveds if they compiled their program with
  54.     the small data model and wish to use global data in their function.
  55.     If you write your function in assembly please preserve all registers.
  56.  
  57.     Example:
  58.  
  59.     BOOL __stdargs __saveds myfunc (ULONG sofar, ULONG crunlen,
  60.                                     ULONG totlen, APTR userdata)
  61.     {
  62.        struct IntuiMessage *msg;
  63.        UWORD code;
  64.  
  65.        if (sofar) {
  66.           sprintf (buff, "%ld%% crunched. (%ld%% gain)   ",
  67.              (sofar * 100) / totlen, 100 - (100 * crunlen) / sofar);
  68.           PrtMsg (buff, BLACK|AT_START);
  69.           }
  70.        while (msg = (struct IntuiMessage *)GetMsg (win->UserPort)) {
  71.           code = msg->Code;
  72.           ReplyMsg ((struct Message *)msg);
  73.           if (code == 0x3 /* CTRL-C */) return (FALSE);
  74.           }
  75.        return (TRUE);
  76.     }
  77.  
  78.     Finally note that you may scratch the A4 register.  This is made possible
  79.     to help people who wish to use 'userdata' to pass A4 (C data pointer).
  80.  
  81.   INPUTS
  82.     efficiency - the efficiency of the crunching. One of the
  83.                  following (defined in "libraries/ppbase.[hi]"):
  84.                     CRUN_FAST
  85.                     CRUN_MEDIOCRE
  86.                     CRUN_GOOD
  87.                     CRUN_VERYGOOD
  88.                     CRUN_BEST
  89.     speedup    - size of speedup buffer to be used. One of the
  90.                  following (defined in "libraries/ppbase.[hi]"):
  91.                     SPEEDUP_BUFFSMALL  - from 3K (fast) to 33K (best)
  92.                     SPEEDUP_BUFFMEDIUM - from 5K (fast) to 65K (best)
  93.                     SPEEDUP_BUFFLARGE  - from 196K (fast) to 256K (best)
  94.     function   - callback function to be called every so often during
  95.                  crunching. Can be used to display percentage crunched
  96.                  so far and to abort crunching.
  97.     userdata   - anything you wish. Will be passed to your callback function.
  98.  
  99.   RESULT
  100.     crunchinfo - pointer to private crunchinfo structure to be passed to
  101.                  ppCrunchBuffer (use ppFreeCrunchInfo to deallocate).
  102.  
  103.   NOTE
  104.     'crunchinfo' may be re-used to crunch several buffers.
  105.  
  106.   BUGS
  107.     none known
  108.  
  109.   SEE ALSO
  110.     ppFreeCrunchInfo(), ppCrunchBuffer()
  111.  
  112. powerpacker.library/ppCalcChecksum         powerpacker.library/ppCalcChecksum
  113.  
  114.   NAME  ppCalcChecksum()
  115.  
  116.     sum = ppCalcChecksum (string);
  117.  
  118.     ULONG ppCalcChecksum (char *);
  119.     D0:16                 A0
  120.  
  121.   DESCRIPTION
  122.     This function calculates a 16 bit checksum of a given string of
  123.     characters.
  124.  
  125.   INPUTS
  126.     string - pointer to a null terminated character string.
  127.  
  128.   RESULT
  129.     sum - checksum of 'string'.
  130.  
  131.   NOTE
  132.     Function used to check if a password is correct.
  133.     Upper 16 bits of checksum are 0.
  134.  
  135.   BUGS
  136.     none
  137.  
  138.   SEE ALSO
  139.     ppLoadData()
  140.     ppDecrunchBuffer()
  141.     ppDecrypt()
  142.     ppCalcPasskey()
  143.  
  144. powerpacker.library/ppCalcPasskey           powerpacker.library/ppCalcPasskey
  145.  
  146.   NAME  ppCalcPasskey()
  147.  
  148.     key = ppCalcPasskey (password);
  149.  
  150.     ULONG ppCalcPasskey (char *);
  151.     D0                   A0
  152.  
  153.   DESCRIPTION
  154.     This function calculates the 32 bit key associated with the given
  155.     password to encrypt/decrypt crunched files with.
  156.  
  157.   INPUTS
  158.     string - pointer to a null terminated character string.
  159.  
  160.   RESULT
  161.     key - passkey corresponding to the given password.
  162.  
  163.   NOTE
  164.     Function used to decrypt encrypted files.
  165.  
  166.   BUGS
  167.     none
  168.  
  169.   SEE ALSO
  170.     ppDecrunchBuffer()
  171.     ppDecrypt()
  172.     ppCalcChecksum()
  173.  
  174. powerpacker.library/ppCrunchBuffer         powerpacker.library/ppCrunchBuffer
  175.  
  176.   NAME  ppCrunchBuffer()  (V35)
  177.  
  178.     crunchedlen = ppCrunchBuffer (crunchinfo, buffer, len);
  179.  
  180.     ULONG ppCrunchBuffer (APTR, UBYTE *, ULONG);
  181.     D0                    A0    A1       D0
  182.  
  183.   DESCRIPTION
  184.     Crunch the buffer pointed to by 'buffer' and of length (in bytes) 'len'.
  185.     'crunchinfo' must have been previously allocated by ppAllocCrunchInfo().
  186.  
  187.     During crunching your callback function will be called (if you have
  188.     provided one).  See the autodoc for ppAllocCrunchInfo() for more
  189.     information.
  190.  
  191.     The value returned is the length of the crunched buffer.  If you wish to
  192.     save this crunched buffer as a PowerPacker data file you should first
  193.     write the data header using ppWriteDataHeader() en then write the
  194.     crunched buffer.
  195.  
  196.   INPUTS
  197.     crunchinfo  - pointer to private crunchinfo structure returned by
  198.                   ppAllocCrunchInfo().
  199.     buffer      - pointer to buffer to be crunched.
  200.     len         - length of buffer to be crunched.
  201.  
  202.   RESULT
  203.     crunchedlen - length of crunched buffer. In case of an error
  204.                   'crunchedlen' may also equal PP_CRUNCHABORTED or
  205.                   PP_BUFFEROVERFLOW.  Be sure to check this!
  206.  
  207.   NOTE
  208.     Be sure you know what you are doing when you intend to use this function.
  209.     You can easily crash your Amiga by passing wrong arguments or by writing 
  210.     a faulty callback function.
  211.  
  212.   BUGS
  213.     none known
  214.  
  215.   SEE ALSO
  216.     ppCrunchBufferDest(), ppAllocCrunchInfo(), ppFreeCrunchInfo()
  217.  
  218. powerpacker.library/ppCrunchBufferDest powerpacker.library/ppCrunchBufferDest
  219.  
  220.   NAME  ppCrunchBufferDest()  (V36)
  221.  
  222.     crunchedlen = ppCrunchBufferDest (crunchinfo, buffer, dest, len);
  223.  
  224.     ULONG ppCrunchBufferDest (APTR, UBYTE *, UBYTE *, ULONG);
  225.     D0                        A0    A1       A2       D0
  226.  
  227.   DESCRIPTION
  228.     Crunch the buffer pointed to by 'buffer' and of length (in bytes) 'len'.
  229.     'crunchinfo' must have been previously allocated by ppAllocCrunchInfo().
  230.     The buffer will be crunched to the destination buffer you must provide.
  231.     The destination buffer must be at least as large as the original buffer.
  232.  
  233.     During crunching your callback function will be called (if you have
  234.     provided one).  See the autodoc for ppAllocCrunchInfo() for more
  235.     information.
  236.  
  237.     The value returned is the length of the crunched buffer.  If you wish to
  238.     save this crunched buffer as a PowerPacker data file you should first
  239.     write the data header using ppWriteDataHeader() en then write the
  240.     crunched destination buffer.
  241.  
  242.   INPUTS
  243.     crunchinfo  - pointer to private crunchinfo structure returned by
  244.                   ppAllocCrunchInfo().
  245.     buffer      - pointer to buffer to be crunched.
  246.     dest        - pointer to buffer to store crunched data in.
  247.     len         - length of buffer