home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / compress / filearchivers / objectarchive / docs / whatis.doc < prev    next >
Text File  |  1995-02-28  |  9KB  |  218 lines
  1.                               WhatIs.library
  2.  
  3.                Copyright  Sylvain Rougier  &  Pierre Carrette.
  4.  
  5.     1.Usage
  6.     2.User's documentation
  7.     3.Programmer's documentation
  8.  
  9.  
  10.     1)
  11.  
  12.     What  is  whatis.library ?   It  is a shared amiga library which allow
  13. programmers  to easily recognize type of files (ilbm, 8svx, maxiplan, exe,
  14. PP,  etc....) BUT the final user (non-programer user) can define new types
  15. so  all programs which use whatis.library can recognize this new type.  At
  16. this  moment  only  BrowserII,  For  and  AddIcon use whatis.library but I
  17. planned  to  rewrite  Icon   (a program which make WorkBench 2.0 recognize
  18. files  which  have  no  icon), and I encourage all programmers to use this
  19. library  so users can define new types only one time and every program can
  20. use it.
  21.  
  22.     For  example,  you  love  graphics, you digitize lots of image with an
  23. official  commercial  program  which  produce  file  ".img",  and you want
  24. BrowserII  to  recognise it. Well, you define this new type in S:FileTypes
  25. and  whatis.library  know  what  it  is, so you BrowserII can do automatic
  26. action on  your  file ".img", but all program which use whatis.library can
  27. reconised  the  ".img"-type  you  just  defined  and  can do what they are
  28. supposed to do with them.
  29.  
  30. List  of  type  that  whatis.library reconize without any S:FileType file:
  31. DOS_DEVICE  VOLUME  ASSIGN  DIR EXECUTABLE EXECPP40 EXECPP30 EXECPP SCRIPT
  32. TEXT  OBJECT  LIB  IFF  ILBM  ILBM24  ANIM  8SVX SMUS FTXT PREFS TERM ICON
  33. IMPDATA PPDATA ZOO LHARC MEDMOD
  34.  
  35.  
  36.     2)
  37. Well,  user.   All  you  need  is  to  know  how  to define a new type.  A
  38. sample/starter  FileTypes  file is provided.  First, have a look at it and
  39. then read what follows, I think there is not much to say.
  40.  
  41. There are 2 methods to scan a file: DEEP and LIGHT.
  42. The  Light  one  is  only  based on the file name and eventualy protection
  43. bits.  It is fast but unsafe.  if you rename an executable as "File.c" and
  44. you   ask  for  a  light  scan  (BrowserII  with  "find  type  by  name"),
  45. WhatIs.library think it is a C language source file.
  46. The  DEEP  one  (currently  only one DEEP mode) is more powerfull, but the
  47. slowest  because  each  file  must be open and the first few bytes scanned
  48. (currently 484 bytes), so this slow down directory scans.
  49.  
  50.  
  51. FileTypes syntax:
  52.  
  53. While not necessary, we recommand use of quotes (") delimiters for strings
  54. to avoid mistakes. The # character can be found in strings while it is the
  55. comment starting char.
  56. The "#" char marks the begining of comment until end of ligne.
  57.  
  58. # example definition:
  59. TYPE "Src Ada"  # you define a new type, it's IDString (curently 9
  60.                 # char max) is "Src Ada", this is the string that
  61.                 # WhatIs.library will return and you can see in
  62.                 # BrowserII  when you ask the "Show file type", it
  63.                 # is also the way you identify this FileType.
  64.  
  65.     SUBTYPE "Text"  # OPTIONNAL: First, the file MUST be a "Text" type,
  66.                     # this means that if the file is not of this type
  67.                     # it cannot be a "Src Ada"
  68.  
  69.     INSERTAFTER "Script"    # OPTIONNAL: You want the type "Src Ada" to be
  70.                             # put after the "Script" type in list. The
  71.                             # type list is not alphabetically-sorted.
  72.                             # This determine the order in which you see
  73.                             # files when you choose "Sort by file type"
  74.                             # in BrowserII
  75.  
  76.     ICONNAME "def_Src Ada"  # OPTIONNAL: this the name of the default
  77.                             # icon file name. These files should be in
  78.                             # the "ENV:Sys/" directory, where WB 2.0 put
  79.                             # its default icons. This will be used by
  80.                             # AddIcon (In BrowserII and given cli command
  81.                             # This string is returned by GetIconName()
  82.  
  83.     # now come the decription of the file, if ANY condition below is
  84.     # not satisfied, the WhatIs.library think it is not this filetype.
  85.     # Exepte for OPNAMEPATTERN which is used for light WhatIs() (only
  86.     # based on the file name)
  87.  
  88.     NAMEPATTERN "#?.ada"    # OPTIONNAL: if given, the filename must match
  89.                             # this pattern.
  90.                             # it is mutualy exclusive with OPTNAMEPATTERN
  91.  
  92.     OPTNAMEPATTERN "#?.ada" # OPTIONNAL: same as NAMEPATTERN but it is
  93.                             # a DEEP scan may override it.
  94.                             # it is mutualy exclusive with NAMEPATTERN
  95.  
  96.     # NAMEPATTERN vs OPTNAMEPATTERN
  97.     # Imagine you are used to name all your image files with .ilbm
  98.     # extension. This way, a LIGHT scan will identify your ilbm files
  99.     # if your specify NAMEPATTERN "#?.ilbm". But ILBM files can also be
  100.     # internally recognized (using DEEP scan). If you specify
  101.     # NAMEPATTERN "#?.ilbm", all ILBM files not ending with .ilbm will
  102.     # not be recognized by whatis.library. But if you specify
  103.     # OPTNAMEPATTERN "#?.ilbm", the DEEP scan will override the (OPT)
  104.     # name pattern, and all ILBM files will be recognized.
  105.  
  106.     # Now come the DEEP description. It is the heart of recognition
  107.     # process.  You can specify numbers in decimal (begining with a
  108.     # digit), in hex (begining with $), in binary (begining with "%").
  109.     # Strings begin with a letter or with a quote '"'
  110.     # The search is done within the first (currently 484) few bytes of
  111.     # the file.
  112.     # All these conditions are optional, and are considered as TRUE
  113.     # by LIGHT scan.
  114.  
  115.     COMPAREBYTE 12 $ABADCAFE    # Test if the file contains the bytes
  116.                                 # $AB $AD $CA $FE at offset 12
  117.  
  118.     COMPAREBYTE $23 "Hello"     # Test if the file contains the string
  119.                                 # "Hello" (i.e the bytes $48 $65 $6c $6f)
  120.                                 # at offset $23 (decimal 35)
  121.  
  122.     # in version 2 of WhatIs.library (only under KS2.x) you have an
  123.     # optionnal CASE modifier, this means "A" is different of "a".
  124.  
  125.     SEARCHBYTE "Good"   # Search for "Good" in the first bytes of file.
  126.  
  127.     SEARCHBYTE $DEADBEEF    # Search for bytes $DE $AD $BE $EF
  128.  
  129.     SEARCHPATTERN [CASE] "ST-??:"   # Search for "ST-??:" pattern in file.
  130.  
  131.     MATCHPATTERN [CASE] 12 "ST-??:" # Search for "ST-??:" pattern in file
  132.                                     # at offset 12.
  133.  
  134. ENDTYPE     # this marks the end of this FileType definition.
  135.  
  136.  
  137.     AskReparse  is  a small executable which ask whatis.library to reparse
  138. the  S:FileTypes  file.   The  file  will  be  effectively  parsed only if
  139. whatis.library  is  not used except by AskReparse at call time.  Else, the
  140. parse is defered until whatis.library has no user.
  141.  
  142.     3)
  143.     Look in the WhatIsBase.h, you will find all you want.
  144.  
  145.     How works WhatIs() ?
  146.     WhatIs is currently based on 2 methods:  light or deep.  The light one
  147. is  only  based  on the information you pass to it.  In deep mode WhatIs()
  148. open  the  file and scans the first few bytes (currently 488:  the size of
  149. an  OldFileSystem  data-block),  so  after  loading these bytes in memory,
  150. WhatIs()  examine them to discover what type it is.  WhatIs() also examine
  151. the FileInfoBlock.
  152.     WhatIs()  return  a PRIVATE ULONG.  You should not make any assumption
  153. about how it is coded, because it may and WILL change in future.  You keep
  154. this  ULONG and give it to the different functions of whatis.library.  All
  155. FileTypes must be first referenced by their IDString "ILBM", "Text", "Exe,
  156. etc..., or returned by WhatIs().
  157.  
  158. For  example you want to check if the file "Amiga" is an ILBM picture, you
  159. should write:
  160.  
  161.     ULONG Type, ILBMType;
  162.  
  163.     Type = WhatIsTags("Amiga", WI_Deep, DEEPTYPE, TAG_DONE);
  164.     ILBMType = GedIdType("ILBM");
  165.     if (CmpFileType( Type, ILBMType) == 0)
  166.     {
  167.         /* Yes it is ILBM ! */
  168.         your code here
  169.     }
  170.     else
  171.     {
  172.         /* Not an ILBM */
  173.         your code here
  174.     }
  175.  
  176. Currently supported tags by WhatIs():
  177.  
  178.     WI_FIB      /* TagItem.ti_data = struct FileInfoBlock *FIB, default = NULL */
  179.     WI_Deep     /* TagItem.ti_data = LIGHTTYPE or DEEPTYPE. default = LIGHTTYPE */
  180.     WI_Buffer   /* TagItem.ti_data = Buffer ptr WARNING: your buffer MUST be NUL terminated */
  181.     WI_BufLen   /* TagItem.ti_data = Buffer Len */
  182.     WI_DLX      /* TagItem.ti_data = DLX_numble, found in ArpBase.h */
  183.     /* Version 2.1 or higher */
  184.     WI_DLT      /* TagItem.ti_data = DLT_numble, found in DOS 2.0 */
  185.  
  186.  
  187. Version history:
  188.  
  189.     1.0:    Version for KickStart 1.3.  Only This Version support 1.3.
  190.             All others need KS2.0
  191.     1.1:    Fixed a little bug.
  192.  
  193.     ALL next versions NEED KS2.0
  194.  
  195.     2.0:    First Version of whatis.library.
  196.             (the 1.0 was a limited version made for 1.3)
  197.  
  198.     3.0:    Fixed a little bug.
  199.             GetParentFileType() Added
  200.             IsSubTypeOf() Added
  201.             DLT support (KS2.0 version of the ARP DLX)
  202.  
  203.     3.4:    25/12/92
  204.             Fixed a Little Bug: the UNKNOWNFILETYPE was not returned by NextType()
  205.  
  206.     3.5:    4/1/93
  207.             Fixed a BIG bug born when fixed the preceding bug:
  208.             Forgot subtype of root in FirstType()/NextType().
  209.  
  210.     3.6:        25/07/93 (Internal)
  211.                 Internal: Incorect scan of TagItems. Fixed.
  212.                 SEARCHPATTERN don't work it string was not entiled by "#?". Fixed
  213.  
  214.     3.7:        12/08/93
  215.                 Fixed an Enforcer hit in NextType()
  216.                 Minor change: change the VERSTRING protocol.
  217.  
  218.