home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d919 / bbbf.lha / BBBF / UnpackLib / UnpackDoc < prev    next >
Text File  |  1993-10-04  |  19KB  |  543 lines
  1. ****************************************************************************
  2. *                         UNPACK.LIBRARY V34.21 DOC                        *
  3. *                                                                          *
  4. *                                                                          *
  5. *                             Update 24-08-93                              *
  6. *                                                                          *
  7. *                                                                          *
  8. *                          SAFE HEX INTERNATIONAL                          *
  9. ****************************************************************************
  10.  
  11.  
  12.  
  13. Welcome to this release version of this library. I hope it's a library
  14. you can use in your virus killer or whatever you are doing. This library
  15. purpose is to help a viruskiller programmer to scan files that are
  16. crunched.
  17.  
  18. This library is copyrighted by SHI and may NOT be used in commercial
  19. programs without a written permission from SHI. All the SHI members and
  20. shareware programmers can of course use this library for free. Remember to 
  21. send your address and program to SHI, to get a written premission.
  22.  
  23. Please  add  the "Wanted.Crunchers.txt" (a list containing wanted crunchers 
  24. for update), and remember to credit the author (Thomas Neumann) and SHI in 
  25. your program as stated in the following:
  26.  
  27.  
  28. Here is a little message about SHI:
  29. ----------------------------------------------------------------------------
  30.  
  31. ABOUT SAFE HEX INTERNATIONAL
  32. If  you   know  a  virus  programmer  you  can  get  a reward of $ 1000 for
  33. supplying  his  name  and  address.  The fact is that the law punishes data 
  34. crime very severely. (5 years in jail in most countries).
  35.  
  36. We  are an international group with more than 500 members  who have started 
  37. trying to stop the spread of virus. Let me give you some example:
  38.  
  39.         1. Our motto is: "Safe Hex", who dares do anything else today?".
  40.         2. A virus bank containing more than 1800 Amiga and PC viruses for
  41.            supporting good shareware antivirus programs.
  42.         3. We help people to get money back lost by virus infection.
  43.         4. We write articles about virus problems for about 20 computer 
  44.            magazines worldwide.
  45.         5. We release the newest and the best virus killers around from 
  46.            about 25 wellknown programmers worldwide.
  47.         6. We have more than 35 PC and Amiga "Virus Centers" worldwide 
  48.            where you can get free virus help by phoning our "Hotline", and 
  49.            the newest killers translated in your own language at very 
  50.            little cost.
  51.  
  52. For more information contact:
  53.  
  54.         SAFE HEX INTERNATIONAL            (Please send 2 "Coupon-Response 
  55.         Erik Loevendahl Soerensen         International" and a self addres-
  56.         Snaphanevej 10                    sed envelope, if you want infor-
  57.         DK-4720 Praestoe                  mation about SHI by letter).
  58.         Denmark                             
  59.         Phone: + 45 55 99 25 12
  60.         Fax  : + 45 55 99 34 98
  61.  
  62. ----------------------------------------------------------------------------
  63.  
  64. ****************************************************************************
  65. *                     Offsets and functions destiptions                    *
  66. ****************************************************************************
  67.  
  68.  
  69. AllocCInfo(34.0)                                            AllocCInfo(34.0)
  70.  
  71.  
  72. NAME
  73.         AllocCInfo - allocates an info structure.
  74.  
  75. SYNOPSIS
  76.         info = AllocCInfo ()
  77.          D0       -30
  78.  
  79. FUNCTION
  80.         AllocCInfo() allocates an info structure the library uses when it
  81.         unpacks files. You just have to call this function in the beginning
  82.         of your program and then free it again with FreeCInfo() in the end.
  83.         I have made this function, because in future versions of this
  84.         library, the structure will be bigger. Your program will then be
  85.         compatible for any future versions of this library.
  86.  
  87. INPUTS
  88.         None.
  89.  
  90. OUTPUTS
  91.         info - is a pointer to the allocated info structure. If there has
  92.                occured an error, a zero is returned.
  93.  
  94. STRUCTURE
  95.         This is how the Info Structure is build:
  96.  
  97.         STRUCTURE UnpackInfo,0
  98.         APTR    UI_Filename
  99.         APTR    UI_Path
  100.         APTR    UI_Jump
  101.         APTR    UI_CruncherName
  102.         APTR    UI_DecrunchAdr
  103.         LONG    UI_DecrunchLen
  104.         UWORD   UI_ErrorNum
  105.         UWORD   UI_CrunchNum
  106.         UBYTE   UI_CrunchType
  107.         UBYTE   UI_Flag
  108.         APTR    UI_LoadNamePoi
  109.         LONG    UI_CrunchLen
  110.  
  111. ; This Is Private, Do NOT Touch
  112.  
  113.         APTR    UI_CrunchAdr
  114.         LONG    UI_CrunchLenTemp
  115.         LONG    UI_FileHandler
  116.         LONG    UI_Lock
  117.         LONG    UI_OldLock
  118.         APTR    UI_InfoAdr
  119.         APTR    UI_UnpackPoi
  120.     ULONG    UI_Temp
  121.         STRUCT  UI_LoadName,128
  122.         STRUCT  UI_ExecuteString,256
  123.         LABEL   UnpackInfo_SIZEOF
  124.  
  125.  
  126.         NOTE:
  127.         -----
  128.  
  129.         The private area is a bad idea to use, because the different
  130.         fields will maybe be moved around in future versions.
  131.  
  132.  
  133.         UI_Filename     is a pointer to the filename you want to scan.
  134.  
  135.         UI_Path         is a pointer to a zero-terminated path where the
  136.                         library have to unpack archive files, such as a LHA
  137.                         archive. Please select a path where you haven't got 
  138.                         some important data, because ALL files will be
  139.                         deleted in the path if the DELETE flag is on.
  140.  
  141.         UI_Jump         This is a pointer to your scan routine. If this
  142.                         pointer are zero, no jump will be made.
  143.  
  144.         UI_CruncherName This is a pointer to the crunchers name the file is
  145.                         crunched with. The name are zero-terminated.
  146.  
  147.         UI_DecrunchAdr  This is the start address of the decrunched file.
  148.                         Your scan routine just have to read this field and
  149.                         the UI_DecrunchLen field and scan that memory.
  150.  
  151.         UI_DecrunchLen  This is the length of the decrunched file.
  152.  
  153.         UI_ErrorNum     If an error occur, the error number is stored in
  154.                         this field. See the unpack.i file for more
  155.                         information.
  156.  
  157.                         NOTE: When you call a function and you success,
  158.                               don't read this flag, because there are
  159.                               stored an error number, but it's false.
  160.  
  161.         UI_CrunchNum    Here is the cruncher number stored. Each cruncher
  162.                         has a number so you can find out which cruncher is
  163.                         used on the file.
  164.  
  165.         UI_CrunchType   Here is a number that tells about the file (archive,
  166.                         data or object file).
  167.  
  168.         UI_Flag         You can select some different things the library has
  169.                         to do when it tests the file. See below for more
  170.                         info.
  171.  
  172.         UI_LoadNamePoi  This is just a pointer to the UI_LoadName field. Use
  173.                         this if you want to use the UI_LoadName field,
  174.                         because the field will be moved in future versions.
  175.  
  176.         UI_LoadName     Here is the filename stored, the library is about
  177.                         to decrunch, if the file is an archive.
  178.  
  179.         UI_CrunchLen    This is the length of the crunched file.
  180.  
  181.  
  182.         The flag have the following functions:
  183.  
  184.         Bit             Function
  185.         --------------------------------------------------------------
  186.          0              Select to unpack one file at a time or the
  187.                         whole archive. If set, one file is selected
  188.          1              Delete files after scanning. Set = Delete. If you
  189.                         set this bit on, ALL files AND directories will be
  190.                         deleted, not only the files there were stored in
  191.                         the archive.
  192.          2-7            Reserved
  193.  
  194. BUGS
  195.         None known.
  196.  
  197. SEE ALSO
  198.         FreeCInfo()
  199.  
  200. ----------------------------------------------------------------------------
  201.  
  202. FreeCInfo(34.0)                                              FreeCInfo(34.0)
  203.  
  204.  
  205. NAME
  206.         FreeCInfo - frees the info structure again.
  207.  
  208. SYNOPSIS
  209.         FreeCInfo (info)
  210.            -36      A0
  211.  
  212. FUNCTION
  213.         FreeCInfo() frees the info structure again. You have to call this
  214.         function in the end of your program.
  215.  
  216. INPUTS
  217.         info - is the memory address you got from the AllocCInfo() function.
  218.                If the memory address is zero, you will NOT take a trip to
  219.                India (and visit the GURU) when you call this function.
  220.  
  221. OUTPUTS
  222.         None.
  223.  
  224. BUGS
  225.         None known.
  226.  
  227. SEE ALSO
  228.         AllocCInfo()
  229.  
  230. ----------------------------------------------------------------------------
  231.  
  232. DetermineFile(34.0)                                      DetermineFile(34.0)
  233.  
  234.  
  235. NAME
  236.         DetermineFile - scans a file to find out which cruncher that are
  237.                         used.
  238.  
  239. SYNOPSIS
  240.         success = DetermineFile (info, filename)
  241.           D0          -42         A0      A1
  242.  
  243. FUNCTION
  244.         DetermineFile() scans a file to find out which cruncher the file is
  245.         crunched with. If the library can't find out, an error message is
  246.         returned. You have to call this function first, then the Unpack()
  247.         function, if no error has occured.
  248.  
  249. INPUTS
  250.         info     - is the memory address you got from the AllocCInfo()
  251.                    function.
  252.  
  253.         filename - is a pointer to the filename you want to scan. The
  254.                    filename has to be zero-terminated.
  255.  
  256. OUTPUTS
  257.         success  - is an indicator that tells about the operation. If every
  258.                    thing is okay, a non-zero value is returned, else a zero
  259.                    will be returned. If you get an error, you can look at
  260.                    the UI_ErrorNum flag in the info structure to see what
  261.                    went wrong.
  262.  
  263. BUGS
  264.         None known.
  265.  
  266. SEE ALSO
  267.         Unpack()
  268.  
  269. ----------------------------------------------------------------------------
  270.  
  271. Unpack(34.0)                                                    Unpack(34.0)
  272.  
  273.  
  274. NAME
  275.         Unpack - unpacks the file.
  276.  
  277. SYNOPSIS
  278.         success = Unpack (info)
  279.           D0       -48     A0
  280.  
  281. FUNCTION
  282.         Unpack() loads the file into memory and unpacks it. When the file
  283.         is unpacked, the library will jump through the UI_Jump pointer to
  284.         your scan routine. If the UI_Jump contains a zero, the library will
  285.         not jump. All what your scan routine has to do, is to get the
  286.         UI_DecrunchAdr and UI_DecrunchLen from the info structure and
  287.         scan that memory. If the file is an archive (Lha, zoo), the library
  288.         will unpack the archive and then read one file at a time and jump
  289.         to your scan routine.
  290.         If you need a password to unpack a file, the library will open a
  291.         little window where it asks for the password. The window will be
  292.         opened on the active screen, so if you open a screen by yourself,
  293.         the window will appear on it (if it's active).
  294.  
  295.         NOTE:
  296.         -----
  297.  
  298.         After an archive is unpacked and scanned, all the files and
  299.         directories in the path you have selected will be deleted if the
  300.         DELETE flag is on, not just the files there were stored in the
  301.         archive, but ALL files will be deleted, so be sure to use a temp
  302.         directory or something like that.
  303.  
  304. INPUTS
  305.         info     - is the memory address you got from the AllocCInfo()
  306.                    function.
  307.  
  308. OUTPUTS
  309.         success  - is an indicator that tells about the operation. If every
  310.                    thing is okay, a non-zero value is returned, else a zero
  311.                    will be returned. If you get an error, you can look at
  312.                    the UI_ErrorNum flag in the info structure to see what
  313.                    went wrong.
  314.  
  315. BUGS
  316.         None known.
  317.  
  318. SEE ALSO
  319.         DetermineFile()
  320.  
  321. ----------------------------------------------------------------------------
  322.  
  323. TestHunk(34.1)                                                TestHunk(34.1)
  324.  
  325.  
  326. NAME
  327.         TestHunk - tests the hunk structure in a file.
  328.  
  329. SYNOPSIS
  330.         success = TestHunk (address)
  331.           D0        -54       A0
  332.  
  333. FUNCTION
  334.         TestHunk() tests a file for the hunk structure. You have to be sure,
  335.         that the file you want to test is an object file, else this routine
  336.         will return an error. You can check this by look in the
  337.         UI_CrunchType flag in the info structure. You don't need to call
  338.         this function by yourself before you calling the Unpack() function,
  339.         because the Unpack() function does that by itself. I'm not quite
  340.         sure it handles the overlay hunk correctly, but it should handle it.
  341.         If you find a file you know are okay and this function says it's
  342.         defect, please send me the file so I can find the error.
  343.  
  344. INPUTS
  345.         address - is the start address of the file you want to test.
  346.  
  347. OUTPUTS
  348.         success  - is an indicator that tells about the operation. If every
  349.                    thing is okay, a non-zero value is returned, else a zero
  350.                    will be returned.
  351.  
  352. BUGS
  353.         None known.
  354.  
  355. ----------------------------------------------------------------------------
  356.  
  357. UnpackNum(34.1)                                              UnpackNum(34.1)
  358.  
  359.  
  360. NAME
  361.         UnpackNum - gives the number of unpackers.
  362.  
  363. SYNOPSIS
  364.         version,revision,types,unpackers=UnpackNum ()
  365.           D0       D1     D2      D3       -60
  366.  
  367. FUNCTION
  368.         UnpackNum() counts the number of unpackers the library can determine
  369.         and unpack. You will get two different numbers of unpackers. The
  370.         first one (types) are the numbers of different types the library
  371.         can unpack, example PowerPacker Data, PowerPacker Library etc.
  372.         The second one (unpackers) is the number of unpackers, example
  373.         PowerPacker, Lha, Imploder etc.
  374.  
  375. INPUTS
  376.         None.
  377.  
  378. OUTPUTS
  379.         version   - is the library version number.
  380.  
  381.         revision  - is the library revision number.
  382.  
  383.         types     - is the number of different types of unpackers.
  384.  
  385.         unpackers - is the number of unpackers the library can determine.
  386.  
  387. BUGS
  388.         None known.
  389.  
  390. ----------------------------------------------------------------------------
  391.  
  392. UnpackList(34.1)                                            UnpackList(34.1)
  393.  
  394.  
  395. NAME
  396.         UnpackList - makes an unpacker name list.
  397.  
  398. SYNOPSIS
  399.         name=UnpackList (info)
  400.          A1     -66       A0
  401.  
  402. FUNCTION
  403.         UnpackList() gives a pointer to the first name of a packer the
  404.         library can determine & unpack. You can use this function, if you
  405.         want to make a list over all the unpackers the library can
  406.         determine. Call this function first and then use UnpackListNext().
  407.  
  408. INPUTS
  409.         info - is the memory address you got from the AllocCInfo()
  410.                function.
  411.  
  412. OUTPUTS
  413.         name - is a pointer to a null-terminated string where the first
  414.                name is stored.
  415.  
  416. BUGS
  417.         None known.
  418.  
  419. SEE ALSO
  420.         UnpackListNext()
  421.  
  422. ----------------------------------------------------------------------------
  423.  
  424. UnpackListNext(34.1)                                    UnpackListNext(34.1)
  425.  
  426.  
  427. NAME
  428.         UnpackListNext - reads the next name in the unpacker list.
  429.  
  430. SYNOPSIS
  431.         success,name=UnpackListNext (info)
  432.           D0     A1       -72         A0
  433.  
  434. FUNCTION
  435.         UnpackListNext() gives a pointer to the next name of a packer the
  436.         library can determine & unpack. You can use this function, if you
  437.         want to make a list over all the unpackers the library can
  438.         determine. Call the UnpackList() function first and then use this
  439.         function.
  440.  
  441. INPUTS
  442.         info    - is the memory address you got from the AllocCInfo()
  443.                   function.
  444.  
  445. OUTPUTS
  446.         name    - is a pointer to a null-terminated string where the next
  447.                   name is stored.
  448.  
  449.         success - if this contains a zero, there are no more crunchers in
  450.                   the list. Otherwise it will contain a non-zero value.
  451.  
  452. BUGS
  453.         None known.
  454.  
  455. SEE ALSO
  456.         UnpackList()
  457.  
  458. ----------------------------------------------------------------------------
  459.  
  460. LoadFile(34.20)                                              LoadFile(34.20)
  461.  
  462.  
  463. NAME
  464.         LoadFile - loads a file into memory.
  465.  
  466. SYNOPSIS
  467.         success=LoadFile (info)
  468.           D0      -78      A0
  469.  
  470. FUNCTION
  471.         This function allocate some memory with the files length and loads
  472.         the file into it. The filename are taken from the UI_Filename field
  473.         in the info structure. The length and address of the file are
  474.         stored in UI_DecrunchLen and UI_DecrunchAdr.
  475.  
  476. INPUTS
  477.         info    - is the memory address you got from the AllocCInfo()
  478.                   function.
  479.  
  480. OUTPUTS
  481.         success  - is an indicator that tells about the operation. If every
  482.                    thing is okay, the file length is returned, else a zero
  483.                    will be returned. If you get an error, you can look at
  484.                    the UI_ErrorNum flag in the info structure to see what
  485.                    went wrong.
  486.  
  487. BUGS
  488.         None known.
  489.  
  490. SEE ALSO
  491.         FreeFile()
  492.  
  493. ----------------------------------------------------------------------------
  494.  
  495. FreeFile(34.20)                                              FreeFile(34.20)
  496.  
  497.  
  498. NAME
  499.         FreeFile - frees a file from memory.
  500.  
  501. SYNOPSIS
  502.         FreeFile (info)
  503.           -84      A0
  504.  
  505. FUNCTION
  506.         You have to call this function after you have called the LoadFile()
  507.         function and are finished with the file. This function frees the
  508.         memory again.
  509.  
  510.         NOTE: You MUST call this function instead of freeing the memory by
  511.         yourself!!
  512.  
  513. INPUTS
  514.         info    - is the memory address you got from the AllocCInfo()
  515.                   function. You can pass a zero to this function.
  516.  
  517. OUTPUTS
  518.         None.
  519.  
  520. BUGS
  521.         None known.
  522.  
  523. SEE ALSO
  524.         LoadFile()
  525.  
  526. ----------------------------------------------------------------------------
  527.  
  528.         I really hope you can use this library. See also the
  529.         Unpack.construct.iff file to see how to construct your program.
  530.  
  531.         If you find any grammatical errors in this doc file, feel free to
  532.         correct them, and send them to me. And of course any new crunchers.
  533.         Please see in the "Wanted-Crunchers.Txt" for more info!
  534.  
  535.  
  536.  
  537.    WE NEED YOUR HELP TO GET THIS LIBRARY EVEN BETTER, THANK YOU VERY MUCH!
  538.  
  539.  
  540.         Thomas Neumann       Member of the SHI Anti Virus Group.
  541.         Kongensgade 78
  542.         3550 Slangerup
  543.         Denmark