home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1996 March / macformat-035.iso / Shareware City / Developers / MoreFiles 1.4.1 / MoreDesktopMgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-12-21  |  9.8 KB  |  283 lines  |  [TEXT/CWIE]
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    A collection of useful high-level Desktop Manager routines.
  5. **    If the Desktop Manager isn't available, use the Desktop file
  6. **    for 'read' operations.
  7. **
  8. **    We do more because we can...
  9. **
  10. **    by Jim Luther and Nitin Ganatra, Apple Developer Technical Support Emeriti
  11. **
  12. **    File:    MoreDesktopMgr.h
  13. **
  14. **    Copyright © 1992-1995 Apple Computer, Inc.
  15. **    All rights reserved.
  16. **
  17. **    You may incorporate this sample code into your applications without
  18. **    restriction, though the sample code has been provided "AS IS" and the
  19. **    responsibility for its operation is 100% yours.  However, what you are
  20. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  21. **    after having made changes. If you're going to re-distribute the source,
  22. **    we require that you make it clear in the source that the code was
  23. **    descended from Apple Sample Code, but that you've made changes.
  24. */
  25.  
  26. #ifndef __MOREDESKTOPMGR__
  27. #define __MOREDESKTOPMGR__
  28.  
  29. #include <Types.h>
  30. #include <Files.h>
  31.  
  32. #ifdef __cplusplus
  33. extern "C" {
  34. #endif
  35.  
  36. /*****************************************************************************/
  37.  
  38. pascal    OSErr    DTOpen(StringPtr volName,
  39.                        short vRefNum,
  40.                        short *dtRefNum,
  41.                        Boolean *newDTDatabase);
  42. /*    ¶ Open a volume's desktop database and return the desktop database refNum.
  43.     The DTOpen function opens a volume's desktop database. It returns
  44.     the reference number of the desktop database and indicates if the
  45.     desktop database was created as a result of this call (if it was created,
  46.     then it is empty).
  47.  
  48.     volName            input:    A pointer to the name of a mounted volume
  49.                             or nil.
  50.     vRefNum            input:    Volume specification.
  51.     dtRefNum        output:    The reference number of Desktop Manager's
  52.                             desktop database on the specified volume.
  53.     newDTDatabase    output:    true if the desktop database was created as a
  54.                             result of this call and thus empty.
  55.                             false if the desktop database was already created,
  56.                             or if it could not be determined if it was already
  57.                             created.
  58. */
  59.  
  60. /*****************************************************************************/
  61.  
  62. pascal    OSErr    DTGetAPPL(StringPtr volName,
  63.                           short vRefNum,
  64.                           OSType creator,
  65.                           short *applVRefNum,
  66.                           long *applParID,
  67.                           Str255 applName);
  68. /*    ¶ Find an application on a volume that can open a file with a given creator.
  69.     The DTGetAPPL function finds an application (file type 'APPL') with
  70.     the specified creator on the specified volume. It first tries to get
  71.     the application mapping from the desktop database. If that fails, then
  72.     it tries to find an application with the specified creator using
  73.     the File Manager's CatSearch routine. If that fails, then it tries to
  74.     find an application in the Desktop file.
  75.  
  76.     volName        input:    A pointer to the name of a mounted volume
  77.                         or nil.
  78.     vRefNum        input:    Volume specification.
  79.     creator        input:    The file's creator type.
  80.     applVRefNum    output:    The volume reference number of the volume the
  81.                         application is on.
  82.     applParID    output:    The parent directory ID of the application.
  83.     applName    output:    The name of the application.
  84.  
  85.     __________
  86.     
  87.     Also see:    FSpDTGetAPPL
  88. */
  89.  
  90. /*****************************************************************************/
  91.  
  92. pascal    OSErr    FSpDTGetAPPL(StringPtr volName,
  93.                              short vRefNum,
  94.                              OSType creator,
  95.                              FSSpec *spec);
  96. /*    ¶ Find an application on a volume that can open a file with a given creator.
  97.     The FSpDTGetAPPL function finds an application (file type 'APPL') with
  98.     the specified creator on the specified volume. It first tries to get
  99.     the application mapping from the desktop database. If that fails, then
  100.     it tries to find an application with the specified creator using
  101.     the File Manager's CatSearch routine. If that fails, then it tries to
  102.     find an application in the Desktop file.
  103.  
  104.     volName        input:    A pointer to the name of a mounted volume
  105.                         or nil.
  106.     vRefNum        input:    Volume specification.
  107.     creator        input:    The file's creator type.
  108.     spec        output:    FSSpec record containing the application name and
  109.                         location.
  110.  
  111.     __________
  112.     
  113.     Also see:    DTGetAPPL
  114. */
  115.  
  116. /*****************************************************************************/
  117.  
  118. pascal    OSErr    DTGetIcon(StringPtr volName,
  119.                           short vRefNum,
  120.                           short iconType,
  121.                           OSType fileCreator,
  122.                           OSType fileType,
  123.                           Handle *iconHandle);
  124. /*    ¶ Get an icon from the desktop database or Desktop file.
  125.     The DTGetIcon function retrieves the specified icon and returns it in
  126.     a newly created handle. The icon is retrieves from the Desktop Manager
  127.     or if the Desktop Manager is not available, from the Finder's Desktop
  128.     file. Your program is responsible for disposing of the handle when it is
  129.     done using the icon.
  130.  
  131.     volName        input:    A pointer to the name of a mounted volume
  132.                         or nil.
  133.     vRefNum        input:    Volume specification.
  134.     iconType    input:    The icon type as defined in Files.h. Valid values are:
  135.                             kLargeIcon
  136.                             kLarge4BitIcon
  137.                             kLarge8BitIcon
  138.                             kSmallIcon
  139.                             kSmall4BitIcon
  140.                             kSmall8BitIcon
  141.     fileCreator    input:    The icon's creator type.
  142.     fileType    input:    The icon's file type.
  143.     iconHandle    output:    A Handle containing the newly created icon.
  144. */
  145.  
  146. /*****************************************************************************/
  147.  
  148. pascal    OSErr    DTSetComment(short vRefNum,
  149.                              long dirID,
  150.                              StringPtr name,
  151.                              ConstStr255Param comment);
  152. /*    ¶ Set a file or directory's Finder comment field.
  153.     The DTSetComment function sets a file or directory's Finder comment
  154.     field. The volume must support the Desktop Manager because you only
  155.     have read access to the Desktop file.
  156.  
  157.     vRefNum    input:    Volume specification.
  158.     dirID    input:    Directory ID.
  159.     name    input:    Pointer to object name, or nil when dirID
  160.                     specifies a directory that's the object.
  161.     comment    input:    The comment to add. Comments are limited to 200 characters;
  162.                     longer comments are truncated.
  163.  
  164.     __________
  165.     
  166.     Also see:    DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
  167.                 FSpDTGetComment
  168. */
  169.  
  170. /*****************************************************************************/
  171.  
  172. pascal    OSErr    FSpDTSetComment(const FSSpec *spec,
  173.                                 ConstStr255Param comment);
  174. /*    ¶ Set a file or directory's Finder comment field.
  175.     The FSpDTSetComment function sets a file or directory's Finder comment
  176.     field. The volume must support the Desktop Manager because you only
  177.     have read access to the Desktop file.
  178.  
  179.     spec    input:    An FSSpec record specifying the file or directory.
  180.     comment    input:    The comment to add. Comments are limited to 200 characters;
  181.                     longer comments are truncated.
  182.  
  183.     __________
  184.     
  185.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
  186.                 FSpDTGetComment
  187. */
  188.  
  189. /*****************************************************************************/
  190.  
  191. pascal    OSErr    DTGetComment(short vRefNum,
  192.                              long dirID,
  193.                              StringPtr name,
  194.                              Str255 comment);
  195. /*    ¶ Get a file or directory's Finder comment field (if any).
  196.     The DTGetComment function gets a file or directory's Finder comment
  197.     field (if any) from the Desktop Manager or if the Desktop Manager is
  198.     not available, from the Finder's Desktop file.
  199.  
  200.     vRefNum    input:    Volume specification.
  201.     dirID    input:    Directory ID.
  202.     name    input:    Pointer to object name, or nil when dirID
  203.                     specifies a directory that's the object.
  204.     comment    output:    A Str255 where the comment is to be returned.
  205.  
  206.     __________
  207.     
  208.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  209.                 FSpDTGetComment
  210. */
  211.  
  212. /*****************************************************************************/
  213.  
  214. pascal    OSErr    FSpDTGetComment(const FSSpec *spec,
  215.                                 Str255 comment);
  216. /*    ¶ Get a file or directory's Finder comment field (if any).
  217.     The FSpDTGetComment function gets a file or directory's Finder comment
  218.     field (if any) from the Desktop Manager or if the Desktop Manager is
  219.     not available, from the Finder's Desktop file.
  220.  
  221.     spec    input:    An FSSpec record specifying the file or directory.
  222.     comment    output:    A Str255 where the comment is to be returned.
  223.  
  224.     __________
  225.     
  226.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  227.                 DTGetComment
  228. */
  229.  
  230. /*****************************************************************************/
  231.  
  232. pascal    OSErr    DTCopyComment(short srcVRefNum,
  233.                               long srcDirID,
  234.                               StringPtr srcName,
  235.                               short dstVRefNum,
  236.                               long dstDirID,
  237.                               StringPtr dstName);
  238. /*    ¶ Copy the file or folder comment from the source to the destination object.
  239.     The DTCopyComment function copies the file or folder comment from the
  240.     source to the destination object.  The destination volume must support
  241.     the Desktop Manager because you only have read access to the Desktop file.
  242.     
  243.     srcVRefNum    input:    Source volume specification.
  244.     srcDirID    input:    Source directory ID.
  245.     srcName        input:    Pointer to source object name, or nil when srcDirID
  246.                         specifies a directory that's the object.
  247.     dstVRefNum    input:    Destination volume specification.
  248.     dstDirID    input:    Destination directory ID.
  249.     dstName        input:    Pointer to destination object name, or nil when
  250.                         dstDirID specifies a directory that's the object.
  251.  
  252.     __________
  253.     
  254.     Also see:    FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  255.                 FSpDTGetComment
  256. */
  257.  
  258. /*****************************************************************************/
  259.  
  260. pascal    OSErr    FSpDTCopyComment(const FSSpec *srcSpec,
  261.                                  const FSSpec *dstSpec);
  262. /*    ¶ Copy the desktop database comment from the source to the destination object.
  263.     The FSpDTCopyComment function copies the desktop database comment from
  264.     the source to the destination object.  Both the source and the
  265.     destination volumes must support the Desktop Manager.
  266.     
  267.     srcSpec        input:    An FSSpec record specifying the source object.
  268.     dstSpec        input:    An FSSpec record specifying the destination object.
  269.  
  270.     __________
  271.     
  272.     Also see:    DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  273.                 FSpDTGetComment
  274. */
  275.  
  276. /*****************************************************************************/
  277.  
  278. #ifdef __cplusplus
  279. }
  280. #endif
  281.  
  282. #endif    /* __MOREDESKTOPMGR__ */
  283.