home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / lib / mac / MoreFiles / MoreDesktopMgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  16.4 KB  |  447 lines
  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-1996 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. /* 
  27.  * This code, which was decended from Apple Sample Code, has been modified by 
  28.  * Netscape.
  29.  */
  30.  
  31. #ifndef __MOREDESKTOPMGR__
  32. #define __MOREDESKTOPMGR__
  33.  
  34. #include <Types.h>
  35. #include <Files.h>
  36.  
  37. #include "PascalElim.h"
  38.  
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42.  
  43. /* Rather than duplicate this case statement I am making this function public */
  44. pascal OSType    DTIconToResIcon(short iconType);
  45. /*****************************************************************************/
  46.  
  47. pascal    OSErr    DTOpen(StringPtr volName,
  48.                        short vRefNum,
  49.                        short *dtRefNum,
  50.                        Boolean *newDTDatabase);
  51. /*    ª Open a volume's desktop database and return the desktop database refNum.
  52.     The DTOpen function opens a volume's desktop database. It returns
  53.     the reference number of the desktop database and indicates if the
  54.     desktop database was created as a result of this call (if it was created,
  55.     then it is empty).
  56.  
  57.     volName            input:    A pointer to the name of a mounted volume
  58.                             or nil.
  59.     vRefNum            input:    Volume specification.
  60.     dtRefNum        output:    The reference number of Desktop Manager's
  61.                             desktop database on the specified volume.
  62.     newDTDatabase    output:    true if the desktop database was created as a
  63.                             result of this call and thus empty.
  64.                             false if the desktop database was already created,
  65.                             or if it could not be determined if it was already
  66.                             created.
  67.     
  68.     Result Codes
  69.         noErr                0        No error
  70.         nsvErr                -35        Volume not found
  71.         ioErr                -36        I/O error
  72.         paramErr            -50        Volume doesn't support this function
  73.         extFSErr            -58        External file system error - no file
  74.                                     system claimed this call.
  75.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  76.                                     the Finder will fix this, but if your
  77.                                     application is not running with the
  78.                                     Finder, use PBDTReset or PBDTDelete
  79. */
  80.  
  81. /*****************************************************************************/
  82.  
  83. pascal    OSErr    DTGetAPPL(StringPtr volName,
  84.                           short vRefNum,
  85.                           OSType creator,
  86.                           short *applVRefNum,
  87.                           long *applParID,
  88.                           Str255 applName);
  89. /*    ª Find an application on a volume that can open a file with a given creator.
  90.     The DTGetAPPL function finds an application (file type 'APPL') with
  91.     the specified creator on the specified volume. It first tries to get
  92.     the application mapping from the desktop database. If that fails, then
  93.     it tries to find an application with the specified creator using
  94.     the File Manager's CatSearch routine. If that fails, then it tries to
  95.     find an application in the Desktop file.
  96.  
  97.     volName        input:    A pointer to the name of a mounted volume
  98.                         or nil.
  99.     vRefNum        input:    Volume specification.
  100.     creator        input:    The file's creator type.
  101.     applVRefNum    output:    The volume reference number of the volume the
  102.                         application is on.
  103.     applParID    output:    The parent directory ID of the application.
  104.     applName    output:    The name of the application.
  105.     
  106.     Result Codes
  107.         noErr                0        No error
  108.         nsvErr                -35        Volume not found
  109.         ioErr                -36        I/O error
  110.         paramErr            -50        No default volume
  111.         rfNumErr            -51        Reference number invalid
  112.         extFSErr            -58        External file system error - no file
  113.                                     system claimed this call
  114.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  115.                                     the Finder will fix this, but if your
  116.                                     application is not running with the
  117.                                     Finder, use PBDTReset or PBDTDelete
  118.         afpItemNotFound        -5012    Information not found
  119.     
  120.     __________
  121.     
  122.     Also see:    FSpDTGetAPPL
  123. */
  124.  
  125. /*****************************************************************************/
  126.  
  127. pascal    OSErr    FSpDTGetAPPL(StringPtr volName,
  128.                              short vRefNum,
  129.                              OSType creator,
  130.                              FSSpec *spec);
  131. /*    ª Find an application on a volume that can open a file with a given creator.
  132.     The FSpDTGetAPPL function finds an application (file type 'APPL') with
  133.     the specified creator on the specified volume. It first tries to get
  134.     the application mapping from the desktop database. If that fails, then
  135.     it tries to find an application with the specified creator using
  136.     the File Manager's CatSearch routine. If that fails, then it tries to
  137.     find an application in the Desktop file.
  138.  
  139.     volName        input:    A pointer to the name of a mounted volume
  140.                         or nil.
  141.     vRefNum        input:    Volume specification.
  142.     creator        input:    The file's creator type.
  143.     spec        output:    FSSpec record containing the application name and
  144.                         location.
  145.     
  146.     Result Codes
  147.         noErr                0        No error
  148.         nsvErr                -35        Volume not found
  149.         ioErr                -36        I/O error
  150.         paramErr            -50        No default volume
  151.         rfNumErr            -51        Reference number invalid
  152.         extFSErr            -58        External file system error - no file
  153.                                     system claimed this call
  154.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  155.                                     the Finder will fix this, but if your
  156.                                     application is not running with the
  157.                                     Finder, use PBDTReset or PBDTDelete
  158.         afpItemNotFound        -5012    Information not found
  159.     
  160.     __________
  161.     
  162.     Also see:    DTGetAPPL
  163. */
  164.  
  165. /*****************************************************************************/
  166.  
  167. pascal    OSErr    DTGetIcon(StringPtr volName,
  168.                           short vRefNum,
  169.                           short iconType,
  170.                           OSType fileCreator,
  171.                           OSType fileType,
  172.                           Handle *iconHandle);
  173. /*    ª Get an icon from the desktop database or Desktop file.
  174.     The DTGetIcon function retrieves the specified icon and returns it in
  175.     a newly created handle. The icon is retrieves from the Desktop Manager
  176.     or if the Desktop Manager is not available, from the Finder's Desktop
  177.     file. Your program is responsible for disposing of the handle when it is
  178.     done using the icon.
  179.  
  180.     volName        input:    A pointer to the name of a mounted volume
  181.                         or nil.
  182.     vRefNum        input:    Volume specification.
  183.     iconType    input:    The icon type as defined in Files.h. Valid values are:
  184.                             kLargeIcon
  185.                             kLarge4BitIcon
  186.                             kLarge8BitIcon
  187.                             kSmallIcon
  188.                             kSmall4BitIcon
  189.                             kSmall8BitIcon
  190.     fileCreator    input:    The icon's creator type.
  191.     fileType    input:    The icon's file type.
  192.     iconHandle    output:    A Handle containing the newly created icon.
  193.     
  194.     Result Codes
  195.         noErr                0        No error
  196.         nsvErr                -35        Volume not found
  197.         ioErr                -36        I/O error
  198.         paramErr            -50        Volume doesn't support this function
  199.         rfNumErr            -51        Reference number invalid
  200.         extFSErr            -58        External file system error - no file
  201.                                     system claimed this call
  202.         memFullErr            -108    iconHandle could not be allocated
  203.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  204.                                     the Finder will fix this, but if your
  205.                                     application is not running with the
  206.                                     Finder, use PBDTReset or PBDTDelete
  207.         afpItemNotFound        -5012    Information not found
  208. */
  209.  
  210. /*****************************************************************************/
  211.  
  212. pascal    OSErr    DTSetComment(short vRefNum,
  213.                              long dirID,
  214.                              StringPtr name,
  215.                              ConstStr255Param comment);
  216. /*    ª Set a file or directory's Finder comment field.
  217.     The DTSetComment function sets a file or directory's Finder comment
  218.     field. The volume must support the Desktop Manager because you only
  219.     have read access to the Desktop file.
  220.  
  221.     vRefNum    input:    Volume specification.
  222.     dirID    input:    Directory ID.
  223.     name    input:    Pointer to object name, or nil when dirID
  224.                     specifies a directory that's the object.
  225.     comment    input:    The comment to add. Comments are limited to 200 characters;
  226.                     longer comments are truncated.
  227.     
  228.     Result Codes
  229.         noErr                0        No error
  230.         nsvErr                -35        Volume not found
  231.         ioErr                -36        I/O error
  232.         fnfErr                ╨43        File or directory doesn╒t exist
  233.         paramErr            -50        Volume doesn't support this function
  234.         wPrErr                ╨44        Volume is locked through hardware
  235.         vLckdErr            ╨46        Volume is locked through software
  236.         rfNumErr            ╨51        Reference number invalid
  237.         extFSErr            -58        External file system error - no file
  238.                                     system claimed this call.
  239.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  240.                                     the Finder will fix this, but if your
  241.                                     application is not running with the
  242.                                     Finder, use PBDTReset or PBDTDelete
  243.     
  244.     __________
  245.     
  246.     Also see:    DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
  247.                 FSpDTGetComment
  248. */
  249.  
  250. /*****************************************************************************/
  251.  
  252. pascal    OSErr    FSpDTSetComment(const FSSpec *spec,
  253.                                 ConstStr255Param comment);
  254. /*    ª Set a file or directory's Finder comment field.
  255.     The FSpDTSetComment function sets a file or directory's Finder comment
  256.     field. The volume must support the Desktop Manager because you only
  257.     have read access to the Desktop file.
  258.  
  259.     spec    input:    An FSSpec record specifying the file or directory.
  260.     comment    input:    The comment to add. Comments are limited to 200 characters;
  261.                     longer comments are truncated.
  262.     
  263.     Result Codes
  264.         noErr                0        No error
  265.         nsvErr                -35        Volume not found
  266.         ioErr                -36        I/O error
  267.         fnfErr                ╨43        File or directory doesn╒t exist
  268.         wPrErr                ╨44        Volume is locked through hardware
  269.         vLckdErr            ╨46        Volume is locked through software
  270.         rfNumErr            ╨51        Reference number invalid
  271.         paramErr            -50        Volume doesn't support this function
  272.         extFSErr            -58        External file system error - no file
  273.                                     system claimed this call.
  274.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  275.                                     the Finder will fix this, but if your
  276.                                     application is not running with the
  277.                                     Finder, use PBDTReset or PBDTDelete
  278.     
  279.     __________
  280.     
  281.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
  282.                 FSpDTGetComment
  283. */
  284.  
  285. /*****************************************************************************/
  286.  
  287. pascal    OSErr    DTGetComment(short vRefNum,
  288.                              long dirID,
  289.                              StringPtr name,
  290.                              Str255 comment);
  291. /*    ª Get a file or directory's Finder comment field (if any).
  292.     The DTGetComment function gets a file or directory's Finder comment
  293.     field (if any) from the Desktop Manager or if the Desktop Manager is
  294.     not available, from the Finder's Desktop file.
  295.  
  296.     vRefNum    input:    Volume specification.
  297.     dirID    input:    Directory ID.
  298.     name    input:    Pointer to object name, or nil when dirID
  299.                     specifies a directory that's the object.
  300.     comment    output:    A Str255 where the comment is to be returned.
  301.     
  302.     Result Codes
  303.         noErr                0        No error
  304.         nsvErr                -35        Volume not found
  305.         ioErr                -36        I/O error
  306.         paramErr            -50        Volume doesn't support this function
  307.         rfNumErr            ╨51        Reference number invalid
  308.         extFSErr            -58        External file system error - no file
  309.                                     system claimed this call.
  310.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  311.                                     the Finder will fix this, but if your
  312.                                     application is not running with the
  313.                                     Finder, use PBDTReset or PBDTDelete
  314.         afpItemNotFound        -5012    Information not found
  315.         
  316.     __________
  317.     
  318.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  319.                 FSpDTGetComment
  320. */
  321.  
  322. /*****************************************************************************/
  323.  
  324. pascal    OSErr    FSpDTGetComment(const FSSpec *spec,
  325.                                 Str255 comment);
  326. /*    ª Get a file or directory's Finder comment field (if any).
  327.     The FSpDTGetComment function gets a file or directory's Finder comment
  328.     field (if any) from the Desktop Manager or if the Desktop Manager is
  329.     not available, from the Finder's Desktop file.
  330.  
  331.     spec    input:    An FSSpec record specifying the file or directory.
  332.     comment    output:    A Str255 where the comment is to be returned.
  333.  
  334.     Result Codes
  335.         noErr                0        No error
  336.         nsvErr                -35        Volume not found
  337.         ioErr                -36        I/O error
  338.         paramErr            -50        Volume doesn't support this function
  339.         rfNumErr            ╨51        Reference number invalid
  340.         extFSErr            -58        External file system error - no file
  341.                                     system claimed this call.
  342.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  343.                                     the Finder will fix this, but if your
  344.                                     application is not running with the
  345.                                     Finder, use PBDTReset or PBDTDelete
  346.         afpItemNotFound        -5012    Information not found
  347.         
  348.     __________
  349.     
  350.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  351.                 DTGetComment
  352. */
  353.  
  354. /*****************************************************************************/
  355.  
  356. pascal    OSErr    DTCopyComment(short srcVRefNum,
  357.                               long srcDirID,
  358.                               StringPtr srcName,
  359.                               short dstVRefNum,
  360.                               long dstDirID,
  361.                               StringPtr dstName);
  362. /*    ª Copy the file or folder comment from the source to the destination object.
  363.     The DTCopyComment function copies the file or folder comment from the
  364.     source to the destination object.  The destination volume must support
  365.     the Desktop Manager because you only have read access to the Desktop file.
  366.     
  367.     srcVRefNum    input:    Source volume specification.
  368.     srcDirID    input:    Source directory ID.
  369.     srcName        input:    Pointer to source object name, or nil when srcDirID
  370.                         specifies a directory that's the object.
  371.     dstVRefNum    input:    Destination volume specification.
  372.     dstDirID    input:    Destination directory ID.
  373.     dstName        input:    Pointer to destination object name, or nil when
  374.                         dstDirID specifies a directory that's the object.
  375.     
  376.     Result Codes
  377.         noErr                0        No error
  378.         nsvErr                -35        Volume not found
  379.         ioErr                -36        I/O error
  380.         fnfErr                ╨43        File or directory doesn╒t exist
  381.         wPrErr                ╨44        Volume is locked through hardware
  382.         vLckdErr            ╨46        Volume is locked through software
  383.         paramErr            -50        Volume doesn't support this function
  384.         rfNumErr            ╨51        Reference number invalid
  385.         paramErr            -50        Volume doesn't support this function
  386.         extFSErr            -58        External file system error - no file
  387.                                     system claimed this call.
  388.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  389.                                     the Finder will fix this, but if your
  390.                                     application is not running with the
  391.                                     Finder, use PBDTReset or PBDTDelete
  392.         afpItemNotFound        -5012    Information not found
  393.         
  394.     __________
  395.     
  396.     Also see:    FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  397.                 FSpDTGetComment
  398. */
  399.  
  400. /*****************************************************************************/
  401.  
  402. pascal    OSErr    FSpDTCopyComment(const FSSpec *srcSpec,
  403.                                  const FSSpec *dstSpec);
  404. /*    ª Copy the desktop database comment from the source to the destination object.
  405.     The FSpDTCopyComment function copies the desktop database comment from
  406.     the source to the destination object.  Both the source and the
  407.     destination volumes must support the Desktop Manager.
  408.     
  409.     srcSpec        input:    An FSSpec record specifying the source object.
  410.     dstSpec        input:    An FSSpec record specifying the destination object.
  411.     
  412.     Result Codes
  413.         noErr                0        No error
  414.         nsvErr                -35        Volume not found
  415.         ioErr                -36        I/O error
  416.         fnfErr                ╨43        File or directory doesn╒t exist
  417.         wPrErr                ╨44        Volume is locked through hardware
  418.         vLckdErr            ╨46        Volume is locked through software
  419.         paramErr            -50        Volume doesn't support this function
  420.         rfNumErr            ╨51        Reference number invalid
  421.         paramErr            -50        Volume doesn't support this function
  422.         extFSErr            -58        External file system error - no file
  423.                                     system claimed this call.
  424.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  425.                                     the Finder will fix this, but if your
  426.                                     application is not running with the
  427.                                     Finder, use PBDTReset or PBDTDelete
  428.         afpItemNotFound        -5012    Information not found
  429.         
  430.     __________
  431.     
  432.     Also see:    DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  433.                 FSpDTGetComment
  434. */
  435.  
  436. /*****************************************************************************/
  437.  
  438. #ifdef __cplusplus
  439. }
  440. #endif
  441.  
  442. #ifndef __COMPILINGMOREFILES
  443. #undef pascal
  444. #endif
  445.  
  446. #endif    /* __MOREDESKTOPMGR__ */
  447.