MoreFilesX.h@ 78394

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

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

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

Download in other formats: