MoreFilesX.h@ 2424

Last change on this file since 2424 was 589, checked in by vboxsync, 18 years ago
Make it build and run on Mac OS X.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 57.3 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/xpcom18a4/xpcom/MoreFiles/MoreFilesX.h@ 2424

Download in other formats: