home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / workbench / addinfo / whatis / whatislibrary.doc < prev    next >
Text File  |  1995-02-27  |  12KB  |  316 lines
  1.                               WhatIs.library
  2.  
  3.                            Copyright S.R. & P.C.
  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 alow
  13. programmers  to easyly 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.  I actualy work on version which support the datatype of KickStart
  21. 3.0  so  user  of whatis.library can use both the customisable whatis type
  22. and the standard datatype type.
  23.  
  24.     For  example,  you  love  graphics, you digitize lots of image with an
  25. official  commercial  program  which  produce  file  ".img",  and you want
  26. BrowserII  can reconised it, well, you define this new type in S:FileTypes
  27. and  whatis.library  know  what  it  is, so you BrowserII can do automatic
  28. thing  on  your  file ".img", but all program which use whatis.library can
  29. reconised  the  ".img"-type  you  just  defined  and  can do what they are
  30. supposed to do with them.
  31.  
  32. List  of  type  that  whatis.library reconize without any S:FileType file:
  33. DOS_DEVICE  VOLUME  ASSIGN  DIR EXECUTABLE EXECPP40 EXECPP30 EXECPP SCRIPT
  34. TEXT  OBJECT  LIB  IFF  ILBM  ILBM24  ANIM  8SVX SMUS FTXT PREFS TERM ICON
  35. IMPDATA PPDATA ZOO LHARC MEDMOD
  36.  
  37.  
  38.     2)
  39. Well,  user.   All  you  need  is  to  know  how  to define a new type.  A
  40. sample/starter  FileTypes  file is provided.  First, have a look at it and
  41. then read what follows, I think there is not much to say.
  42.  
  43. There are 2 methods to scan a file: DEEP and LIGHT.
  44. The  Light  one  is  only  based on the file name and eventualy protection
  45. bits.  It is fast but unsafe.  if you rename an executable as "File.c" and
  46. you   ask  for  a  light  scan  (BrowserII  with  "find  type  by  name"),
  47. WhatIs.library think it is a C language source file.
  48. The  DEEP  one  (currently  only one DEEP mode) is more powerfull, but the
  49. slowest  because  each  file  must be open and the first few bytes scanned
  50. (currently 484 bytes), so this slow down directory scans.
  51.  
  52.  
  53. FileTypes syntax:
  54.  
  55. While not necessary, we recommand use of quotes (") delimiters for strings
  56. to avoid mistakes. The # character can be found in strings while it is the
  57. comment starting char.
  58. The "#" char marks the begining of comment until end of ligne.
  59.  
  60. # example definition:
  61. TYPE "Src Ada"  # you define a new type, it's IDString (curently 9
  62.                 # char max) is "Src Ada", this is the string that
  63.                 # WhatIs.library will return and you can see in
  64.                 # BrowserII  when you ask the "Show file type", it
  65.                 # is also the way you identify this FileType.
  66.  
  67.     SUBTYPE "Text"  # OPTIONNAL: First, the file MUST be a "Text" type,
  68.                     # this means that if the file is not of this type
  69.                     # it cannot be a "Src Ada"
  70.  
  71.     INSERTAFTER "Script"    # OPTIONNAL: You want the type "Src Ada" to be
  72.                             # put after the "Script" type in list. The
  73.                             # type list is not alphabetically-sorted.
  74.                             # This determine the order in which you see
  75.                             # files when you choose "Sort by file type"
  76.                             # in BrowserII
  77.  
  78.     ICONNAME "def_Src Ada"  # OPTIONNAL: this the name of the default
  79.                             # icon file name. These files should be in
  80.                             # the "ENV:Sys/" directory, where WB 2.0 put
  81.                             # its default icons. This will be used by
  82.                             # AddIcon (In BrowserII and given cli command
  83.                             # This string is returned by GetIconName()
  84.  
  85.     # now come the decription of the file, if ANY condition below is
  86.     # not satisfied, the WhatIs.library think it is not this filetype.
  87.     # Exepte for OPNAMEPATTERN which is used for light WhatIs() (only
  88.     # based on the file name)
  89.  
  90.     NAMEPATTERN "#?.ada"    # OPTIONNAL: if given, the filename must match
  91.                             # this pattern.
  92.                             # it is mutualy exclusive with OPTNAMEPATTERN
  93.  
  94.     OPTNAMEPATTERN "#?.ada" # OPTIONNAL: same as NAMEPATTERN but it is
  95.                             # a DEEP scan may override it.
  96.                             # it is mutualy exclusive with NAMEPATTERN
  97.  
  98.     # NAMEPATTERN vs OPTNAMEPATTERN
  99.     # Imagine you are used to name all your image files with .ilbm
  100.     # extension. This way, a LIGHT scan will identify your ilbm files
  101.     # if your specify NAMEPATTERN "#?.ilbm". But ILBM files can also be
  102.     # internally recognized (using DEEP scan). If you specify
  103.     # NAMEPATTERN "#?.ilbm", all ILBM files not ending with .ilbm will
  104.     # not be recognized by whatis.library. But if you specify
  105.     # OPTNAMEPATTERN "#?.ilbm", the DEEP scan will override the (OPT)
  106.     # name pattern, and all ILBM files will be recognized.
  107.  
  108.     # Now come the DEEP description. It is the heart of recognition
  109.     # process.  You can specify numbers in decimal (begining with a
  110.     # digit), in hex (begining with $), in binary (begining with "%").
  111.     # Strings begin with a letter or with a quote '"'
  112.     # The search is done within the first (currently 484) few bytes of
  113.     # the file.
  114.     # All these conditions are optional, and are considered as TRUE
  115.     # by LIGHT scan.
  116.  
  117.     COMPAREBYTE 12 $ABADCAFE    # Test if the file contains the bytes
  118.                                 # $AB $AD $CA $FE at offset 12
  119.  
  120.     COMPAREBYTE $23 "Hello"     # Test if the file contains the string
  121.                                 # "Hello" (i.e the bytes $48 $65 $6c $6f)
  122.                                 # at offset $23 (decimal 35)
  123.  
  124.     # in version 2 of WhatIs.library (only under KS2.x) you have an
  125.     # optionnal CASE modifier, this means "A" is different of "a".
  126.  
  127.     SEARCHBYTE "Good"   # Search for "Good" in the first bytes of file.
  128.  
  129.     SEARCHBYTE $DEADBEEF    # Search for bytes $DE $AD $BE $EF
  130.  
  131.     SEARCHPATTERN [CASE] "ST-??:"   # Search for "ST-??:" pattern in file.
  132.  
  133.     MATCHPATTERN [CASE] 12 "ST-??:" # Search for "ST-??:" pattern in file
  134.                                     # at offset 12.
  135.  
  136. ENDTYPE     # this marks the end of this FileType definition.
  137.  
  138.  
  139.     AskReparse  is  a small executable which ask whatis.library to reparse
  140. the  S:FileTypes  file.   The  file  will  be  effectively  parsed only if
  141. whatis.library  is  not used except by AskReparse at call time.  Else, the
  142. parse is defered until whatis.library has no user.
  143.  
  144.     3)
  145.     Look in the WhatIsBase.h, you will find all you want.
  146.  
  147.     How works WhatIs() ?
  148.     WhatIs is currently based on 2 methods:  light or deep.  The light one
  149. is  only  based  on the information you pass to it.  In deep mode WhatIs()
  150. open  the  file and scans the first few bytes (currently 488:  the size of
  151. an  OldFileSystem  data-block),  so  after  loading these bytes in memory,
  152. WhatIs()  examine them to discover what type it is.  WhatIs() also examine
  153. the FileInfoBlock.
  154.     WhatIs()  return  a PRIVATE ULONG.  You should not make any assumption
  155. about how it is coded, because it may and WILL change in future.  You keep
  156. this  ULONG and give it to the different functions of whatis.library.  All
  157. FileTypes must be first referenced by their IDString "ILBM", "Text", "Exe,
  158. etc..., or returned by WhatIs().
  159.  
  160. For  example you want to check if the file "Amiga" is an ILBM picture, you
  161. should write:
  162.  
  163.     ULONG Type, ILBMType;
  164.  
  165.     Type = WhatIsTags("Amiga", WI_Deep, DEEPTYPE, TAG_DONE);
  166.     ILBMType = GedIdType("ILBM");
  167.     if (CmpFileType( Type, ILBMType) == 0)
  168.     {
  169.         /* Yes it is ILBM ! */
  170.         your code here
  171.     }
  172.     else
  173.     {
  174.         /* Not an ILBM */
  175.         your code here
  176.     }
  177.  
  178. Currently supported tags by WhatIs():
  179.  
  180.     WI_FIB      /* TagItem.ti_data = struct FileInfoBlock *FIB, default = NULL */
  181.     WI_Deep     /* TagItem.ti_data = LIGHTTYPE or DEEPTYPE. default = LIGHTTYPE */
  182.     WI_Buffer   /* TagItem.ti_data = Buffer ptr WARNING: your buffer MUST be NUL terminated */
  183.     WI_BufLen   /* TagItem.ti_data = Buffer Len */
  184.     WI_DLX      /* TagItem.ti_data = DLX_numble, found in ArpBase.h */
  185.     /* Version 2.1 or higher */
  186.     WI_DLT      /* TagItem.ti_data = DLT_numble, found in DOS 2.0 */
  187.  
  188.  
  189. whatis.library/MakeTypeInfos
  190.  
  191.     NAME
  192.     MakeTypeInfos -- Add information to each FileType (V4)
  193.     
  194.     SYNOPSIS
  195.     MakeTypeInfos( SizeOfInfo)
  196.             d0
  197.  
  198.     APTR MakeTypeInfos( ULONG SizeOfInfo);
  199.  
  200.     FUNCTION
  201.     Alloc SizeOfInfo byte for each FileType.
  202.  
  203.     INPUTS
  204.     SizeOfInfo size in byte of information to be added to each FileType
  205.  
  206.     RESULT
  207.     A private handle to the information.
  208.  
  209.     NOTE
  210.     All information must be freed by FreeTypeInfos()
  211.  
  212.     SEE ALSO
  213.     GetTypeInfo(), FreeTypeInfos()
  214.  
  215. whatis.library/GetTypeInfo
  216.  
  217.     NAME
  218.     GetTypeInfo -- Get information of particular FileType (V4)
  219.     
  220.     SYNOPSIS
  221.     GetTypeInfo( Handle, FileType)
  222.             a0    d0
  223.  
  224.     void * GetTypeInfo( APTR Handle, FileType Type);
  225.  
  226.     FUNCTION
  227.     Get info of a FileType.
  228.  
  229.     INPUTS
  230.     Handle = Handle returned by MakeTypeInfos() of all Info.
  231.     Type = The file type the information is needed.
  232.  
  233.     RESULT
  234.     A pointer on the byte containing information for the passed type.
  235.  
  236.     SEE ALSO
  237.     MakeTypeInfos(), FreeTypeInfos()
  238.  
  239. whatis.library/FreeTypeInfos
  240.  
  241.     NAME
  242.     FreeTypeInfos -- Free information of all FileType (V4)
  243.     
  244.     SYNOPSIS
  245.     FreeTypeInfos( Handle)
  246.             a0
  247.  
  248.     void FreeTypeInfos( Handle);
  249.  
  250.     FUNCTION
  251.     Free info allocated by MakeTypeInfos().
  252.  
  253.     INPUTS
  254.     The handle returned by MakeTypeInfo
  255.  
  256.     RESULT
  257.  
  258.     SEE ALSO
  259.     GetTypeInfo(), MakeTypeInfos()
  260.  
  261.  
  262. Version history:
  263.  
  264.     1.0:    Version for KickStart 1.3.  Only This Version support 1.3.
  265.             All others need KS2.0
  266.     1.1:    Fixed a little bug.
  267.  
  268.     ALL next versions NEED KS2.0
  269.  
  270.     2.0:    First Version of whatis.library.
  271.             (the 1.0 was a limited version made for 1.3)
  272.  
  273.     3.0:    Fixed a little bug.
  274.             GetParentFileType() Added
  275.             IsSubTypeOf() Added
  276.             DLT support (KS2.0 version of the ARP DLX)
  277.  
  278.     3.4:    25/12/92
  279.             Fixed a Little Bug: the UNKNOWNFILETYPE was not returned by NextType()
  280.  
  281.     3.5:    4/1/93
  282.             Fixed a BIG bug born when fixed the preceding bug:
  283.             Forgot subtype of root in FirstType()/NextType().
  284.  
  285.     3.6:        25/07/93 (Internal)
  286.                 Internal: Incorect scan of TagItems. Fixed.
  287.                 SEARCHPATTERN don't work it string was not entiled by "#?". Fixed
  288.  
  289.     3.7:        12/08/93
  290.                 Fixed an Enforcer hit in NextType()
  291.                 Minor change: change the VERSTRING protocol.
  292.  
  293.     3.8:        9/9/93
  294.                 Internal change.
  295.                 Not realesed.
  296.  
  297.     4.0:        2/11/93
  298.                 User need to append a "#?" at end of string in MATCHPATTERN. Fixed
  299.                 Internal  change,  fixed  a  bug  born in 3.8 causing "Dir" not
  300.                 recognized in deep mode.
  301.                 Adding ConstructTypeInfos(SizeOfInfo), GetTypeInfo(Handle,Type),
  302.                 DestructTypeInfos(Handle)  to  allow  apli-prog  to have custom
  303.                 data relative to each file type.
  304.  
  305.     4.1:        30/1/94
  306.                 Now icon name are inherited from parent type.
  307.  
  308.     4.2:        11/5/94
  309.                 Only med module "MMD0" was not recognise, not "MMD1". fixed to "MMD?"
  310.                 Retetesting Hard type in the custome type test, causing some
  311.                 file  to  improperly recognise as hard type.  ( for example CRM
  312.                 "dummy.doc" was misrecognise as "Doc" file type) fixed.
  313.                 The last type was not given in the NextType(). fixed (thanks to xxx)
  314.                 Now  optimize  in  time  to  make  a faster library.  Surprise,
  315.                 little than 4.1.  8-))
  316.