]> git.saurik.com Git - wxWidgets.git/blob - src/mac/morefile/MoreDesktopMgr.h
classic fixes
[wxWidgets.git] / src / mac / 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