System Booster

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

/ System Booster / System Booster.iso / Archives / ForCLI / infolist.lha / Infolist / developer / xfd / autodoc / xfdmaster.doc

Wrap

Text File | 1995-01-05 | 21.8 KB | 677 lines

TABLE OF CONTENTS xfdmaster.library/--Overview-- xfdmaster.library/xfdAllocBufferInfo xfdmaster.library/xfdAllocSegmentInfo xfdmaster.library/xfdDecrunchBuffer xfdmaster.library/xfdDecrunchSegment xfdmaster.library/xfdFreeBufferInfo xfdmaster.library/xfdFreeSegmentInfo xfdmaster.library/xfdGetErrorText xfdmaster.library/xfdRecogBuffer xfdmaster.library/xfdRecogSegment xfdmaster.library/xfdRelocate xfdmaster.library/xfdTestHunkStructure xfdmaster.library/xfdTestHunkStructureNew xfdForeman/--Overview-- xfdSlave/--Overview-- xfdSlave/RecogBufferXYZ xfdSlave/DecrunchBufferXYZ xfdSlave/RecogSegmentXYZ xfdSlave/DecrunchSegmentXYZ xfdmaster.library/--Overview-- xfdmaster.library/--Overview-- This section describes the usual way how to use xfdmaster.library from your own applications. If you want to decrunch files from a buffer, do it like this: 1. Call xfdAllocBufferInfo(). If not successful, go on with 12. 2. Get file size, allocate buffer with that size and load file to buffer. If not successful, go on with 10. 3. Call xfdRecogBuffer() with xfdbi_SourceBuffer and xfdbi_SourceBufLen initialized. If not successful, file is not crunched and you may work with that file as it is, release the used memory and go on with 10. 4. Check xfdbi_PackerFlags for XFDPFB_PASSWORD, go on with 6. if not set. 5. Get password (maximum length is stored in xfdbi_MaxSpecialLen) and store a pointer to it in xfdbi_Special. 6. Initialize xfdbi_TargetBufMemType and call xfdDecrunchBuffer(). If not successful, work with crunched file, release memory afterwards and go on with 10. 7. Release memory of xfdbi_SourceBuffer. 8. Work with decrunched file. 9. Release memory of xfdbi_TargetBuffer. 10. If you have another file to decrunch, step back to 2. 11. Call xfdFreeBufferInfo(). 12. Exit! If you want to decrunch a segment list, do it like this: 1. Call xfdAllocSegmentInfo(). If not successful, go on with 11. 2. dos.library/LoadSeg() file. If not successful, go on with 9. 3. Call xfdRecogSegment() with xfdsi_SegList initialized. If not successful, seglist isn't crunched and you may go on with 7. 4. Check xfdsi_PackerFlags for XFDPFB_PASSWORD. If set, get password (maximum length is stored in xfdsi_MaxSpecialLen) and store a pointer to it in xfdsi_Special. 5. (V34) Check xfdsi_PackerFlags for XFDPFB_RELMODE. If set, init xfdsi_RelMode with the desired value. 6. Call xfdDecrunchSegment(). If not successful, test xfdsi_SegList. If this field contains NULL, no seglist is available anymore. You have to dos.library/LoadSeg() the file again then. 7. Work with segment list. 8. dos.library/UnloadSeg() segment list. 9. If you have another segment list to decrunch, step back to 2. 10. Call xfdFreeSegmentInfo(). 11. Exit! Whenever you intend to use a feature of the xfdmaster.library that is marked (V34) or higher, make sure that you use this version number during the exec.library/OpenLibrary() call. Otherwise, if you try to use new features with an old library version, the system might crash. xfdmaster.library/xfdAllocBufferInfo xfdmaster.library/xfdAllocBufferInfo NAME xfdAllocBufferInfo -- Allocate memory for BufferInfo structure. SYNOPSIS bufferinfo = xfdAllocBufferInfo() D0 -30 struct xfdBufferInfo *xfdAllocBufferInfo(void); FUNCTION Allocates a memory block large enough to hold all information of the xfdBufferInfo structure. Never do this in any other way for compatibility with library updates. INPUTS None. RESULT bufferinfo - Pointer to the xfdBufferInfo structure or NULL if there occured an error. SEE ALSO xfdFreeBufferInfo() xfdmaster.library/xfdAllocSegmentInfo xfdmaster.library/xfdAllocSegmentInfo NAME xfdAllocSegmentInfo -- Allocate memory for SegmentInfo structure. SYNOPSIS segmentinfo = xfdAllocSegmentInfo() D0 -42 struct xfdSegmentInfo *xfdAllocSegmentInfo(void); FUNCTION Allocates a memory block large enough to hold all information of the xfdSegmentInfo structure. Never do this in any other way for compatibility with library updates. INPUTS None. RESULT segmentinfo - Pointer to the xfdSegmentInfo structure or NULL if there occured an error. SEE ALSO xfdFreeSegmentInfo() xfdmaster.library/xfdDecrunchBuffer xfdmaster.library/xfdDecrunchBuffer NAME xfdDecrunchBuffer -- Decrunch a file from buffer. SYNOPSIS success = xfdDecrunchBuffer(bufferinfo) D0 -60 A0 BOOL xfdDecrunchBuffer(struct xfdBufferInfo *); FUNCTION Decrunches a file to a separate buffer. You have to call xfdRecogBuffer() first, only if this call was successful, you may call xfdDecrunchBuffer(). You have to pass the type of memory that should be used for the target buffer in xfdbi_TargetBufMemType. Additionally you have to init the xfdbi_Special field with a pointer to a special info buffer if any special flags are set in the xfdbi_PackerFlags field. The contents of this buffer depend on the type of special info (eg. password). If the decrunching was successful, the following fields in the xfdBufferInfo structure will be initialized: xfdbi_TargetBuffer - Pointer to decrunched file buffer. xfdbi_TargetBufSaveLen - Length of decrunched file (for saving etc.). xfdbi_TargetBufLen - Total length of allocated buffer. xfdbi_DecrAddress - If XFDPFB_ADDR is set in xfdbi_PackerFlags, this contains the address where the crunched file has been relocated to. xfdbi_JmpAddress - If XFDPFB_ADDR is set in xfdbi_PackerFlags, this contains the address where to jump at in order to run the file. INPUTS bufferinfo - Pointer to an initialized xfdBufferInfo structure: xfdbi_TargetBufMemType - Type of memory for target buffer. xfdbi_Special - Pointer to special info if required. RESULT success - TRUE if decrunching was successful, FALSE if anything went wrong. NOTE xfdDecrunchBuffer() allocates a buffer for the decrunched file, but it doesn't release this memory afterwards. That is because you first have to work with the decrunched file (what else?). Therefore you have to do a call to exec.library/FreeMem() after you finished work. Use the following parameters: xfdbi_TargetBufLen - Lenght of buffer. xfdbi_TargetBuffer - Pointer to buffer. Don't forget: xfdbi_TargetBufLen contains the length of the allocated memory area, xfdbi_TargetBufSaveLen the length of the decrunched file in that buffer. xfdDecrunchBuffer() never touches the buffer that contains the crunched file. It's again your task to release this after decrunching. SEE ALSO xfdRecogBuffer(), exec.library/FreeMem() xfdmaster.library/xfdDecrunchSegment xfdmaster.library/xfdDecrunchSegment NAME xfdDecrunchSegment -- Decrunch a file from its segment list. SYNOPSIS success = xfdDecrunchSegment(segmentinfo) D0 -72 A0 BOOL xfdDecrunchSegment(struct xfdSegmentInfo *); FUNCTION Decrunches a segment list. You have to call xfdRecogSegment() first, only if this call was successful, you may call xfdDecrunchSegment(). You have to init the xfdsi_Special field with a pointer to a special info buffer if any special flags are set in the xfdsi_PackerFlags field. The contents of this buffer depend on the type of special info (eg. password). (V34) Check xfdsi_Packerflags for XFDPFB_RELMODE. If set, initialize xfdsi_RelMode with the desired XFDREL_#? value. If decrunching was successful, xfdsi_SegList holds a BPTR to the decrunched segment list. The old segment list has been released and/or replaced by the new one (depends on cruncher). If decrunching failed, xfdsi_SegList may be NULL. This happens if an error occured after the seglist has already been changed in any way. It then will be released. Otherwise, if xfdsi_SegList is not NULL, it still contains a valid BPTR to the crunched segment list. INPUTS segmentinfo - Pointer to an initialized xfdSegmentInfo structure: xfdsi_Special - Pointer to special info if required. xfdsi_RelMode - (V34) XFDREL_#? value if required. RESULT success - TRUE if decrunching was successful, FALSE if anything went wrong. NOTE If you no longer need the decrunched segment list, you may release it by simply calling dos.library/UnloadSeg(). SEE ALSO xfdRecogSegment(), dos.library/UnloadSeg() xfdmaster.library/xfdFreeBufferInfo xfdmaster.library/xfdFreeBufferInfo NAME xfdFreeBufferInfo -- Free memory of xfdBufferInfo structure. SYNOPSIS xfdFreeBufferInfo(bufferinfo) -36 A1 void xfdFreeBufferInfo(struct xfdBufferInfo *); FUNCTION Deallocates the memory reserved via xfdAllocBufferInfo(). INPUTS bufferinfo - Pointer to xfdBufferInfo structure. RESULT None. SEE ALSO xfdAllocBufferInfo() xfdmaster.library/xfdFreeSegmentInfo xfdmaster.library/xfdFreeSegmentInfo NAME xfdFreeSegmentInfo -- Free memory of xfdSegmentInfo structure. SYNOPSIS xfdFreeSegmentInfo(segmentinfo) -48 A1 void xfdFreeSegmentInfo(struct xfdSegmentInfo *); FUNCTION Deallocates the memory reserved via xfdAllocSegmentInfo(). INPUTS segmentinfo - Pointer to xfdSegmentInfo structure. RESULT None. SEE ALSO xfdAllocSegmentInfo() xfdmaster.library/xfdGetErrorText xfdmaster.library/xfdGetErrorText NAME xfdGetErrorText -- Get an ascii string from an error number. SYNOPSIS string = xfdGetErrorText(error) D0 -78 D0.w STRPTR xfdGetErrorText(UWORD); FUNCTION Whenever a library call fails, you receive an error number either in the xfd#?_Error field or directly as a returncode. This function gets the corresponding ascii string to the occured error. INPUTS error - Error number from xfd#?_Error or returncode. RESULT string - Pointer to an ascii string that describes the error. SEE ALSO xfdDecrunchBuffer(), xfdDecrunchSegment(), xfdRelocate(), xfdTestHunkStructureNew() xfdmaster.library/xfdRecogBuffer xfdmaster.library/xfdRecogBuffer NAME xfdRecogBuffer -- Examine buffer for crunched file. SYNOPSIS success = xfdRecogBuffer(bufferinfo) D0 -54 A0 BOOL xfdRecogBuffer(struct xfdBufferInfo *); FUNCTION Examines a file for known crunchers. You pass a pointer to the file buffer in xfdbi_SourceBuffer and the length of the buffer in xfdbi_SourceBufLen. If a crunched file has been recognized, the following fields in the xfdBufferInfo structure will be initialized: xfdbi_PackerName - Pointer to the name of the cruncher. xfdbi_PackerFlags - Contains the packer type and additional information (eg. password). xfdbi_MaxSpecialLen - Only used if any special flags are set. INPUTS bufferinfo - Pointer to an initialized xfdBufferInfo structure: xfdbi_SourceBuffer - Pointer to file buffer. xfdbi_SourceBufLen - Length of file buffer. RESULT success - TRUE if a cruncher has been recognized, FALSE if file is unknown. SEE ALSO xfdDecrunchBuffer() xfdmaster.library/xfdRecogSegment xfdmaster.library/xfdRecogSegment NAME xfdRecogSegment -- Examine segment list for crunched file. SYNOPSIS success = xfdRecogSegment(segmentinfo) D0 -66 A0 BOOL xfdRecogSegment(struct xfdSegmentInfo *); FUNCTION Examines a segment list for known crunchers. You pass a BPTR to the segment list in xfdsi_SegList. If a crunched segment list has been recognized, the following fields in the xfdSegmentInfo structure will be initialized: xfdsi_PackerName - Pointer to the name of the cruncher. xfdsi_PackerFlags - Contains the packer type and additional information (eg. password). xfdsi_MaxSpecialLen - Only used if any special flags are set. INPUTS segmentinfo - Pointer to an initialized xfdSegmentInfo structure: xfdsi_SegList - BPTR to segment list. RESULT success - TRUE if a cruncher has been recognized, FALSE if segment list is unknown. SEE ALSO xfdDecrunchSegment() xfdmaster.library/xfdRelocate xfdmaster.library/xfdRelocate NAME xfdRelocate -- Create segment list from file buffer. (V34) SYNOPSIS error = xfdRelocate(buffer, length, result, mode) D0.w -96 A0 D0 A1 D1.w UWORD xfdRelocate(APTR, ULONG, ULONG *, UWORD); FUNCTION Creates a relocated and fully executable segment list from a file buffer. The result is a BPTR to the first segment, similar to the result of a call to dos.library/LoadSeg(). INPUTS buffer - Pointer to the file buffer that should be relocated. length - Length of the file buffer. result - Pointer to the longword that should hold the result. mode - Any XFDREL_#? relocation mode. RESULT error - XFDERR_OK if no error occured, else XFDERR_#?. result - Holds a BPTR to the first segment if error = XFDERR_OK. NOTE There is no need to call xfdTestHunkStructure[New]() before relocation because xfdRelocate() does this already. This routine supports the following hunk types: - hunk_unit ($3e7) -> Skipped. - hunk_name ($3e8) -> Skipped. - hunk_code ($3e9) -> Creates new code segment. - hunk_data ($3ea) -> Creates new data segment. - hunk_bss ($3eb) -> Creates new bss segment. - hunk_reloc32 ($3ec) -> Used for relocation. - hunk_ext ($3ef) -> Skipped. - hunk_symbol ($3f0) -> Skipped. - hunk_debug ($3f1) -> Skipped. - hunk_end ($3f2) -> May be left out. Any other hunk types create an error. There is no support for hunk_overlay, because the main purpose of this routine is to be called from xfds_DecrunchSegment. And in that case, the real dos.library/LoadSeg() has already initialized the overlay header. xfdmaster.library/xfdTestHunkStructure xfdmaster.library/xfdTestHunkStructure NAME xfdTestHunkStructure -- Test hunks of executable file. SYNOPSIS success = xfdTestHunkStructure(buffer, length) D0 -84 A0 D0 BOOL xfdTestHunkStructure(APTR, ULONG); FUNCTION Checks an executable file for a valid hunk structure. This is important for decrunching files, because an incomplete or damaged file may cause a system crash. INPUTS buffer - Pointer to the file buffer that should be checked. length - Length of the file buffer. RESULT success - TRUE if file is ok, FALSE if file is damaged. SEE ALSO xfdTestHunkStructureNew() xfdmaster.lib/xfdTestHunkStructureNew xfdmaster.lib/xfdTestHunkStructureNew NAME xfdTestHunkStructureNew -- Test hunks of executable file. (V34) SYNOPSIS error = xfdTestHunkStructureNew(buffer, length) D0.w -90 A0 D0 UWORD xfdTestHunkStructureNew(APTR, ULONG); FUNCTION Checks an executable file for a valid hunk structure. This is important for decrunching files, because an incomplete or damaged file may cause a system crash. INPUTS buffer - Pointer to the file buffer that should be checked. length - Length of the file buffer. RESULT error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged. NOTE You don't have to call this function before trying to decrunch a file, because xfdDecrunchBuffer() does this already. This hunk checker supports all standard hunk types from hunk_unit ($3e7) to hunk_index ($3fb). It recognizes the standard hunk_overlay ($3f5) format and some user-defined overlay types too. Anyway, it may happen that some weird overlay hunk causes problems because there isn't any real definition for overlays. The hunk structure of a non-overlayed file will nevertheless be checked 100% correctly. SEE ALSO xfdTestHunkStructure() xfdForeman/--Overview-- xfdForeman/--Overview-- The xfdForeman structure is just some kind of header for external slaves. It protects the slaves from being executed accidentally by having a small piece of code (moveq #-1,d0 : rts) in the first 4 bytes. The master can identify a valid bunch of external slaves by checking the first few bytes of the file for the foreman identification. Finally, a foreman holds the pointer to a linked list of slaves and thus enables the master to work with these slaves. xfdSlave/--Overview-- xfdSlave/--Overview-- The xfdSlave structure is the heart of the whole library system. Each slave enables the master to recognize and decrunch packed files and/or segments. Therefore each slave contains 4 routines that are called from the master. Pointers to these routines are stored in xfds_Recog#? and xfds_Decrunch#?. All have one thing in common: the CPU registers D0/D1/A0/A1 are so called scratch registers, they may change during execution, all other registers must remain unchanged. CPU register A6 holds a pointer to the xfdMasterBase structure. See chapters below for a description of the slave routines. ALL SLAVE ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC MEMORY AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT THE ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME! The name of the packer that is supported by the slave and the flags that describe the packer are stored in xfds_PackerName and xfds_PackerFlags. Whenever you intend to use features of the xfdmaster.library in your slaves that are marked (V34) or higher, make sure to set xfds_MasterVersion to the desired version number, otherwise an old library version might crash while using the new slave. xfdSlave/RecogBufferXYZ xfdSlave/RecogBufferXYZ NAME RecogBufferXYZ -- Recognize crunched file in buffer. SYNOPSIS result = RecogBufferXYZ(buffer, length) D0 A0 D0 BOOL RecogBufferXYZ(APTR, ULONG); FUNCTION This routine should examine the buffer for a crunched file. First thing is to check if the size of the file allows it to be crunched with the packer in question. After that, simply do some compares to figure out if the file has been crunched or not. INPUTS buffer - Pointer to a buffer that holds the crunched file. length - Length of that buffer. RESULT result - TRUE if packer has been recognized, else FALSE. NOTE You have to initialize xfds_RecogBuffer with a pointer to your RecogBufferXYZ routine. SEE ALSO Example sourcecodes. xfdSlave/DecrunchBufferXYZ xfdSlave/DecrunchBufferXYZ NAME DecrunchBufferXYZ -- Decrunch file from buffer to buffer. SYNOPSIS result = DecrunchBufferXYZ(bufferinfo) D0 A0 BOOL DecrunchBufferXYZ(struct xfdBufferInfo *); FUNCTION The typical steps of such a routine are: - Get length of decrunched file (exactly or a bit too much). - Allocate memory (with memtype from xfdbi_TargetBufMemType). - Decrunch file from xfdbi_SourceBuffer to xfdbi_TargetBuffer. - Initialize all necessary parts of the xfdBufferInfo structure. - Set xfdbi_Error if an error occurs. INPUTS bufferinfo - A valid xfdBufferInfo structure that successfully went through a call to xfdRecogBuffer(). RESULT result - TRUE if decrunching succeeded, FALSE if something went wrong. NOTE You have to initialize xfds_DecrunchBuffer with a pointer to your DecrunchBufferXYZ routine. SEE ALSO Example sourcecodes. xfdSlave/RecogSegmentXYZ xfdSlave/RecogSegmentXYZ NAME RecogSegmentXYZ -- Recognize crunched segment list. SYNOPSIS result = RecogSegmentXYZ(seglist) D0 A0 BOOL RecogSegmentXYZ(BPTR); FUNCTION This routine should examine if a segment list is crunched. You can check the whole segment list for correct lengths of hunks and for contents of hunks if you like. There should be at least 3 comparations to determine the cruncher. INPUTS seglist - BPTR to first segment. RESULT result - TRUE if packer has been recognized, else FALSE. NOTE You have to initialize xfds_RecogSegment with a pointer to your RecogSegmentXYZ routine. SEE ALSO Example sourcecodes. xfdSlave/DecrunchSegmentXYZ xfdSlave/DecrunchSegmentXYZ NAME DecrunchSegmentXYZ -- Decrunch segment list. SYNOPSIS result = DecrunchSegmentXYZ(segmentinfo) D0 A0 BOOL DecrunchSegmentXYZ(struct xfdSegmentInfo *); FUNCTION There are two possibilities how to decrunch a segment list. The first one works like this: - Modify decrunch header to make it return to the caller. - Call decrunch header. - dos.library/UnloadSeg() whole seglist and clear xfdsi_SegList if an error occurs and the seglist has already been altered in any way. - Otherwise only release segments that are no longer necessary. - Store BPTR to first hunk of decrunched segment list in xfdsi_SegList. - Set xfdsi_Error if an error occurs. The second possibility works the same way as the first with the difference that you don't jump to the original code, but you include all necessary parts of it (decrunch routine, relocator) in your own routine. The big advantage is that you can handle error conditions much better because most of the standard decrunch headers in executable files have problems with low memory etc. (V34) If the decruncher allows it, always support XFDPFB_RELMODE. That way the caller can determine the type of memory the segments should be placed in by initializing xfdsi_RelMode with XFDREL_#?. Many crunchers don't change the hunk structure of the crunched data. If this is the case, you can simply call the decrunch code in the segment list and then use xfdRelocate() (V34). INPUTS segmentinfo - A valid xfdSegmentInfo structure that successfully went through a call to xfdRecogSegment(). RESULT result - TRUE if decrunching succeeded, FALSE if something went wrong. NOTE You have to initialize xfds_DecrunchSegment with a pointer to your DecrunchSegmentXYZ routine. SEE ALSO Example sourcecodes.