src/mac/carbon/morefile/MoreDesktopMgr.h

   1 /*
   2      File:       MoreDesktopMgr.h
   3
   4      Contains:   A collection of useful high-level Desktop Manager routines. If the Desktop Manager is not available, use the Desktop file for 'read' operations.
   5
   6      Version:    Technology: MoreFiles
   7                  Release:    1.5.2
   8
   9      Copyright:  © 1992-2001 by Apple Computer, Inc., all rights reserved.
  10
  11      Bugs?:      For bug reports, consult the following page on
  12                  the World Wide Web:
  13
  14                      http://developer.apple.com/bugreporter/
  15
  16 */
  17
  18 /*
  19     You may incorporate this sample code into your applications without
  20     restriction, though the sample code has been provided "AS IS" and the
  21     responsibility for its operation is 100% yours.  However, what you are
  22     not permitted to do is to redistribute the source as "DSC Sample Code"
  23     after having made changes. If you're going to re-distribute the source,
  24     we require that you make it clear in the source that the code was
  25     descended from Apple Sample Code, but that you've made changes.
  26 */
  27
  28 #ifndef __MOREDESKTOPMGR__
  29 #define __MOREDESKTOPMGR__
  30
  31 #ifndef __MACTYPES__
  32 #include <MacTypes.h>
  33 #endif
  34
  35 #ifndef __FILES__
  36 #include <Files.h>
  37 #endif
  38
  39 #include "Optimization.h"
  40
  41
  42 #if PRAGMA_ONCE
  43 #pragma once
  44 #endif
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 #if PRAGMA_IMPORT
  51 #pragma import on
  52 #endif
  53
  54 #if PRAGMA_STRUCT_ALIGN
  55     #pragma options align=mac68k
  56 #elif PRAGMA_STRUCT_PACKPUSH
  57     #pragma pack(push, 2)
  58 #elif PRAGMA_STRUCT_PACK
  59     #pragma pack(2)
  60 #endif
  61
  62 /*****************************************************************************/
  63
  64 EXTERN_API( OSErr )
  65 DTOpen(
  66   ConstStr255Param   volName,
  67   short              vRefNum,
  68   short *            dtRefNum,
  69   Boolean *          newDTDatabase);
  70
  71
  72 /*
  73     The DTOpen function opens a volume's desktop database. It returns
  74     the reference number of the desktop database and indicates if the
  75     desktop database was created as a result of this call (if it was created,
  76     then it is empty).
  77
  78     volName         input:  A pointer to the name of a mounted volume
  79                             or nil.
  80     vRefNum         input:  Volume specification.
  81     dtRefNum        output: The reference number of Desktop Manager's
  82                             desktop database on the specified volume.
  83     newDTDatabase   output: true if the desktop database was created as a
  84                             result of this call and thus empty.
  85                             false if the desktop database was already created,
  86                             or if it could not be determined if it was already
  87                             created.
  88
  89     Result Codes
  90         noErr               0       No error
  91         nsvErr              -35     Volume not found
  92         ioErr               -36     I/O error
  93         paramErr            -50     Volume doesn't support this function
  94         extFSErr            -58     External file system error - no file
  95                                     system claimed this call.
  96         desktopDamagedErr   -1305   The desktop database has become corrupted -
  97                                     the Finder will fix this, but if your
  98                                     application is not running with the
  99                                     Finder, use PBDTReset or PBDTDelete
 100 */
 101
 102 /*****************************************************************************/
 103
 104 EXTERN_API( OSErr )
 105 DTXGetAPPL(
 106   ConstStr255Param   volName,
 107   short              vRefNum,
 108   OSType             creator,
 109   Boolean            searchCatalog,
 110   short *            applVRefNum,
 111   long *             applParID,
 112   Str255             applName);
 113
 114
 115 /*
 116     The DTXGetAPPL function finds an application (file type 'APPL') with
 117     the specified creator on the specified volume. It first tries to get
 118     the application mapping from the desktop database. If that fails,
 119     then it tries to find an application in the Desktop file. If that
 120     fails and searchCatalog is true, then it tries to find an application
 121     with the specified creator using the File Manager's CatSearch routine.
 122
 123     volName         input:  A pointer to the name of a mounted volume
 124                             or nil.
 125     vRefNum         input:  Volume specification.
 126     creator         input:  The file's creator type.
 127     searchCatalog   input:  If true, search the catalog for the application
 128                             if it isn't found in the desktop database.
 129     applVRefNum     output: The volume reference number of the volume the
 130                             application is on.
 131     applParID       output: The parent directory ID of the application.
 132     applName        output: The name of the application.
 133
 134     Result Codes
 135         noErr               0       No error
 136         nsvErr              -35     Volume not found
 137         ioErr               -36     I/O error
 138         paramErr            -50     No default volume
 139         rfNumErr            -51     Reference number invalid
 140         extFSErr            -58     External file system error - no file
 141                                     system claimed this call
 142         desktopDamagedErr   -1305   The desktop database has become corrupted -
 143                                     the Finder will fix this, but if your
 144                                     application is not running with the
 145                                     Finder, use PBDTReset or PBDTDelete
 146         afpItemNotFound     -5012   Information not found
 147
 148     __________
 149
 150     Also see:   FSpDTGetAPPL
 151 */
 152
 153 /*****************************************************************************/
 154
 155 EXTERN_API( OSErr )
 156 FSpDTXGetAPPL(
 157   ConstStr255Param   volName,
 158   short              vRefNum,
 159   OSType             creator,
 160   Boolean            searchCatalog,
 161   FSSpec *           spec);
 162
 163
 164 /*
 165     The FSpDTXGetAPPL function finds an application (file type 'APPL') with
 166     the specified creator on the specified volume. It first tries to get
 167     the application mapping from the desktop database. If that fails,
 168     then it tries to find an application in the Desktop file. If that
 169     fails and searchCatalog is true, then it tries to find an application
 170     with the specified creator using the File Manager's CatSearch routine.
 171
 172     volName         input:  A pointer to the name of a mounted volume
 173                             or nil.
 174     vRefNum         input:  Volume specification.
 175     creator         input:  The file's creator type.
 176     searchCatalog   input:  If true, search the catalog for the application
 177                             if it isn't found in the desktop database.
 178     spec            output: FSSpec record containing the application name and
 179                             location.
 180
 181     Result Codes
 182         noErr               0       No error
 183         nsvErr              -35     Volume not found
 184         ioErr               -36     I/O error
 185         paramErr            -50     No default volume
 186         rfNumErr            -51     Reference number invalid
 187         extFSErr            -58     External file system error - no file
 188                                     system claimed this call
 189         desktopDamagedErr   -1305   The desktop database has become corrupted -
 190                                     the Finder will fix this, but if your
 191                                     application is not running with the
 192                                     Finder, use PBDTReset or PBDTDelete
 193         afpItemNotFound     -5012   Information not found
 194
 195     __________
 196
 197     Also see:   FSpDTGetAPPL
 198 */
 199
 200 /*****************************************************************************/
 201
 202 EXTERN_API( OSErr )
 203 DTGetAPPL(
 204   ConstStr255Param   volName,
 205   short              vRefNum,
 206   OSType             creator,
 207   short *            applVRefNum,
 208   long *             applParID,
 209   Str255             applName);
 210
 211
 212 /*
 213     The DTGetAPPL function finds an application (file type 'APPL') with
 214     the specified creator on the specified volume. It first tries to get
 215     the application mapping from the desktop database. If that fails,
 216     then it tries to find an application in the Desktop file. If that
 217     fails, then it tries to find an application with the specified creator
 218     using the File Manager's CatSearch routine.
 219
 220     volName     input:  A pointer to the name of a mounted volume
 221                         or nil.
 222     vRefNum     input:  Volume specification.
 223     creator     input:  The file's creator type.
 224     applVRefNum output: The volume reference number of the volume the
 225                         application is on.
 226     applParID   output: The parent directory ID of the application.
 227     applName    output: The name of the application.
 228
 229     Result Codes
 230         noErr               0       No error
 231         nsvErr              -35     Volume not found
 232         ioErr               -36     I/O error
 233         paramErr            -50     No default volume
 234         rfNumErr            -51     Reference number invalid
 235         extFSErr            -58     External file system error - no file
 236                                     system claimed this call
 237         desktopDamagedErr   -1305   The desktop database has become corrupted -
 238                                     the Finder will fix this, but if your
 239                                     application is not running with the
 240                                     Finder, use PBDTReset or PBDTDelete
 241         afpItemNotFound     -5012   Information not found
 242
 243     __________
 244
 245     Also see:   FSpDTGetAPPL
 246 */
 247
 248 /*****************************************************************************/
 249
 250 EXTERN_API( OSErr )
 251 FSpDTGetAPPL(
 252   ConstStr255Param   volName,
 253   short              vRefNum,
 254   OSType             creator,
 255   FSSpec *           spec);
 256
 257
 258 /*
 259     The FSpDTGetAPPL function finds an application (file type 'APPL') with
 260     the specified creator on the specified volume. It first tries to get
 261     the application mapping from the desktop database. If that fails,
 262     then it tries to find an application in the Desktop file. If that
 263     fails, then it tries to find an application with the specified creator
 264     using the File Manager's CatSearch routine.
 265
 266     volName     input:  A pointer to the name of a mounted volume
 267                         or nil.
 268     vRefNum     input:  Volume specification.
 269     creator     input:  The file's creator type.
 270     spec        output: FSSpec record containing the application name and
 271                         location.
 272
 273     Result Codes
 274         noErr               0       No error
 275         nsvErr              -35     Volume not found
 276         ioErr               -36     I/O error
 277         paramErr            -50     No default volume
 278         rfNumErr            -51     Reference number invalid
 279         extFSErr            -58     External file system error - no file
 280                                     system claimed this call
 281         desktopDamagedErr   -1305   The desktop database has become corrupted -
 282                                     the Finder will fix this, but if your
 283                                     application is not running with the
 284                                     Finder, use PBDTReset or PBDTDelete
 285         afpItemNotFound     -5012   Information not found
 286
 287     __________
 288
 289     Also see:   DTGetAPPL
 290 */
 291
 292 /*****************************************************************************/
 293
 294 EXTERN_API( OSErr )
 295 DTGetIcon(
 296   ConstStr255Param   volName,
 297   short              vRefNum,
 298   short              iconType,
 299   OSType             fileCreator,
 300   OSType             fileType,
 301   Handle *           iconHandle);
 302
 303
 304 /*
 305     The DTGetIcon function retrieves the specified icon and returns it in
 306     a newly created handle. The icon is retrieves from the Desktop Manager
 307     or if the Desktop Manager is not available, from the Finder's Desktop
 308     file. Your program is responsible for disposing of the handle when it is
 309     done using the icon.
 310
 311     volName     input:  A pointer to the name of a mounted volume
 312                         or nil.
 313     vRefNum     input:  Volume specification.
 314     iconType    input:  The icon type as defined in Files.h. Valid values are:
 315                             kLargeIcon
 316                             kLarge4BitIcon
 317                             kLarge8BitIcon
 318                             kSmallIcon
 319                             kSmall4BitIcon
 320                             kSmall8BitIcon
 321     fileCreator input:  The icon's creator type.
 322     fileType    input:  The icon's file type.
 323     iconHandle  output: A Handle containing the newly created icon.
 324
 325     Result Codes
 326         noErr               0       No error
 327         nsvErr              -35     Volume not found
 328         ioErr               -36     I/O error
 329         paramErr            -50     Volume doesn't support this function
 330         rfNumErr            -51     Reference number invalid
 331         extFSErr            -58     External file system error - no file
 332                                     system claimed this call
 333         memFullErr          -108    iconHandle could not be allocated
 334         desktopDamagedErr   -1305   The desktop database has become corrupted -
 335                                     the Finder will fix this, but if your
 336                                     application is not running with the
 337                                     Finder, use PBDTReset or PBDTDelete
 338         afpItemNotFound     -5012   Information not found
 339 */
 340
 341 /*****************************************************************************/
 342
 343 EXTERN_API( OSErr )
 344 DTSetComment(
 345   short              vRefNum,
 346   long               dirID,
 347   ConstStr255Param   name,
 348   ConstStr255Param   comment);
 349
 350
 351 /*
 352     The DTSetComment function sets a file or directory's Finder comment
 353     field. The volume must support the Desktop Manager because you only
 354     have read access to the Desktop file.
 355
 356     vRefNum input:  Volume specification.
 357     dirID   input:  Directory ID.
 358     name    input:  Pointer to object name, or nil when dirID
 359                     specifies a directory that's the object.
 360     comment input:  The comment to add. Comments are limited to 200 characters;
 361                     longer comments are truncated.
 362
 363     Result Codes
 364         noErr               0       No error
 365         nsvErr              -35     Volume not found
 366         ioErr               -36     I/O error
 367         fnfErr              Ð43     File or directory doesnÕt exist
 368         paramErr            -50     Volume doesn't support this function
 369         wPrErr              Ð44     Volume is locked through hardware
 370         vLckdErr            Ð46     Volume is locked through software
 371         rfNumErr            Ð51     Reference number invalid
 372         extFSErr            -58     External file system error - no file
 373                                     system claimed this call.
 374         desktopDamagedErr   -1305   The desktop database has become corrupted -
 375                                     the Finder will fix this, but if your
 376                                     application is not running with the
 377                                     Finder, use PBDTReset or PBDTDelete
 378
 379     __________
 380
 381     Also see:   DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
 382                 FSpDTGetComment
 383 */
 384
 385 /*****************************************************************************/
 386
 387 EXTERN_API( OSErr )
 388 FSpDTSetComment(
 389   const FSSpec *     spec,
 390   ConstStr255Param   comment);
 391
 392
 393 /*
 394     The FSpDTSetComment function sets a file or directory's Finder comment
 395     field. The volume must support the Desktop Manager because you only
 396     have read access to the Desktop file.
 397
 398     spec    input:  An FSSpec record specifying the file or directory.
 399     comment input:  The comment to add. Comments are limited to 200 characters;
 400                     longer comments are truncated.
 401
 402     Result Codes
 403         noErr               0       No error
 404         nsvErr              -35     Volume not found
 405         ioErr               -36     I/O error
 406         fnfErr              Ð43     File or directory doesnÕt exist
 407         wPrErr              Ð44     Volume is locked through hardware
 408         vLckdErr            Ð46     Volume is locked through software
 409         rfNumErr            Ð51     Reference number invalid
 410         paramErr            -50     Volume doesn't support this function
 411         extFSErr            -58     External file system error - no file
 412                                     system claimed this call.
 413         desktopDamagedErr   -1305   The desktop database has become corrupted -
 414                                     the Finder will fix this, but if your
 415                                     application is not running with the
 416                                     Finder, use PBDTReset or PBDTDelete
 417
 418     __________
 419
 420     Also see:   DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
 421                 FSpDTGetComment
 422 */
 423
 424 /*****************************************************************************/
 425
 426 EXTERN_API( OSErr )
 427 DTGetComment(
 428   short              vRefNum,
 429   long               dirID,
 430   ConstStr255Param   name,
 431   Str255             comment);
 432
 433
 434 /*
 435     The DTGetComment function gets a file or directory's Finder comment
 436     field (if any) from the Desktop Manager or if the Desktop Manager is
 437     not available, from the Finder's Desktop file.
 438
 439     IMPORTANT NOTE: Inside Macintosh says that comments are up to
 440     200 characters. While that may be correct for the HFS file system's
 441     Desktop Manager, other file systems (such as Apple Photo Access) return
 442     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
 443     regret it.
 444
 445     vRefNum input:  Volume specification.
 446     dirID   input:  Directory ID.
 447     name    input:  Pointer to object name, or nil when dirID
 448                     specifies a directory that's the object.
 449     comment output: A Str255 where the comment is to be returned.
 450
 451     Result Codes
 452         noErr               0       No error
 453         nsvErr              -35     Volume not found
 454         ioErr               -36     I/O error
 455         fnfErr              -43     File not found
 456         paramErr            -50     Volume doesn't support this function
 457         rfNumErr            Ð51     Reference number invalid
 458         extFSErr            -58     External file system error - no file
 459                                     system claimed this call.
 460         desktopDamagedErr   -1305   The desktop database has become corrupted -
 461                                     the Finder will fix this, but if your
 462                                     application is not running with the
 463                                     Finder, use PBDTReset or PBDTDelete
 464         afpItemNotFound     -5012   Information not found
 465
 466     __________
 467
 468     Also see:   DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
 469                 FSpDTGetComment
 470 */
 471
 472 /*****************************************************************************/
 473
 474 EXTERN_API( OSErr )
 475 FSpDTGetComment(
 476   const FSSpec *  spec,
 477   Str255          comment);
 478
 479
 480 /*
 481     The FSpDTGetComment function gets a file or directory's Finder comment
 482     field (if any) from the Desktop Manager or if the Desktop Manager is
 483     not available, from the Finder's Desktop file.
 484
 485     IMPORTANT NOTE: Inside Macintosh says that comments are up to
 486     200 characters. While that may be correct for the HFS file system's
 487     Desktop Manager, other file systems (such as Apple Photo Access) return
 488     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
 489     regret it.
 490
 491     spec    input:  An FSSpec record specifying the file or directory.
 492     comment output: A Str255 where the comment is to be returned.
 493
 494     Result Codes
 495         noErr               0       No error
 496         nsvErr              -35     Volume not found
 497         ioErr               -36     I/O error
 498         fnfErr              -43     File not found
 499         paramErr            -50     Volume doesn't support this function
 500         rfNumErr            Ð51     Reference number invalid
 501         extFSErr            -58     External file system error - no file
 502                                     system claimed this call.
 503         desktopDamagedErr   -1305   The desktop database has become corrupted -
 504                                     the Finder will fix this, but if your
 505                                     application is not running with the
 506                                     Finder, use PBDTReset or PBDTDelete
 507         afpItemNotFound     -5012   Information not found
 508
 509     __________
 510
 511     Also see:   DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
 512                 DTGetComment
 513 */
 514
 515 /*****************************************************************************/
 516
 517 EXTERN_API( OSErr )
 518 DTCopyComment(
 519   short              srcVRefNum,
 520   long               srcDirID,
 521   ConstStr255Param   srcName,
 522   short              dstVRefNum,
 523   long               dstDirID,
 524   ConstStr255Param   dstName);
 525
 526
 527 /*
 528     The DTCopyComment function copies the file or folder comment from the
 529     source to the destination object.  The destination volume must support
 530     the Desktop Manager because you only have read access to the Desktop file.
 531
 532     srcVRefNum  input:  Source volume specification.
 533     srcDirID    input:  Source directory ID.
 534     srcName     input:  Pointer to source object name, or nil when srcDirID
 535                         specifies a directory that's the object.
 536     dstVRefNum  input:  Destination volume specification.
 537     dstDirID    input:  Destination directory ID.
 538     dstName     input:  Pointer to destination object name, or nil when
 539                         dstDirID specifies a directory that's the object.
 540
 541     Result Codes
 542         noErr               0       No error
 543         nsvErr              -35     Volume not found
 544         ioErr               -36     I/O error
 545         fnfErr              Ð43     File or directory doesnÕt exist
 546         wPrErr              Ð44     Volume is locked through hardware
 547         vLckdErr            Ð46     Volume is locked through software
 548         paramErr            -50     Volume doesn't support this function
 549         rfNumErr            Ð51     Reference number invalid
 550         paramErr            -50     Volume doesn't support this function
 551         extFSErr            -58     External file system error - no file
 552                                     system claimed this call.
 553         desktopDamagedErr   -1305   The desktop database has become corrupted -
 554                                     the Finder will fix this, but if your
 555                                     application is not running with the
 556                                     Finder, use PBDTReset or PBDTDelete
 557         afpItemNotFound     -5012   Information not found
 558
 559     __________
 560
 561     Also see:   FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
 562                 FSpDTGetComment
 563 */
 564
 565 /*****************************************************************************/
 566
 567 EXTERN_API( OSErr )
 568 FSpDTCopyComment(
 569   const FSSpec *  srcSpec,
 570   const FSSpec *  dstSpec);
 571
 572
 573 /*
 574     The FSpDTCopyComment function copies the desktop database comment from
 575     the source to the destination object.  Both the source and the
 576     destination volumes must support the Desktop Manager.
 577
 578     srcSpec     input:  An FSSpec record specifying the source object.
 579     dstSpec     input:  An FSSpec record specifying the destination object.
 580
 581     Result Codes
 582         noErr               0       No error
 583         nsvErr              -35     Volume not found
 584         ioErr               -36     I/O error
 585         fnfErr              Ð43     File or directory doesnÕt exist
 586         wPrErr              Ð44     Volume is locked through hardware
 587         vLckdErr            Ð46     Volume is locked through software
 588         paramErr            -50     Volume doesn't support this function
 589         rfNumErr            Ð51     Reference number invalid
 590         paramErr            -50     Volume doesn't support this function
 591         extFSErr            -58     External file system error - no file
 592                                     system claimed this call.
 593         desktopDamagedErr   -1305   The desktop database has become corrupted -
 594                                     the Finder will fix this, but if your
 595                                     application is not running with the
 596                                     Finder, use PBDTReset or PBDTDelete
 597         afpItemNotFound     -5012   Information not found
 598
 599     __________
 600
 601     Also see:   DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
 602                 FSpDTGetComment
 603 */
 604
 605 /*****************************************************************************/
 606
 607 #include "OptimizationEnd.h"
 608
 609 #if PRAGMA_STRUCT_ALIGN
 610     #pragma options align=reset
 611 #elif PRAGMA_STRUCT_PACKPUSH
 612     #pragma pack(pop)
 613 #elif PRAGMA_STRUCT_PACK
 614     #pragma pack()
 615 #endif
 616
 617 #ifdef PRAGMA_IMPORT_OFF
 618 #pragma import off
 619 #elif PRAGMA_IMPORT
 620 #pragma import reset
 621 #endif
 622
 623 #ifdef __cplusplus
 624 }
 625 #endif
 626
 627 #endif /* __MOREDESKTOPMGR__ */
 628