POWERPACKER LIBRARY Typed in by ???. Edited by PARASITE. TABLE OF CONTENTS powerpacker.library/ppLoadData powerpacker.library/ppDecrunchBuffer powerpacker.library/ppCalcChecksum powerpacker.library/ppCalcPasskey powerpacker.library/ppDecrypt powerpacker.library/ppGetPassword powerpacker.library/ppGetString powerpacker.library/ppGetLong powerpacker.library/ppLoadData NAME ppLoadData() error = ppLoadData (filename, col, memtype, &buffer, &len, func); ULONG ppLoadData (char *, ULONG, ULONG, UBYTE **, ULONG *, BOOL (*)()); D0 A0 D0 D1 A1 A2 A3 DESCRIPTION This function loads a file in memory. The memory necessary to load the file will be allocated by this function. Files crunched with PowerPacker will be decrunched, plain files will simply be loaded. If the file can't be opened ".pp" will be appended before trying again. The address of the loaded file will be stored in 'buffer', the length in 'len'. You must free this memory yourself (see NOTE) ! The 'func' argument is the address of a function to be called when ppLoadData() needs a password to decrypt an encrypted file. If you do not want to load encrypted files call with func equal to -1, if you want ppLoadData() to use ppGetPassword(), call with func equal to NULL. If you wish to use your own password prompting function you must call ppLoadData() with func equal to the address of this type of function: BOOL __stdargs myFunction (UBYTE *password, UWORD checksum); On entry 'password' points to a buffer to hold up to 16 characters and a terminating zero (so 17 bytes in all), 'checksum' is the checksum of the password we are looking for. Your function must prompt for a string and compare the checksum with 'checksum' (use ppCalcChecksum() for this). If they are equal you must store the string in 'password' (in C you can use 'strcpy') and return TRUE, if not you should give the user a few more chances (usually three in all) and return FALSE if no correct password was entered. The two arguments are pushed on the stack according to C convention, so if you write your function in assembly you will find the arguments on the stack, the pointer to the buffer at 4(a7) and the checksum at 8(a7) (longword !). Assembly functions must preserve all registers ! INPUTS filename - pointer to a null terminated pathname of the file to load. col - the effect to be used during decrunching. One of the following (defined in "libraries/ppbase.[hi]"): DECR_COL0 - flash color 0 DECR_COL1 - flash color 1 DECR_POINTER - flash mouse pointer DECR_SCROLL - weird stuff :-) DECR_NONE - no decrunching effect memtype - type of memory to allocate (see AllocMem()). &buffer - address of (!) variable to hold memory location of loaded file. &len - address of (!) variable to hold length of loaded file. func - function to be called to prompt the user for a password, NULL for the the default password prompt and -1 for no password prompt. RESULT error - 0 if all went ok, if not one of the following error codes will be returned (defined in "libraries/ppbase.(h|i)"): PP_OPENERR - unable to open file. PP_READERR - read error. PP_NOMEMORY - not enough memory to load file. PP_CRYPTED - file is encrypted (only when 'func' == -1). PP_PASSERR - incorrect password, 'func()' returned FALSE. PP_UNKNOWNPP - crunched by unknown version of PowerPacker. NOTE Do not forget to free the memory allocated by this function ! Use "FreeMem (buffer, len);" before quitting your program, but only if ppLoadData() didn't return an error. After calling 'func()' ppLoadData() doesn't check the checksum again, only the returned boolean. Therefore it is VERY important that your function is correct and only returns TRUE when the entered password has the correct checksum ! Don't forget to copy your string to the memory pointed to by 'password' before leaving 'func()' ! This password is needed to decrypt the file !! Note that 'password' is a C string and must be null terminated ! In case you call ppLoadData() with 'func' equal to NULL (use automatic password prompting) the pr_WindowPtr of your Process will be used to find the screen to open the password requester on. If pr_WindowPtr equals 0 or -1 the WorkBench screen will be used, otherwise the screen of the pr_WindowPtr window will be used. Only a process can call ppLoadData() (it uses DOS) so pr_WindowPtr exists. Set it like this: struct Window *yourwindow; struct Process *proc; APTR oldwinptr; /* Open your screen and window... */ ... /* set pr_WindowPtr */ proc = (struct Process *)FindTask (NULL); oldwinptr = proc->pr_WindowPtr; proc->pr_WindowPtr = (APTR)yourwindow; ... /* restore before quitting (VERY IMPORTANT !!) */ proc->pr_WindowPtr = oldwinptr; exit (0); BUGS none known SEE ALSO exec.library/AllocMem() exec.library/FreeMem() ppCalcChecksum() ppGetPassword() powerpacker.library/ppDecrunchBuffer NAME ppDecrunchBuffer() ppDecrunchBuffer (endcrun, decrbuff, effptr, col); void ppDecrunchBuffer (UBYTE *, UBYTE *, ULONG *, ULONG); A0 A1 A2 D0 DESCRIPTION Function to decrunch from one memory location to another. The address of the destination can be as close as 8 bytes after the start address of the source, so you can decrunch a file with almost no memory overhead. If you wish to call this function you need to know the format of a crunched file: 1 longword identifier 'PP20' or 'PX20' [1 word checksum (if 'PX20') $ssss] 1 longword efficiency $eeeeeeee X longwords crunched file $cccccccc,$cccccccc,... 1 longword decrunch info 'decrlen' << 8 | '8 bits other info' The following procedure must be followed to decrunch a file: First you must read 'decrunch info' to find the length of the decrunched file, then you must allocate memory to decrunch it in (shift 'decrunch info' right 8 bits and add a safety margin (8 bytes) to get the length of this memory block). If the file is encrypted ('PX20') you must call ppDecrypt to decrypt the crunched part before calling ppDecrunchBuffer. So: - read identifier. - if PX20, read checksum. - read efficiency. - allocate 'decrlen' + 8 (safety margin) bytes. - load 'crunched file' and 'decrunch info' at start of allocated memory. - if PX20, prompt for a password (compare checksum !). - if PX20, calculate the passkey (use ppCalcPasskey). - if PX20, call ppDecrypt to decrypt 'crunched file' only. (NOT 'decrunch info' !) - and finally call ppDecrunchBuffer() with 'endcrun' pointing right after 'decrunch info', 'decrbuff' pointing 8 bytes after where you loaded the file and 'effptr' pointing to the 'efficieny' longword. If this seems complicated that is probably because it is :-) ppLoadData was written to make things simpler and should suffice for most cases. INPUTS endcrun - pointer just after the last byte of the crunched block. decrbuff - pointer to beginning of memory to decrunch to (this must be at least 8 bytes behind the start of the crunched file). effptr - pointer to efficiency table. col - decrunching effect (see ppLoadData). RESULT none NOTE This function is used by ppLoadData() and will probably not be used very often on its own. BUGS none known SEE ALSO ppLoadData() ppDecrypt() ppCalcPasskey() ppCalcChecksum() ppGetPassword() powerpacker.library/ppCalcChecksum NAME ppCalcChecksum() sum = ppCalcChecksum (string); UWORD ppCalcChecksum (char *); D0 A0 DESCRIPTION This function calculates a 16 bit checksum of a given string of characters. INPUTS string - pointer to a null terminated character string. RESULT sum - checksum of 'string'. NOTE Function used to check if a password is correct. BUGS none SEE ALSO ppLoadData() ppDecrunchBuffer() ppDecrypt() ppCalcPasskey() powerpacker.library/ppCalcPasskey NAME ppCalcPasskey() key = ppCalcPasskey (password); ULONG ppCalcPasskey (char *); D0 A0 DESCRIPTION INPUTS string - pointer to a null terminated character string. RESULT key - passkey corresponding to the given password. NOTE Function used to decrypt encrypted files. BUGS none SEE ALSO ppDecrunchBuffer() ppDecrypt() ppCalcChecksum() powerpacker.library/ppDecrypt NAME ppDecrypt() ppDecrypt (buffer, len, key) void ppDecrypt (UBYTE *, ULONG, ULONG); A0 D0 D1 DESCRIPTION This function will decrypt a memory region with a given passkey. It must be called before calling ppDecrunchBuffer() (if the file was encrypted). INPUTS buffer - start address of memory region to decrypt (word alligned !). len - length in bytes of memory region to decrypt (rounded up to the next multiple of 4). key - key of password as returned by ppCalcPasskey(). RESULT none NOTE If you call this function before calling ppDecrunchBuffer make sure you decrypt the correct memory region, don't decrypt the last longword ! BUGS none SEE ALSO ppDecrunchBuffer() ppCalcChecksum() ppCalcPasskey() ppLoadData() powerpacker.library/ppGetPassword NAME ppGetPassword() bool = ppGetPassword (screen, buffer, maxchars, checksum); BOOL ppGetPassword (struct Screen *, UBYTE *, ULONG, UWORD); D0 A0 A1 D0 D1 DESCRIPTION Opens a small requester to prompt the user for a password. Returns when the user enters a password with a checksum equal to 'checksum' or when he has failed to enter a correct password (three chances). The password will not be visible when typed. INPUTS screen - address of Intuition screen where requester should appear, or NULL for WorkBench screen. buffer - buffer to hold correct password. maxchars - maximum number of characters in password (should be 16, buffer should be at least 17 bytes big !). checksum - checksum of password we are looking for. RESULT bool - TRUE when the correct password was entered (can be found in buffer), FALSE when no correct password was given after three tries. NOTE This function will be used by ppLoadData() to prompt for a password when you called it with 'func' equal to NULL. Automatically adjusts the requester to the screens font. BUGS none known SEE ALSO ppLoadData() ppDecrunchBuffer() powerpacker.library/ppGetString NAME ppGetString() bool = ppGetString (screen, buffer, maxchars, title); BOOL ppGetString (struct Screen *, UBYTE *, ULONG, char *); D0 A0 A1 D0 A2 DESCRIPTION Puts up a string requester to get a line of text from the user. The string present in 'buffer' upon entry will be displayed, ready to be edited. INPUTS screen - address of Intuition screen where requester should appear, or NULL for WorkBench screen. buffer - pointer to buffer to hold characters entered. maxchars - maximum number of characters that fit in buffer (EX-cluding the 0 to terminate the string !). title - pointer to null terminated title of requester window. RESULT bool - TRUE if user entered something, FALSE otherwise (empty buffer). NOTE Doesn't have much to do with PowerPacker, but was put in because it is a useful function and it only required a small amount of code (using the main part of the ppGetPassword() function). Automatically adjusts the requester to the screens font. BUGS none known SEE ALSO powerpacker.library/ppGetLong NAME ppGetLong() bool = ppGetLong (screen, &longvar, title); BOOL ppGetLong (struct Screen *, ULONG *, char *); D0 A0 A1 A2 DESCRIPTION Puts up a requester to get a signed long (32-bit) number from the user. INPUTS screen - address of Intuition screen where requester should appear, or NULL for WorkBench screen. &longvar - address of (!) long (32 bit) variable to hold result. title - points to null terminated title of requester window. RESULT bool - TRUE if user entered a number, FALSE if not. NOTE Doesn't have much to do with PowerPacker, but was put in because it is a useful function and it only required a small amount of code (using the main part of the ppGetPassword() function). Automatically adjusts the requester to the screens font. End.