home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / dirs / pplib_414.lzh / PPLib / doc / pplib.doc < prev    next >
Text File  |  1990-12-15  |  14KB  |  405 lines
  1. TABLE OF CONTENTS
  2.  
  3. powerpacker.library/ppLoadData
  4. powerpacker.library/ppDecrunchBuffer
  5. powerpacker.library/ppCalcChecksum
  6. powerpacker.library/ppCalcPasskey
  7. powerpacker.library/ppDecrypt
  8. powerpacker.library/ppGetPassword
  9. powerpacker.library/ppGetString
  10. powerpacker.library/ppGetLong
  11. powerpacker.library/ppLoadData                 powerpacker.library/ppLoadData
  12.  
  13.   NAME  ppLoadData()
  14.  
  15.     error = ppLoadData (filename, col, memtype, &buffer, &len, func);
  16.  
  17.     ULONG ppLoadData (char *, ULONG, ULONG, UBYTE **, ULONG *, BOOL (*)());
  18.     D0                A0      D0     D1     A1        A2       A3
  19.  
  20.   DESCRIPTION
  21.     This function loads a file in memory. The memory necessary to load the
  22.     file will be allocated by this function. Files crunched with PowerPacker
  23.     will be decrunched, plain files will simply be loaded. If the file can't
  24.     be opened ".pp" will be appended before trying again. The address of the
  25.     loaded file will be stored in 'buffer', the length in 'len'. You must
  26.     free this memory yourself (see NOTE) !
  27.  
  28.     The 'func' argument is the address of a function to be called when
  29.     ppLoadData() needs a password to decrypt an encrypted file. If you do
  30.     not want to load encrypted files call with func equal to -1, if you want
  31.     ppLoadData() to use ppGetPassword(), call with func equal to NULL.
  32.  
  33.     If you wish to use your own password prompting function you must call
  34.     ppLoadData() with func equal to the address of this type of function:
  35.  
  36.         BOOL __stdargs myFunction (UBYTE *password, ULONG checksum);
  37.  
  38.     On entry 'password' points to a buffer to hold up to 16 characters and a
  39.     terminating zero (so 17 bytes in all), 'checksum' is the checksum of the
  40.     password we are looking for. Your function must prompt for a string and
  41.     compare the checksum with 'checksum' (use ppCalcChecksum() for this). If
  42.     they are equal you must store the string in 'password' (in C you can use
  43.     'strcpy') and return TRUE, if not you should give the user a few more
  44.     chances (usually three in all) and return FALSE if no correct password
  45.     was entered. The two arguments are pushed on the stack according to C
  46.     convention, so if you write your function in assembly you will find the
  47.     arguments on the stack, the pointer to the buffer at 4(a7) and the
  48.     checksum at 8(a7) (longword !). Assembly functions must preserve all
  49.     registers !
  50.  
  51.   INPUTS
  52.     filename - pointer to a null terminated pathname of the file to load.
  53.     col      - the effect to be used during decrunching. One of the
  54.                following (defined in "libraries/ppbase.[hi]"):
  55.                    DECR_COL0    - flash color 0
  56.                    DECR_COL1    - flash color 1
  57.                    DECR_POINTER - flash mouse pointer
  58.                    DECR_SCROLL  - weird stuff :-)
  59.                    DECR_NONE    - no decrunching effect
  60.     memtype  - type of memory to allocate (see AllocMem()).
  61.     &buffer  - address of (!) variable to hold memory location of loaded
  62.                file.
  63.     &len     - address of (!) variable to hold length of loaded file.
  64.     func     - function to be called to prompt the user for a password,
  65.                NULL for the the default password prompt and -1 for no
  66.                password prompt.
  67.  
  68.   RESULT
  69.     error - 0 if all went ok, if not one of the following error codes will
  70.             be returned (defined in "libraries/ppbase.(h|i)"):
  71.                 PP_OPENERR   - unable to open file.
  72.                 PP_READERR   - read error.
  73.                 PP_NOMEMORY  - not enough memory to load file.
  74.                 PP_CRYPTED   - file is encrypted (only when 'func' == -1).
  75.                 PP_PASSERR   - incorrect password, 'func()' returned FALSE.
  76.                 PP_UNKNOWNPP - crunched by unknown version of PowerPacker.
  77.  
  78.   NOTE
  79.     Do not forget to free the memory allocated by this function !
  80.     Use "FreeMem (buffer, len);" before quitting your program, but only if
  81.     ppLoadData() didn't return an error.
  82.  
  83.     After calling 'func()' ppLoadData() doesn't check the checksum again,
  84.     only the returned boolean. Therefore it is VERY important that your
  85.     function is correct and only returns TRUE when the entered password has
  86.     the correct checksum !
  87.     Don't forget to copy your string to the memory pointed to by 'password'
  88.     before leaving 'func()' ! This password is needed to decrypt the file !!
  89.     Note that 'password' is a C string and must be null terminated !
  90.  
  91.     In case you call ppLoadData() with 'func' equal to NULL (use automatic
  92.     password prompting) the pr_WindowPtr of your Process will be used to
  93.     find the screen to open the password requester on. If pr_WindowPtr
  94.     equals 0 or -1 the WorkBench screen will be used, otherwise the screen
  95.     of the pr_WindowPtr window will be used. Only a process can call
  96.     ppLoadData() (it uses DOS) so pr_WindowPtr exists. Set it like this:
  97.  
  98.         struct Window *yourwindow;
  99.         struct Process *proc;
  100.         APTR oldwinptr;
  101.  
  102.         /* Open your screen and window... */
  103.  
  104.         ...
  105.  
  106.         /* set pr_WindowPtr */
  107.         proc = (struct Process *)FindTask (NULL);
  108.         oldwinptr = proc->pr_WindowPtr;
  109.         proc->pr_WindowPtr = (APTR)yourwindow;
  110.  
  111.         ...
  112.  
  113.         /* restore before quitting (VERY IMPORTANT !!) */
  114.         proc->pr_WindowPtr = oldwinptr;
  115.         exit (0);
  116.  
  117.   BUGS
  118.     none known
  119.  
  120.   SEE ALSO
  121.     exec.library/AllocMem()
  122.     exec.library/FreeMem()
  123.     ppCalcChecksum()
  124.     ppGetPassword()
  125.  
  126. powerpacker.library/ppDecrunchBuffer     powerpacker.library/ppDecrunchBuffer
  127.  
  128.   NAME  ppDecrunchBuffer()
  129.  
  130.     ppDecrunchBuffer (endcrun, decrbuff, effptr, col);
  131.  
  132.     void ppDecrunchBuffer (UBYTE *, UBYTE *, ULONG *, ULONG);
  133.                            A0       A1       A2       D0
  134.  
  135.   DESCRIPTION
  136.     Function to decrunch from one memory location to another. The address of
  137.     the destination can be as close as 8 bytes after the start address of
  138.     the source, so you can decrunch a file with almost no memory overhead.
  139.  
  140.     If you wish to call this function you need to know the format of a
  141.     crunched file:
  142.  
  143.         1 longword identifier           'PP20' or 'PX20'
  144.        [1 word checksum (if 'PX20')     $ssss]
  145.         1 longword efficiency           $eeeeeeee
  146.         X longwords crunched file       $cccccccc,$cccccccc,...
  147.         1 longword decrunch info        'decrlen' << 8 | '8 bits other info'
  148.  
  149.     The following procedure must be followed to decrunch a file:
  150.  
  151.     First you must read 'decrunch info' to find the length of the decrunched
  152.     file, then you must allocate memory to decrunch it in (shift 'decrunch
  153.     info' right 8 bits and add a safety margin (8 bytes) to get the length
  154.     of this memory block).  If the file is encrypted ('PX20') you must call
  155.     ppDecrypt to decrypt the crunched part before calling ppDecrunchBuffer.
  156.  
  157.     So:
  158.     - read identifier.
  159.     - if PX20, read checksum (16 bits, not 32 !).
  160.     - read efficiency.
  161.     - allocate 'decrlen' + 8 (safety margin) bytes.
  162.     - load 'crunched file' and 'decrunch info' at start of allocated memory.
  163.     - if PX20, prompt for a password (compare checksum !).
  164.     - if PX20, calculate the passkey (use ppCalcPasskey).
  165.     - if PX20, call ppDecrypt to decrypt 'crunched file' only.
  166.       (NOT 'decrunch info' !)
  167.     - and finally call ppDecrunchBuffer() with 'endcrun' pointing right after
  168.       'decrunch info', 'decrbuff' pointing 8 bytes after where you loaded the
  169.       file and 'effptr' pointing to the 'efficieny' longword.
  170.  
  171.     If this seems complicated that is probably because it is :-) ppLoadData
  172.     was written to make things simpler and should suffice for most cases.
  173.  
  174.   INPUTS
  175.     endcrun  - pointer just after the last byte of the crunched block.
  176.     decrbuff - pointer to beginning of memory to decrunch to (this must be
  177.                at least 8 bytes behind the start of the crunched file).
  178.     effptr   - pointer to efficiency table.
  179.     col      - decrunching effect (see ppLoadData).
  180.  
  181.   RESULT
  182.     none
  183.  
  184.   NOTE
  185.     This function is used by ppLoadData() and will probably not be used very
  186.     often on its own.
  187.  
  188.   BUGS
  189.     none known
  190.  
  191.   SEE ALSO
  192.     ppLoadData()
  193.     ppDecrypt()
  194.     ppCalcPasskey()
  195.     ppCalcChecksum()
  196.     ppGetPassword()
  197.  
  198. powerpacker.library/ppCalcChecksum         powerpacker.library/ppCalcChecksum
  199.  
  200.   NAME  ppCalcChecksum()
  201.  
  202.     sum = ppCalcChecksum (string);
  203.  
  204.     ULONG ppCalcChecksum (char *);
  205.     D0:16                 A0
  206.  
  207.   DESCRIPTION
  208.     This function calculates a 16 bit checksum of a given string of
  209.     characters.
  210.  
  211.   INPUTS
  212.     string - pointer to a null terminated character string.
  213.  
  214.   RESULT
  215.     sum - checksum of 'string'.
  216.  
  217.   NOTE
  218.     Function used to check if a password is correct.
  219.     Upper 16 bits of checksum are 0.
  220.  
  221.   BUGS
  222.     none
  223.  
  224.   SEE ALSO
  225.     ppLoadData()
  226.     ppDecrunchBuffer()
  227.     ppDecrypt()
  228.     ppCalcPasskey()
  229.  
  230. powerpacker.library/ppCalcPasskey           powerpacker.library/ppCalcPasskey
  231.  
  232.   NAME  ppCalcPasskey()
  233.  
  234.     key = ppCalcPasskey (password);
  235.  
  236.     ULONG ppCalcPasskey (char *);
  237.     D0                   A0
  238.  
  239.   DESCRIPTION
  240.  
  241.   INPUTS
  242.     string - pointer to a null terminated character string.
  243.  
  244.   RESULT
  245.     key - passkey corresponding to the given password.
  246.  
  247.   NOTE
  248.     Function used to decrypt encrypted files.
  249.  
  250.   BUGS
  251.     none
  252.  
  253.   SEE ALSO
  254.     ppDecrunchBuffer()
  255.     ppDecrypt()
  256.     ppCalcChecksum()
  257.  
  258. powerpacker.library/ppDecrypt                   powerpacker.library/ppDecrypt
  259.  
  260.   NAME  ppDecrypt()
  261.  
  262.     ppDecrypt (buffer, len, key)
  263.  
  264.     void ppDecrypt (UBYTE *, ULONG, ULONG);
  265.                     A0       D0     D1
  266.  
  267.   DESCRIPTION
  268.     This function will decrypt a memory region with a given passkey. It
  269.     must be called before calling ppDecrunchBuffer() (if the file was
  270.     encrypted).
  271.  
  272.   INPUTS
  273.     buffer - start address of memory region to decrypt (word alligned !).
  274.     len    - length in bytes of memory region to decrypt (rounded up to the
  275.              next multiple of 4).
  276.     key    - key of password as returned by ppCalcPasskey().
  277.  
  278.   RESULT
  279.     none
  280.  
  281.   NOTE
  282.     If you call this function before calling ppDecrunchBuffer make sure you
  283.     decrypt the correct memory region, don't decrypt the last longword !
  284.  
  285.   BUGS
  286.     none
  287.  
  288.   SEE ALSO
  289.     ppDecrunchBuffer()
  290.     ppCalcChecksum()
  291.     ppCalcPasskey()
  292.     ppLoadData()
  293.  
  294. powerpacker.library/ppGetPassword           powerpacker.library/ppGetPassword
  295.  
  296.   NAME  ppGetPassword()
  297.  
  298.     bool = ppGetPassword (screen, buffer, maxchars, checksum);
  299.  
  300.     BOOL ppGetPassword (struct Screen *, UBYTE *, ULONG, ULONG);
  301.     D0                  A0               A1       D0     D1:16
  302.  
  303.   DESCRIPTION
  304.     Opens a small requester to prompt the user for a password. Returns when
  305.     the user enters a password with a checksum equal to 'checksum' or when
  306.     he has failed to enter a correct password (three chances). The password
  307.     will not be visible when typed.
  308.  
  309.   INPUTS
  310.     screen   - address of Intuition screen where requester should appear,
  311.                or NULL for WorkBench screen.
  312.     buffer   - buffer to hold correct password.
  313.     maxchars - maximum number of characters in password (should be 16,
  314.                buffer should be at least 17 bytes big !).
  315.     checksum - checksum of password we are looking for.
  316.  
  317.   RESULT
  318.     bool - TRUE when the correct password was entered (can be found in
  319.            buffer), FALSE when no correct password was given after three
  320.            tries.
  321.  
  322.   NOTE
  323.     This function will be used by ppLoadData() to prompt for a password when
  324.     you called it with 'func' equal to NULL.
  325.  
  326.     Automatically adjusts the requester to the screens font.
  327.  
  328.   BUGS
  329.     none known
  330.  
  331.   SEE ALSO
  332.     ppLoadData()
  333.     ppDecrunchBuffer()
  334.  
  335. powerpacker.library/ppGetString               powerpacker.library/ppGetString
  336.  
  337.   NAME  ppGetString()
  338.  
  339.     bool = ppGetString (screen, buffer, maxchars, title);
  340.  
  341.     BOOL ppGetString (struct Screen *, UBYTE *, ULONG, char *);
  342.     D0                A0               A1       D0     A2
  343.  
  344.   DESCRIPTION
  345.     Puts up a string requester to get a line of text from the user.
  346.     The string present in 'buffer' upon entry will be displayed, ready to
  347.     be edited.
  348.  
  349.   INPUTS
  350.     screen   - address of Intuition screen where requester should appear,
  351.                or NULL for WorkBench screen.
  352.     buffer   - pointer to buffer to hold characters entered.
  353.     maxchars - maximum number of characters that fit in buffer (EX-cluding
  354.                the 0 to terminate the string !).
  355.     title    - pointer to null terminated title of requester window.
  356.  
  357.   RESULT
  358.     bool - TRUE if user entered something, FALSE otherwise (empty buffer).
  359.  
  360.   NOTE
  361.     Doesn't have much to do with PowerPacker, but was put in because it is
  362.     a useful function and it only required a small amount of code (using
  363.     the main part of the ppGetPassword() function).
  364.  
  365.     Automatically adjusts the requester to the screens font.
  366.  
  367.   BUGS
  368.     none known
  369.  
  370.   SEE ALSO
  371.  
  372. powerpacker.library/ppGetLong                   powerpacker.library/ppGetLong
  373.  
  374.   NAME  ppGetLong()
  375.  
  376.     bool = ppGetLong (screen, &longvar, title);
  377.  
  378.     BOOL ppGetLong (struct Screen *, ULONG *, char *);
  379.     D0              A0               A1       A2
  380.  
  381.   DESCRIPTION
  382.     Puts up a requester to get a signed long (32-bit) number from the user.
  383.  
  384.   INPUTS
  385.     screen   - address of Intuition screen where requester should appear,
  386.                or NULL for WorkBench screen.
  387.     &longvar - address of (!) long (32 bit) variable to hold result.
  388.     title    - points to null terminated title of requester window.
  389.  
  390.   RESULT
  391.     bool - TRUE if user entered a number, FALSE if not.
  392.  
  393.   NOTE
  394.     Doesn't have much to do with PowerPacker, but was put in because it is
  395.     a useful function and it only required a small amount of code (using
  396.     the main part of the ppGetPassword() function).
  397.  
  398.     Automatically adjusts the requester to the screens font.
  399.  
  400.   BUGS
  401.     none known
  402.  
  403.   SEE ALSO
  404.  
  405.