]> git.saurik.com Git - wxWidgets.git/blob - src/mac/morefile/MoreDesk.h
projects / wxWidgets.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
added carbonaccessors.o
[wxWidgets.git] / 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__ */
wxWidgets (Impactor)