Otherware

home *** CD-ROM | disk | FTP | other *** search

/ Otherware / Otherware_1_SB_Development.iso / amiga / misc / pplib15.lha / PPLib / doc / pplib.doc

Wrap

Text File | 1992-05-21 | 21.0 KB | 631 lines

TABLE OF CONTENTS powerpacker.library/ppAllocCrunchInfo powerpacker.library/ppCalcChecksum powerpacker.library/ppCalcPasskey powerpacker.library/ppCrunchBuffer powerpacker.library/ppDecrunchBuffer powerpacker.library/ppDecrypt powerpacker.library/ppEnterPassword powerpacker.library/ppErrorMessage powerpacker.library/ppFreeCrunchInfo powerpacker.library/ppGetPassword powerpacker.library/ppLoadData powerpacker.library/ppWriteDataHeader powerpacker.library/ppAllocCrunchInfo powerpacker.library/ppAllocCrunchInfo NAME ppAllocCrunchInfo() (V35) crunchinfo = ppAllocCrunchInfo (efficiency, speedup, function, userdata); APTR ppAllocCrunchInfo (ULONG, ULONG, BOOL (*)(), APTR); D0 D0 D1 A0 A1 DESCRIPTION Allocate all the necessary memory needed to crunch a buffer. This function must be called before using ppCrunchBuffer. You must pass the crunching efficiency and the size of the speedup buffer. You can pass a callback function to be called during crunching. Use this type of function: BOOL __stdargs myFunction (ULONG lensofar, ULONG crunlen, ULONG totlen, APTR userdata); If you do not wish to use this feature pass a NULL. The function can be used for two things: o to display the percentage crunched and gain so far. o to allow the user to abort crunching. Your function will be passed four arguments (on the stack, normal C conventions): lensofar - length of part crunched so far. crunlen - crunched length of lensofar. totlen - total length of buffer. userdata - the userdata you provided to ppAllocCrunchInfo(). If your function returns a non-zero value the crunching will continue, returning zero will abort crunching. SAS/C users shouldn't forget __saveds if they compiled their program with the small data model and wish to use global data in their function. If you write your function in assembly please preserve all registers. Example: BOOL __stdargs __saveds myfunc (ULONG sofar, ULONG crunlen, ULONG totlen, APTR userdata) { struct IntuiMessage *msg; UWORD code; if (sofar) { sprintf (buff, "%ld%% crunched. (%ld%% gain) ", (sofar * 100) / totlen, 100 - (100 * crunlen) / sofar); PrtMsg (buff, BLACK|AT_START); } while (msg = (struct IntuiMessage *)GetMsg (win->UserPort)) { code = msg->Code; ReplyMsg ((struct Message *)msg); if (code == 0x3 /* CTRL-C */) return (FALSE); } return (TRUE); } Finally note that you may scratch the A4 register. This is made possible to help people who wish to use 'userdata' to pass A4 (C data pointer). INPUTS efficiency - the efficiency of the crunching. One of the following (defined in "libraries/ppbase.[hi]"): CRUN_FAST CRUN_MEDIOCRE CRUN_GOOD CRUN_VERYGOOD CRUN_BEST speedup - size of speedup buffer to be used. One of the following (defined in "libraries/ppbase.[hi]"): SPEEDUP_BUFFSMALL - from 3K (fast) to 33K (best) SPEEDUP_BUFFMEDIUM - from 5K (fast) to 65K (best) SPEEDUP_BUFFLARGE - from 196K (fast) to 256K (best) function - callback function to be called every so often during crunching. Can be used to display percentage crunched so far and to abort crunching. userdata - anything you wish. Will be passed to your callback function. RESULT crunchinfo - pointer to private crunchinfo structure to be passed to ppCrunchBuffer (use ppFreeCrunchInfo to deallocate). NOTE 'crunchinfo' may be re-used to crunch several buffers. BUGS none known SEE ALSO ppFreeCrunchInfo(), ppCrunchBuffer() powerpacker.library/ppCalcChecksum powerpacker.library/ppCalcChecksum NAME ppCalcChecksum() sum = ppCalcChecksum (string); ULONG ppCalcChecksum (char *); D0:16 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. Upper 16 bits of checksum are 0. BUGS none SEE ALSO ppLoadData() ppDecrunchBuffer() ppDecrypt() ppCalcPasskey() powerpacker.library/ppCalcPasskey powerpacker.library/ppCalcPasskey NAME ppCalcPasskey() key = ppCalcPasskey (password); ULONG ppCalcPasskey (char *); D0 A0 DESCRIPTION This function calculates the 32 bit key associated with the given password to encrypt/decrypt crunched files with. 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/ppCrunchBuffer powerpacker.library/ppCrunchBuffer NAME ppCrunchBuffer() (V35) crunchedlen = ppCrunchBuffer (crunchinfo, buffer, len); ULONG ppCrunchBuffer (APTR, UBYTE *, ULONG); D0 A0 A1 D0 DESCRIPTION Crunch the buffer pointed to by 'buffer' and of length (in bytes) 'len'. 'crunchinfo' must have been previously allocated by ppAllocCrunchInfo(). During crunching your callback function will be called (if you have provided one). See the autodoc for ppAllocCrunchInfo() for more information. The value returned is the length of the crunched buffer. If you wish to save this crunched buffer as a PowerPacker data file you should first write the data header using ppWriteDataHeader() en then write the crunched buffer. INPUTS crunchinfo - pointer to private crunchinfo structure returned by ppAllocCrunchInfo(). buffer - pointer to buffer to be crunched. len - length of buffer to be crunched. RESULT crunchedlen - length of crunched buffer. In case of an error 'crunchedlen' may also equal PP_CRUNCHABORTED or PP_BUFFEROVERFLOW. Be sure to check this! NOTE Be sure you know what you are doing when you intend to use this function. You can easily crash your Amiga by passing wrong arguments or by writing a faulty callback function. BUGS none known SEE ALSO ppAllocCrunchInfo(), ppFreeCrunchInfo() powerpacker.library/ppDecrunchBuffer 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 (16 bits, not 32!). - read efficiency. - read the longword of decrunch info at the end of the file. - calculate 'decrlen'. - allocate 'decrlen' + 8 (safety margin) bytes. - load 'crunched file' and 'decrunch info' at start of allocated memory. - if PX20, prompt for a password (check result of ppGetPassword()!). - 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 in most cases. WARNING: 'effptr' is a POINTER to the efficiency longword read, NOT the efficiency longword itself! 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 (DECR_COL0, DECR_COL1, DECR_POINTER, DECR_SCROLL, DECR_NONE). See also 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/ppDecrypt 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). This function can also be used to encrypt files. 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/ppEnterPassword powerpacker.library/ppEnterPassword NAME ppEnterPassword() (V35) bool = ppEnterPassword (screen, buffer); BOOL ppEnterPassword (struct Screen *, char *); D0 A0 A1 DESCRIPTION reqtools.library _MUST_ be available! Opens a small requester to prompt the user for a password. The password will not be visible when typed. Returns when the user has succesfully entered a password AND a verification. When buffer already holds a string on entry, a 'Last' gadget will appear in the requester so the user may re-enter his last password without retyping it. It is up to you to support this feature. If you do not wish to support this make sure buffer holds an empty string (buffer[0] = 0). INPUTS screen - screen where the requester should appear or NULL. buffer - buffer to hold the password. Must be at least 17 bytes big! RESULT bool - TRUE if a password was entered (can be found in buffer), FALSE if user aborted the requester. NOTE The contents of the buffer will NOT change if the requester is aborted. Automatically adjusts the requester to the screen's font. ppEnterPassword() checks the pr_WindowPtr of your process to find the screen to put the requester on (if screen == NULL). BUGS none known SEE ALSO powerpacker.library/ppErrorMessage powerpacker.library/ppErrorMessage NAME ppErrorMessage() (V35) message = ppErrorMessage (errorcode); char *ppErrorMessage (ULONG); D0 D0 DESCRIPTION Returns a pointer to a null-terminated string holding a descriptive error message for the supplied error code. Currently only works for error codes returned by ppLoadData(). INPUTS errorcode - error code returned by ppLoadData(). RESULT message - pointer to error message (null terminated string) associated with error code. BUGS none known SEE ALSO ppLoadData() powerpacker.library/ppFreeCrunchInfo powerpacker.library/ppFreeCrunchInfo NAME ppFreeCrunchInfo() (V35) ppFreeCrunchInfo (crunchinfo); void ppFreeCrunchInfo (APTR); A0 DESCRIPTION Free all memory associated with the private crunchinfo structure returned by ppAllocCrunchInfo(). INPUTS crunchinfo - pointer to private crunchinfo structure. RESULT none NOTE crunchinfo may be NULL, no action will be taken. BUGS none known SEE ALSO ppAllocCrunchInfo(), ppCrunchBuffer() powerpacker.library/ppGetPassword powerpacker.library/ppGetPassword NAME ppGetPassword() bool = ppGetPassword (screen, buffer, maxlen, checksum); BOOL ppGetPassword (struct Screen *, UBYTE *, ULONG, ULONG); D0 A0 A1 D0 D1:16 DESCRIPTION reqtools.library _MUST_ be available! 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 - screen where the requester should appear. buffer - buffer to hold correct password. Must at least 17 bytes big! maxlen - maximum length of password, should always be 16. 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 attempts. NOTE New for V35: The contents of the buffer will NOT change if the requester is aborted. 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 screen's font. ppGetPassword() checks the pr_WindowPtr of your process to find the screen to put the requester on (if screen == NULL). BUGS none known SEE ALSO ppLoadData() ppDecrunchBuffer() powerpacker.library/ppLoadData 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, ULONG 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) (longwords!). Assembly functions must preserve all registers ! SAS/C users shouldn't forget __saveds if they compiled their program with the small data model and wish to use global data in their function. 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_EMPTYFILE - file is empty, there is nothing to load. 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(), ppErrorMessage(), ppGetPassword() powerpacker.library/ppWriteDataHeader powerpacker.library/ppWriteDataHeader NAME ppWriteDataHeader() (V35) success = ppWriteDataHeader (lock, efficiency, crypt, checksum); ULONG ppWriteDataHeader (BPTR, ULONG, BOOL, ULONG); D0 D0 D1 D2 D3:16 DESCRIPTION Use this function to write the PowerPacker data header at the beginning of a file. If you write the data header for an encrypted file remember you must have encrypted the file first using the ppDecrypt() function. Remember not to encrypt the last longword! INPUTS lock - BCPL pointer to a DOS file handle. efficiency - efficiency used to crunch the buffer. See ppAllocCrunchInfo(). (CRUN_FAST, ... ,CRUN_BEST) crypt - TRUE for a header of an encrypted file, FALSE otherwise. checksum - (if crypt = TRUE) checksum of password used to encrypt. RESULT success - TRUE on success, FALSE if a write error occured. NOTE BUGS none known SEE ALSO ppAllocCrunchInfo(), ppDecrypt()