MoreDesktopMgr.h

Go to the documentation of this file.
00001 
00002 /*  $Id: MoreDesktopMgr.h 355 2005-01-11 22:48:55Z andreradke $    */
00003 
00004 /*
00005     File:       MoreDesktopMgr.h
00006     
00007     Description:A collection of useful high-level Desktop Manager routines.
00008                 If the Desktop Manager isn't available, use the Desktop file
00009                 for 'read' operations.
00010                 We do more because we can...
00011 
00012     Author:     JL & NG
00013 
00014     Copyright:  Copyright: © 1992-1999 by Apple Computer, Inc.
00015                 all rights reserved.
00016     
00017     Disclaimer: You may incorporate this sample code into your applications without
00018                 restriction, though the sample code has been provided "AS IS" and the
00019                 responsibility for its operation is 100% yours.  However, what you are
00020                 not permitted to do is to redistribute the source as "DSC Sample Code"
00021                 after having made changes. If you're going to re-distribute the source,
00022                 we require that you make it clear in the source that the code was
00023                 descended from Apple Sample Code, but that you've made changes.
00024     
00025     Change History (most recent first):
00026                 6/25/99 Updated for Metrowerks Codewarror Pro 2.1(KG)
00027 */
00028 #ifndef __MOREDESKTOPMGR__
00029 #define __MOREDESKTOPMGR__
00030 
00031 #include <Types.h>
00032 #include <Files.h>
00033 
00034 #include "Optimization.h"
00035 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif
00039 
00040 /*****************************************************************************/
00041 
00042 pascal  OSErr   DTOpen(ConstStr255Param volName,
00043                        short vRefNum,
00044                        short *dtRefNum,
00045                        Boolean *newDTDatabase);
00046 /*  ¶ Open a volume's desktop database and return the desktop database refNum.
00047     The DTOpen function opens a volume's desktop database. It returns
00048     the reference number of the desktop database and indicates if the
00049     desktop database was created as a result of this call (if it was created,
00050     then it is empty).
00051 
00052     volName         input:  A pointer to the name of a mounted volume
00053                             or nil.
00054     vRefNum         input:  Volume specification.
00055     dtRefNum        output: The reference number of Desktop Manager's
00056                             desktop database on the specified volume.
00057     newDTDatabase   output: true if the desktop database was created as a
00058                             result of this call and thus empty.
00059                             false if the desktop database was already created,
00060                             or if it could not be determined if it was already
00061                             created.
00062     
00063     Result Codes
00064         noErr               0       No error
00065         nsvErr              -35     Volume not found
00066         ioErr               -36     I/O error
00067         paramErr            -50     Volume doesn't support this function
00068         extFSErr            -58     External file system error - no file
00069                                     system claimed this call.
00070         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00071                                     the Finder will fix this, but if your
00072                                     application is not running with the
00073                                     Finder, use PBDTReset or PBDTDelete
00074 */
00075 
00076 /*****************************************************************************/
00077 
00078 pascal  OSErr   DTXGetAPPL(ConstStr255Param volName,
00079                            short vRefNum,
00080                            OSType creator,
00081                            Boolean searchCatalog,
00082                            short *applVRefNum,
00083                            long *applParID,
00084                            Str255 applName);
00085 /*  ¶ Find an application on a volume that can open a file with a given creator.
00086     The DTXGetAPPL function finds an application (file type 'APPL') with
00087     the specified creator on the specified volume. It first tries to get
00088     the application mapping from the desktop database. If that fails,
00089     then it tries to find an application in the Desktop file. If that
00090     fails and searchCatalog is true, then it tries to find an application
00091     with the specified creator using the File Manager's CatSearch routine. 
00092 
00093     volName         input:  A pointer to the name of a mounted volume
00094                             or nil.
00095     vRefNum         input:  Volume specification.
00096     creator         input:  The file's creator type.
00097     searchCatalog   input:  If true, search the catalog for the application
00098                             if it isn't found in the desktop database.
00099     applVRefNum     output: The volume reference number of the volume the
00100                             application is on.
00101     applParID       output: The parent directory ID of the application.
00102     applName        output: The name of the application.
00103     
00104     Result Codes
00105         noErr               0       No error
00106         nsvErr              -35     Volume not found
00107         ioErr               -36     I/O error
00108         paramErr            -50     No default volume
00109         rfNumErr            -51     Reference number invalid
00110         extFSErr            -58     External file system error - no file
00111                                     system claimed this call
00112         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00113                                     the Finder will fix this, but if your
00114                                     application is not running with the
00115                                     Finder, use PBDTReset or PBDTDelete
00116         afpItemNotFound     -5012   Information not found
00117     
00118     __________
00119     
00120     Also see:   FSpDTGetAPPL
00121 */
00122 
00123 /*****************************************************************************/
00124 
00125 pascal  OSErr   FSpDTXGetAPPL(ConstStr255Param volName,
00126                               short vRefNum,
00127                               OSType creator,
00128                               Boolean searchCatalog,
00129                               FSSpec *spec);
00130 /*  ¶ Find an application on a volume that can open a file with a given creator.
00131     The FSpDTXGetAPPL function finds an application (file type 'APPL') with
00132     the specified creator on the specified volume. It first tries to get
00133     the application mapping from the desktop database. If that fails,
00134     then it tries to find an application in the Desktop file. If that
00135     fails and searchCatalog is true, then it tries to find an application
00136     with the specified creator using the File Manager's CatSearch routine. 
00137 
00138     volName         input:  A pointer to the name of a mounted volume
00139                             or nil.
00140     vRefNum         input:  Volume specification.
00141     creator         input:  The file's creator type.
00142     searchCatalog   input:  If true, search the catalog for the application
00143                             if it isn't found in the desktop database.
00144     spec            output: FSSpec record containing the application name and
00145                             location.
00146     
00147     Result Codes
00148         noErr               0       No error
00149         nsvErr              -35     Volume not found
00150         ioErr               -36     I/O error
00151         paramErr            -50     No default volume
00152         rfNumErr            -51     Reference number invalid
00153         extFSErr            -58     External file system error - no file
00154                                     system claimed this call
00155         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00156                                     the Finder will fix this, but if your
00157                                     application is not running with the
00158                                     Finder, use PBDTReset or PBDTDelete
00159         afpItemNotFound     -5012   Information not found
00160     
00161     __________
00162     
00163     Also see:   FSpDTGetAPPL
00164 */
00165 
00166 /*****************************************************************************/
00167 
00168 pascal  OSErr   DTGetAPPL(ConstStr255Param volName,
00169                           short vRefNum,
00170                           OSType creator,
00171                           short *applVRefNum,
00172                           long *applParID,
00173                           Str255 applName);
00174 /*  ¶ Find an application on a volume that can open a file with a given creator.
00175     The DTGetAPPL function finds an application (file type 'APPL') with
00176     the specified creator on the specified volume. It first tries to get
00177     the application mapping from the desktop database. If that fails,
00178     then it tries to find an application in the Desktop file. If that
00179     fails, then it tries to find an application with the specified creator
00180     using the File Manager's CatSearch routine. 
00181 
00182     volName     input:  A pointer to the name of a mounted volume
00183                         or nil.
00184     vRefNum     input:  Volume specification.
00185     creator     input:  The file's creator type.
00186     applVRefNum output: The volume reference number of the volume the
00187                         application is on.
00188     applParID   output: The parent directory ID of the application.
00189     applName    output: The name of the application.
00190     
00191     Result Codes
00192         noErr               0       No error
00193         nsvErr              -35     Volume not found
00194         ioErr               -36     I/O error
00195         paramErr            -50     No default volume
00196         rfNumErr            -51     Reference number invalid
00197         extFSErr            -58     External file system error - no file
00198                                     system claimed this call
00199         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00200                                     the Finder will fix this, but if your
00201                                     application is not running with the
00202                                     Finder, use PBDTReset or PBDTDelete
00203         afpItemNotFound     -5012   Information not found
00204     
00205     __________
00206     
00207     Also see:   FSpDTGetAPPL
00208 */
00209 
00210 /*****************************************************************************/
00211 
00212 pascal  OSErr   FSpDTGetAPPL(ConstStr255Param volName,
00213                              short vRefNum,
00214                              OSType creator,
00215                              FSSpec *spec);
00216 /*  ¶ Find an application on a volume that can open a file with a given creator.
00217     The FSpDTGetAPPL function finds an application (file type 'APPL') with
00218     the specified creator on the specified volume. It first tries to get
00219     the application mapping from the desktop database. If that fails,
00220     then it tries to find an application in the Desktop file. If that
00221     fails, then it tries to find an application with the specified creator
00222     using the File Manager's CatSearch routine. 
00223 
00224     volName     input:  A pointer to the name of a mounted volume
00225                         or nil.
00226     vRefNum     input:  Volume specification.
00227     creator     input:  The file's creator type.
00228     spec        output: FSSpec record containing the application name and
00229                         location.
00230     
00231     Result Codes
00232         noErr               0       No error
00233         nsvErr              -35     Volume not found
00234         ioErr               -36     I/O error
00235         paramErr            -50     No default volume
00236         rfNumErr            -51     Reference number invalid
00237         extFSErr            -58     External file system error - no file
00238                                     system claimed this call
00239         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00240                                     the Finder will fix this, but if your
00241                                     application is not running with the
00242                                     Finder, use PBDTReset or PBDTDelete
00243         afpItemNotFound     -5012   Information not found
00244     
00245     __________
00246     
00247     Also see:   DTGetAPPL
00248 */
00249 
00250 /*****************************************************************************/
00251 
00252 pascal  OSErr   DTGetIcon(ConstStr255Param volName,
00253                           short vRefNum,
00254                           short iconType,
00255                           OSType fileCreator,
00256                           OSType fileType,
00257                           Handle *iconHandle);
00258 /*  ¶ Get an icon from the desktop database or Desktop file.
00259     The DTGetIcon function retrieves the specified icon and returns it in
00260     a newly created handle. The icon is retrieves from the Desktop Manager
00261     or if the Desktop Manager is not available, from the Finder's Desktop
00262     file. Your program is responsible for disposing of the handle when it is
00263     done using the icon.
00264 
00265     volName     input:  A pointer to the name of a mounted volume
00266                         or nil.
00267     vRefNum     input:  Volume specification.
00268     iconType    input:  The icon type as defined in Files.h. Valid values are:
00269                             kLargeIcon
00270                             kLarge4BitIcon
00271                             kLarge8BitIcon
00272                             kSmallIcon
00273                             kSmall4BitIcon
00274                             kSmall8BitIcon
00275     fileCreator input:  The icon's creator type.
00276     fileType    input:  The icon's file type.
00277     iconHandle  output: A Handle containing the newly created icon.
00278     
00279     Result Codes
00280         noErr               0       No error
00281         nsvErr              -35     Volume not found
00282         ioErr               -36     I/O error
00283         paramErr            -50     Volume doesn't support this function
00284         rfNumErr            -51     Reference number invalid
00285         extFSErr            -58     External file system error - no file
00286                                     system claimed this call
00287         memFullErr          -108    iconHandle could not be allocated
00288         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00289                                     the Finder will fix this, but if your
00290                                     application is not running with the
00291                                     Finder, use PBDTReset or PBDTDelete
00292         afpItemNotFound     -5012   Information not found
00293 */
00294 
00295 /*****************************************************************************/
00296 
00297 pascal  OSErr   DTSetComment(short vRefNum,
00298                              long dirID,
00299                              ConstStr255Param name,
00300                              ConstStr255Param comment);
00301 /*  ¶ Set a file or directory's Finder comment field.
00302     The DTSetComment function sets a file or directory's Finder comment
00303     field. The volume must support the Desktop Manager because you only
00304     have read access to the Desktop file.
00305 
00306     vRefNum input:  Volume specification.
00307     dirID   input:  Directory ID.
00308     name    input:  Pointer to object name, or nil when dirID
00309                     specifies a directory that's the object.
00310     comment input:  The comment to add. Comments are limited to 200 characters;
00311                     longer comments are truncated.
00312     
00313     Result Codes
00314         noErr               0       No error
00315         nsvErr              -35     Volume not found
00316         ioErr               -36     I/O error
00317         fnfErr              –43     File or directory doesn’t exist
00318         paramErr            -50     Volume doesn't support this function
00319         wPrErr              –44     Volume is locked through hardware
00320         vLckdErr            –46     Volume is locked through software
00321         rfNumErr            –51     Reference number invalid
00322         extFSErr            -58     External file system error - no file
00323                                     system claimed this call.
00324         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00325                                     the Finder will fix this, but if your
00326                                     application is not running with the
00327                                     Finder, use PBDTReset or PBDTDelete
00328     
00329     __________
00330     
00331     Also see:   DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
00332                 FSpDTGetComment
00333 */
00334 
00335 /*****************************************************************************/
00336 
00337 pascal  OSErr   FSpDTSetComment(const FSSpec *spec,
00338                                 ConstStr255Param comment);
00339 /*  ¶ Set a file or directory's Finder comment field.
00340     The FSpDTSetComment function sets a file or directory's Finder comment
00341     field. The volume must support the Desktop Manager because you only
00342     have read access to the Desktop file.
00343 
00344     spec    input:  An FSSpec record specifying the file or directory.
00345     comment input:  The comment to add. Comments are limited to 200 characters;
00346                     longer comments are truncated.
00347     
00348     Result Codes
00349         noErr               0       No error
00350         nsvErr              -35     Volume not found
00351         ioErr               -36     I/O error
00352         fnfErr              –43     File or directory doesn’t exist
00353         wPrErr              –44     Volume is locked through hardware
00354         vLckdErr            –46     Volume is locked through software
00355         rfNumErr            –51     Reference number invalid
00356         paramErr            -50     Volume doesn't support this function
00357         extFSErr            -58     External file system error - no file
00358                                     system claimed this call.
00359         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00360                                     the Finder will fix this, but if your
00361                                     application is not running with the
00362                                     Finder, use PBDTReset or PBDTDelete
00363     
00364     __________
00365     
00366     Also see:   DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
00367                 FSpDTGetComment
00368 */
00369 
00370 /*****************************************************************************/
00371 
00372 pascal  OSErr   DTGetComment(short vRefNum,
00373                              long dirID,
00374                              ConstStr255Param name,
00375                              Str255 comment);
00376 /*  ¶ Get a file or directory's Finder comment field (if any).
00377     The DTGetComment function gets a file or directory's Finder comment
00378     field (if any) from the Desktop Manager or if the Desktop Manager is
00379     not available, from the Finder's Desktop file.
00380 
00381     IMPORTANT NOTE: Inside Macintosh says that comments are up to
00382     200 characters. While that may be correct for the HFS file system's
00383     Desktop Manager, other file systems (such as Apple Photo Access) return
00384     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
00385     regret it.
00386     
00387     vRefNum input:  Volume specification.
00388     dirID   input:  Directory ID.
00389     name    input:  Pointer to object name, or nil when dirID
00390                     specifies a directory that's the object.
00391     comment output: A Str255 where the comment is to be returned.
00392     
00393     Result Codes
00394         noErr               0       No error
00395         nsvErr              -35     Volume not found
00396         ioErr               -36     I/O error
00397         fnfErr              -43     File not found
00398         paramErr            -50     Volume doesn't support this function
00399         rfNumErr            –51     Reference number invalid
00400         extFSErr            -58     External file system error - no file
00401                                     system claimed this call.
00402         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00403                                     the Finder will fix this, but if your
00404                                     application is not running with the
00405                                     Finder, use PBDTReset or PBDTDelete
00406         afpItemNotFound     -5012   Information not found
00407         
00408     __________
00409     
00410     Also see:   DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
00411                 FSpDTGetComment
00412 */
00413 
00414 /*****************************************************************************/
00415 
00416 pascal  OSErr   FSpDTGetComment(const FSSpec *spec,
00417                                 Str255 comment);
00418 /*  ¶ Get a file or directory's Finder comment field (if any).
00419     The FSpDTGetComment function gets a file or directory's Finder comment
00420     field (if any) from the Desktop Manager or if the Desktop Manager is
00421     not available, from the Finder's Desktop file.
00422 
00423     IMPORTANT NOTE: Inside Macintosh says that comments are up to
00424     200 characters. While that may be correct for the HFS file system's
00425     Desktop Manager, other file systems (such as Apple Photo Access) return
00426     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
00427     regret it.
00428     
00429     spec    input:  An FSSpec record specifying the file or directory.
00430     comment output: A Str255 where the comment is to be returned.
00431 
00432     Result Codes
00433         noErr               0       No error
00434         nsvErr              -35     Volume not found
00435         ioErr               -36     I/O error
00436         fnfErr              -43     File not found
00437         paramErr            -50     Volume doesn't support this function
00438         rfNumErr            –51     Reference number invalid
00439         extFSErr            -58     External file system error - no file
00440                                     system claimed this call.
00441         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00442                                     the Finder will fix this, but if your
00443                                     application is not running with the
00444                                     Finder, use PBDTReset or PBDTDelete
00445         afpItemNotFound     -5012   Information not found
00446         
00447     __________
00448     
00449     Also see:   DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
00450                 DTGetComment
00451 */
00452 
00453 /*****************************************************************************/
00454 
00455 pascal  OSErr   DTCopyComment(short srcVRefNum,
00456                               long srcDirID,
00457                               ConstStr255Param srcName,
00458                               short dstVRefNum,
00459                               long dstDirID,
00460                               ConstStr255Param dstName);
00461 /*  ¶ Copy the file or folder comment from the source to the destination object.
00462     The DTCopyComment function copies the file or folder comment from the
00463     source to the destination object.  The destination volume must support
00464     the Desktop Manager because you only have read access to the Desktop file.
00465     
00466     srcVRefNum  input:  Source volume specification.
00467     srcDirID    input:  Source directory ID.
00468     srcName     input:  Pointer to source object name, or nil when srcDirID
00469                         specifies a directory that's the object.
00470     dstVRefNum  input:  Destination volume specification.
00471     dstDirID    input:  Destination directory ID.
00472     dstName     input:  Pointer to destination object name, or nil when
00473                         dstDirID specifies a directory that's the object.
00474     
00475     Result Codes
00476         noErr               0       No error
00477         nsvErr              -35     Volume not found
00478         ioErr               -36     I/O error
00479         fnfErr              –43     File or directory doesn’t exist
00480         wPrErr              –44     Volume is locked through hardware
00481         vLckdErr            –46     Volume is locked through software
00482         paramErr            -50     Volume doesn't support this function
00483         rfNumErr            –51     Reference number invalid
00484         paramErr            -50     Volume doesn't support this function
00485         extFSErr            -58     External file system error - no file
00486                                     system claimed this call.
00487         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00488                                     the Finder will fix this, but if your
00489                                     application is not running with the
00490                                     Finder, use PBDTReset or PBDTDelete
00491         afpItemNotFound     -5012   Information not found
00492         
00493     __________
00494     
00495     Also see:   FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
00496                 FSpDTGetComment
00497 */
00498 
00499 /*****************************************************************************/
00500 
00501 pascal  OSErr   FSpDTCopyComment(const FSSpec *srcSpec,
00502                                  const FSSpec *dstSpec);
00503 /*  ¶ Copy the desktop database comment from the source to the destination object.
00504     The FSpDTCopyComment function copies the desktop database comment from
00505     the source to the destination object.  Both the source and the
00506     destination volumes must support the Desktop Manager.
00507     
00508     srcSpec     input:  An FSSpec record specifying the source object.
00509     dstSpec     input:  An FSSpec record specifying the destination object.
00510     
00511     Result Codes
00512         noErr               0       No error
00513         nsvErr              -35     Volume not found
00514         ioErr               -36     I/O error
00515         fnfErr              –43     File or directory doesn’t exist
00516         wPrErr              –44     Volume is locked through hardware
00517         vLckdErr            –46     Volume is locked through software
00518         paramErr            -50     Volume doesn't support this function
00519         rfNumErr            –51     Reference number invalid
00520         paramErr            -50     Volume doesn't support this function
00521         extFSErr            -58     External file system error - no file
00522                                     system claimed this call.
00523         desktopDamagedErr   -1305   The desktop database has become corrupted - 
00524                                     the Finder will fix this, but if your
00525                                     application is not running with the
00526                                     Finder, use PBDTReset or PBDTDelete
00527         afpItemNotFound     -5012   Information not found
00528         
00529     __________
00530     
00531     Also see:   DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
00532                 FSpDTGetComment
00533 */
00534 
00535 /*****************************************************************************/
00536 
00537 #ifdef __cplusplus
00538 }
00539 #endif
00540 
00541 #include "OptimizationEnd.h"
00542 
00543 #endif  /* __MOREDESKTOPMGR__ */
00544 
00545 

Generated on Wed May 31 18:19:55 2006 for frontierkernel 10.1.10a by  doxygen 1.4.6