home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga Shareware Floppies / ma32.dms / ma32.adf / xfd-lib / autodoc / xfdmaster.doc
Text File  |  1994-03-27  |  15KB  |  482 lines
  1. TABLE OF CONTENTS
  2.  
  3. xfdmaster.library/--Overview--
  4. xfdmaster.library/xfdAllocBufferInfo
  5. xfdmaster.library/xfdAllocSegmentInfo
  6. xfdmaster.library/xfdDecrunchBuffer
  7. xfdmaster.library/xfdDecrunchSegment
  8. xfdmaster.library/xfdFreeBufferInfo
  9. xfdmaster.library/xfdFreeSegmentInfo
  10. xfdmaster.library/xfdGetErrorText
  11. xfdmaster.library/xfdRecogBuffer
  12. xfdmaster.library/xfdRecogSegment
  13. xfdmaster.library/xfdTestHunkStructure
  14. xfdForeman/--Overview--
  15. xfdSlave/--Overview--
  16. xfdSlave/xfds_DecrunchBuffer
  17. xfdSlave/xfds_DecrunchSegment
  18. xfdSlave/xfds_RecogBuffer
  19. xfdSlave/xfds_RecogSegment
  20.  
  21. xfdmaster.library/--Overview--                 xfdmaster.library/--Overview--
  22.  
  23. This section describes the usual way how to use xfdmaster.library from your
  24. own applications.
  25.  
  26. If you want to decrunch files from a buffer, do it like this:
  27.  
  28. 1.  Call xfdAllocBufferInfo().
  29. 2.  Get file size, allocate buffer with that size and load file to buffer.
  30. 3.  Call xfdRecogBuffer() with xfdbi_SourceBuffer and xfdbi_SourceBufLen
  31.     initialized.
  32. 4.  Check xfdbi_PackerFlags for XFDPFB_PASSWORD, go on with 6. if not set.
  33. 5.  Get password (maximum length is xfdbi_MaxSpecialLen) and store a pointer
  34.     to it in xfdbi_Special.
  35. 6.  Initialize xfdbi_TargetBufMemType and call xfdDecrunchBuffer().
  36. 7.  Release memory of xfdbi_SourceBuffer.
  37. 8.  Work with decrunched file.
  38. 9.  Release memory in xfdbi_TargetBuffer.
  39. 10. Call xfdFreeBufferInfo().
  40.  
  41. If you want to decrunch a segment, do it like this:
  42.  
  43. 1.  Call xfdAllocSegmentInfo().
  44. 2.  LoadSeg() file.
  45. 3.  Call xfdRecogSegment() with xfdsi_SegList initialized.
  46. 4.  Check xfdsi_PackerFlags for XFDPFB_PASSWORD, go on with 6. if not set.
  47. 5.  Get password (maximum length is xfdsi_MaxSpecialLen) and store a pointer
  48.     to it in xfdsi_Special.
  49. 6.  Call xfdDecrunchSegment().
  50. 7.  Work with decrunched segment list.
  51. 8.  UnloadSeg() segment list.
  52. 10. Call xfdFreeSegmentInfo().
  53.  
  54. xfdmaster.library/xfdAllocBufferInfo     xfdmaster.library/xfdAllocBufferInfo
  55.  
  56.    NAME
  57.     xfdAllocBufferInfo -- allocate memory for BufferInfo structure
  58.  
  59.    SYNOPSIS
  60.     bufferinfo = xfdAllocBufferInfo()
  61.         D0               -30
  62.  
  63.    FUNCTION
  64.     Allocates a memory block large enough to hold all information of
  65.     the BufferInfo structure. Never do this in any other way for
  66.     compatibility with library updates.
  67.  
  68.    INPUTS
  69.     None.
  70.  
  71.    RESULT
  72.     bufferinfo - pointer to the BufferInfo structure or NULL if there
  73.                  occured an error.
  74.  
  75.    SEE ALSO
  76.     xfdFreeBufferInfo()
  77.  
  78. xfdmaster.library/xfdAllocSegmentInfo   xfdmaster.library/xfdAllocSegmentInfo
  79.  
  80.    NAME
  81.     xfdAllocSegmentInfo -- allocate memory for SegmentInfo structure
  82.  
  83.    SYNOPSIS
  84.     segmentinfo = xfdAllocSegmentInfo()
  85.         D0                -42
  86.  
  87.    FUNCTION
  88.     Allocates a memory block large enough to hold all information of
  89.     the SegmentInfo structure. Never do this in any other way for
  90.     compatibility with library updates.
  91.  
  92.    INPUTS
  93.     None.
  94.  
  95.    RESULT
  96.     segmentinfo - pointer to the SegmentInfo structure or NULL if there
  97.                   occured an error.
  98.  
  99.    SEE ALSO
  100.     xfdFreeSegmentInfo()
  101.  
  102. xfdmaster.library/xfdDecrunchBuffer       xfdmaster.library/xfdDecrunchBuffer
  103.  
  104.    NAME
  105.     xfdDecrunchBuffer -- decrunch a file from buffer
  106.  
  107.    SYNOPSIS
  108.     success = xfdDecrunchBuffer (bufferinfo)
  109.       D0             -60             A0
  110.  
  111.    FUNCTION
  112.     Decrunches a file to a separate buffer. You have to call
  113.     xfdRecogBuffer() first, only if this call was successful,
  114.     you may call xfdDecrunchBuffer().
  115.  
  116.     You have to pass the type of memory that should be used for
  117.     the target buffer in xfdbi_TargetBufMemType.
  118.     Additionally you have to init the xfdbi_Special field with
  119.     a pointer to a special info buffer if any special flags are
  120.     set in the xfdbi_PackerFlags field. The contents of this
  121.     buffer depend on the type of special info (eg. password).
  122.  
  123.     If the decrunching was successful, the following fields in
  124.     the BufferInfo structure will be initialized:
  125.  
  126.     xfdbi_TargetBuffer     - pointer to decrunched file buffer
  127.     xfdbi_TargetBufSaveLen - length of decrunched file (for saving etc.)
  128.     xfdbi_TargetBufLen     - total length of allocated buffer
  129.     xfdbi_DecrAddress      - if XFDPFB_ADDR is set in xfdbi_PackerFlags,
  130.                              this contains the address where the crunched
  131.                              file has been relocated to
  132.     xfdbi_JmpAddress       - if XFDPFB_ADDR is set in xfdbi_PackerFlags,
  133.                              this contains the address where to jump at
  134.                              in order to run the file
  135.  
  136.    INPUTS
  137.     bufferinfo - pointer to an initialized BufferInfo structure:
  138.        xfdbi_TargetBufMemType - type of memory for target buffer
  139.        xfdbi_Special          - pointer to special info if required
  140.  
  141.    RESULT
  142.     success - TRUE if decrunching was successful, FALSE if
  143.               anything went wrong.
  144.  
  145.    NOTE
  146.     xfdDecrunchBuffer() allocates a buffer for the decrunched file,
  147.     but it doesn't release this memory afterwards. That is because
  148.     you first have to work with the decrunched file (what else?).
  149.     Therefore you have to do a call to exec.library/FreeMem() after
  150.     you finished work. Use the following parameters:
  151.     xfdbi_TargetBufLen - lenght of buffer in D0
  152.     xfdbi_TargetBuffer - pointer to buffer in A1
  153.  
  154.     Don't forget:
  155.     xfdbi_TargetBufLen contains the length of the allocated memory
  156.     area, xfdbi_TargetBufSaveLen the length of the decrunched file
  157.     in that buffer.
  158.  
  159.     xfdDecrunchBuffer() never touches the buffer that contains the
  160.     crunched file. It's again your task to release this after
  161.     decrunching.
  162.  
  163.    SEE ALSO
  164.     xfdRecogBuffer()
  165.  
  166. xfdmaster.library/xfdDecrunchSegment     xfdmaster.library/xfdDecrunchSegment
  167.  
  168.    NAME
  169.     xfdDecrunchSegment -- decrunch a file from its segment list
  170.  
  171.    SYNOPSIS
  172.     success = xfdDecrunchSegment (segmentinfo)
  173.       D0             -72              A0
  174.  
  175.    FUNCTION
  176.     Decrunches a segment list. You have to call xfdRecogSegment()
  177.     first, only if this call was successful, you may call
  178.     xfdDecrunchSegment().
  179.  
  180.     You have to init the xfdsi_Special field with a pointer to a
  181.     special info buffer if any special flags are set in the
  182.     xfdsi_PackerFlags field. The contents of this buffer depend on
  183.     the type of special info (eg. password).
  184.  
  185.     If decrunching was successful, xfdsi_SegList holds a BPTR to
  186.     the decrunched segment list. The old segment list has been
  187.     released and/or replaced by the new one (depends on cruncher).
  188.  
  189.    INPUTS
  190.     segmentinfo - pointer to an initialized SegmentInfo structure:
  191.        xfdsi_Special - pointer to special info if required
  192.  
  193.    RESULT
  194.     success - TRUE if decrunching was successful, FALSE if
  195.               anything went wrong.
  196.  
  197.    NOTE
  198.         If you no longer need the decrunched segment list, you may
  199.         release it by simply calling dos.library/UnloadSeg().
  200.  
  201.    SEE ALSO
  202.     xfdRecogSegment()
  203.  
  204. xfdmaster.library/xfdFreeBufferInfo       xfdmaster.library/xfdFreeBufferInfo
  205.  
  206.    NAME
  207.     xfdFreeBufferInfo -- free memory of BufferInfo structure
  208.  
  209.    SYNOPSIS
  210.     xfdFreeBufferInfo (bufferinfo)
  211.            -36             A1
  212.  
  213.    FUNCTION
  214.     Deallocates the memory reserved via xfdAllocBufferInfo().
  215.  
  216.    INPUTS
  217.     bufferinfo - pointer to BufferInfo structure
  218.  
  219.    RESULT
  220.     None.
  221.  
  222.    SEE ALSO
  223.     xfdAllocBufferInfo()
  224.  
  225. xfdmaster.library/xfdFreeSegmentInfo     xfdmaster.library/xfdFreeSegmentInfo
  226.  
  227.    NAME
  228.     xfdFreeSegmentInfo -- free memory of SegmentInfo structure
  229.  
  230.    SYNOPSIS
  231.     xfdFreeSegmentInfo (segmentinfo)
  232.            -48              A1
  233.  
  234.    FUNCTION
  235.     Deallocates the memory reserved via xfdAllocSegmentInfo().
  236.  
  237.    INPUTS
  238.     segmentinfo - pointer to SegmentInfo structure
  239.  
  240.    RESULT
  241.     None.
  242.  
  243.    SEE ALSO
  244.     xfdAllocSegmentInfo()
  245.  
  246. xfdmaster.library/xfdGetErrorText           xfdmaster.library/xfdGetErrorText
  247.  
  248.    NAME
  249.     xfdGetErrorText -- get an ascii string from an error number
  250.  
  251.    SYNOPSIS
  252.     string = xfdGetErrorText (error)
  253.       D0           -78         D0
  254.  
  255.    FUNCTION
  256.     Whenever a call to xfdDecrunch??() or xfdRecog??() fails, you
  257.     receive an error number in the xfd??_Error field. This function
  258.     gets the corresponding ascii string to the occured error.
  259.  
  260.    INPUTS
  261.     error - error number from xfd??_Error
  262.  
  263.    RESULT
  264.     string - pointer to an ascii string that describes the error
  265.  
  266.    SEE ALSO
  267.     xfdDecrunchBuffer(), xfdDecrunchSegment()
  268.  
  269. xfdmaster.library/xfdRecogBuffer             xfdmaster.library/xfdRecogBuffer
  270.  
  271.    NAME
  272.     xfdRecogBuffer -- examine buffer for crunched file
  273.  
  274.    SYNOPSIS
  275.     success = xfdRecogBuffer (bufferinfo)
  276.       D0             -54          A0
  277.  
  278.    FUNCTION
  279.     Examines a file for known crunchers. You pass a pointer to
  280.     the file buffer in xfdbi_SourceBuffer and the length of the
  281.     buffer in xfdbi_SourceBufLen.
  282.  
  283.     If a crunched file has been recognized, the following fields
  284.     in the BufferInfo structure will be initialized:
  285.  
  286.     xfdbi_PackerName    - pointer to the name of the cruncher
  287.     xfdbi_PackerFlags   - contains the packer type and additional
  288.                               information (eg. password)
  289.     xfdbi_MaxSpecialLen - only used if any special flags are set
  290.  
  291.    INPUTS
  292.     bufferinfo - pointer to an initialized BufferInfo structure:
  293.        xfdbi_SourceBuffer - pointer to file buffer
  294.            xfdbi_SourceBufLen - length of file buffer
  295.  
  296.    RESULT
  297.     success - TRUE if a cruncher has been recognized, FALSE if
  298.               file is unknown.
  299.  
  300. xfdmaster.library/xfdRecogSegment           xfdmaster.library/xfdRecogSegment
  301.  
  302.    NAME
  303.     xfdRecogSegment -- examine segment list for crunched file
  304.  
  305.    SYNOPSIS
  306.     success = xfdRecogSegment (segmentinfo)
  307.       D0             -66           A0
  308.  
  309.    FUNCTION
  310.     Examines a segment list for known crunchers. You pass a BPTR
  311.     to the segment list in xfdsi_SegList.
  312.  
  313.     If a crunched segment list has been recognized, the following
  314.     fields in the SegmentInfo structure will be initialized:
  315.  
  316.     xfdsi_PackerName    - pointer to the name of the cruncher
  317.     xfdsi_PackerFlags   - contains the packer type and additional
  318.                               information (eg. password)
  319.     xfdsi_MaxSpecialLen - only used if any special flags are set
  320.  
  321.    INPUTS
  322.     segmentinfo - pointer to an initialized SegmentInfo structure:
  323.        xfdsi_SegList - BPTR to segment list
  324.  
  325.    RESULT
  326.     success - TRUE if a cruncher has been recognized, FALSE if
  327.               segment list is unknown.
  328.  
  329. xfdmaster.library/xfdTestHunkStructure xfdmaster.library/xfdTestHunkStructure
  330.  
  331.    NAME
  332.     xfdTestHunkStructure -- test hunks of executable file
  333.  
  334.    SYNOPSIS
  335.     success = xfdTestHunkStructure (buffer, length)
  336.       D0              -84             A0      D0
  337.  
  338.    FUNCTION
  339.     Checks an executable file for a valid hunk structure.
  340.     This is important for decrunching files, because an incomplete
  341.     or damaged file may cause a system crash.
  342.  
  343.    INPUTS
  344.     buffer - pointer to the file buffer that should be checked
  345.     length - length of the file buffer
  346.  
  347.    RESULT
  348.     success - TRUE if file is ok, FALSE if file is damaged.
  349.  
  350.    NOTE 1
  351.     You don't have to call this function before trying to decrunch
  352.     a file, because xfdDecrunch??() does this already.
  353.  
  354.    NOTE 2
  355.     It is really some kind of complicated to write a hunk checker
  356.     that supports all kinds of hunk structures because the DOS loader
  357.     is quite flexible with this subject. You may or may not skip
  358.     hunk_end, overlays aren't defined in any way, etc. Therefore this
  359.     checker has been made as compatible as possible, but will never
  360.     be perfect. It currently accepts more overlay types than
  361.     PowerPacker, but still has problems with files like LhASFX
  362.     executable archives etc.
  363.     The hunk structure of a non-overlayed file will nevertheless
  364.     be checked 100% correctly.
  365.  
  366. xfdForeman/--Overview--                               xfdForeman/--Overview--
  367.  
  368. The xfdForeman structure is just some kind of header for external slaves.
  369. It protects the slaves from being executed accidentally by having a small
  370. piece of code (moveq #-1,d0 : rts) in the first 4 bytes.
  371. The master can identify a valid bunch of external slaves by checking the
  372. first few bytes of the file for the foreman identification.
  373. Finally, a foreman holds the pointer to a linked list of slaves and thus
  374. enables the master to work with these slaves.
  375.  
  376. xfdSlave/--Overview--                                   xfdSlave/--Overview--
  377.  
  378. The xfdSlave structure is the heart of the whole library system. Each slave
  379. enables the master to recognize and decrunch a certain kind of packed file.
  380. Therefore slaves have 4 entrypoints that are called from the master. These
  381. 4 routines have all one thing in common: the CPU registers D0/D1/A0/A1 are
  382. so called scratch registers, they may change during execution, all other
  383. registers must remain unchanged. CPU register A6 holds a pointer to the
  384. xfdMasterBase structure. See chapters below for a description of the
  385. 4 slave routines. The name of the packer and the flags associated with
  386. that packer are stored in xfds_PackerName and xfds_PackerFlags.
  387.  
  388. xfdSlave/xfds_DecrunchBuffer                     xfdSlave/xfds_DecrunchBuffer
  389.  
  390. NAME
  391.     xfds_DecrunchBuffer -- decrunch file from buffer to buffer
  392.  
  393. SYNOPSIS
  394.     result = xfds_DecrunchBuffer (bufferinfo)
  395.       D0                              A0
  396.  
  397. FUNCTION
  398.     This is one main routine of the whole slave. The typical steps of
  399.     such a routine are:
  400.     - get length of decrunched file (exactly or a bit too much)
  401.     - allocate memory (with memtype from xfdbi_TargetBufMemType)
  402.     - decrunch file from xfdbi_SourceBuffer to xfdbi_TargetBuffer
  403.     - initialize all necessary parts of the xfdBufferInfo structure
  404.     - set xfdbi_Error if an error occurs
  405.  
  406. INPUTS
  407.     bufferinfo - a valid BufferInfo structure that successfully went
  408.                  through a call to xfdRecogBuffer()
  409.  
  410. RESULT
  411.     result - TRUE if decrunching succeeded, FALSE if something went wrong
  412.  
  413. xfdSlave/xfds_DecrunchSegment                   xfdSlave/xfds_DecrunchSegment
  414.  
  415. NAME
  416.     xfds_DecrunchSegment -- decrunch segment list
  417.  
  418. SYNOPSIS
  419.     result = xfds_DecrunchSegment (segmentinfo)
  420.       D0                                A0
  421.  
  422. FUNCTION
  423.     This is one main routine of the whole slave. The typical steps of
  424.     such a routine are:
  425.     - modify decrunch header to make it return to the caller
  426.     - call decrunch header
  427.     - release segments that are no longer necessary
  428.     - store BPTR to first hunk of decrunched segment list in
  429.       xfdsi_SegList
  430.     - set xfdsi_Error if an error occurs
  431.  
  432. INPUTS
  433.     segmentinfo - a valid SegmentInfo structure that successfully went
  434.                   through a call to xfdRecogSegment()
  435.  
  436. RESULT
  437.     result - TRUE if decrunching succeeded, FALSE if something went wrong
  438.  
  439. xfdSlave/xfds_RecogBuffer                           xfdSlave/xfds_RecogBuffer
  440.  
  441. NAME
  442.     xfds_RecogBuffer -- recognize crunched file in buffer
  443.  
  444. SYNOPSIS
  445.     result = xfds_RecogBuffer (buffer, length)
  446.       D0                         A0      D0
  447.  
  448. FUNCTION
  449.     This routine should examine the buffer for a crunched file.
  450.     First thing is to check if the size of the file allows it to be
  451.     crunched by the packer to be checked for. After that, simply
  452.     do some compares to figure out if the file has been crunched
  453.     or not.
  454.  
  455. INPUTS
  456.     buffer - pointer to a buffer that holds the crunched file
  457.     length - length of that buffer
  458.  
  459. RESULT
  460.     result - TRUE if packer has been recognized, else FALSE
  461.  
  462. xfdSlave/xfds_RecogSegment                         xfdSlave/xfds_RecogSegment
  463.  
  464. NAME
  465.     xfds_RecogSegment -- recognize crunched segment list
  466.  
  467. SYNOPSIS
  468.     result = xfds_RecogSegment (seglist)
  469.       D0                          A0
  470.  
  471. FUNCTION
  472.     This routine should examine if a segment list is crunched.
  473.     You can check the whole segment list for correct lengths of hunks
  474.     and for contents of hunks if you like. There should be at least
  475.     3 comparations to determine the cruncher.
  476.  
  477. INPUTS
  478.     seglist - BPTR to first segment
  479.  
  480. RESULT
  481.     result - TRUE if packer has been recognized, else FALSE
  482.