|
NCBI Home IEB Home C Toolkit docs C++ Toolkit source browser C Toolkit source browser (2) |
NCBI C Toolkit Cross ReferenceC/corelib/morefile/MoreFilesX.h |
source navigation diff markup identifier search freetext search file search |
1 /*
2 File: MoreFilesX.h
3
4 Contains: A collection of useful high-level File Manager routines
5 which use the HFS Plus APIs wherever possible.
6
7 Version: MoreFilesX 1.0
8
9 Copyright: © 1992-2002 by Apple Computer, Inc., all rights reserved.
10
11 You may incorporate this sample code into your applications without
12 restriction, though the sample code has been provided "AS IS" and the
13 responsibility for its operation is 100% yours. However, what you are
14 not permitted to do is to redistribute the source as "DSC Sample Code"
15 after having made changes. If you're going to re-distribute the source,
16 we require that you make it clear in the source that the code was
17 descended from Apple Sample Code, but that you've made changes.
18
19 File Ownership:
20
21 DRI: Apple Macintosh Developer Technical Support
22
23 Other Contact: For bug reports, consult the following page on
24 the World Wide Web:
25 http://developer.apple.com/bugreporter/
26
27 Technology: DTS Sample Code
28
29 Writers:
30
31 (JL) Jim Luther
32
33 Change History (most recent first):
34
35 <1> 1/25/02 JL MoreFilesX 1.0
36
37 Notes:
38 What do those arrows in the documentation for each routine mean?
39
40 --> The parameter is an input
41
42 <-- The parameter is an output. The pointer to the variable
43 where the output will be returned (must not be NULL).
44
45 <** The parameter is an optional output. If it is not a
46 NULL pointer, it points to the variable where the output
47 will be returned. If it is a NULL pointer, the output will
48 not be returned and will possibly let the routine and the
49 File Manager do less work. If you don't need an optional output,
50 don't ask for it.
51 **> The parameter is an optional input. If it is not a
52 NULL pointer, it points to the variable containing the
53 input data. If it is a NULL pointer, the input is not used
54 and will possibly let the routine and the File Manager
55 do less work.
56 */
57
58 #ifndef __MOREFILESX__
59 #define __MOREFILESX__
60
61 #ifndef __MACTYPES__
62 #include <MacTypes.h>
63 #endif
64
65 #ifndef __FINDER__
66 #include <Finder.h>
67 #endif
68
69 #ifndef __FILES__
70 #include <Files.h>
71 #endif
72
73 #ifndef __TEXTCOMMON__
74 #include <TextCommon.h>
75 #endif
76
77 #if PRAGMA_ONCE
78 #pragma once
79 #endif
80
81 #ifdef __cplusplus
82 extern "C" {
83 #endif
84
85 #if PRAGMA_IMPORT
86 #pragma import on
87 #endif
88
89 #if PRAGMA_STRUCT_ALIGN
90 #pragma options align=mac68k
91 #elif PRAGMA_STRUCT_PACKPUSH
92 #pragma pack(push, 2)
93 #elif PRAGMA_STRUCT_PACK
94 #pragma pack(2)
95 #endif
96
97 /*****************************************************************************/
98
99 #pragma mark ----- FinderInfo and ExtendedFinderInfo -----
100
101 /*
102 * FSGetFinderInfo and FSSetFinderInfo use these unions for Finder information.
103 */
104
105 union FinderInfo
106 {
107 FileInfo file;
108 FolderInfo folder;
109 };
110 typedef union FinderInfo FinderInfo;
111
112 union ExtendedFinderInfo
113 {
114 ExtendedFileInfo file;
115 ExtendedFolderInfo folder;
116 };
117 typedef union ExtendedFinderInfo ExtendedFinderInfo;
118
119 /*****************************************************************************/
120
121 #pragma mark ----- GetVolParmsInfoBuffer Macros -----
122
123 /*
124 * Macros to get information out of GetVolParmsInfoBuffer.
125 */
126
127 /* version 1 field getters */
128 #define GetVolParmsInfoVersion(volParms) \
129 ((volParms)->vMVersion)
130 #define GetVolParmsInfoAttrib(volParms) \
131 ((volParms)->vMAttrib)
132 #define GetVolParmsInfoLocalHand(volParms) \
133 ((volParms)->vMLocalHand)
134 #define GetVolParmsInfoServerAdr(volParms) \
135 ((volParms)->vMServerAdr)
136
137 /* version 2 field getters (assume zero result if version < 2) */
138 #define GetVolParmsInfoVolumeGrade(volParms) \
139 (((volParms)->vMVersion >= 2) ? (volParms)->vMVolumeGrade : 0)
140 #define GetVolParmsInfoForeignPrivID(volParms) \
141 (((volParms)->vMVersion >= 2) ? (volParms)->vMForeignPrivID : 0)
142
143 /* version 3 field getters (assume zero result if version < 3) */
144 #define GetVolParmsInfoExtendedAttributes(volParms) \
145 (((volParms)->vMVersion >= 3) ? (volParms)->vMExtendedAttributes : 0)
146
147 /* attribute bits supported by all versions of GetVolParmsInfoBuffer */
148 #define VolIsNetworkVolume(volParms) \
149 ((volParms)->vMServerAdr != 0)
150 #define VolHasLimitFCBs(volParms) \
151 (((volParms)->vMAttrib & (1L << bLimitFCBs)) != 0)
152 #define VolHasLocalWList(volParms) \
153 (((volParms)->vMAttrib & (1L << bLocalWList)) != 0)
154 #define VolHasNoMiniFndr(volParms) \
155 (((volParms)->vMAttrib & (1L << bNoMiniFndr)) != 0)
156 #define VolHasNoVNEdit(volParms) \
157 (((volParms)->vMAttrib & (1L << bNoVNEdit)) != 0)
158 #define VolHasNoLclSync(volParms) \
159 (((volParms)->vMAttrib & (1L << bNoLclSync)) != 0)
160 #define VolHasTrshOffLine(volParms) \
161 (((volParms)->vMAttrib & (1L << bTrshOffLine)) != 0)
162 #define VolHasNoSwitchTo(volParms) \
163 (((volParms)->vMAttrib & (1L << bNoSwitchTo)) != 0)
164 #define VolHasNoDeskItems(volParms) \
165 (((volParms)->vMAttrib & (1L << bNoDeskItems)) != 0)
166 #define VolHasNoBootBlks(volParms) \
167 (((volParms)->vMAttrib & (1L << bNoBootBlks)) != 0)
168 #define VolHasAccessCntl(volParms) \
169 (((volParms)->vMAttrib & (1L << bAccessCntl)) != 0)
170 #define VolHasNoSysDir(volParms) \
171 (((volParms)->vMAttrib & (1L << bNoSysDir)) != 0)
172 #define VolHasExtFSVol(volParms) \
173 (((volParms)->vMAttrib & (1L << bHasExtFSVol)) != 0)
174 #define VolHasOpenDeny(volParms) \
175 (((volParms)->vMAttrib & (1L << bHasOpenDeny)) != 0)
176 #define VolHasCopyFile(volParms) \
177 (((volParms)->vMAttrib & (1L << bHasCopyFile)) != 0)
178 #define VolHasMoveRename(volParms) \
179 (((volParms)->vMAttrib & (1L << bHasMoveRename)) != 0)
180 #define VolHasDesktopMgr(volParms) \
181 (((volParms)->vMAttrib & (1L << bHasDesktopMgr)) != 0)
182 #define VolHasShortName(volParms) \
183 (((volParms)->vMAttrib & (1L << bHasShortName)) != 0)
184 #define VolHasFolderLock(volParms) \
185 (((volParms)->vMAttrib & (1L << bHasFolderLock)) != 0)
186 #define VolHasPersonalAccessPrivileges(volParms) \
187 (((volParms)->vMAttrib & (1L << bHasPersonalAccessPrivileges)) != 0)
188 #define VolHasUserGroupList(volParms) \
189 (((volParms)->vMAttrib & (1L << bHasUserGroupList)) != 0)
190 #define VolHasCatSearch(volParms) \
191 (((volParms)->vMAttrib & (1L << bHasCatSearch)) != 0)
192 #define VolHasFileIDs(volParms) \
193 (((volParms)->vMAttrib & (1L << bHasFileIDs)) != 0)
194 #define VolHasBTreeMgr(volParms) \
195 (((volParms)->vMAttrib & (1L << bHasBTreeMgr)) != 0)
196 #define VolHasBlankAccessPrivileges(volParms) \
197 (((volParms)->vMAttrib & (1L << bHasBlankAccessPrivileges)) != 0)
198 #define VolSupportsAsyncRequests(volParms) \
199 (((volParms)->vMAttrib & (1L << bSupportsAsyncRequests)) != 0)
200 #define VolSupportsTrashVolumeCache(volParms) \
201 (((volParms)->vMAttrib & (1L << bSupportsTrashVolumeCache)) != 0)
202
203 /* attribute bits supported by version 3 and greater versions of GetVolParmsInfoBuffer */
204 #define VolIsEjectable(volParms) \
205 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsEjectable)) != 0)
206 #define VolSupportsHFSPlusAPIs(volParms) \
207 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsHFSPlusAPIs)) != 0)
208 #define VolSupportsFSCatalogSearch(volParms) \
209 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSCatalogSearch)) != 0)
210 #define VolSupportsFSExchangeObjects(volParms) \
211 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSExchangeObjects)) != 0)
212 #define VolSupports2TBFiles(volParms) \
213 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupports2TBFiles)) != 0)
214 #define VolSupportsLongNames(volParms) \
215 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsLongNames)) != 0)
216 #define VolSupportsMultiScriptNames(volParms) \
217 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsMultiScriptNames)) != 0)
218 #define VolSupportsNamedForks(volParms) \
219 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsNamedForks)) != 0)
220 #define VolSupportsSubtreeIterators(volParms) \
221 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSubtreeIterators)) != 0)
222 #define VolL2PCanMapFileBlocks(volParms) \
223 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bL2PCanMapFileBlocks)) != 0)
224 #define VolParentModDateChanges(volParms) \
225 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bParentModDateChanges)) != 0)
226 #define VolAncestorModDateChanges(volParms) \
227 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bAncestorModDateChanges)) != 0)
228 #define VolSupportsSymbolicLinks(volParms) \
229 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSymbolicLinks)) != 0)
230 #define VolIsAutoMounted(volParms) \
231 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsAutoMounted)) != 0)
232
233 /*****************************************************************************/
234
235 #pragma mark ----- userPrivileges Bit Masks and Macros -----
236
237 /*
238 * Bit masks and macros to get common information out of userPrivileges byte
239 * returned by FSGetCatalogInfo.
240 *
241 * Note: The userPrivileges byte is the same as the ioACUser byte returned
242 * by PBGetCatInfo, and is the 1's complement of the user's privileges
243 * byte returned in ioACAccess by PBHGetDirAccess. That's where the
244 * ioACUser names came from.
245 *
246 * The userPrivileges are user's effective privileges based on the
247 * user ID and the groups that user belongs to, and the owner, group,
248 * and everyone privileges for the given directory.
249 */
250
251 enum
252 {
253 /* mask for just the access restriction bits */
254 kioACUserAccessMask = (kioACUserNoSeeFolderMask +
255 kioACUserNoSeeFilesMask +
256 kioACUserNoMakeChangesMask),
257 /* common access privilege settings */
258 kioACUserFull = 0x00, /* no access restiction bits on */
259 kioACUserNone = kioACUserAccessMask, /* all access restiction bits on */
260 kioACUserDropBox = (kioACUserNoSeeFolderMask +
261 kioACUserNoSeeFilesMask), /* make changes, but not see files or folders */
262 kioACUserBulletinBoard = kioACUserNoMakeChangesMask /* see files and folders, but not make changes */
263 };
264
265
266 /* Macros for testing ioACUser bits. */
267
268 #define UserIsOwner(userPrivileges) \
269 (((userPrivileges) & kioACUserNotOwnerMask) == 0)
270 #define UserHasFullAccess(userPrivileges) \
271 (((userPrivileges) & (kioACUserAccessMask)) == kioACUserFull)
272 #define UserHasDropBoxAccess(userPrivileges) \
273 (((userPrivileges) & kioACUserAccessMask) == kioACUserDropBox)
274 #define UserHasBulletinBoard(userPrivileges) \
275 (((userPrivileges) & kioACUserAccessMask) == kioACUserBulletinBoard)
276 #define UserHasNoAccess(userPrivileges) \
277 (((userPrivileges) & kioACUserAccessMask) == kioACUserNone)
278
279 /*****************************************************************************/
280
281 #pragma mark ----- File Access Routines -----
282
283 /*****************************************************************************/
284
285 #pragma mark FSCopyFork
286
287 OSErr
288 FSCopyFork(
289 SInt16 srcRefNum,
290 SInt16 dstRefNum,
291 void *copyBufferPtr,
292 ByteCount copyBufferSize);
293
294 /*
295 The FSCopyFork function copies all data from the source fork to the
296 destination fork of open file forks and makes sure the destination EOF
297 is equal to the source EOF.
298
299 srcRefNum --> The source file reference number.
300 dstRefNum --> The destination file reference number.
301 copyBufferPtr --> Pointer to buffer to use during copy. The
302 buffer should be at least 4K-bytes minimum.
303 The larger the buffer, the faster the copy
304 (up to a point).
305 copyBufferSize --> The size of the copy buffer.
306 */
307
308 /*****************************************************************************/
309
310 #pragma mark ----- Volume Access Routines -----
311
312 /*****************************************************************************/
313
314 #pragma mark FSGetVolParms
315
316 OSErr
317 FSGetVolParms(
318 FSVolumeRefNum volRefNum,
319 UInt32 bufferSize,
320 GetVolParmsInfoBuffer *volParmsInfo,
321 UInt32 *actualInfoSize);
322
323 /*
324 The FSGetVolParms function returns information about the characteristics
325 of a volume. A result of paramErr usually just means the volume doesn't
326 support GetVolParms and the feature you were going to check
327 for isn't available.
328
329 volRefNum --> Volume specification.
330 bufferSize --> Size of buffer pointed to by volParmsInfo.
331 volParmsInfo <-- A GetVolParmsInfoBuffer record where the volume
332 attributes information is returned.
333 actualInfoSize <-- The number of bytes actually returned
334 in volParmsInfo.
335
336 __________
337
338 Also see: The GetVolParmsInfoBuffer Macros for checking attribute bits
339 in this file
340 */
341
342 /*****************************************************************************/
343
344 #pragma mark FSGetVRefNum
345
346 OSErr
347 FSGetVRefNum(
348 const FSRef *ref,
349 FSVolumeRefNum *vRefNum);
350
351 /*
352 The FSGetVRefNum function determines the volume reference
353 number of a volume from a FSRef.
354
355 ref --> The FSRef.
356 vRefNum <-- The volume reference number.
357 */
358
359 /*****************************************************************************/
360
361 #pragma mark FSGetVInfo
362
363 OSErr
364 FSGetVInfo(
365 FSVolumeRefNum volume,
366 HFSUniStr255 *volumeName, /* can be NULL */
367 UInt64 *freeBytes, /* can be NULL */
368 UInt64 *totalBytes); /* can be NULL */
369
370 /*
371 The FSGetVInfo function returns the name, available space (in bytes),
372 and total space (in bytes) for the specified volume.
373
374 volume --> The volume reference number.
375 volumeName <** An optional pointer to a HFSUniStr255.
376 If not NULL, the volume name will be returned in
377 the HFSUniStr255.
378 freeBytes <** An optional pointer to a UInt64.
379 If not NULL, the number of free bytes on the
380 volume will be returned in the UInt64.
381 totalBytes <** An optional pointer to a UInt64.
382 If not NULL, the total number of bytes on the
383 volume will be returned in the UInt64.
384 */
385
386 /*****************************************************************************/
387
388 #pragma mark FSGetVolFileSystemID
389
390 OSErr
391 FSGetVolFileSystemID(
392 FSVolumeRefNum volume,
393 UInt16 *fileSystemID, /* can be NULL */
394 UInt16 *signature); /* can be NULL */
395
396 /*
397 The FSGetVolFileSystemID function returns the file system ID and signature
398 of a mounted volume. The file system ID identifies the file system
399 that handles requests to a particular volume. The signature identifies the
400 volume type of the volume (for example, FSID 0 is Macintosh HFS Plus, HFS
401 or MFS, where a signature of 0x4244 identifies the volume as HFS).
402 Here's a partial list of file system ID numbers (only Apple's file systems
403 are listed):
404 FSID File System
405 ----- -----------------------------------------------------
406 $0000 Macintosh HFS Plus, HFS or MFS
407 $0100 ProDOS File System
408 $0101 PowerTalk Mail Enclosures
409 $4147 ISO 9660 File Access (through Foreign File Access)
410 $4242 High Sierra File Access (through Foreign File Access)
411 $464D QuickTake File System (through Foreign File Access)
412 $4953 Macintosh PC Exchange (MS-DOS)
413 $4A48 Audio CD Access (through Foreign File Access)
414 $4D4B Apple Photo Access (through Foreign File Access)
415 $6173 AppleShare (later versions of AppleShare only)
416
417 See the Technical Note "FL 35 - Determining Which File System
418 Is Active" and the "Guide to the File System Manager" for more
419 information.
420
421 volume --> The volume reference number.
422 fileSystemID <** An optional pointer to a UInt16.
423 If not NULL, the volume's file system ID will
424 be returned in the UInt16.
425 signature <** An optional pointer to a UInt16.
426 If not NULL, the volume's signature will
427 be returned in the UInt16.
428 */
429
430 /*****************************************************************************/
431
432 #pragma mark FSGetMountedVolumes
433
434 OSErr
435 FSGetMountedVolumes(
436 FSRef ***volumeRefsHandle, /* pointer to handle of FSRefs */
437 ItemCount *numVolumes);
438
439 /*
440 The FSGetMountedVolumes function returns the list of volumes currently
441 mounted in an array of FSRef records. The array of FSRef records is
442 returned in a Handle, volumeRefsHandle, which is allocated by
443 FSGetMountedVolumes. The caller is responsible for disposing of
444 volumeRefsHandle if the FSGetMountedVolumes returns noErr.
445
446 volumeRefsHandle <-- Pointer to an FSRef Handle where the array of
447 FSRefs is to be returned.
448 numVolumes <-- The number of volumes returned in the array.
449 */
450
451 /*****************************************************************************/
452
453 #pragma mark ----- FSRef/FSpec/Path/Name Conversion Routines -----
454
455 /*****************************************************************************/
456
457 #pragma mark FSRefMakeFSSpec
458
459 OSErr
460 FSRefMakeFSSpec(
461 const FSRef *ref,
462 FSSpec *spec);
463
464 /*
465 The FSRefMakeFSSpec function returns an FSSpec for the file or
466 directory specified by the ref parameter.
467
468 ref --> An FSRef specifying the file or directory.
469 spec <-- The FSSpec.
470 */
471
472 /*****************************************************************************/
473
474 #pragma mark FSMakeFSRef
475
476 OSErr
477 FSMakeFSRef(
478 FSVolumeRefNum volRefNum,
479 SInt32 dirID,
480 ConstStr255Param name,
481 FSRef *ref);
482
483 /*
484 The FSMakeFSRef function creates an FSRef from the traditional
485 volume reference number, directory ID and pathname inputs. It is
486 functionally equivalent to FSMakeFSSpec followed by FSpMakeFSRef.
487
488 volRefNum --> Volume specification.
489 dirID --> Directory specification.
490 name --> The file or directory name, or NULL.
491 ref <-- The FSRef.
492 */
493
494 /*****************************************************************************/
495
496 #pragma mark FSMakePath
497
498 OSStatus
499 FSMakePath(
500 SInt16 vRefNum,
501 SInt32 dirID,
502 ConstStr255Param name,
503 UInt8 *path,
504 UInt32 maxPathSize);
505
506 /*
507 The FSMakePath function creates a pathname from the traditional volume reference
508 number, directory ID, and pathname inputs. It is functionally equivalent to
509 FSMakeFSSpec, FSpMakeFSRef, FSRefMakePath.
510
511 volRefNum --> Volume specification.
512 dirID --> Directory specification.
513 name --> The file or directory name, or NULL.
514 path <-- A pointer to a buffer which FSMakePath will
515 fill with a C string representing the pathname
516 to the file or directory specified. The format of
517 the pathname returned can be determined with the
518 Gestalt selector gestaltFSAttr's
519 gestaltFSUsesPOSIXPathsForConversion bit.
520 If the gestaltFSUsesPOSIXPathsForConversion bit is
521 clear, the pathname is a Mac OS File Manager full
522 pathname in a C string, and file or directory names
523 in the pathname may be mangled as returned by
524 the File Manager. If the
525 gestaltFSUsesPOSIXPathsForConversion bit is set,
526 the pathname is a UTF8 encoded POSIX absolute
527 pathname in a C string. In either case, the
528 pathname returned can be passed back to
529 FSPathMakeRef to create an FSRef to the file or
530 directory, or FSPathMakeFSSpec to craete an FSSpec
531 to the file or directory.
532 maxPathSize --> The size of the path buffer in bytes. If the path
533 buffer is too small for the pathname string,
534 FSMakePath returns pathTooLongErr or
535 buffersTooSmall.
536 */
537
538 /*****************************************************************************/
539
540 #pragma mark FSPathMakeFSSpec
541
542 OSStatus
543 FSPathMakeFSSpec(
544 const UInt8 *path,
545 FSSpec *spec,
546 Boolean *isDirectory); /* can be NULL */
547
548 /*
549 The FSPathMakeFSSpec function converts a pathname to an FSSpec.
550
551 path --> A pointer to a C String that is the pathname. The
552 format of the pathname you must supply can be
553 determined with the Gestalt selector gestaltFSAttr's
554 gestaltFSUsesPOSIXPathsForConversion bit.
555 If the gestaltFSUsesPOSIXPathsForConversion bit is
556 clear, the pathname must be a Mac OS File Manager
557 full pathname in a C string. If the
558 gestaltFSUsesPOSIXPathsForConversion bit is set,
559 the pathname must be a UTF8 encoded POSIX absolute
560 pathname in a C string.
561 spec <-- The FSSpec.
562 isDirectory <** An optional pointer to a Boolean.
563 If not NULL, true will be returned in the Boolean
564 if the specified path is a directory, or false will
565 be returned in the Boolean if the specified path is
566 a file.
567 */
568
569 /*****************************************************************************/
570
571 #pragma mark UnicodeNameGetHFSName
572
573 OSErr
574 UnicodeNameGetHFSName(
575 UniCharCount nameLength,
576 const UniChar *name,
577 TextEncoding textEncodingHint,
578 Boolean isVolumeName,
579 Str31 hfsName);
580
581 /*
582 The UnicodeNameGetHFSName function converts a Unicode string
583 to a Pascal Str31 (or Str27) string using an algorithm similar to that used
584 by the File Manager. Note that if the name is too long or cannot be converted
585 using the given text encoding hint, you will get an error instead of the
586 mangled name that the File Manager would return.
587
588 nameLength --> Number of UniChar in name parameter.
589 name --> The Unicode string to convert.
590 textEncodingHint --> The text encoding hint used for the conversion.
591 You can pass kTextEncodingUnknown to use the
592 "default" textEncodingHint.
593 isVolumeName --> If true, the output name will be limited to
594 27 characters (kHFSMaxVolumeNameChars). If false,
595 the output name will be limited to 31 characters
596 (kHFSMaxFileNameChars).
597 hfsName <-- The hfsName as a Pascal string.
598
599 __________
600
601 Also see: HFSNameGetUnicodeName
602 */
603
604 /*****************************************************************************/
605
606 #pragma mark HFSNameGetUnicodeName
607
608 OSErr
609 HFSNameGetUnicodeName(
610 ConstStr31Param hfsName,
611 TextEncoding textEncodingHint,
612 HFSUniStr255 *unicodeName);
613
614 /*
615 The HFSNameGetUnicodeName function converts a Pascal Str31 string to an
616 Unicode HFSUniStr255 string using the same routines as the File Manager.
617
618 hfsName --> The Pascal string to convert.
619 textEncodingHint --> The text encoding hint used for the conversion.
620 You can pass kTextEncodingUnknown to use the
621 "default" textEncodingHint.
622 unicodeName <-- The Unicode string.
623
624 __________
625
626 Also see: UnicodeNameGetHFSName
627 */
628
629 /*****************************************************************************/
630
631 #pragma mark ----- File/Directory Manipulation Routines -----
632
633 /*****************************************************************************/
634
635 #pragma mark FSRefValid
636
637 Boolean FSRefValid(const FSRef *ref);
638
639 /*
640 The FSRefValid function determines if an FSRef is valid. If the result is
641 true, then the FSRef refers to an existing file or directory.
642
643 ref --> FSRef to a file or directory.
644 */
645
646 /*****************************************************************************/
647
648 #pragma mark FSGetParentRef
649
650 OSErr
651 FSGetParentRef(
652 const FSRef *ref,
653 FSRef *parentRef);
654
655 /*
656 The FSGetParentRef function gets the parent directory FSRef of the
657 specified object.
658
659 Note: FSRefs always point to real file system objects. So, there cannot
660 be a FSRef to the parent of volume root directories. If you call
661 FSGetParentRef with a ref to the root directory of a volume, the
662 function result will be noErr and the parentRef will be invalid (using it
663 for other file system requests will fail).
664
665 ref --> FSRef to a file or directory.
666 parentRef <-- The parent directory's FSRef.
667 */
668
669 /*****************************************************************************/
670
671 #pragma mark FSGetFileDirName
672
673 OSErr
674 FSGetFileDirName(
675 const FSRef *ref,
676 HFSUniStr255 *outName);
677
678 /*
679 The FSGetFileDirName function gets the name of the file or directory
680 specified.
681
682 ref --> FSRef to a file or directory.
683 outName <-- The file or directory name.
684 */
685
686 /*****************************************************************************/
687
688 #pragma mark FSGetNodeID
689
690 OSErr
691 FSGetNodeID(
692 const FSRef *ref,
693 long *nodeID, /* can be NULL */
694 Boolean *isDirectory); /* can be NULL */
695
696 /*
697 The GetNodeIDFromFSRef function gets the node ID number of the
698 file or directory specified (note: the node ID is the directory ID
699 for directories).
700
701 ref --> FSRef to a file or directory.
702 nodeID <** An optional pointer to a long.
703 If not NULL, the node ID will be returned in
704 the long.
705 isDirectory <** An optional pointer to a Boolean.
706 If not NULL, true will be returned in the Boolean
707 if the object is a directory, or false will be
708 returned in the Boolean if object is a file.
709 */
710
711 /*****************************************************************************/
712
713 #pragma mark FSGetUserPrivilegesPermissions
714
715 OSErr
716 FSGetUserPrivilegesPermissions(
717 const FSRef *ref,
718 UInt8 *userPrivileges, /* can be NULL */
719 UInt32 permissions[4]); /* can be NULL */
720
721 /*
722 The FSGetUserPrivilegesPermissions function gets the userPrivileges and/or
723 permissions of the file or directory specified.
724
725 ref --> FSRef to a file or directory.
726 userPrivileges <** An optional pointer to a UInt8.
727 If not NULL, the userPrivileges will be returned
728 in the UInt8.
729 permissions <** An optional pointer to an UInt32[4] array.
730 If not NULL, the permissions will be returned
731 in the UInt32[4] array.
732 */
733
734 /*****************************************************************************/
735
736 #pragma mark FSCheckLock
737
738 OSErr
739 FSCheckLock(
740 const FSRef *ref);
741
742 /*
743 The FSCheckLock function determines if a file or directory is locked.
744 If FSCheckLock returns noErr, then the file or directory is not locked
745 and the volume it is on is not locked either. If FSCheckLock returns
746 fLckdErr, then the file or directory is locked. If FSCheckLock returns
747 wPrErr, then the volume is locked by hardware (i.e., locked tab on
748 removable media). If FSCheckLock returns vLckdErr, then the volume is
749 locked by software.
750
751 ref --> FSRef to a file or directory.
752 */
753
754 /*****************************************************************************/
755
756 #pragma mark FSGetForkSizes
757
758 OSErr
759 FSGetForkSizes(
760 const FSRef *ref,
761 UInt64 *dataLogicalSize, /* can be NULL */
762 UInt64 *rsrcLogicalSize); /* can be NULL */
763
764 /*
765 The FSGetForkSizes returns the size of the data and/or resource fork for
766 the specified file.
767
768 ref --> FSRef to a file or directory.
769 dataLogicalSize <** An optional pointer to a UInt64.
770 If not NULL, the data fork's size will be
771 returned in the UInt64.
772 rsrcLogicalSize <** An optional pointer to a UInt64.
773 If not NULL, the resource fork's size will be
774 returned in the UInt64.
775
776 __________
777
778 Also see: FSGetTotalForkSizes
779 */
780
781 /*****************************************************************************/
782
783 #pragma mark FSGetTotalForkSizes
784
785 OSErr
786 FSGetTotalForkSizes(
787 const FSRef *ref,
788 UInt64 *totalLogicalSize, /* can be NULL */
789 UInt64 *totalPhysicalSize, /* can be NULL */
790 ItemCount *forkCount); /* can be NULL */
791
792 /*
793 The FSGetTotalForkSizes returns the total logical size and/or the total
794 physical size of the specified file (i.e., it adds the sizes of all file
795 forks). It optionally returns the number of file forks.
796
797 ref --> FSRef to a file or directory.
798 totalLogicalSize <** An optional pointer to a UInt64.
799 If not NULL, the sum of all fork logical sizes
800 will be returned in the UInt64.
801 totalPhysicalSize <** An optional pointer to a UInt64.
802 If not NULL, the sum of all fork physical sizes
803 will be returned in the UInt64.
804 forkCount <** An optional pointer to a ItemCount.
805 If not NULL, the number of file forks
806 will be returned in the ItemCount.
807
808 __________
809
810 Also see: FSGetForkSizes
811 */
812
813 /*****************************************************************************/
814
815 #pragma mark FSBumpDate
816
817 OSErr
818 FSBumpDate(
819 const FSRef *ref);
820
821 /*
822 The FSBumpDate function changes the content modification date of a file
823 or directory to the current date/time. If the content modification date
824 is already equal to the current date/time, then add one second to the
825 content modification date.
826
827 ref --> FSRef to a file or directory.
828 */
829
830 /*****************************************************************************/
831
832 #pragma mark FSGetFinderInfo
833
834 OSErr
835 FSGetFinderInfo(
836 const FSRef *ref,
837 FinderInfo *info, /* can be NULL */
838 ExtendedFinderInfo *extendedInfo, /* can be NULL */
839 Boolean *isDirectory); /* can be NULL */
840
841 /*
842 The FSGetFinderInfo function gets the finder information for a file or
843 directory.
844
845 ref --> FSRef to a file or directory.
846 info <** An optional pointer to a FinderInfo.
847 If not NULL, the FileInfo (if ref is a file) or
848 the FolderInfo (if ref is a folder) will be
849 returned in the FinderInfo.
850 extendedInfo <** An optional pointer to a ExtendedFinderInfo.
851 If not NULL, the ExtendedFileInfo (if ref is a file)
852 or the ExtendedFolderInfo (if ref is a folder) will
853 be returned in the ExtendedFinderInfo.
854 isDirectory <** An optional pointer to a Boolean.
855 If not NULL, true will be returned in the Boolean
856 if the object is a directory, or false will be
857 returned in the Boolean if object is a file.
858
859 __________
860
861 Also see: FSSetFinderInfo
862 */
863
864 /*****************************************************************************/
865
866 #pragma mark FSSetFinderInfo
867
868 OSErr
869 FSSetFinderInfo(
870 const FSRef *ref,
871 const FinderInfo *info, /* can be NULL */
872 const ExtendedFinderInfo *extendedInfo); /* can be NULL */
873
874 /*
875 The FSSetFinderInfo function sets the finder information for a file or
876 directory.
877
878 ref --> FSRef to a file or directory.
879 info **> A pointer to a FinderInfo record with the new
880 FileInfo (if ref is a file) or new FolderInfo
881 (if ref is a folder), or NULL if the FinderInfo
882 is not to be changed.
883 extendedInfo **> A pointer to a FinderInfo record with the new
884 ExtendedFileInfo (if ref is a file) or new
885 ExtendedFolderInfo (if ref is a folder), or NULL
886 if the ExtendedFinderInfo is not to be changed.
887
888 __________
889
890 Also see: FSGetFinderInfo
891 */
892
893 /*****************************************************************************/
894
895 #pragma mark FSChangeCreatorType
896
897 OSErr
898 FSChangeCreatorType(
899 const FSRef *ref,
900 OSType fileCreator,
901 OSType fileType);
902
903 /*
904 The FSChangeCreatorType function changes the creator and/or file type of a file.
905
906 ref --> FSRef to a file.
907 creator --> The new creator type or 0x00000000 to leave
908 the creator type alone.
909 fileType --> The new file type or 0x00000000 to leave the
910 file type alone.
911 */
912
913 /*****************************************************************************/
914
915 #pragma mark FSChangeFinderFlags
916
917 OSErr
918 FSChangeFinderFlags(
919 const FSRef *ref,
920 Boolean setBits,
921 UInt16 flagBits);
922
923 /*
924 The FSChangeFinderFlags function sets or clears flag bits in
925 the finderFlags field of a file's FileInfo record or a
926 directory's FolderInfo record.
927
928 ref --> FSRef to a file or directory.
929 setBits --> If true, then set the bits specified in flagBits.
930 If false, then clear the bits specified in flagBits.
931 flagBits --> The flagBits parameter specifies which Finder Flag
932 bits to set or clear. If a bit in flagBits is set,
933 then the same bit in fdFlags is either set or
934 cleared depending on the state of the setBits
935 parameter.
936 */
937
938 /*****************************************************************************/
939
940 #pragma mark FSSetInvisible
941
942 OSErr
943 FSSetInvisible(
944 const FSRef *ref);
945
946 #pragma mark FSClearInvisible
947
948 OSErr
949 FSClearInvisible(
950 const FSRef *ref);
951
952 /*
953 The FSSetInvisible and FSClearInvisible functions set or clear the
954 kIsInvisible bit in the finderFlags field of the specified file or
955 directory's finder information.
956
957 ref --> FSRef to a file or directory.
958 */
959
960 /*****************************************************************************/
961
962 #pragma mark FSSetNameLocked
963
964 OSErr
965 FSSetNameLocked(
966 const FSRef *ref);
967
968 #pragma mark FSClearNameLocked
969
970 OSErr
971 FSClearNameLocked(
972 const FSRef *ref);
973
974 /*
975 The FSSetNameLocked and FSClearNameLocked functions set or clear the
976 kNameLocked bit bit in the finderFlags field of the specified file or
977 directory's finder information.
978
979 ref --> FSRef to a file or directory.
980 */
981
982 /*****************************************************************************/
983
984 #pragma mark FSSetIsStationery
985
986 OSErr
987 FSSetIsStationery(
988 const FSRef *ref);
989
990 #pragma mark FSClearIsStationery
991
992 OSErr
993 FSClearIsStationery(
994 const FSRef *ref);
995
996 /*
997 The FSSetIsStationery and FSClearIsStationery functions set or clear the
998 kIsStationery bit bit in the finderFlags field of the specified file or
999 directory's finder information.
1000
1001 ref --> FSRef to a file or directory.
1002 */
1003
1004 /*****************************************************************************/
1005
1006 #pragma mark FSSetHasCustomIcon
1007
1008 OSErr
1009 FSSetHasCustomIcon(
1010 const FSRef *ref);
1011
1012 #pragma mark FSClearHasCustomIcon
1013
1014 OSErr
1015 FSClearHasCustomIcon(
1016 const FSRef *ref);
1017
1018 /*
1019 The FSSetHasCustomIcon and FSClearHasCustomIcon functions set or clear the
1020 kHasCustomIcon bit bit in the finderFlags field of the specified file or
1021 directory's finder information.
1022
1023 ref --> FSRef to a file or directory.
1024 */
1025
1026 /*****************************************************************************/
1027
1028 #pragma mark FSClearHasBeenInited
1029
1030 OSErr
1031 FSClearHasBeenInited(
1032 const FSRef *ref);
1033
1034 /*
1035 The FSClearHasBeenInited function clears the kHasBeenInited bit in the
1036 finderFlags field of the specified file or directory's finder information.
1037
1038 Note: There is no FSSetHasBeenInited function because ONLY the Finder
1039 should set the kHasBeenInited bit.
1040
1041 ref --> FSRef to a file or directory.
1042 */
1043
1044 /*****************************************************************************/
1045
1046 #pragma mark FSCopyFileMgrAttributes
1047
1048 OSErr
1049 FSCopyFileMgrAttributes(
1050 const FSRef *sourceRef,
1051 const FSRef *destinationRef,
1052 Boolean copyLockBit);
1053
1054 /*
1055 The CopyFileMgrAttributes function copies all File Manager attributes
1056 from the source file or directory to the destination file or directory.
1057 If copyLockBit is true, then set the locked state of the destination
1058 to match the source.
1059
1060 sourceRef --> FSRef to a file or directory.
1061 destinationRef --> FSRef to a file or directory.
1062 copyLockBit --> If true, set the locked state of the destination
1063 to match the source.
1064 */
1065
1066 /*****************************************************************************/
1067
1068 #pragma mark FSMoveRenameObjectUnicode
1069
1070 OSErr
1071 FSMoveRenameObjectUnicode(
1072 const FSRef *ref,
1073 const FSRef *destDirectory,
1074 UniCharCount nameLength,
1075 const UniChar *name, /* can be NULL (no rename during move) */
1076 TextEncoding textEncodingHint,
1077 FSRef *newRef); /* if function fails along the way, newRef is final location of file */
1078
1079 /*
1080 The FSMoveRenameObjectUnicode function moves a file or directory and
1081 optionally renames it. The source and destination locations must be on
1082 the same volume.
1083
1084 Note: If the input ref parameter is invalid, this call will fail and
1085 newRef, like ref, will be invalid.
1086
1087 ref --> FSRef to a file or directory.
1088 destDirectory --> FSRef to the destination directory.
1089 nameLength --> Number of UniChar in name parameter.
1090 name --> An Unicode string with the new name for the
1091 moved object, or NULL if no rename is wanted.
1092 textEncodingHint --> The text encoding hint used for the rename.
1093 You can pass kTextEncodingUnknown to use the
1094 "default" textEncodingHint.
1095 newRef <-- The new FSRef of the object moved. Note that if
1096 this function fails at any step along the way,
1097 newRef is still then final location of the object.
1098 */
1099
1100 /*****************************************************************************/
1101
1102 #pragma mark FSDeleteContainerContents
1103
1104 OSErr
1105 FSDeleteContainerContents(
1106 const FSRef *container);
1107
1108 /*
1109 The FSDeleteContainerContents function deletes the contents of a container
1110 directory. All files and subdirectories in the specified container are
1111 deleted. If a locked file or directory is encountered, it is unlocked and
1112 then deleted. If any unexpected errors are encountered,
1113 FSDeleteContainerContents quits and returns to the caller.
1114
1115 container --> FSRef to a directory.
1116
1117 __________
1118
1119 Also see: FSDeleteContainer
1120 */
1121
1122 /*****************************************************************************/
1123
1124 #pragma mark FSDeleteContainer
1125
1126 OSErr
1127 FSDeleteContainer(
1128 const FSRef *container);
1129
1130 /*
1131 The FSDeleteContainer function deletes a container directory and its contents.
1132 All files and subdirectories in the specified container are deleted.
1133 If a locked file or directory is encountered, it is unlocked and then
1134 deleted. After deleting the container's contents, the container is
1135 deleted. If any unexpected errors are encountered, FSDeleteContainer
1136 quits and returns to the caller.
1137
1138 container --> FSRef to a directory.
1139
1140 __________
1141
1142 Also see: FSDeleteContainerContents
1143 */
1144
1145 /*****************************************************************************/
1146
1147 #pragma mark IterateContainerFilterProcPtr
1148
1149 typedef CALLBACK_API( Boolean , IterateContainerFilterProcPtr ) (
1150 Boolean containerChanged,
1151 ItemCount currentLevel,
1152 const FSCatalogInfo *catalogInfo,
1153 const FSRef *ref,
1154 const FSSpec *spec,
1155 const HFSUniStr255 *name,
1156 void *yourDataPtr);
1157
1158 /*
1159 This is the prototype for the IterateContainerFilterProc function which
1160 is called once for each file and directory found by FSIterateContainer.
1161 The IterateContainerFilterProc can use the read-only data it receives for
1162 whatever it wants.
1163
1164 The result of the IterateContainerFilterProc function indicates if
1165 iteration should be stopped. To stop iteration, return true; to continue
1166 iteration, return false.
1167
1168 The yourDataPtr parameter can point to whatever data structure you might
1169 want to access from within the IterateContainerFilterProc.
1170
1171 containerChanged --> Set to true if the container's contents changed
1172 during iteration.
1173 currentLevel --> The current recursion level into the container.
1174 1 = the container, 2 = the container's immediate
1175 subdirectories, etc.
1176 catalogInfo --> The catalog information for the current object.
1177 Only the fields requested by the whichInfo
1178 parameter passed to FSIterateContainer are valid.
1179 ref --> The FSRef to the current object.
1180 spec --> The FSSpec to the current object if the wantFSSpec
1181 parameter passed to FSIterateContainer is true.
1182 name --> The name of the current object if the wantName
1183 parameter passed to FSIterateContainer is true.
1184 yourDataPtr --> An optional pointer to whatever data structure you
1185 might want to access from within the
1186 IterateFilterProc.
1187 result <-- To stop iteration, return true; to continue
1188 iteration, return false.
1189
1190 __________
1191
1192 Also see: FSIterateContainer
1193 */
1194
1195 /*****************************************************************************/
1196
1197 #pragma mark CallIterateContainerFilterProc
1198
1199 #define CallIterateContainerFilterProc(userRoutine, containerChanged, currentLevel, catalogInfo, ref, spec, name, yourDataPtr) \
1200 (*(userRoutine))((containerChanged), (currentLevel), (catalogInfo), (ref), (spec), (name), (yourDataPtr))
1201
1202 /*****************************************************************************/
1203
1204 #pragma mark FSIterateContainer
1205
1206 OSErr
1207 FSIterateContainer(
1208 const FSRef *container,
1209 ItemCount maxLevels,
1210 FSCatalogInfoBitmap whichInfo,
1211 Boolean wantFSSpec,
1212 Boolean wantName,
1213 IterateContainerFilterProcPtr iterateFilter,
1214 void *yourDataPtr);
1215
1216 /*
1217 The FSIterateContainer function performs a recursive iteration (scan) of the
1218 specified container directory and calls your IterateContainerFilterProc
1219 function once for each file and directory found.
1220
1221 The maxLevels parameter lets you control how deep the recursion goes.
1222 If maxLevels is 1, FSIterateContainer only scans the specified directory;
1223 if maxLevels is 2, FSIterateContainer scans the specified directory and
1224 one subdirectory below the specified directory; etc. Set maxLevels to
1225 zero to scan all levels.
1226
1227 The yourDataPtr parameter can point to whatever data structure you might
1228 want to access from within your IterateContainerFilterProc.
1229
1230 container --> The FSRef to the container directory to iterate.
1231 maxLevels --> Maximum number of directory levels to scan or
1232 zero to scan all directory levels.
1233 whichInfo --> The fields of the FSCatalogInfo you wish to get.
1234 wantFSSpec --> Set to true if you want the FSSpec to each
1235 object passed to your IterateContainerFilterProc.
1236 wantName --> Set to true if you want the name of each
1237 object passed to your IterateContainerFilterProc.
1238 iterateFilter --> A pointer to the IterateContainerFilterProc you
1239 want called once for each file and directory found
1240 by FSIterateContainer.
1241 yourDataPtr --> An optional pointer to whatever data structure you
1242 might want to access from within the
1243 IterateFilterProc.
1244 */
1245
1246 /*****************************************************************************/
1247
1248 #pragma mark FSGetDirectoryItems
1249
1250 OSErr
1251 FSGetDirectoryItems(
1252 const FSRef *container,
1253 FSRef ***refsHandle, /* pointer to handle of FSRefs */
1254 ItemCount *numRefs,
1255 Boolean *containerChanged);
1256
1257 /*
1258 The FSGetDirectoryItems function returns the list of items in the specified
1259 container. The array of FSRef records is returned in a Handle, refsHandle,
1260 which is allocated by FSGetDirectoryItems. The caller is responsible for
1261 disposing of refsHandle if the FSGetDirectoryItems returns noErr.
1262
1263 container --> FSRef to a directory.
1264 refsHandle <-- Pointer to an FSRef Handle where the array of
1265 FSRefs is to be returned.
1266 numRefs <-- The number of FSRefs returned in the array.
1267 containerChanged <-- Set to true if the container changes while the
1268 list of items is being obtained.
1269 */
1270
1271 /*****************************************************************************/
1272
1273 #pragma mark FSExchangeObjectsCompat
1274
1275 OSErr
1276 FSExchangeObjectsCompat(
1277 const FSRef *sourceRef,
1278 const FSRef *destRef,
1279 FSRef *newSourceRef,
1280 FSRef *newDestRef);
1281
1282 /*
1283 The FSExchangeObjectsCompat function exchanges the data between two files.
1284
1285 The FSExchangeObjectsCompat function is an enhanced version of
1286 FSExchangeObjects function. The two enhancements FSExchangeObjectsCompat
1287 provides are:
1288
1289 1, FSExchangeObjectsCompat will work on volumes which do not support
1290 FSExchangeObjects. FSExchangeObjectsCompat does this by emulating
1291 FSExchangeObjects through a series of File Manager operations. If
1292 there is a failure at any step along the way, FSExchangeObjectsCompat
1293 attempts to undo any steps already taken to leave the files in their
1294 original state in their original locations.
1295
1296 2. FSExchangeObjectsCompat returns new FSRefs to the source and
1297 destination files. Note that if this function fails at any step along
1298 the way, newSourceRef and newDestRef still give you access to the final
1299 locations of the files being exchanged -- even if they are renamed or
1300 not in their original locations.
1301
1302 sourceRef --> FSRef to the source file.
1303 destRef --> FSRef to the destination file.
1304 newSourceRef <-- The new FSRef to the source file.
1305 newDestRef <-- The new FSRef to the destination file.
1306 */
1307
1308 /*****************************************************************************/
1309
1310 #pragma mark ----- Shared Environment Routines -----
1311
1312 /*****************************************************************************/
1313
1314 #pragma mark FSGetDirAccess
1315
1316 OSErr
1317 FSGetDirAccess(
1318 const FSRef *ref,
1319 SInt32 *ownerID, /* can be NULL */
1320 SInt32 *groupID, /* can be NULL */
1321 SInt32 *accessRights); /* can be NULL */
1322
1323 /*
1324 The FSGetDirAccess function retrieves the directory access control
1325 information for a directory on a shared volume.
1326
1327 ref --> An FSRef specifying the directory.
1328 ownerID <** An optional pointer to a SInt32.
1329 If not NULL, the directory's owner ID
1330 will be returned in the SInt32.
1331 groupID <** An optional pointer to a SInt32.
1332 If not NULL, the directory's group ID, or 0
1333 if no group affiliation, will be returned in
1334 the SInt32.
1335 accessRights <** An optional pointer to a SInt32.
1336 If not NULL, the directory's access rights
1337 will be returned in the SInt32.
1338
1339 __________
1340
1341 Also see: FSSetDirAccess, FSMapID, FSMapName
1342 */
1343
1344 /*****************************************************************************/
1345
1346 #pragma mark FSSetDirAccess
1347
1348 OSErr
1349 FSSetDirAccess(
1350 const FSRef *ref,
1351 SInt32 ownerID,
1352 SInt32 groupID,
1353 SInt32 accessRights);
1354
1355 /*
1356 The FSpSetDirAccess function changes the directory access control
1357 information for a directory on a shared volume. You must be the owner of
1358 a directory to change its access control information.
1359
1360 ref --> An FSRef specifying the directory.
1361 ownerID --> The directory's owner ID.
1362 groupID --> The directory's group ID or 0 if no group affiliation.
1363 accessRights --> The directory's access rights.
1364
1365 __________
1366
1367 Also see: FSGetDirAccess, FSMapID, FSMapName
1368 */
1369
1370 /*****************************************************************************/
1371
1372 #pragma mark FSGetVolMountInfoSize
1373
1374 OSErr
1375 FSGetVolMountInfoSize(
1376 FSVolumeRefNum volRefNum,
1377 SInt16 *size);
1378
1379 /*
1380 The FSGetVolMountInfoSize function determines the how much space the
1381 program needs to allocate for a volume mounting information record.
1382
1383 volRefNum --> Volume specification.
1384 size <-- The space needed (in bytes) of the volume
1385 mounting information record.
1386
1387 __________
1388
1389 Also see: FSGetVolMountInfo, VolumeMount
1390 */
1391
1392 /*****************************************************************************/
1393
1394 #pragma mark FSGetVolMountInfo
1395
1396 OSErr
1397 FSGetVolMountInfo(
1398 FSVolumeRefNum volRefNum,
1399 void *volMountInfo);
1400
1401 /*
1402 The FSGetVolMountInfo function retrieves a volume mounting information
1403 record containing all the information needed to mount the volume,
1404 except for passwords.
1405
1406 volRefNum --> Volume specification.
1407 volMountInfo <-- The volume mounting information.
1408
1409 __________
1410
1411 Also see: FSGetVolMountInfoSize, VolumeMount
1412 */
1413
1414 /*****************************************************************************/
1415
1416 #pragma mark FSVolumeMount
1417
1418 OSErr
1419 FSVolumeMount(
1420 const void *volMountInfo,
1421 FSVolumeRefNum *volRefNum);
1422
1423 /*
1424 The VolumeMount function mounts a volume using a volume mounting
1425 information record.
1426
1427 volMountInfo --> A volume mounting information record.
1428 volRefNum <-- The volume reference number.
1429
1430 __________
1431
1432 Also see: FSGetVolMountInfoSize, FSGetVolMountInfo
1433 */
1434
1435 /*****************************************************************************/
1436
1437 #pragma mark FSMapID
1438
1439 OSErr
1440 FSMapID(
1441 FSVolumeRefNum volRefNum,
1442 SInt32 ugID,
1443 SInt16 objType,
1444 Str31 name);
1445
1446 /*
1447 The FSMapID function determines the name of a user or group if you know
1448 the user or group ID.
1449
1450 volRefNum --> Volume specification.
1451 objType --> The mapping function code:
1452 kOwnerID2Name to map a user ID to a user name
1453 kGroupID2Name to map a group ID to a group name
1454 name <** An optional pointer to a buffer (minimum Str31).
1455 If not NULL, the user or group name
1456 will be returned in the buffer.
1457
1458 __________
1459
1460 Also see: FSGetDirAccess, FSSetDirAccess, FSMapName
1461 */
1462
1463 /*****************************************************************************/
1464
1465 #pragma mark FSMapName
1466
1467 OSErr
1468 FSMapName(
1469 FSVolumeRefNum volRefNum,
1470 ConstStr255Param name,
1471 SInt16 objType,
1472 SInt32 *ugID);
1473
1474 /*
1475 The FSMapName function determines the user or group ID if you know the
1476 user or group name.
1477
1478 volRefNum --> Volume specification.
1479 name --> The user or group name.
1480 objType --> The mapping function code:
1481 kOwnerName2ID to map a user name to a user ID
1482 kGroupName2ID to map a user name to a group ID
1483 ugID <-- The user or group ID.
1484
1485 __________
1486
1487 Also see: FSGetDirAccess, FSSetDirAccess, FSMapID
1488 */
1489
1490 /*****************************************************************************/
1491
1492 #pragma mark FSCopyFile
1493
1494 OSErr
1495 FSCopyFile(
1496 const FSRef *srcFileRef,
1497 const FSRef *dstDirectoryRef,
1498 UniCharCount nameLength,
1499 const UniChar *copyName, /* can be NULL (no rename during copy) */
1500 TextEncoding textEncodingHint,
1501 FSRef *newRef); /* can be NULL */
1502
1503 /*
1504 The FSCopyFile function duplicates a file and optionally renames it.
1505 The source and destination volumes must be on the same file server.
1506 This function instructs the server to copy the file.
1507
1508 srcFileRef --> An FSRef specifying the source file.
1509 dstDirectoryRef --> An FSRef specifying the destination directory.
1510 nameLength --> Number of UniChar in copyName parameter (ignored
1511 if copyName is NULL).
1512 copyName --> Points to the new file name if the file is to be
1513 renamed, or NULL if the file isn't to be renamed.
1514 textEncodingHint --> The text encoding hint used for the rename.
1515 You can pass kTextEncodingUnknown to use the
1516 "default" textEncodingHint.
1517 newRef <** An optional pointer to a FSRef.
1518 If not NULL, the FSRef of the duplicated file
1519 will be returned in the FSRef.
1520 */
1521
1522 /*****************************************************************************/
1523
1524 #pragma mark FSMoveRename
1525
1526 OSErr
1527 FSMoveRename(
1528 const FSRef *srcFileRef,
1529 const FSRef *dstDirectoryRef,
1530 UniCharCount nameLength,
1531 const UniChar *moveName, /* can be NULL (no rename during move) */
1532 TextEncoding textEncodingHint,
1533 FSRef *newRef); /* can be NULL */
1534
1535 /*
1536 The FSMoveRename function moves a file or directory (object), and
1537 optionally renames it. The source and destination locations must be on
1538 the same shared volume.
1539
1540 srcFileRef --> An FSRef specifying the source file.
1541 dstDirectoryRef --> An FSRef specifying the destination directory.
1542 nameLength --> Number of UniChar in moveName parameter (ignored
1543 if copyName is NULL)
1544 moveName --> Points to the new object name if the object is to be
1545 renamed, or NULL if the object isn't to be renamed.
1546 textEncodingHint --> The text encoding hint used for the rename.
1547 You can pass kTextEncodingUnknown to use the
1548 "default" textEncodingHint.
1549 newRef <** An optional pointer to a FSRef.
1550 If not NULL, the FSRef of the moved object
1551 will be returned in the FSRef.
1552 */
1553
1554 /*****************************************************************************/
1555
1556 #pragma mark ----- File ID Routines -----
1557
1558 /*****************************************************************************/
1559
1560 #pragma mark FSResolveFileIDRef
1561
1562 OSErr
1563 FSResolveFileIDRef(
1564 FSVolumeRefNum volRefNum,
1565 SInt32 fileID,
1566 FSRef *ref);
1567
1568 /*
1569 The FSResolveFileIDRef function returns an FSRef for the file with the
1570 specified file ID reference.
1571
1572 volRefNum --> Volume specification.
1573 fileID --> The file ID reference.
1574 ref <-- The FSRef for the file ID reference.
1575
1576 __________
1577
1578 Also see: FSCreateFileIDRef, FSDeleteFileIDRef
1579 */
1580
1581 /*****************************************************************************/
1582
1583 #pragma mark FSCreateFileIDRef
1584
1585 OSErr
1586 FSCreateFileIDRef(
1587 const FSRef *ref,
1588 SInt32 *fileID);
1589
1590 /*
1591 The FSCreateFileIDRef function creates a file ID reference for the
1592 specified file, or if a file ID reference already exists, supplies
1593 the file ID reference and returns the result code fidExists or afpIDExists.
1594
1595 ref --> The FSRef for the file.
1596 fileID <-- The file ID reference (if result is noErr,
1597 fidExists, or afpIDExists).
1598
1599 __________
1600
1601 Also see: GetFSRefFromFileIDRef, FSDeleteFileIDRef
1602 */
1603
1604 /*****************************************************************************/
1605
1606 #pragma mark FSDeleteFileIDRef
1607
1608 /*
1609 Why is there no FSDeleteFileIDRef routine? There are two reasons:
1610
1611 1. Since Mac OS 8.1, PBDeleteFileIDRef hasn't deleted file ID references.
1612 On HFS volumes, deleting a file ID reference breaks aliases (which
1613 use file ID references to track files as they are moved around on a
1614 volume) and file ID references are automatically deleted when the file
1615 they refer to is deleted. On HFS Plus volumes, file ID references are
1616 always created when a file is created, deleted when the file is deleted,
1617 and cannot be deleted at any other time.
1618
1619 2. PBDeleteFileIDRef causes a memory access fault under Mac OS X 10.0
1620 through 10.1.x. While this will be fixed in a future release, the
1621 implementation, like the Mac OS 8/9 implementation, does not delete
1622 file ID references.
1623
1624 __________
1625
1626 Also see: GetFSRefFromFileIDRef, FSCreateFileIDRef
1627 */
1628
1629 /*****************************************************************************/
1630
1631 #pragma mark ----- Utility Routines -----
1632
1633 /*****************************************************************************/
1634
1635 #pragma mark GetTempBuffer
1636
1637 Ptr
1638 GetTempBuffer(
1639 ByteCount buffReqSize,
1640 ByteCount *buffActSize);
1641
1642 /*
1643 The GetTempBuffer function allocates a temporary buffer for file system
1644 operations which is at least 4K bytes and a multiple of 4K bytes.
1645
1646 buffReqSize --> Size you'd like the buffer to be.
1647 buffActSize <-- The size of the buffer allocated.
1648 function result <-- Pointer to memory allocated, or NULL if no memory
1649 was available. The caller is responsible for
1650 disposing of this buffer with DisposePtr.
1651 */
1652
1653 /*****************************************************************************/
1654
1655 #pragma mark FileRefNumGetFSRef
1656
1657 OSErr
1658 FileRefNumGetFSRef(
1659 short refNum,
1660 FSRef *ref);
1661
1662 /*
1663 The FileRefNumGetFSRef function gets the FSRef of an open file.
1664
1665 refNum --> The file reference number of an open file.
1666 ref <-- The FSRef to the open file.
1667 */
1668
1669 /*****************************************************************************/
1670
1671 #pragma mark FSSetDefault
1672
1673 OSErr
1674 FSSetDefault(
1675 const FSRef *newDefault,
1676 FSRef *oldDefault);
1677
1678 /*
1679 The FSSetDefault function sets the current working directory to the
1680 directory specified by newDefault. The previous current working directory
1681 is returned in oldDefault and must be used to restore the current working
1682 directory to its previous state with the FSRestoreDefault function.
1683 These two functions are designed to be used as a wrapper around
1684 Standard I/O routines where the location of the file is implied to be the
1685 current working directory. This is how you should use these functions:
1686
1687 result = FSSetDefault(&newDefault, &oldDefault);
1688 if ( noErr == result )
1689 {
1690 // call the Stdio functions like remove, rename,
1691 // fopen, freopen, etc here!
1692
1693 result = FSRestoreDefault(&oldDefault);
1694 }
1695
1696 newDefault --> An FSRef that specifies the new current working
1697 directory.
1698 oldDefault <-- The previous current working directory's FSRef.
1699
1700 __________
1701
1702 Also see: FSRestoreDefault
1703 */
1704
1705 /*****************************************************************************/
1706
1707 #pragma mark FSRestoreDefault
1708
1709 OSErr
1710 FSRestoreDefault(
1711 const FSRef *oldDefault);
1712
1713 /*
1714 The FSRestoreDefault function restores the current working directory
1715 to the directory specified by oldDefault. The oldDefault parameter was
1716 previously obtained from the FSSetDefault function.
1717 These two functions are designed to be used as a wrapper around
1718 Standard I/O routines where the location of the file is implied to be the
1719 current working directory. This is how you should use these functions:
1720
1721 result = FSSetDefault(&newDefault, &oldDefault);
1722 if ( noErr == result )
1723 {
1724 // call the Stdio functions like remove, rename,
1725 // fopen, freopen, etc here!
1726
1727 result = FSRestoreDefault(&oldDefault);
1728 }
1729
1730 oldDefault --> The FSRef of the location to restore.
1731
1732 __________
1733
1734 Also see: FSSetDefault
1735 */
1736
1737 /*****************************************************************************/
1738
1739 #if PRAGMA_STRUCT_ALIGN
1740 #pragma options align=reset
1741 #elif PRAGMA_STRUCT_PACKPUSH
1742 #pragma pack(pop)
1743 #elif PRAGMA_STRUCT_PACK
1744 #pragma pack()
1745 #endif
1746
1747 #ifdef PRAGMA_IMPORT_OFF
1748 #pragma import off
1749 #elif PRAGMA_IMPORT
1750 #pragma import reset
1751 #endif
1752
1753 #ifdef __cplusplus
1754 }
1755 #endif
1756
1757 #endif /* __MOREFILESX__ */
1758
1759 |
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more information. |