src/mac/morefile/MoreDesk.h

   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-1998 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 #include "optim.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /*****************************************************************************/
  39
  40 pascal  OSErr   DTOpen(ConstStr255Param volName,
  41                                            short vRefNum,
  42                                            short *dtRefNum,
  43                                            Boolean *newDTDatabase);
  44 /*      ¦ Open a volume's desktop database and return the desktop database refNum.
  45         The DTOpen function opens a volume's desktop database. It returns
  46         the reference number of the desktop database and indicates if the
  47         desktop database was created as a result of this call (if it was created,
  48         then it is empty).
  49
  50         volName                 input:  A pointer to the name of a mounted volume
  51                                                         or nil.
  52         vRefNum                 input:  Volume specification.
  53         dtRefNum                output: The reference number of Desktop Manager's
  54                                                         desktop database on the specified volume.
  55         newDTDatabase   output: true if the desktop database was created as a
  56                                                         result of this call and thus empty.
  57                                                         false if the desktop database was already created,
  58                                                         or if it could not be determined if it was already
  59                                                         created.
  60
  61         Result Codes
  62                 noErr                           0               No error
  63                 nsvErr                          -35             Volume not found
  64                 ioErr                           -36             I/O error
  65                 paramErr                        -50             Volume doesn't support this function
  66                 extFSErr                        -58             External file system error - no file
  67                                                                         system claimed this call.
  68                 desktopDamagedErr       -1305   The desktop database has become corrupted -
  69                                                                         the Finder will fix this, but if your
  70                                                                         application is not running with the
  71                                                                         Finder, use PBDTReset or PBDTDelete
  72 */
  73
  74 /*****************************************************************************/
  75
  76 pascal  OSErr   DTXGetAPPL(ConstStr255Param volName,
  77                                                    short vRefNum,
  78                                                    OSType creator,
  79                                                    Boolean searchCatalog,
  80                                                    short *applVRefNum,
  81                                                    long *applParID,
  82                                                    Str255 applName);
  83 /*      ¦ Find an application on a volume that can open a file with a given creator.
  84         The DTXGetAPPL function finds an application (file type 'APPL') with
  85         the specified creator on the specified volume. It first tries to get
  86         the application mapping from the desktop database. If that fails,
  87         then it tries to find an application in the Desktop file. If that
  88         fails and searchCatalog is true, then it tries to find an application
  89         with the specified creator using the File Manager's CatSearch routine.
  90
  91         volName                 input:  A pointer to the name of a mounted volume
  92                                                         or nil.
  93         vRefNum                 input:  Volume specification.
  94         creator                 input:  The file's creator type.
  95         searchCatalog   input:  If true, search the catalog for the application
  96                                                         if it isn't found in the desktop database.
  97         applVRefNum             output: The volume reference number of the volume the
  98                                                         application is on.
  99         applParID               output: The parent directory ID of the application.
 100         applName                output: The name of the application.
 101
 102         Result Codes
 103                 noErr                           0               No error
 104                 nsvErr                          -35             Volume not found
 105                 ioErr                           -36             I/O error
 106                 paramErr                        -50             No default volume
 107                 rfNumErr                        -51             Reference number invalid
 108                 extFSErr                        -58             External file system error - no file
 109                                                                         system claimed this call
 110                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 111                                                                         the Finder will fix this, but if your
 112                                                                         application is not running with the
 113                                                                         Finder, use PBDTReset or PBDTDelete
 114                 afpItemNotFound         -5012   Information not found
 115
 116         __________
 117
 118         Also see:       FSpDTGetAPPL
 119 */
 120
 121 /*****************************************************************************/
 122
 123 pascal  OSErr   FSpDTXGetAPPL(ConstStr255Param volName,
 124                                                           short vRefNum,
 125                                                           OSType creator,
 126                                                           Boolean searchCatalog,
 127                                                           FSSpec *spec);
 128 /*      ¦ Find an application on a volume that can open a file with a given creator.
 129         The FSpDTXGetAPPL function finds an application (file type 'APPL') with
 130         the specified creator on the specified volume. It first tries to get
 131         the application mapping from the desktop database. If that fails,
 132         then it tries to find an application in the Desktop file. If that
 133         fails and searchCatalog is true, then it tries to find an application
 134         with the specified creator using the File Manager's CatSearch routine.
 135
 136         volName                 input:  A pointer to the name of a mounted volume
 137                                                         or nil.
 138         vRefNum                 input:  Volume specification.
 139         creator                 input:  The file's creator type.
 140         searchCatalog   input:  If true, search the catalog for the application
 141                                                         if it isn't found in the desktop database.
 142         spec                    output: FSSpec record containing the application name and
 143                                                         location.
 144
 145         Result Codes
 146                 noErr                           0               No error
 147                 nsvErr                          -35             Volume not found
 148                 ioErr                           -36             I/O error
 149                 paramErr                        -50             No default volume
 150                 rfNumErr                        -51             Reference number invalid
 151                 extFSErr                        -58             External file system error - no file
 152                                                                         system claimed this call
 153                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 154                                                                         the Finder will fix this, but if your
 155                                                                         application is not running with the
 156                                                                         Finder, use PBDTReset or PBDTDelete
 157                 afpItemNotFound         -5012   Information not found
 158
 159         __________
 160
 161         Also see:       FSpDTGetAPPL
 162 */
 163
 164 /*****************************************************************************/
 165
 166 pascal  OSErr   DTGetAPPL(ConstStr255Param volName,
 167                                                   short vRefNum,
 168                                                   OSType creator,
 169                                                   short *applVRefNum,
 170                                                   long *applParID,
 171                                                   Str255 applName);
 172 /*      ¦ Find an application on a volume that can open a file with a given creator.
 173         The DTGetAPPL function finds an application (file type 'APPL') with
 174         the specified creator on the specified volume. It first tries to get
 175         the application mapping from the desktop database. If that fails,
 176         then it tries to find an application in the Desktop file. If that
 177         fails, then it tries to find an application with the specified creator
 178         using the File Manager's CatSearch routine.
 179
 180         volName         input:  A pointer to the name of a mounted volume
 181                                                 or nil.
 182         vRefNum         input:  Volume specification.
 183         creator         input:  The file's creator type.
 184         applVRefNum     output: The volume reference number of the volume the
 185                                                 application is on.
 186         applParID       output: The parent directory ID of the application.
 187         applName        output: The name of the application.
 188
 189         Result Codes
 190                 noErr                           0               No error
 191                 nsvErr                          -35             Volume not found
 192                 ioErr                           -36             I/O error
 193                 paramErr                        -50             No default volume
 194                 rfNumErr                        -51             Reference number invalid
 195                 extFSErr                        -58             External file system error - no file
 196                                                                         system claimed this call
 197                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 198                                                                         the Finder will fix this, but if your
 199                                                                         application is not running with the
 200                                                                         Finder, use PBDTReset or PBDTDelete
 201                 afpItemNotFound         -5012   Information not found
 202
 203         __________
 204
 205         Also see:       FSpDTGetAPPL
 206 */
 207
 208 /*****************************************************************************/
 209
 210 pascal  OSErr   FSpDTGetAPPL(ConstStr255Param volName,
 211                                                          short vRefNum,
 212                                                          OSType creator,
 213                                                          FSSpec *spec);
 214 /*      ¦ Find an application on a volume that can open a file with a given creator.
 215         The FSpDTGetAPPL function finds an application (file type 'APPL') with
 216         the specified creator on the specified volume. It first tries to get
 217         the application mapping from the desktop database. If that fails,
 218         then it tries to find an application in the Desktop file. If that
 219         fails, then it tries to find an application with the specified creator
 220         using the File Manager's CatSearch routine.
 221
 222         volName         input:  A pointer to the name of a mounted volume
 223                                                 or nil.
 224         vRefNum         input:  Volume specification.
 225         creator         input:  The file's creator type.
 226         spec            output: FSSpec record containing the application name and
 227                                                 location.
 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:       DTGetAPPL
 246 */
 247
 248 /*****************************************************************************/
 249
 250 pascal  OSErr   DTGetIcon(ConstStr255Param volName,
 251                                                   short vRefNum,
 252                                                   short iconType,
 253                                                   OSType fileCreator,
 254                                                   OSType fileType,
 255                                                   Handle *iconHandle);
 256 /*      ¦ Get an icon from the desktop database or Desktop file.
 257         The DTGetIcon function retrieves the specified icon and returns it in
 258         a newly created handle. The icon is retrieves from the Desktop Manager
 259         or if the Desktop Manager is not available, from the Finder's Desktop
 260         file. Your program is responsible for disposing of the handle when it is
 261         done using the icon.
 262
 263         volName         input:  A pointer to the name of a mounted volume
 264                                                 or nil.
 265         vRefNum         input:  Volume specification.
 266         iconType        input:  The icon type as defined in Files.h. Valid values are:
 267                                                         kLargeIcon
 268                                                         kLarge4BitIcon
 269                                                         kLarge8BitIcon
 270                                                         kSmallIcon
 271                                                         kSmall4BitIcon
 272                                                         kSmall8BitIcon
 273         fileCreator     input:  The icon's creator type.
 274         fileType        input:  The icon's file type.
 275         iconHandle      output: A Handle containing the newly created icon.
 276
 277         Result Codes
 278                 noErr                           0               No error
 279                 nsvErr                          -35             Volume not found
 280                 ioErr                           -36             I/O error
 281                 paramErr                        -50             Volume doesn't support this function
 282                 rfNumErr                        -51             Reference number invalid
 283                 extFSErr                        -58             External file system error - no file
 284                                                                         system claimed this call
 285                 memFullErr                      -108    iconHandle could not be allocated
 286                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 287                                                                         the Finder will fix this, but if your
 288                                                                         application is not running with the
 289                                                                         Finder, use PBDTReset or PBDTDelete
 290                 afpItemNotFound         -5012   Information not found
 291 */
 292
 293 /*****************************************************************************/
 294
 295 pascal  OSErr   DTSetComment(short vRefNum,
 296                                                          long dirID,
 297                                                          ConstStr255Param name,
 298                                                          ConstStr255Param comment);
 299 /*      ¦ Set a file or directory's Finder comment field.
 300         The DTSetComment function sets a file or directory's Finder comment
 301         field. The volume must support the Desktop Manager because you only
 302         have read access to the Desktop file.
 303
 304         vRefNum input:  Volume specification.
 305         dirID   input:  Directory ID.
 306         name    input:  Pointer to object name, or nil when dirID
 307                                         specifies a directory that's the object.
 308         comment input:  The comment to add. Comments are limited to 200 characters;
 309                                         longer comments are truncated.
 310
 311         Result Codes
 312                 noErr                           0               No error
 313                 nsvErr                          -35             Volume not found
 314                 ioErr                           -36             I/O error
 315                 fnfErr                          Ð43            File or directory doesnÕt exist
 316                 paramErr                        -50             Volume doesn't support this function
 317                 wPrErr                          Ð44            Volume is locked through hardware
 318                 vLckdErr                        Ð46            Volume is locked through software
 319                 rfNumErr                        Ð51            Reference number invalid
 320                 extFSErr                        -58             External file system error - no file
 321                                                                         system claimed this call.
 322                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 323                                                                         the Finder will fix this, but if your
 324                                                                         application is not running with the
 325                                                                         Finder, use PBDTReset or PBDTDelete
 326
 327         __________
 328
 329         Also see:       DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
 330                                 FSpDTGetComment
 331 */
 332
 333 /*****************************************************************************/
 334
 335 pascal  OSErr   FSpDTSetComment(const FSSpec *spec,
 336                                                                 ConstStr255Param comment);
 337 /*      ¦ Set a file or directory's Finder comment field.
 338         The FSpDTSetComment function sets a file or directory's Finder comment
 339         field. The volume must support the Desktop Manager because you only
 340         have read access to the Desktop file.
 341
 342         spec    input:  An FSSpec record specifying the file or directory.
 343         comment input:  The comment to add. Comments are limited to 200 characters;
 344                                         longer comments are truncated.
 345
 346         Result Codes
 347                 noErr                           0               No error
 348                 nsvErr                          -35             Volume not found
 349                 ioErr                           -36             I/O error
 350                 fnfErr                          Ð43            File or directory doesnÕt exist
 351                 wPrErr                          Ð44            Volume is locked through hardware
 352                 vLckdErr                        Ð46            Volume is locked through software
 353                 rfNumErr                        Ð51            Reference number invalid
 354                 paramErr                        -50             Volume doesn't support this function
 355                 extFSErr                        -58             External file system error - no file
 356                                                                         system claimed this call.
 357                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 358                                                                         the Finder will fix this, but if your
 359                                                                         application is not running with the
 360                                                                         Finder, use PBDTReset or PBDTDelete
 361
 362         __________
 363
 364         Also see:       DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
 365                                 FSpDTGetComment
 366 */
 367
 368 /*****************************************************************************/
 369
 370 pascal  OSErr   DTGetComment(short vRefNum,
 371                                                          long dirID,
 372                                                          ConstStr255Param name,
 373                                                          Str255 comment);
 374 /*      ¦ Get a file or directory's Finder comment field (if any).
 375         The DTGetComment function gets a file or directory's Finder comment
 376         field (if any) from the Desktop Manager or if the Desktop Manager is
 377         not available, from the Finder's Desktop file.
 378
 379         IMPORTANT NOTE: Inside Macintosh says that comments are up to
 380         200 characters. While that may be correct for the HFS file system's
 381         Desktop Manager, other file systems (such as Apple Photo Access) return
 382         up to 255 characters. Make sure the comment buffer is a Str255 or you'll
 383         regret it.
 384
 385         vRefNum input:  Volume specification.
 386         dirID   input:  Directory ID.
 387         name    input:  Pointer to object name, or nil when dirID
 388                                         specifies a directory that's the object.
 389         comment output: A Str255 where the comment is to be returned.
 390
 391         Result Codes
 392                 noErr                           0               No error
 393                 nsvErr                          -35             Volume not found
 394                 ioErr                           -36             I/O error
 395                 fnfErr                          -43             File not found
 396                 paramErr                        -50             Volume doesn't support this function
 397                 rfNumErr                        Ð51            Reference number invalid
 398                 extFSErr                        -58             External file system error - no file
 399                                                                         system claimed this call.
 400                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 401                                                                         the Finder will fix this, but if your
 402                                                                         application is not running with the
 403                                                                         Finder, use PBDTReset or PBDTDelete
 404                 afpItemNotFound         -5012   Information not found
 405
 406         __________
 407
 408         Also see:       DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
 409                                 FSpDTGetComment
 410 */
 411
 412 /*****************************************************************************/
 413
 414 pascal  OSErr   FSpDTGetComment(const FSSpec *spec,
 415                                                                 Str255 comment);
 416 /*      ¦ Get a file or directory's Finder comment field (if any).
 417         The FSpDTGetComment function gets a file or directory's Finder comment
 418         field (if any) from the Desktop Manager or if the Desktop Manager is
 419         not available, from the Finder's Desktop file.
 420
 421         IMPORTANT NOTE: Inside Macintosh says that comments are up to
 422         200 characters. While that may be correct for the HFS file system's
 423         Desktop Manager, other file systems (such as Apple Photo Access) return
 424         up to 255 characters. Make sure the comment buffer is a Str255 or you'll
 425         regret it.
 426
 427         spec    input:  An FSSpec record specifying the file or directory.
 428         comment output: A Str255 where the comment is to be returned.
 429
 430         Result Codes
 431                 noErr                           0               No error
 432                 nsvErr                          -35             Volume not found
 433                 ioErr                           -36             I/O error
 434                 fnfErr                          -43             File not found
 435                 paramErr                        -50             Volume doesn't support this function
 436                 rfNumErr                        Ð51            Reference number invalid
 437                 extFSErr                        -58             External file system error - no file
 438                                                                         system claimed this call.
 439                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 440                                                                         the Finder will fix this, but if your
 441                                                                         application is not running with the
 442                                                                         Finder, use PBDTReset or PBDTDelete
 443                 afpItemNotFound         -5012   Information not found
 444
 445         __________
 446
 447         Also see:       DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
 448                                 DTGetComment
 449 */
 450
 451 /*****************************************************************************/
 452
 453 pascal  OSErr   DTCopyComment(short srcVRefNum,
 454                                                           long srcDirID,
 455                                                           ConstStr255Param srcName,
 456                                                           short dstVRefNum,
 457                                                           long dstDirID,
 458                                                           ConstStr255Param dstName);
 459 /*      ¦ Copy the file or folder comment from the source to the destination object.
 460         The DTCopyComment function copies the file or folder comment from the
 461         source to the destination object.  The destination volume must support
 462         the Desktop Manager because you only have read access to the Desktop file.
 463
 464         srcVRefNum      input:  Source volume specification.
 465         srcDirID        input:  Source directory ID.
 466         srcName         input:  Pointer to source object name, or nil when srcDirID
 467                                                 specifies a directory that's the object.
 468         dstVRefNum      input:  Destination volume specification.
 469         dstDirID        input:  Destination directory ID.
 470         dstName         input:  Pointer to destination object name, or nil when
 471                                                 dstDirID specifies a directory that's the object.
 472
 473         Result Codes
 474                 noErr                           0               No error
 475                 nsvErr                          -35             Volume not found
 476                 ioErr                           -36             I/O error
 477                 fnfErr                          Ð43            File or directory doesnÕt exist
 478                 wPrErr                          Ð44            Volume is locked through hardware
 479                 vLckdErr                        Ð46            Volume is locked through software
 480                 paramErr                        -50             Volume doesn't support this function
 481                 rfNumErr                        Ð51            Reference number invalid
 482                 paramErr                        -50             Volume doesn't support this function
 483                 extFSErr                        -58             External file system error - no file
 484                                                                         system claimed this call.
 485                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 486                                                                         the Finder will fix this, but if your
 487                                                                         application is not running with the
 488                                                                         Finder, use PBDTReset or PBDTDelete
 489                 afpItemNotFound         -5012   Information not found
 490
 491         __________
 492
 493         Also see:       FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
 494                                 FSpDTGetComment
 495 */
 496
 497 /*****************************************************************************/
 498
 499 pascal  OSErr   FSpDTCopyComment(const FSSpec *srcSpec,
 500                                                                  const FSSpec *dstSpec);
 501 /*      ¦ Copy the desktop database comment from the source to the destination object.
 502         The FSpDTCopyComment function copies the desktop database comment from
 503         the source to the destination object.  Both the source and the
 504         destination volumes must support the Desktop Manager.
 505
 506         srcSpec         input:  An FSSpec record specifying the source object.
 507         dstSpec         input:  An FSSpec record specifying the destination object.
 508
 509         Result Codes
 510                 noErr                           0               No error
 511                 nsvErr                          -35             Volume not found
 512                 ioErr                           -36             I/O error
 513                 fnfErr                          Ð43            File or directory doesnÕt exist
 514                 wPrErr                          Ð44            Volume is locked through hardware
 515                 vLckdErr                        Ð46            Volume is locked through software
 516                 paramErr                        -50             Volume doesn't support this function
 517                 rfNumErr                        Ð51            Reference number invalid
 518                 paramErr                        -50             Volume doesn't support this function
 519                 extFSErr                        -58             External file system error - no file
 520                                                                         system claimed this call.
 521                 desktopDamagedErr       -1305   The desktop database has become corrupted -
 522                                                                         the Finder will fix this, but if your
 523                                                                         application is not running with the
 524                                                                         Finder, use PBDTReset or PBDTDelete
 525                 afpItemNotFound         -5012   Information not found
 526
 527         __________
 528
 529         Also see:       DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
 530                                 FSpDTGetComment
 531 */
 532
 533 /*****************************************************************************/
 534
 535 #ifdef __cplusplus
 536 }
 537 #endif
 538
 539 #include "optimend.h"
 540
 541 #endif  /* __MOREDESKTOPMGR__ */