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 47extern "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 64EXTERN_API( OSErr ) 65DTOpen( 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 104EXTERN_API( OSErr ) 105DTXGetAPPL( 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 155EXTERN_API( OSErr ) 156FSpDTXGetAPPL( 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 202EXTERN_API( OSErr ) 203DTGetAPPL( 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 250EXTERN_API( OSErr ) 251FSpDTGetAPPL( 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 294EXTERN_API( OSErr ) 295DTGetIcon( 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 343EXTERN_API( OSErr ) 344DTSetComment( 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 387EXTERN_API( OSErr ) 388FSpDTSetComment( 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 426EXTERN_API( OSErr ) 427DTGetComment( 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 474EXTERN_API( OSErr ) 475FSpDTGetComment( 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 517EXTERN_API( OSErr ) 518DTCopyComment( 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 567EXTERN_API( OSErr ) 568FSpDTCopyComment( 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 629