home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / Cruncher / XFD111.LHA / xfd / autodoc / xfdmaster.doc
Encoding:
Text File  |  1996-02-04  |  33.4 KB  |  1,009 lines
  1. TABLE OF CONTENTS
  2.  
  3. xfdmaster.library/--Overview--
  4. xfdmaster.library/xfdAllocBufferInfo
  5. xfdmaster.library/xfdAllocObject
  6. xfdmaster.library/xfdAllocSegmentInfo
  7. xfdmaster.library/xfdDecrunchBuffer
  8. xfdmaster.library/xfdDecrunchSegment
  9. xfdmaster.library/xfdFreeBufferInfo
  10. xfdmaster.library/xfdFreeObject
  11. xfdmaster.library/xfdFreeSegmentInfo
  12. xfdmaster.library/xfdGetErrorText
  13. xfdmaster.library/xfdRecogBuffer
  14. xfdmaster.library/xfdRecogLinker
  15. xfdmaster.library/xfdRecogSegment
  16. xfdmaster.library/xfdRelocate
  17. xfdmaster.library/xfdStripHunks
  18. xfdmaster.library/xfdTestHunkStructure
  19. xfdmaster.library/xfdTestHunkStructureFlags
  20. xfdmaster.library/xfdTestHunkStructureNew
  21. xfdmaster.library/xfdUnlink
  22. xfdForeman/--Overview--
  23. xfdSlave/--Overview--
  24. xfdSlave/RecogBufferXYZ
  25. xfdSlave/DecrunchBufferXYZ
  26. xfdSlave/RecogSegmentXYZ
  27. xfdSlave/DecrunchSegmentXYZ
  28.  
  29. xfdmaster.library/--Overview--                 xfdmaster.library/--Overview--
  30.  
  31. This section describes the usual way how to use xfdmaster.library from your
  32. own applications.
  33.  
  34. If you want to decrunch files from a buffer, do it like this:
  35.  
  36. 1.  Call xfdAllocObject() with XFDOBJ_BUFFERINFO (V36). If not successful,
  37.     go on with 12.
  38. 2.  Get file size, allocate buffer with that size and load file to buffer.
  39.     If not successful, go on with 10.
  40. 3.  Call xfdRecogBuffer() with xfdbi_SourceBuffer and xfdbi_SourceBufLen
  41.     initialized. If not successful, file is not crunched and you may work
  42.     with that file as it is, release the used memory and go on with 10.
  43. 4.  Check xfdbi_PackerFlags for XFDPFB_PASSWORD or XFDPFB_KEY16/32 (V35),
  44.     go on with 6. if not set.
  45. 5.  Get password (maximum length is stored in xfdbi_MaxSpecialLen) or
  46.     the required 16/32 bit key and store a pointer to it in xfdbi_Special.
  47.     If xfdbi_MaxSpecialLen is -1 then password length is not limited.
  48. 6.  Initialize xfdbi_TargetBufMemType and call xfdDecrunchBuffer(). If not
  49.     successful, work with crunched file, release memory afterwards and
  50.     go on with 10.
  51. 7.  Release memory of xfdbi_SourceBuffer.
  52. 8.  Work with decrunched file.
  53. 9.  Release memory of xfdbi_TargetBuffer.
  54. 10. If you have another file to decrunch, step back to 2.
  55. 11. Call xfdFreeObject() (V36).
  56. 12. Exit!
  57.  
  58. If you want to decrunch a segment list, do it like this:
  59.  
  60. 1.  Call xfdAllocObject() with XFDOBJ_SEGMENTINFO (V36). If not successful,
  61.     go on with 11.
  62. 2.  dos.library/LoadSeg() file. If not successful, go on with 9.
  63. 3.  Call xfdRecogSegment() with xfdsi_SegList initialized. If not
  64.     successful, seglist isn't crunched and you may go on with 7.
  65. 4.  Check xfdsi_PackerFlags for XFDPFB_PASSWORD or XFDPFB_KEY16/32 (V35).
  66.     If set, get password (maximum length is stored in xfdsi_MaxSpecialLen)
  67.     or 16/32 bit key and store a pointer to it in xfdsi_Special.
  68.     If xfdsi_MaxSpecialLen is -1 then password length is not limited.
  69. 5.  (V34) Check xfdsi_PackerFlags for XFDPFB_RELMODE. If set, init
  70.     xfdsi_RelMode with the desired value.
  71. 6.  Call xfdDecrunchSegment(). If not successful, test xfdsi_SegList.
  72.     If this field contains NULL, no seglist is available anymore. You
  73.     have to dos.library/LoadSeg() the file again then.
  74. 7.  Work with segment list.
  75. 8.  dos.library/UnloadSeg() segment list.
  76. 9.  If you have another segment list to decrunch, step back to 2.
  77. 10. Call xfdFreeObject() (V36).
  78. 11. Exit!
  79.  
  80. If you only want to test if one or more files are crunched without
  81. decrunching it afterwards, here's a way to do this:
  82.  
  83. 1.  Call xfdAllocObject() with XFDOBJ_BUFFERINFO (V36). If not successful,
  84.     go on with 9.
  85. 2.  Get minimum buffer size for recognition from xfdm_MinBufferSize (V36),
  86.     allocate buffer with that size and initialize xfdbi_SourceBuffer
  87.     and xfdbi_SourceBufLen. On error goto 8.
  88. 3.  Read as many bytes from the file as fit in xfdbi_SourceBuffer.
  89.     If file is shorter than xfdm_MinBufferSize, set real length in
  90.     xfdbi_SourceBufLen. If reading fails, goto 6.
  91. 4.  Call xfdRecogBuffer(). If not successful, file is not crunched.
  92.     Go on with 6 then.
  93. 5.  Print information about cruncher or something similar.
  94. 6.  If you have another file to test, step back to 3.
  95. 7.  Release memory of xfdbi_SourceBuffer.
  96. 8.  Call xfdFreeObject() (V36).
  97. 9.  Exit!
  98.  
  99. If you want to unlink two files, do it like this:
  100.  
  101. 1.  Call xfdAllocObject() with XFDOBJ_LINKERINFO (V36). If not successful,
  102.     go on with 9.
  103. 2.  Get file size, allocate buffer with that size and load file to buffer.
  104.     If not successful, go on with 7.
  105. 3.  Call xfdRecogLinker() with xfdli_Buffer and xfdli_BufLen initialized.
  106.     If not successful, file is not linked. Go on with 6 then.
  107. 4.  Call xfdUnlink(). If not successful, go on with 6.
  108. 5.  Do something with unlinked files.
  109. 6.  Release memory of xfdli_Buffer.
  110. 7.  If you have another file to unlink, step back to 2.
  111. 8.  Call xfdFreeObject() (V36).
  112. 9.  Exit!
  113.  
  114. If you only want to test if a file is a linked one without unlinking
  115. it afterwards, here's a way to do this:
  116.  
  117. 1.  Call xfdAllocObject() with XFDOBJ_LINKERINFO (V36). If not successful,
  118.     go on with 9.
  119. 2.  Get minimum buffer size for recognition from xfdm_MinLinkerSize (V36),
  120.     allocate buffer with that size and initialize xfdli_Buffer and
  121.     xfdli_BufLen. On error goto 8.
  122. 3.  Read as many bytes from the file as fit in xfdli_Buffer.
  123.     If file is shorter than xfdm_MinLinkerSize, set real length in
  124.     xfdli_BufLen. If reading fails, goto 6.
  125. 4.  Call xfdRecogLinker(). If not successful, file is not linked.
  126.     Go on with 6 then.
  127. 5.  Print information about linker or something similar.
  128. 6.  If you have another file to test, step back to 3.
  129. 7.  Release memory of xfdli_Buffer.
  130. 8.  Call xfdFreeObject() (V36).
  131. 9.  Exit!
  132.  
  133. Whenever you intend to use a feature of the xfdmaster.library that is
  134. marked (V34) or higher, make sure that you use this version number
  135. during the exec.library/OpenLibrary() call. Otherwise, if you try to
  136. use new features with an old library version, the system might crash.
  137.  
  138. xfdmaster.library/xfdAllocBufferInfo     xfdmaster.library/xfdAllocBufferInfo
  139.  
  140.    NAME
  141.     xfdAllocBufferInfo -- Allocate memory for BufferInfo structure.
  142.  
  143.    SYNOPSIS
  144.     bufferinfo = xfdAllocBufferInfo()
  145.         D0              -30
  146.  
  147.     struct xfdBufferInfo *xfdAllocBufferInfo(void);
  148.  
  149.    FUNCTION
  150.     Allocates a memory block large enough to hold all information of
  151.     the xfdBufferInfo structure.
  152.  
  153.     (V36) This function is obsolete and shouldn't be used with new
  154.     code any longer. Use xfdAllocObject() instead.
  155.  
  156.    INPUTS
  157.     None.
  158.  
  159.    RESULT
  160.     bufferinfo - Pointer to the xfdBufferInfo structure or NULL if
  161.                  there occured an error.
  162.  
  163.    SEE ALSO
  164.     xfdFreeBufferInfo(), xfdFreeObject()
  165.  
  166. xfdmaster.library/xfdAllocObject             xfdmaster.library/xfdAllocObject
  167.  
  168.    NAME
  169.     xfdAllocObject -- Allocate memory for specified object. (V36)
  170.  
  171.    SYNOPSIS
  172.     object = xfdAllocObject(objecttype)
  173.       D0          -114          D0
  174.  
  175.     object *xfdAllocObject(objecttype);
  176.  
  177.    FUNCTION
  178.     Allocates a memory block for the specified object. Never do this in
  179.     any other way for compatibility with library updates.
  180.  
  181.    INPUTS
  182.     objecttype - One of the XFDOBJ_#? types.
  183.  
  184.    RESULT
  185.     object - Pointer to the object or NULL if there occured an error.
  186.  
  187.    SEE ALSO
  188.     xfdFreeObject()
  189.  
  190. xfdmaster.library/xfdAllocSegmentInfo   xfdmaster.library/xfdAllocSegmentInfo
  191.  
  192.    NAME
  193.     xfdAllocSegmentInfo -- Allocate memory for SegmentInfo structure.
  194.  
  195.    SYNOPSIS
  196.     segmentinfo = xfdAllocSegmentInfo()
  197.         D0                -42
  198.  
  199.     struct xfdSegmentInfo *xfdAllocSegmentInfo(void);
  200.  
  201.    FUNCTION
  202.     Allocates a memory block large enough to hold all information of
  203.     the xfdSegmentInfo structure.
  204.  
  205.     (V36) This function is obsolete and shouldn't be used with new
  206.     code any longer. Use xfdAllocObject() instead.
  207.  
  208.    INPUTS
  209.     None.
  210.  
  211.    RESULT
  212.     segmentinfo - Pointer to the xfdSegmentInfo structure or NULL if
  213.                   there occured an error.
  214.  
  215.    SEE ALSO
  216.     xfdFreeSegmentInfo(), xfdFreeObject()
  217.  
  218. xfdmaster.library/xfdDecrunchBuffer       xfdmaster.library/xfdDecrunchBuffer
  219.  
  220.    NAME
  221.     xfdDecrunchBuffer -- Decrunch a file from buffer.
  222.  
  223.    SYNOPSIS
  224.     success = xfdDecrunchBuffer(bufferinfo)
  225.       D0             -60            A0
  226.  
  227.     BOOL xfdDecrunchBuffer(struct xfdBufferInfo *);
  228.  
  229.    FUNCTION
  230.     Decrunches a file to a separate buffer. You have to call
  231.     xfdRecogBuffer() first, only if this call was successful,
  232.     you may call xfdDecrunchBuffer().
  233.  
  234.     You have to pass the type of memory that should be used for
  235.     the target buffer in xfdbi_TargetBufMemType.
  236.     Additionally you have to init the xfdbi_Special field with
  237.     a pointer to a special info buffer if any special flags are
  238.     set in the xfdbi_PackerFlags field:
  239.     XFDPFB_PASSWORD    - Buffer contains password (max. length of
  240.                  password is stored in xfdbi_MaxSpecialLen,
  241.                  if this is -1, password is not limited).
  242.     XFDPFB_KEY16 (V35) - xfdbi_Special points to an UWORD that holds
  243.                          a 16 bit key.
  244.     XFDPFB_KEY32 (V35) - xfdbi_Special points to an ULONG that holds
  245.                          a 32 bit key.
  246.  
  247.     If the decrunching was successful, the following fields in
  248.     the xfdBufferInfo structure will be initialized:
  249.  
  250.     xfdbi_TargetBuffer     - Pointer to decrunched file buffer.
  251.     xfdbi_TargetBufSaveLen - Length of decrunched file (for saving etc.).
  252.     xfdbi_TargetBufLen     - Total length of allocated buffer.
  253.     xfdbi_DecrAddress      - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
  254.                              this contains the address where the crunched
  255.                              file has been relocated to.
  256.     xfdbi_JmpAddress       - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
  257.                              this contains the address where to jump at
  258.                              in order to run the file.
  259.  
  260.    INPUTS
  261.     bufferinfo - Pointer to an initialized xfdBufferInfo structure:
  262.        xfdbi_TargetBufMemType - Type of memory for target buffer.
  263.        xfdbi_Special          - Pointer to special info if required.
  264.  
  265.    RESULT
  266.     success - TRUE if decrunching was successful, FALSE if
  267.               anything went wrong.
  268.  
  269.    NOTE
  270.     xfdDecrunchBuffer() allocates a buffer for the decrunched file,
  271.     but it doesn't release this memory afterwards. That is because
  272.     you first have to work with the decrunched file (what else?).
  273.     Therefore you have to do a call to exec.library/FreeMem() after
  274.     you finished work. Use the following parameters:
  275.     xfdbi_TargetBufLen - Lenght of buffer.
  276.     xfdbi_TargetBuffer - Pointer to buffer.
  277.  
  278.     Don't forget:
  279.     xfdbi_TargetBufLen contains the length of the allocated memory
  280.     area, xfdbi_TargetBufSaveLen the length of the decrunched file
  281.     in that buffer.
  282.  
  283.     xfdDecrunchBuffer() never touches the buffer that contains the
  284.     crunched file. It's again your task to release this after
  285.     decrunching.
  286.  
  287.    SEE ALSO
  288.     xfdRecogBuffer(), exec.library/FreeMem()
  289.  
  290. xfdmaster.library/xfdDecrunchSegment     xfdmaster.library/xfdDecrunchSegment
  291.  
  292.    NAME
  293.     xfdDecrunchSegment -- Decrunch a file from its segment list.
  294.  
  295.    SYNOPSIS
  296.     success = xfdDecrunchSegment(segmentinfo)
  297.       D0             -72             A0
  298.  
  299.     BOOL xfdDecrunchSegment(struct xfdSegmentInfo *);
  300.  
  301.    FUNCTION
  302.     Decrunches a segment list. You have to call xfdRecogSegment()
  303.     first, only if this call was successful, you may call
  304.     xfdDecrunchSegment().
  305.  
  306.     You have to init the xfdsi_Special field with a pointer to a
  307.     special info buffer if any special flags are set in the
  308.     xfdsi_PackerFlags field:
  309.     XFDPFB_PASSWORD    - Buffer contains password (max. length of
  310.                  password is stored in xfdsi_MaxSpecialLen,
  311.                  if this is -1, password is not limited).
  312.     XFDPFB_KEY16 (V35) - xfdsi_Special points to an UWORD that holds
  313.                          a 16 bit key.
  314.     XFDPFB_KEY32 (V35) - xfdsi_Special points to an ULONG that holds
  315.                          a 32 bit key.
  316.  
  317.     (V34) Check xfdsi_Packerflags for XFDPFB_RELMODE. If set,
  318.     initialize xfdsi_RelMode with the desired XFDREL_#? value.
  319.  
  320.     If decrunching was successful, xfdsi_SegList holds a BPTR to
  321.     the decrunched segment list. The old segment list has been
  322.     released and/or replaced by the new one (depends on cruncher).
  323.  
  324.     If decrunching failed, xfdsi_SegList may be NULL. This happens
  325.     if an error occured after the seglist has already been changed
  326.     in any way. It then will be released.
  327.     Otherwise, if xfdsi_SegList is not NULL, it still contains a
  328.     valid BPTR to the crunched segment list.
  329.  
  330.    INPUTS
  331.     segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
  332.        xfdsi_Special - Pointer to special info if required.
  333.        xfdsi_RelMode - (V34) XFDREL_#? value if required.
  334.  
  335.    RESULT
  336.     success - TRUE if decrunching was successful, FALSE if
  337.               anything went wrong.
  338.  
  339.    NOTE
  340.     If you no longer need the decrunched segment list, you may
  341.     release it by simply calling dos.library/UnloadSeg().
  342.  
  343.    SEE ALSO
  344.     xfdRecogSegment(), dos.library/UnloadSeg()
  345.  
  346. xfdmaster.library/xfdFreeBufferInfo       xfdmaster.library/xfdFreeBufferInfo
  347.  
  348.    NAME
  349.     xfdFreeBufferInfo -- Free memory of xfdBufferInfo structure.
  350.  
  351.    SYNOPSIS
  352.     xfdFreeBufferInfo(bufferinfo)
  353.            -36            A1
  354.  
  355.     void xfdFreeBufferInfo(struct xfdBufferInfo *);
  356.  
  357.    FUNCTION
  358.     Deallocates the memory reserved via xfdAllocBufferInfo().
  359.  
  360.     (V36) This function is obsolete and shouldn't be used with new
  361.     code any longer. Use xfdFreeObject() instead.
  362.  
  363.    INPUTS
  364.     bufferinfo - Pointer to xfdBufferInfo structure.
  365.  
  366.    RESULT
  367.     None.
  368.  
  369.    SEE ALSO
  370.     xfdAllocBufferInfo(), xfdAllocObject()
  371.  
  372. xfdmaster.library/xfdFreeObject               xfdmaster.library/xfdFreeObject
  373.  
  374.    NAME
  375.     xfdFreeObject -- Free memory of object. (V36)
  376.  
  377.    SYNOPSIS
  378.     xfdFreeObject(object)
  379.         -120        A1
  380.  
  381.     void xfdFreeObject(object *);
  382.  
  383.    FUNCTION
  384.     Deallocates the memory reserved via xfdAllocObject().
  385.  
  386.    INPUTS
  387.     object - Pointer to object.
  388.  
  389.    RESULT
  390.     None.
  391.  
  392.    SEE ALSO
  393.     xfdAllocObject()
  394.  
  395. xfdmaster.library/xfdFreeSegmentInfo     xfdmaster.library/xfdFreeSegmentInfo
  396.  
  397.    NAME
  398.     xfdFreeSegmentInfo -- Free memory of xfdSegmentInfo structure.
  399.  
  400.    SYNOPSIS
  401.     xfdFreeSegmentInfo(segmentinfo)
  402.            -48             A1
  403.  
  404.     void xfdFreeSegmentInfo(struct xfdSegmentInfo *);
  405.  
  406.    FUNCTION
  407.     Deallocates the memory reserved via xfdAllocSegmentInfo().
  408.  
  409.     (V36) This function is obsolete and shouldn't be used with new
  410.     code any longer. Use xfdFreeObject() instead.
  411.  
  412.    INPUTS
  413.     segmentinfo - Pointer to xfdSegmentInfo structure.
  414.  
  415.    RESULT
  416.     None.
  417.  
  418.    SEE ALSO
  419.     xfdAllocSegmentInfo(), xfdAllocObject()
  420.  
  421. xfdmaster.library/xfdGetErrorText           xfdmaster.library/xfdGetErrorText
  422.  
  423.    NAME
  424.     xfdGetErrorText -- Get an ascii string from an error number.
  425.  
  426.    SYNOPSIS
  427.     string = xfdGetErrorText(error)
  428.       D0           -78        D0.w
  429.  
  430.     STRPTR xfdGetErrorText(UWORD);
  431.  
  432.    FUNCTION
  433.     Whenever a library call fails, you receive an error number either
  434.     in the xfd#?_Error field or directly as a returncode. This function
  435.     gets the corresponding ascii string to the occured error.
  436.  
  437.    INPUTS
  438.     error - Error number from xfd#?_Error or returncode.
  439.  
  440.    RESULT
  441.     string - Pointer to an ascii string that describes the error.
  442.  
  443. xfdmaster.library/xfdRecogBuffer             xfdmaster.library/xfdRecogBuffer
  444.  
  445.    NAME
  446.     xfdRecogBuffer -- Examine buffer for crunched file.
  447.  
  448.    SYNOPSIS
  449.     success = xfdRecogBuffer(bufferinfo)
  450.       D0             -54         A0
  451.  
  452.     BOOL xfdRecogBuffer(struct xfdBufferInfo *);
  453.  
  454.    FUNCTION
  455.     Examines a file for known crunchers. You pass a pointer to
  456.     the file buffer in xfdbi_SourceBuffer and the length of the
  457.     buffer in xfdbi_SourceBufLen.
  458.  
  459.     If a crunched file has been recognized, the following fields
  460.     in the xfdBufferInfo structure will be initialized:
  461.  
  462.     xfdbi_PackerName    - Pointer to the name of the cruncher.
  463.     xfdbi_PackerFlags   - Contains the packer type and additional
  464.                           information (eg. password).
  465.     xfdbi_MaxSpecialLen - Only used if any special flags are set.
  466.  
  467.    INPUTS
  468.     bufferinfo - Pointer to an initialized xfdBufferInfo structure:
  469.        xfdbi_SourceBuffer - Pointer to file buffer.
  470.        xfdbi_SourceBufLen - Length of file buffer.
  471.  
  472.    RESULT
  473.     success - TRUE if a cruncher has been recognized, FALSE if
  474.               file is unknown.
  475.  
  476.    SEE ALSO
  477.     xfdDecrunchBuffer()
  478.  
  479. xfdmaster.library/xfdRecogLinker             xfdmaster.library/xfdRecogLinker
  480.  
  481.    NAME
  482.     xfdRecogLinker -- Examine buffer for linked file. (V36)
  483.  
  484.    SYNOPSIS
  485.     success = xfdRecogLinker(linkerinfo)
  486.       D0           -126          A0
  487.  
  488.     BOOL xfdRecogLinker(struct xfdLinkerInfo *);
  489.  
  490.    FUNCTION
  491.     Examines a file for known link mechanisms. You pass a pointer to
  492.     the file buffer in xfdli_Buffer and the length of the buffer in
  493.     xfdli_BufLen.
  494.  
  495.     If a linked file has been recognized, the following fields
  496.     in the xfdLinkerInfo structure will be initialized:
  497.  
  498.     xfdli_LinkerName - Pointer to the name of the linker.
  499.  
  500.    INPUTS
  501.     linkerinfo - Pointer to an initialized xfdLinkerInfo structure:
  502.        xfdli_Buffer - Pointer to file buffer.
  503.        xfdli_BufLen - Length of file buffer.
  504.  
  505.    RESULT
  506.     success - TRUE if a linker has been recognized, FALSE if
  507.               file is unknown.
  508.  
  509.    SEE ALSO
  510.     xfdUnlink()
  511.  
  512. xfdmaster.library/xfdRecogSegment           xfdmaster.library/xfdRecogSegment
  513.  
  514.    NAME
  515.     xfdRecogSegment -- Examine segment list for crunched file.
  516.  
  517.    SYNOPSIS
  518.     success = xfdRecogSegment(segmentinfo)
  519.       D0             -66          A0
  520.  
  521.     BOOL xfdRecogSegment(struct xfdSegmentInfo *);
  522.  
  523.    FUNCTION
  524.     Examines a segment list for known crunchers. You pass a BPTR
  525.     to the segment list in xfdsi_SegList.
  526.  
  527.     If a crunched segment list has been recognized, the following
  528.     fields in the xfdSegmentInfo structure will be initialized:
  529.  
  530.     xfdsi_PackerName    - Pointer to the name of the cruncher.
  531.     xfdsi_PackerFlags   - Contains the packer type and additional
  532.                           information (eg. password).
  533.     xfdsi_MaxSpecialLen - Only used if any special flags are set.
  534.  
  535.    INPUTS
  536.     segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
  537.        xfdsi_SegList - BPTR to segment list.
  538.  
  539.    RESULT
  540.     success - TRUE if a cruncher has been recognized, FALSE if
  541.               segment list is unknown.
  542.  
  543.    SEE ALSO
  544.     xfdDecrunchSegment()
  545.  
  546. xfdmaster.library/xfdRelocate                   xfdmaster.library/xfdRelocate
  547.  
  548.    NAME
  549.     xfdRelocate -- Create segment list from file buffer. (V34)
  550.  
  551.    SYNOPSIS
  552.     error = xfdRelocate(buffer, length, result, mode)
  553.      D0.w       -96       A0      D0      A1    D1.w
  554.  
  555.     UWORD xfdRelocate(APTR, ULONG, ULONG *, UWORD);
  556.  
  557.    FUNCTION
  558.     Creates a relocated and fully executable segment list from
  559.     a file buffer. The result is a BPTR to the first segment,
  560.     similar to the result of a call to dos.library/LoadSeg().
  561.  
  562.    INPUTS
  563.     buffer - Pointer to the file buffer that should be relocated.
  564.     length - Length of the file buffer.
  565.     result - Pointer to the longword that should hold the result.
  566.     mode   - Any XFDREL_#? relocation mode.
  567.  
  568.    RESULT
  569.     error  - XFDERR_OK if no error occured, else XFDERR_#?.
  570.     result - Holds a BPTR to the first segment if error = XFDERR_OK.
  571.  
  572.    NOTE
  573.     There is no need to call xfdTestHunkStructure[New|Flags]() before
  574.     relocation because xfdRelocate() does this already.
  575.  
  576.     This routine supports the following hunk types:
  577.     - hunk_name         ($3e8) -> Skipped.
  578.     - hunk_code         ($3e9) -> Creates new code segment.
  579.     - hunk_data         ($3ea) -> Creates new data segment.
  580.     - hunk_bss          ($3eb) -> Creates new bss segment.
  581.     - hunk_reloc32      ($3ec) -> Used for relocation.
  582.     - hunk_symbol       ($3f0) -> Skipped.
  583.     - hunk_debug        ($3f1) -> Skipped.
  584.     - hunk_end          ($3f2) -> May be left out.
  585.     - hunk_header       ($3f3) -> Only at top of file.
  586.     - hunk_reloc32short ($3f7/$3fc) -> Used for relocation.
  587.     Any other hunk types create an error. There is no support for
  588.     hunk_overlay, because the main purpose of this routine is to
  589.     be called from xfds_DecrunchSegment. And in that case, the real
  590.     dos.library/LoadSeg() has already initialized the overlay header.
  591.  
  592. xfdmaster.library/xfdStripHunks               xfdmaster.library/xfdStripHunks
  593.  
  594.    NAME
  595.     xfdStripHunks -- Remove annoying hunks from file buffer. (V36)
  596.  
  597.    SYNOPSIS
  598.     error = xfdStripHunks(buffer, length, result, flags)
  599.      D0.w       -108        A0      D0      A1    D1.w
  600.  
  601.     UWORD xfdStripHunks(APTR, ULONG, ULONG *, UWORD);
  602.  
  603.    FUNCTION
  604.     Strips hunk_name, hunk_symbol and hunk_debug from file buffer.
  605.     This might be useful to shorten executables, but the main
  606.     purpose is to remove decrunch protections based on modified
  607.     hunk structures.
  608.  
  609.    INPUTS
  610.     buffer - Pointer to the file buffer that should be stripped.
  611.     length - Length of the file buffer.
  612.     result - Pointer to the longword that should hold the new
  613.              file length after stripping.
  614.     flags  - One or more XFDSHB_#? strip flags.
  615.  
  616.    RESULT
  617.     error  - XFDERR_OK if no error occured, else XFDERR_#?.
  618.     result - Holds new length of file if error = XFDERR_OK.
  619.  
  620.    NOTE
  621.     There is no need to call xfdTestHunkStructure[New|Flags]() before
  622.     stripping because xfdStripHunks() does this already.
  623.  
  624.     Attention! The new file length given as a result may be used
  625.     to save the modified file to disk, but the length of the
  626.     buffer itself is still the same as it was before the call.
  627.  
  628.     This routine supports the following hunk types:
  629.     - hunk_name         ($3e8) -> Stripped on XFDSHB_NAME.
  630.     - hunk_code         ($3e9) -> Skipped.
  631.     - hunk_data         ($3ea) -> Skipped.
  632.     - hunk_bss          ($3eb) -> Skipped.
  633.     - hunk_reloc32      ($3ec) -> Skipped.
  634.     - hunk_symbol       ($3f0) -> Stripped on XFDSHB_SYMBOL.
  635.     - hunk_debug        ($3f1) -> Stripped on XFDSHB_DEBUG.
  636.     - hunk_end          ($3f2) -> Skipped.
  637.     - hunk_header       ($3f3) -> Only at top of file.
  638.     - hunk_reloc32short ($3f7/$3fc) -> Skipped.
  639.     Any other hunk types create an error.
  640.  
  641. xfdmaster.library/xfdTestHunkStructure xfdmaster.library/xfdTestHunkStructure
  642.  
  643.    NAME
  644.     xfdTestHunkStructure -- Test hunks of executable file.
  645.  
  646.    SYNOPSIS
  647.     success = xfdTestHunkStructure(buffer, length)
  648.       D0              -84            A0      D0
  649.  
  650.     BOOL xfdTestHunkStructure(APTR, ULONG);
  651.  
  652.    FUNCTION
  653.     Checks an executable file for a valid hunk structure.
  654.     This is important for decrunching files, because an incomplete
  655.     or damaged file may cause a system crash.
  656.  
  657.    INPUTS
  658.     buffer - Pointer to the file buffer that should be checked.
  659.     length - Length of the file buffer.
  660.  
  661.    RESULT
  662.     success - TRUE if file is ok, FALSE if file is damaged.
  663.  
  664.    NOTE
  665.     It is recommended to use xfdTestHunkStructureNew() instead of
  666.     this routine for a more detailed error description. Internally
  667.     both calls use the same routines, this one is only left here
  668.     for downward compatibility.
  669.  
  670.    SEE ALSO
  671.     xfdTestHunkStructureNew(), xfdTestHunkStructureFlags()
  672.  
  673. xfdmaster.l/xfdTestHunkStructureFlags   xfdmaster.l/xfdTestHunkStructureFlags
  674.  
  675.    NAME
  676.     xfdTestHunkStructureFlags -- Test hunks of executable file. (V36)
  677.  
  678.    SYNOPSIS
  679.     error = xfdTestHunkStructureFlags(buffer, length, flags)
  680.      D0.w            -102               A0      D0     D1.w
  681.  
  682.     UWORD xfdTestHunkStructureFlags(APTR, ULONG, UWORD);
  683.  
  684.    FUNCTION
  685.     Checks an executable file for a valid hunk structure and reacts
  686.     on certain hunk types if special flags are given.
  687.     This is important for decrunching files, because an incomplete
  688.     or damaged file may cause a system crash.
  689.  
  690.    INPUTS
  691.     buffer - Pointer to the file buffer that should be checked.
  692.     length - Length of the file buffer.
  693.     flags  - Flags to cause special actions on certain hunk types.
  694.              These are:
  695.              XFDTHB_NOOVERLAYS - forces error on hunk_overlay.
  696.  
  697.    RESULT
  698.     error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged
  699.             or special flags got activated.
  700.  
  701.    NOTE
  702.     You don't have to call this function before trying to decrunch
  703.     a file, because xfdDecrunchBuffer() does this already.
  704.  
  705.     This hunk checker supports the following hunk types:
  706.     - hunk_name         ($3e8)
  707.     - hunk_code         ($3e9)
  708.     - hunk_data         ($3ea)
  709.     - hunk_bss          ($3eb)
  710.     - hunk_reloc32      ($3ec)
  711.     - hunk_symbol       ($3f0)
  712.     - hunk_debug        ($3f1)
  713.     - hunk_end          ($3f2)
  714.     - hunk_header       ($3f3)
  715.     - hunk_overlay      ($3f5) -> forces error on XFDTHB_NOOVERLAYS
  716.     - hunk_break        ($3f6)
  717.     - hunk_reloc32short ($3f7/$3fc)
  718.     It recognizes the standard hunk_overlay ($3f5) format and some
  719.     user-defined overlay types too. Anyway, it may happen that some
  720.     weird overlay hunk causes problems because there isn't any real
  721.     definition for overlays.
  722.     The hunk structure of a non-overlayed file will nevertheless
  723.     be checked 100% correctly.
  724.  
  725.    SEE ALSO
  726.     xfdTestHunkStructureNew()
  727.  
  728. xfdmaster.lib/xfdTestHunkStructureNew   xfdmaster.lib/xfdTestHunkStructureNew
  729.  
  730.    NAME
  731.     xfdTestHunkStructureNew -- Test hunks of executable file. (V34)
  732.  
  733.    SYNOPSIS
  734.     error = xfdTestHunkStructureNew(buffer, length)
  735.      D0.w           -90               A0      D0
  736.  
  737.     UWORD xfdTestHunkStructureNew(APTR, ULONG);
  738.  
  739.    FUNCTION
  740.     Checks an executable file for a valid hunk structure.
  741.     This is important for decrunching files, because an incomplete
  742.     or damaged file may cause a system crash.
  743.  
  744.    INPUTS
  745.     buffer - Pointer to the file buffer that should be checked.
  746.     length - Length of the file buffer.
  747.  
  748.    RESULT
  749.     error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged.
  750.  
  751.    NOTE
  752.     This is actually just a call to xfdTestHunkStructureFlags()
  753.     with no flags set.
  754.  
  755.    SEE ALSO
  756.     xfdTestHunkStructureFlags()
  757.  
  758. xfdmaster.library/xfdUnlink                       xfdmaster.library/xfdUnlink
  759.  
  760.    NAME
  761.     xfdUnlink -- Unlink two files inside the same buffer. (V36)
  762.  
  763.    SYNOPSIS
  764.     success = xfdUnlink(linkerinfo)
  765.       D0        -132        A0
  766.  
  767.     BOOL xfdUnlink(struct xfdLinkerInfo *);
  768.  
  769.    FUNCTION
  770.     Unlinks two files that have been joined by some so-called
  771.     4EB9-Linker. No new buffers are created, unlinked files are both
  772.     located inside source buffer. You have to call xfdRecogLinker()
  773.     first, only if this call was successful, you may call xfdUnlink().
  774.  
  775.     If unlinking was successful, the following fields in the
  776.     xfdLinkerInfo structure will be initialized:
  777.  
  778.     xfdli_Save1    - Pointer to first unlinked file.
  779.     xfdli_Save2    - Pointer to second unlinked file.
  780.     xfdli_SaveLen1 - Length of first unlinked file.
  781.     xfdli_SaveLen2 - Length of second unlinked file.
  782.  
  783.    INPUTS
  784.     linkerinfo - Pointer to an initialized xfdLinkerInfo structure
  785.                  as received by xfdRecogLinker().
  786.  
  787.    RESULT
  788.     success - TRUE if unlinking was successful, FALSE if
  789.               anything went wrong.
  790.  
  791.    NOTE
  792.     After a call to xfdUnlink(), the contents of xfdli_Buffer are
  793.     under no circumstances valid any longer. The only way to make use
  794.     of the buffer contents is via xfdli_Save1 and xfdli_Save2.
  795.     But if you have finished work with the splitted files, you have
  796.     to release exactly the memory you have allocated for xfdli_Buffer.
  797.  
  798.     There exist several programs that produce the same linker output.
  799.     Some of them are very badly programmed, so if unlinking fails or
  800.     produces non-executable files, don't blame xfdmaster.library.
  801.  
  802.    SEE ALSO
  803.     xfdRecogLinker()
  804.  
  805. xfdForeman/--Overview--                               xfdForeman/--Overview--
  806.  
  807. The xfdForeman structure is just some kind of header for external slaves.
  808. It protects the slaves from being executed accidentally by having a small
  809. piece of code (moveq #-1,d0 : rts) in the first 4 bytes.
  810. The master can identify a valid bunch of external slaves by checking the
  811. first few bytes of the file for the foreman identification.
  812. Finally, a foreman holds the pointer to a linked list of slaves and thus
  813. enables the master to work with these slaves.
  814.  
  815. xfdSlave/--Overview--                                   xfdSlave/--Overview--
  816.  
  817. The xfdSlave structure is the heart of the whole library system. Each slave
  818. enables the master to recognize and decrunch packed files and/or segments.
  819.  
  820. Therefore each slave contains 4 routines that are called from the master.
  821. Pointers to these routines are stored in xfds_Recog#? and xfds_Decrunch#?.
  822. All have one thing in common: the CPU registers D0/D1/A0/A1 are so called
  823. scratch registers, they may change during execution, all other registers
  824. must remain unchanged. CPU register A6 holds a pointer to the xfdMasterBase
  825. structure. See chapters below for a description of the slave routines.
  826.  
  827. ALL SLAVE ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC MEMORY
  828. AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT THE
  829. ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME!
  830.  
  831. The name of the packer that is supported by the slave and the flags that
  832. describe the packer are stored in xfds_PackerName and xfds_PackerFlags.
  833.  
  834. (V36) Internal slaves all have an unique ID value stored in xfds_SlaveID.
  835. This field should be set to NULL for external slaves.
  836.  
  837. (V36) If you have written a slave that should replace an internal one
  838. because it's faster or otherwise enhanced, simply put the ID of the slave
  839. to be replaced in xfds_ReplaceID. The old slave will then be taken out of
  840. the list of used slaves. Otherwise, xfds_ReplaceID must be NULL.
  841.  
  842. (V36) xfdRecogBuffer() usually only requires a quite small part of a file
  843. to recognize it properly. To avoid reading the whole file for recognition
  844. purposes, you may set xfds_MinBufferSize to the minimum amount of bytes
  845. that is required to recognize the crunched file correctly.
  846. Note that xfdRecogBuffer() uses this value internally to decide whether
  847. a file might be crunched with a packer or not, so you don't have to do
  848. an extra size comparison in your xfds_RecogBuffer function any more.
  849. For packer headers with non-constant sizes, simply set xfds_MinBufferSize
  850. to a value that will ensure correct recognition of all possible files.
  851.  
  852. Whenever you intend to use features of the xfdmaster.library in your slaves
  853. that are marked (V34) or higher, make sure to set xfds_MasterVersion to
  854. the desired version number, otherwise an old library version might crash
  855. while using the new slave.
  856.  
  857. xfdSlave/RecogBufferXYZ                               xfdSlave/RecogBufferXYZ
  858.  
  859.    NAME
  860.     RecogBufferXYZ -- Recognize crunched file in buffer.
  861.  
  862.    SYNOPSIS
  863.     result = RecogBufferXYZ(buffer, length)
  864.       D0                      A0      D0
  865.  
  866.     BOOL RecogBufferXYZ(APTR, ULONG);
  867.  
  868.    FUNCTION
  869.     This routine should examine the buffer for a crunched file.
  870.     First thing is to check if the size of the file allows it to
  871.     be crunched with the packer in question. After that, simply
  872.     do some compares to figure out if the file has been crunched
  873.     or not.
  874.  
  875.     (V36) You don't have to do any size comparisons if you set
  876.     xfds_MinBufferSize to the minimum amount of bytes that are
  877.     necessary for a file to be crunched with that packer.
  878.  
  879.    INPUTS
  880.     buffer - Pointer to a buffer that holds the crunched file.
  881.     length - Length of that buffer.
  882.  
  883.    RESULT
  884.     result - TRUE if packer has been recognized, else FALSE.
  885.  
  886.    NOTE
  887.     You have to initialize xfds_RecogBuffer with a pointer to your
  888.     RecogBufferXYZ routine.
  889.  
  890.    SEE ALSO
  891.     Example sourcecodes.
  892.  
  893. xfdSlave/DecrunchBufferXYZ                         xfdSlave/DecrunchBufferXYZ
  894.  
  895.    NAME
  896.     DecrunchBufferXYZ -- Decrunch file from buffer to buffer.
  897.  
  898.    SYNOPSIS
  899.     result = DecrunchBufferXYZ(bufferinfo)
  900.       D0                           A0
  901.  
  902.     BOOL DecrunchBufferXYZ(struct xfdBufferInfo *);
  903.  
  904.    FUNCTION
  905.     The typical steps of such a routine are:
  906.     - Get length of decrunched file (exactly or a bit too much).
  907.     - Allocate memory (with memtype from xfdbi_TargetBufMemType).
  908.     - Decrunch file from xfdbi_SourceBuffer to xfdbi_TargetBuffer.
  909.     - Initialize all necessary parts of the xfdBufferInfo structure.
  910.     - Set xfdbi_Error if an error occurs.
  911.  
  912.    INPUTS
  913.     bufferinfo - A valid xfdBufferInfo structure that successfully went
  914.                  through a call to xfdRecogBuffer().
  915.  
  916.    RESULT
  917.     result - TRUE if decrunching succeeded, FALSE if something went wrong.
  918.  
  919.    NOTE
  920.     You have to initialize xfds_DecrunchBuffer with a pointer to your
  921.     DecrunchBufferXYZ routine.
  922.  
  923.    SEE ALSO
  924.     Example sourcecodes.
  925.  
  926. xfdSlave/RecogSegmentXYZ                             xfdSlave/RecogSegmentXYZ
  927.  
  928.    NAME
  929.     RecogSegmentXYZ -- Recognize crunched segment list.
  930.  
  931.    SYNOPSIS
  932.     result = RecogSegmentXYZ(seglist)
  933.       D0                       A0
  934.  
  935.     BOOL RecogSegmentXYZ(BPTR);
  936.  
  937.    FUNCTION
  938.     This routine should examine if a segment list is crunched.
  939.     You can check the whole segment list for correct lengths of hunks
  940.     and for contents of hunks if you like. There should be at least
  941.     3 comparations to determine the cruncher.
  942.  
  943.    INPUTS
  944.     seglist - BPTR to first segment.
  945.  
  946.    RESULT
  947.     result - TRUE if packer has been recognized, else FALSE.
  948.  
  949.    NOTE
  950.     You have to initialize xfds_RecogSegment with a pointer to your
  951.     RecogSegmentXYZ routine.
  952.  
  953.    SEE ALSO
  954.     Example sourcecodes.
  955.  
  956. xfdSlave/DecrunchSegmentXYZ                       xfdSlave/DecrunchSegmentXYZ
  957.  
  958.    NAME
  959.     DecrunchSegmentXYZ -- Decrunch segment list.
  960.  
  961.    SYNOPSIS
  962.     result = DecrunchSegmentXYZ(segmentinfo)
  963.       D0                             A0
  964.  
  965.     BOOL DecrunchSegmentXYZ(struct xfdSegmentInfo *);
  966.  
  967.    FUNCTION
  968.     There are two possibilities how to decrunch a segment list. The
  969.     first one works like this:
  970.     - Modify decrunch header to make it return to the caller.
  971.     - Call decrunch header.
  972.     - dos.library/UnloadSeg() whole seglist and clear xfdsi_SegList
  973.       if an error occurs and the seglist has already been altered
  974.       in any way.
  975.     - Otherwise only release segments that are no longer necessary.
  976.     - Store BPTR to first hunk of decrunched segment list in
  977.       xfdsi_SegList.
  978.     - Set xfdsi_Error if an error occurs.
  979.  
  980.     The second possibility works the same way as the first with
  981.     the difference that you don't jump to the original code, but you
  982.     include all necessary parts of it (decrunch routine, relocator)
  983.     in your own routine. The big advantage is that you can handle
  984.     error conditions much better because most of the standard decrunch
  985.     headers in executable files have problems with low memory etc.
  986.  
  987.     (V34) If the decruncher allows it, always support XFDPFB_RELMODE.
  988.     That way the caller can determine the type of memory the segments
  989.     should be placed in by initializing xfdsi_RelMode with XFDREL_#?.
  990.  
  991.     Many crunchers don't change the hunk structure of the crunched
  992.     data. If this is the case, you can simply call the decrunch code
  993.     in the segment list and then use xfdRelocate() (V34).
  994.  
  995.    INPUTS
  996.     segmentinfo - A valid xfdSegmentInfo structure that successfully went
  997.                   through a call to xfdRecogSegment().
  998.  
  999.    RESULT
  1000.     result - TRUE if decrunching succeeded, FALSE if something went wrong.
  1001.  
  1002.    NOTE
  1003.     You have to initialize xfds_DecrunchSegment with a pointer to your
  1004.     DecrunchSegmentXYZ routine.
  1005.  
  1006.    SEE ALSO
  1007.     Example sourcecodes.
  1008.  
  1009.