vfslowlevel.h@ 106814

Last change on this file since 106814 was 106061, checked in by vboxsync, 3 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 61.5 KB

Line
1	/** @file
2	* IPRT - Virtual Filesystem.
3	*/
4
5	/*
6	* Copyright (C) 2010-2024 Oracle and/or its affiliates.
7	*
8	* This file is part of VirtualBox base platform packages, as
9	* available from https://www.virtualbox.org.
10	*
11	* This program is free software; you can redistribute it and/or
12	* modify it under the terms of the GNU General Public License
13	* as published by the Free Software Foundation, in version 3 of the
14	* License.
15	*
16	* This program is distributed in the hope that it will be useful, but
17	* WITHOUT ANY WARRANTY; without even the implied warranty of
18	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19	* General Public License for more details.
20	*
21	* You should have received a copy of the GNU General Public License
22	* along with this program; if not, see <https://www.gnu.org/licenses>.
23	*
24	* The contents of this file may alternatively be used under the terms
25	* of the Common Development and Distribution License Version 1.0
26	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27	* in the VirtualBox distribution, in which case the provisions of the
28	* CDDL are applicable instead of those of the GPL.
29	*
30	* You may elect to license modified versions of this file under the
31	* terms and conditions of either the GPL or the CDDL or both.
32	*
33	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34	*/
35
36	#ifndef IPRT_INCLUDED_vfslowlevel_h
37	#define IPRT_INCLUDED_vfslowlevel_h
38	#ifndef RT_WITHOUT_PRAGMA_ONCE
39	# pragma once
40	#endif
41
42	#include <iprt/vfs.h>
43	#include <iprt/errcore.h>
44	#include <iprt/list.h>
45	#include <iprt/param.h>
46
47
48	RT_C_DECLS_BEGIN
49
50	/** @defgroup grp_rt_vfs_lowlevel RTVfs - Low-level Interface.
51	* @ingroup grp_rt_vfs
52	* @{
53	*/
54
55
56	/** @name VFS Lock Abstraction
57	* @todo This should be moved somewhere else as it is of general use.
58	* @{ */
59
60	/**
61	* VFS lock types.
62	*/
63	typedef enum RTVFSLOCKTYPE
64	{
65	/** Invalid lock type. */
66	RTVFSLOCKTYPE_INVALID = 0,
67	/** Read write semaphore. */
68	RTVFSLOCKTYPE_RW,
69	/** Fast mutex semaphore (critical section in ring-3). */
70	RTVFSLOCKTYPE_FASTMUTEX,
71	/** Full fledged mutex semaphore. */
72	RTVFSLOCKTYPE_MUTEX,
73	/** The end of valid lock types. */
74	RTVFSLOCKTYPE_END,
75	/** The customary 32-bit type hack. */
76	RTVFSLOCKTYPE_32BIT_HACK = 0x7fffffff
77	} RTVFSLOCKTYPE;
78
79	/** VFS lock handle. */
80	typedef struct RTVFSLOCKINTERNAL *RTVFSLOCK;
81	/** Pointer to a VFS lock handle. */
82	typedef RTVFSLOCK *PRTVFSLOCK;
83	/** Nil VFS lock handle. */
84	#define NIL_RTVFSLOCK ((RTVFSLOCK)~(uintptr_t)0)
85
86	/** Special handle value for creating a new read/write semaphore based lock. */
87	#define RTVFSLOCK_CREATE_RW ((RTVFSLOCK)~(uintptr_t)1)
88	/** Special handle value for creating a new fast mutex semaphore based lock. */
89	#define RTVFSLOCK_CREATE_FASTMUTEX ((RTVFSLOCK)~(uintptr_t)2)
90	/** Special handle value for creating a new mutex semaphore based lock. */
91	#define RTVFSLOCK_CREATE_MUTEX ((RTVFSLOCK)~(uintptr_t)3)
92
93	/**
94	* Retains a reference to the VFS lock handle.
95	*
96	* @returns New reference count on success, UINT32_MAX on failure.
97	* @param hLock The VFS lock handle.
98	*/
99	RTDECL(uint32_t) RTVfsLockRetain(RTVFSLOCK hLock);
100
101	/**
102	* Releases a reference to the VFS lock handle.
103	*
104	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
105	* @param hLock The VFS lock handle.
106	*/
107	RTDECL(uint32_t) RTVfsLockRelease(RTVFSLOCK hLock);
108
109	/**
110	* Gets the lock type.
111	*
112	* @returns The lock type on success, RTVFSLOCKTYPE_INVALID if the handle is
113	* not valid.
114	* @param hLock The lock handle.
115	*/
116	RTDECL(RTVFSLOCKTYPE) RTVfsLockGetType(RTVFSLOCK hLock);
117
118
119
120	RTDECL(void) RTVfsLockAcquireReadSlow(RTVFSLOCK hLock);
121	RTDECL(void) RTVfsLockReleaseReadSlow(RTVFSLOCK hLock);
122	RTDECL(void) RTVfsLockAcquireWriteSlow(RTVFSLOCK hLock);
123	RTDECL(void) RTVfsLockReleaseWriteSlow(RTVFSLOCK hLock);
124
125	/**
126	* Acquire a read lock.
127	*
128	* @param hLock The lock handle, can be NIL.
129	*/
130	DECLINLINE(void) RTVfsLockAcquireRead(RTVFSLOCK hLock)
131	{
132	if (hLock != NIL_RTVFSLOCK)
133	RTVfsLockAcquireReadSlow(hLock);
134	}
135
136
137	/**
138	* Release a read lock.
139	*
140	* @param hLock The lock handle, can be NIL.
141	*/
142	DECLINLINE(void) RTVfsLockReleaseRead(RTVFSLOCK hLock)
143	{
144	if (hLock != NIL_RTVFSLOCK)
145	RTVfsLockReleaseReadSlow(hLock);
146	}
147
148
149	/**
150	* Acquire a write lock.
151	*
152	* @param hLock The lock handle, can be NIL.
153	*/
154	DECLINLINE(void) RTVfsLockAcquireWrite(RTVFSLOCK hLock)
155	{
156	if (hLock != NIL_RTVFSLOCK)
157	RTVfsLockAcquireWriteSlow(hLock);
158	}
159
160
161	/**
162	* Release a write lock.
163	*
164	* @param hLock The lock handle, can be NIL.
165	*/
166	DECLINLINE(void) RTVfsLockReleaseWrite(RTVFSLOCK hLock)
167	{
168	if (hLock != NIL_RTVFSLOCK)
169	RTVfsLockReleaseWriteSlow(hLock);
170	}
171
172	/** @} */
173
174	/**
175	* Info queried via RTVFSOBJOPS::pfnQueryInfoEx, ++.
176	*/
177	typedef enum RTVFSQIEX
178	{
179	/** Invalid zero value. */
180	RTVFSQIEX_INVALID = 0,
181	/** Volume label.
182	* Returns a UTF-8 string. */
183	RTVFSQIEX_VOL_LABEL,
184	/** Alternative volume label, the primary one for ISOs, otherwise treated same
185	* as RTVFSQIEX_VOL_LABEL. */
186	RTVFSQIEX_VOL_LABEL_ALT,
187	/** Volume serial number.
188	* Returns a uint32_t, uint64_t or RTUUID. */
189	RTVFSQIEX_VOL_SERIAL,
190	/** End of valid queries. */
191	RTVFSQIEX_END,
192
193	/** The usual 32-bit hack. */
194	RTVFSQIEX_32BIT_SIZE_HACK = 0x7fffffff
195	} RTVFSQIEX;
196
197
198	/**
199	* The basis for all virtual file system objects.
200	*/
201	typedef struct RTVFSOBJOPS
202	{
203	/** The structure version (RTVFSOBJOPS_VERSION). */
204	uint32_t uVersion;
205	/** The object type for type introspection. */
206	RTVFSOBJTYPE enmType;
207	/** The name of the operations. */
208	const char *pszName;
209
210	/**
211	* Close the object.
212	*
213	* @returns IPRT status code.
214	* @param pvThis The implementation specific file data.
215	*/
216	DECLCALLBACKMEMBER(int, pfnClose,(void *pvThis));
217
218	/**
219	* Get information about the file.
220	*
221	* @returns IPRT status code. See RTVfsObjQueryInfo.
222	* @retval VERR_WRONG_TYPE if file system or file system stream.
223	*
224	* @param pvThis The implementation specific file data.
225	* @param pObjInfo Where to return the object info on success.
226	* @param enmAddAttr Which set of additional attributes to request.
227	* @sa RTVfsObjQueryInfo, RTFileQueryInfo, RTPathQueryInfo
228	*/
229	DECLCALLBACKMEMBER(int, pfnQueryInfo,(void *pvThis, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr));
230
231	/**
232	* Query arbritray information about the file, volume, or whatever.
233	*
234	* @returns IPRT status code.
235	* @retval VERR_BUFFER_OVERFLOW sets pcbRet.
236	*
237	* @param pvThis The implementation specific file data.
238	* @param enmInfo The information being queried.
239	* @param pvInfo Where to return the info.
240	* @param cbInfo The size of the @a pvInfo buffer.
241	* @param pcbRet The size of the returned data. In case of
242	* VERR_BUFFER_OVERFLOW this will be set to the required
243	* buffer size.
244	*/
245	DECLCALLBACKMEMBER(int, pfnQueryInfoEx,(void pvThis, RTVFSQIEX enmInfo, void pvInfo, size_t cbInfo, size_t *pcbRet));
246
247	/** Marks the end of the structure (RTVFSOBJOPS_VERSION). */
248	uintptr_t uEndMarker;
249	} RTVFSOBJOPS;
250	/** Pointer to constant VFS object operations. */
251	typedef RTVFSOBJOPS const *PCRTVFSOBJOPS;
252
253	/** The RTVFSOBJOPS structure version. */
254	#define RTVFSOBJOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x1f,2,0)
255
256
257	/**
258	* The VFS operations.
259	*/
260	typedef struct RTVFSOPS
261	{
262	/** The basic object operation. */
263	RTVFSOBJOPS Obj;
264	/** The structure version (RTVFSOPS_VERSION). */
265	uint32_t uVersion;
266	/** The virtual file system feature mask. */
267	uint32_t fFeatures;
268
269	/**
270	* Opens the root directory.
271	*
272	* @returns IPRT status code.
273	* @param pvThis The implementation specific data.
274	* @param phVfsDir Where to return the handle to the root directory.
275	*/
276	DECLCALLBACKMEMBER(int, pfnOpenRoot,(void *pvThis, PRTVFSDIR phVfsDir));
277
278	/**
279	* Query the status of the given storage range (optional).
280	*
281	* This can be used by the image compaction utilites to evict non-zero blocks
282	* that aren't currently being used by the file system.
283	*
284	* @returns IPRT status code.
285	* @param pvThis The implementation specific data.
286	* @param off Start offset to check.
287	* @param cb Number of bytes to check.
288	* @param pfUsed Where to store whether the given range is in use.
289	*/
290	DECLCALLBACKMEMBER(int, pfnQueryRangeState,(void pvThis, uint64_t off, size_t cb, bool pfUsed));
291
292	/** @todo There will be more methods here to optimize opening and
293	* querying. */
294
295	#if 0
296	/**
297	* Optional entry point for optimizing path traversal within the file system.
298	*
299	* @returns IPRT status code.
300	* @param pvThis The implementation specific data.
301	* @param pszPath The path to resolve.
302	* @param poffPath The current path offset on input, what we've
303	* traversed to on successful return.
304	* @param phVfs??? Return handle to what we've traversed.
305	* @param p??? Return other stuff...
306	*/
307	DECLCALLBACKMEMBER(int, pfnTraverse,(void pvThis, const char pszPath, size_t poffPath, PRTVFS??? phVfs?, ??? p???));
308	#endif
309
310	/** @todo need rename API */
311
312	/** Marks the end of the structure (RTVFSOPS_VERSION). */
313	uintptr_t uEndMarker;
314	} RTVFSOPS;
315	/** Pointer to constant VFS operations. */
316	typedef RTVFSOPS const *PCRTVFSOPS;
317
318	/** The RTVFSOPS structure version. */
319	#define RTVFSOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x0f,1,0)
320
321	/** @name RTVFSOPS::fFeatures
322	* @{ */
323	/** The VFS supports attaching other systems. */
324	#define RTVFSOPS_FEAT_ATTACH RT_BIT_32(0)
325	/** @} */
326
327	/**
328	* Creates a new VFS handle.
329	*
330	* @returns IPRT status code
331	* @param pVfsOps The VFS operations.
332	* @param cbInstance The size of the instance data.
333	* @param hVfs The VFS handle to associate this VFS with.
334	* NIL_VFS is ok.
335	* @param hLock Handle to a custom lock to be used with the new
336	* object. The reference is consumed. NIL and
337	* special lock handles are fine.
338	* @param phVfs Where to return the new handle.
339	* @param ppvInstance Where to return the pointer to the instance data
340	* (size is @a cbInstance).
341	*/
342	RTDECL(int) RTVfsNew(PCRTVFSOPS pVfsOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
343	PRTVFS phVfs, void **ppvInstance);
344
345
346	/**
347	* Creates a new VFS base object handle.
348	*
349	* @returns IPRT status code
350	* @param pObjOps The base object operations.
351	* @param cbInstance The size of the instance data.
352	* @param hVfs The VFS handle to associate this base object
353	* with. NIL_VFS is ok.
354	* @param hLock Handle to a custom lock to be used with the new
355	* object. The reference is consumed. NIL and
356	* special lock handles are fine.
357	* @param phVfsObj Where to return the new handle.
358	* @param ppvInstance Where to return the pointer to the instance data
359	* (size is @a cbInstance).
360	*/
361	RTDECL(int) RTVfsNewBaseObj(PCRTVFSOBJOPS pObjOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
362	PRTVFSOBJ phVfsObj, void **ppvInstance);
363
364
365	/**
366	* Gets the private data of a base object.
367	*
368	* @returns Pointer to the private data. NULL if the handle is invalid in some
369	* way.
370	* @param hVfsObj The I/O base object handle.
371	* @param pObjOps The base object operations. This servers as a
372	* sort of password.
373	*/
374	RTDECL(void *) RTVfsObjToPrivate(RTVFSOBJ hVfsObj, PCRTVFSOBJOPS pObjOps);
375
376	/**
377	* Additional operations for setting object attributes.
378	*/
379	typedef struct RTVFSOBJSETOPS
380	{
381	/** The structure version (RTVFSOBJSETOPS_VERSION). */
382	uint32_t uVersion;
383	/** The offset back to the RTVFSOBJOPS structure. */
384	uint32_t offObjOps;
385
386	/**
387	* Set the unix style owner and group.
388	*
389	* @returns IPRT status code.
390	* @param pvThis The implementation specific file data.
391	* @param fMode The new mode bits.
392	* @param fMask The mask indicating which bits we are
393	* changing.
394	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
395	* @sa RTFileSetMode
396	*/
397	DECLCALLBACKMEMBER(int, pfnSetMode,(void *pvThis, RTFMODE fMode, RTFMODE fMask));
398
399	/**
400	* Set the timestamps associated with the object.
401	*
402	* @returns IPRT status code.
403	* @param pvThis The implementation specific file data.
404	* @param pAccessTime Pointer to the new access time. NULL if not
405	* to be changed.
406	* @param pModificationTime Pointer to the new modifcation time. NULL if
407	* not to be changed.
408	* @param pChangeTime Pointer to the new change time. NULL if not
409	* to be changed.
410	* @param pBirthTime Pointer to the new time of birth. NULL if
411	* not to be changed.
412	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
413	* host OS or underlying VFS provider.
414	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
415	* @sa RTFileSetTimes
416	*/
417	DECLCALLBACKMEMBER(int, pfnSetTimes,(void *pvThis, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
418	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime));
419
420	/**
421	* Set the unix style owner and group.
422	*
423	* @returns IPRT status code.
424	* @param pvThis The implementation specific file data.
425	* @param uid The user ID of the new owner. NIL_RTUID if
426	* unchanged.
427	* @param gid The group ID of the new owner group. NIL_RTGID if
428	* unchanged.
429	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
430	* @sa RTFileSetOwner
431	*/
432	DECLCALLBACKMEMBER(int, pfnSetOwner,(void *pvThis, RTUID uid, RTGID gid));
433
434	/** Marks the end of the structure (RTVFSOBJSETOPS_VERSION). */
435	uintptr_t uEndMarker;
436	} RTVFSOBJSETOPS;
437	/** Pointer to const object attribute setter operations. */
438	typedef RTVFSOBJSETOPS const *PCRTVFSOBJSETOPS;
439
440	/** The RTVFSOBJSETOPS structure version. */
441	#define RTVFSOBJSETOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x2f,1,0)
442
443
444	/**
445	* The filesystem stream operations.
446	*
447	* @extends RTVFSOBJOPS
448	*/
449	typedef struct RTVFSFSSTREAMOPS
450	{
451	/** The basic object operation. */
452	RTVFSOBJOPS Obj;
453	/** The structure version (RTVFSFSSTREAMOPS_VERSION). */
454	uint32_t uVersion;
455	/** Reserved field, MBZ. */
456	uint32_t fReserved;
457
458	/**
459	* Gets the next object in the stream.
460	*
461	* Readable streams only.
462	*
463	* @returns IPRT status code.
464	* @retval VINF_SUCCESS if a new object was retrieved.
465	* @retval VERR_EOF when there are no more objects.
466	* @param pvThis The implementation specific directory data.
467	* @param ppszName Where to return the object name. Must be freed by
468	* calling RTStrFree.
469	* @param penmType Where to return the object type.
470	* @param phVfsObj Where to return the object handle (referenced). This
471	* must be cast to the desired type before use.
472	* @sa RTVfsFsStrmNext
473	*
474	* @note Setting this member to NULL is okay for write-only streams.
475	*/
476	DECLCALLBACKMEMBER(int, pfnNext,(void pvThis, char ppszName, RTVFSOBJTYPE penmType, PRTVFSOBJ phVfsObj));
477
478	/**
479	* Adds another object into the stream.
480	*
481	* Writable streams only.
482	*
483	* @returns IPRT status code.
484	* @param pvThis The implementation specific directory data.
485	* @param pszPath The path to the object.
486	* @param hVfsObj The object to add.
487	* @param fFlags Reserved for the future, MBZ.
488	* @sa RTVfsFsStrmAdd
489	*
490	* @note Setting this member to NULL is okay for read-only streams.
491	*/
492	DECLCALLBACKMEMBER(int, pfnAdd,(void pvThis, const char pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags));
493
494	/**
495	* Pushes an byte stream onto the stream (optional).
496	*
497	* Writable streams only.
498	*
499	* This differs from RTVFSFSSTREAMOPS::pfnAdd() in that it will create a regular
500	* file in the output file system stream and provide the actual content bytes
501	* via the returned I/O stream object.
502	*
503	* @returns IPRT status code.
504	* @param pvThis The implementation specific directory data.
505	* @param pszPath The path to the file.
506	* @param cbFile The file size. This can also be set to UINT64_MAX if
507	* the file system stream is backed by a file.
508	* @param paObjInfo Array of zero or more RTFSOBJINFO structures containing
509	* different pieces of information about the file. If any
510	* provided, the first one should be a RTFSOBJATTRADD_UNIX
511	* one, additional can be supplied if wanted. What exactly
512	* is needed depends on the underlying FS stream
513	* implementation.
514	* @param cObjInfo Number of items in the array @a paObjInfo points at.
515	* @param fFlags RTVFSFSSTRM_PUSH_F_XXX.
516	* @param phVfsIos Where to return the I/O stream to feed the file content
517	* to. If the FS stream is backed by a file, the returned
518	* handle can be cast to a file if necessary.
519	*/
520	DECLCALLBACKMEMBER(int, pfnPushFile,(void pvThis, const char pszPath, uint64_t cbFile,
521	PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos));
522
523	/**
524	* Marks the end of the stream.
525	*
526	* Writable streams only.
527	*
528	* @returns IPRT status code.
529	* @param pvThis The implementation specific directory data.
530	* @sa RTVfsFsStrmEnd
531	*
532	* @note Setting this member to NULL is okay for read-only streams.
533	*/
534	DECLCALLBACKMEMBER(int, pfnEnd,(void *pvThis));
535
536	/** Marks the end of the structure (RTVFSFSSTREAMOPS_VERSION). */
537	uintptr_t uEndMarker;
538	} RTVFSFSSTREAMOPS;
539	/** Pointer to const object attribute setter operations. */
540	typedef RTVFSFSSTREAMOPS const *PCRTVFSFSSTREAMOPS;
541
542	/** The RTVFSFSSTREAMOPS structure version. */
543	#define RTVFSFSSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x3f,2,0)
544
545
546	/**
547	* Creates a new VFS filesystem stream handle.
548	*
549	* @returns IPRT status code
550	* @param pFsStreamOps The filesystem stream operations.
551	* @param cbInstance The size of the instance data.
552	* @param hVfs The VFS handle to associate this filesystem
553	* stream with. NIL_VFS is ok.
554	* @param hLock Handle to a custom lock to be used with the new
555	* object. The reference is consumed. NIL and
556	* special lock handles are fine.
557	* @param fAccess RTFILE_O_READ and/or RTFILE_O_WRITE.
558	* @param phVfsFss Where to return the new handle.
559	* @param ppvInstance Where to return the pointer to the instance data
560	* (size is @a cbInstance).
561	*/
562	RTDECL(int) RTVfsNewFsStream(PCRTVFSFSSTREAMOPS pFsStreamOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock, uint32_t fAccess,
563	PRTVFSFSSTREAM phVfsFss, void **ppvInstance);
564
565	/**
566	* Gets the private data of an filesystem stream.
567	*
568	* @returns Pointer to the private data. NULL if the handle is invalid in some
569	* way.
570	* @param hVfsFss The FS stream handle.
571	* @param pFsStreamOps The FS stream operations. This servers as a
572	* sort of password.
573	*/
574	RTDECL(void *) RTVfsFsStreamToPrivate(RTVFSFSSTREAM hVfsFss, PCRTVFSFSSTREAMOPS pFsStreamOps);
575
576
577	/**
578	* The directory operations.
579	*
580	* @extends RTVFSOBJOPS
581	* @extends RTVFSOBJSETOPS
582	*/
583	typedef struct RTVFSDIROPS
584	{
585	/** The basic object operation. */
586	RTVFSOBJOPS Obj;
587	/** The structure version (RTVFSDIROPS_VERSION). */
588	uint32_t uVersion;
589	/** Reserved field, MBZ. */
590	uint32_t fReserved;
591	/** The object setter operations. */
592	RTVFSOBJSETOPS ObjSet;
593
594	/**
595	* Generic method for opening any kind of file system object.
596	*
597	* Can also create files and directories. Symbolic links, devices and such
598	* needs to be created using special methods or this would end up being way more
599	* complicated than it already is.
600	*
601	* There are optional specializations available.
602	*
603	* @returns IPRT status code.
604	* @retval VERR_PATH_NOT_FOUND or VERR_FILE_NOT_FOUND if @a pszEntry was not
605	* found.
606	* @retval VERR_IS_A_FILE if @a pszEntry is a file or similar but @a fFlags
607	* indicates that the type of object should not be opened.
608	* @retval VERR_IS_A_DIRECTORY if @a pszEntry is a directory but @a fFlags
609	* indicates that directories should not be opened.
610	* @retval VERR_IS_A_SYMLINK if @a pszEntry is a symbolic link but @a fFlags
611	* indicates that symbolic links should not be opened (or followed).
612	* @retval VERR_IS_A_FIFO if @a pszEntry is a FIFO but @a fFlags indicates that
613	* FIFOs should not be opened.
614	* @retval VERR_IS_A_SOCKET if @a pszEntry is a socket but @a fFlags indicates
615	* that sockets should not be opened.
616	* @retval VERR_IS_A_BLOCK_DEVICE if @a pszEntry is a block device but
617	* @a fFlags indicates that block devices should not be opened, or vice
618	* versa.
619	*
620	* @param pvThis The implementation specific directory data.
621	* @param pszEntry The name of the immediate file to open or create.
622	* @param fOpenFile RTFILE_O_XXX combination.
623	* @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
624	* The meaning of RTPATH_F_FOLLOW_LINK differs here, if
625	* @a pszEntry is a symlink it should be opened for
626	* traversal rather than according to @a fOpenFile.
627	* @param phVfsObj Where to return the handle to the opened object.
628	* @sa RTFileOpen, RTDirOpen
629	*/
630	DECLCALLBACKMEMBER(int, pfnOpen,(void pvThis, const char pszEntry, uint64_t fOpenFile,
631	uint32_t fObjFlags, PRTVFSOBJ phVfsObj));
632
633	/**
634	* Optional method for symbolic link handling in the vfsstddir.cpp.
635	*
636	* This is really just a hack to make symbolic link handling work when working
637	* with directory objects that doesn't have an associated VFS. It also helps
638	* deal with drive letters in symbolic links on Windows and OS/2.
639	*
640	* @returns IPRT status code.
641	* @retval VERR_PATH_IS_RELATIVE if @a pszPath isn't absolute and should be
642	* handled using pfnOpen().
643	*
644	* @param pvThis The implementation specific directory data.
645	* @param pszRoot Path to the alleged root.
646	* @param phVfsDir Where to return the handle to the specified root
647	* directory (or may current dir on a drive letter).
648	*/
649	DECLCALLBACKMEMBER(int, pfnFollowAbsoluteSymlink,(void pvThis, const char pszRoot, PRTVFSDIR phVfsDir));
650
651	/**
652	* Open or create a file.
653	*
654	* @returns IPRT status code.
655	* @param pvThis The implementation specific directory data.
656	* @param pszFilename The name of the immediate file to open or create.
657	* @param fOpen The open flags (RTFILE_O_XXX).
658	* @param phVfsFile Where to return the handle to the opened file.
659	* @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
660	* @sa RTFileOpen.
661	*/
662	DECLCALLBACKMEMBER(int, pfnOpenFile,(void pvThis, const char pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile));
663
664	/**
665	* Open an existing subdirectory.
666	*
667	* @returns IPRT status code.
668	* @retval VERR_IS_A_SYMLINK if @a pszSubDir is a symbolic link.
669	* @retval VERR_NOT_A_DIRECTORY is okay for symbolic links too.
670	*
671	* @param pvThis The implementation specific directory data.
672	* @param pszSubDir The name of the immediate subdirectory to open.
673	* @param fFlags RTDIR_F_XXX.
674	* @param phVfsDir Where to return the handle to the opened directory.
675	* Optional.
676	* @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
677	* @sa RTDirOpen.
678	*/
679	DECLCALLBACKMEMBER(int, pfnOpenDir,(void pvThis, const char pszSubDir, uint32_t fFlags, PRTVFSDIR phVfsDir));
680
681	/**
682	* Creates a new subdirectory.
683	*
684	* @returns IPRT status code.
685	* @param pvThis The implementation specific directory data.
686	* @param pszSubDir The name of the immediate subdirectory to create.
687	* @param fMode The mode mask of the new directory.
688	* @param phVfsDir Where to optionally return the handle to the newly
689	* create directory.
690	* @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
691	* @sa RTDirCreate.
692	*/
693	DECLCALLBACKMEMBER(int, pfnCreateDir,(void pvThis, const char pszSubDir, RTFMODE fMode, PRTVFSDIR phVfsDir));
694
695	/**
696	* Opens an existing symbolic link.
697	*
698	* @returns IPRT status code.
699	* @param pvThis The implementation specific directory data.
700	* @param pszSymlink The name of the immediate symbolic link to open.
701	* @param phVfsSymlink Where to optionally return the handle to the
702	* newly create symbolic link.
703	* @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
704	* @sa RTSymlinkCreate.
705	*/
706	DECLCALLBACKMEMBER(int, pfnOpenSymlink,(void pvThis, const char pszSymlink, PRTVFSSYMLINK phVfsSymlink));
707
708	/**
709	* Creates a new symbolic link.
710	*
711	* @returns IPRT status code.
712	* @param pvThis The implementation specific directory data.
713	* @param pszSymlink The name of the immediate symbolic link to create.
714	* @param pszTarget The symbolic link target.
715	* @param enmType The symbolic link type.
716	* @param phVfsSymlink Where to optionally return the handle to the
717	* newly create symbolic link.
718	* @sa RTSymlinkCreate.
719	*/
720	DECLCALLBACKMEMBER(int, pfnCreateSymlink,(void pvThis, const char pszSymlink, const char *pszTarget,
721	RTSYMLINKTYPE enmType, PRTVFSSYMLINK phVfsSymlink));
722
723	/**
724	* Query information about an entry.
725	*
726	* @returns IPRT status code.
727	* @param pvThis The implementation specific directory data.
728	* @param pszEntry The name of the directory entry to remove.
729	* @param pObjInfo Where to return the info on success.
730	* @param enmAddAttr Which set of additional attributes to request.
731	* @note Optional. RTVFSDIROPS::pfnOpenObj and RTVFSOBJOPS::pfnQueryInfo
732	* will be used if NULL.
733	* @sa RTPathQueryInfo, RTVFSOBJOPS::pfnQueryInfo
734	*/
735	DECLCALLBACKMEMBER(int, pfnQueryEntryInfo,(void pvThis, const char pszEntry,
736	PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr));
737
738	/**
739	* Removes a directory entry.
740	*
741	* @returns IPRT status code.
742	* @param pvThis The implementation specific directory data.
743	* @param pszEntry The name of the directory entry to remove.
744	* @param fType If non-zero, this restricts the type of the entry to
745	* the object type indicated by the mask
746	* (RTFS_TYPE_XXX).
747	* @sa RTFileRemove, RTDirRemove, RTSymlinkRemove.
748	*/
749	DECLCALLBACKMEMBER(int, pfnUnlinkEntry,(void pvThis, const char pszEntry, RTFMODE fType));
750
751	/**
752	* Renames a directory entry.
753	*
754	* @returns IPRT status code.
755	* @param pvThis The implementation specific directory data.
756	* @param pszEntry The name of the directory entry to rename.
757	* @param fType If non-zero, this restricts the type of the entry to
758	* the object type indicated by the mask
759	* (RTFS_TYPE_XXX).
760	* @param pszNewName The new entry name.
761	* @sa RTPathRename
762	*
763	* @todo This API is not flexible enough, must be able to rename between
764	* directories within a file system.
765	*/
766	DECLCALLBACKMEMBER(int, pfnRenameEntry,(void pvThis, const char pszEntry, RTFMODE fType, const char *pszNewName));
767
768	/**
769	* Rewind the directory stream so that the next read returns the first
770	* entry.
771	*
772	* @returns IPRT status code.
773	* @param pvThis The implementation specific directory data.
774	*/
775	DECLCALLBACKMEMBER(int, pfnRewindDir,(void *pvThis));
776
777	/**
778	* Rewind the directory stream so that the next read returns the first
779	* entry.
780	*
781	* @returns IPRT status code.
782	* @param pvThis The implementation specific directory data.
783	* @param pDirEntry Output buffer.
784	* @param pcbDirEntry Complicated, see RTDirReadEx.
785	* @param enmAddAttr Which set of additional attributes to request.
786	* @sa RTDirReadEx
787	*/
788	DECLCALLBACKMEMBER(int, pfnReadDir,(void pvThis, PRTDIRENTRYEX pDirEntry, size_t pcbDirEntry, RTFSOBJATTRADD enmAddAttr));
789
790	/** Marks the end of the structure (RTVFSDIROPS_VERSION). */
791	uintptr_t uEndMarker;
792	} RTVFSDIROPS;
793	/** Pointer to const directory operations. */
794	typedef RTVFSDIROPS const *PCRTVFSDIROPS;
795	/** The RTVFSDIROPS structure version. */
796	#define RTVFSDIROPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x4f,1,0)
797
798
799	/**
800	* Creates a new VFS directory handle.
801	*
802	* @returns IPRT status code
803	* @param pDirOps The directory operations.
804	* @param cbInstance The size of the instance data.
805	* @param fFlags RTVFSDIR_F_XXX
806	* @param hVfs The VFS handle to associate this directory with.
807	* NIL_VFS is ok.
808	* @param hLock Handle to a custom lock to be used with the new
809	* object. The reference is consumed. NIL and
810	* special lock handles are fine.
811	* @param phVfsDir Where to return the new handle.
812	* @param ppvInstance Where to return the pointer to the instance data
813	* (size is @a cbInstance).
814	*/
815	RTDECL(int) RTVfsNewDir(PCRTVFSDIROPS pDirOps, size_t cbInstance, uint32_t fFlags, RTVFS hVfs, RTVFSLOCK hLock,
816	PRTVFSDIR phVfsDir, void **ppvInstance);
817
818	/** @name RTVFSDIR_F_XXX
819	* @{ */
820	/** Don't reference the @a hVfs parameter passed to RTVfsNewDir.
821	* This is a permanent root directory hack. */
822	#define RTVFSDIR_F_NO_VFS_REF RT_BIT_32(0)
823	/** @} */
824
825	/**
826	* Gets the private data of a directory.
827	*
828	* @returns Pointer to the private data. NULL if the handle is invalid in some
829	* way.
830	* @param hVfsDir The directory handle.
831	* @param pDirOps The directory operations. This servers as a
832	* sort of password.
833	*/
834	RTDECL(void *) RTVfsDirToPrivate(RTVFSDIR hVfsDir, PCRTVFSDIROPS pDirOps);
835
836
837	/**
838	* The symbolic link operations.
839	*
840	* @extends RTVFSOBJOPS
841	* @extends RTVFSOBJSETOPS
842	*/
843	typedef struct RTVFSSYMLINKOPS
844	{
845	/** The basic object operation. */
846	RTVFSOBJOPS Obj;
847	/** The structure version (RTVFSSYMLINKOPS_VERSION). */
848	uint32_t uVersion;
849	/** Reserved field, MBZ. */
850	uint32_t fReserved;
851	/** The object setter operations. */
852	RTVFSOBJSETOPS ObjSet;
853
854	/**
855	* Read the symbolic link target.
856	*
857	* @returns IPRT status code.
858	* @param pvThis The implementation specific symbolic link data.
859	* @param pszTarget The target buffer.
860	* @param cbTarget The size of the target buffer.
861	* @sa RTSymlinkRead
862	*/
863	DECLCALLBACKMEMBER(int, pfnRead,(void pvThis, char pszTarget, size_t cbTarget));
864
865	/** Marks the end of the structure (RTVFSSYMLINKOPS_VERSION). */
866	uintptr_t uEndMarker;
867	} RTVFSSYMLINKOPS;
868	/** Pointer to const symbolic link operations. */
869	typedef RTVFSSYMLINKOPS const *PCRTVFSSYMLINKOPS;
870	/** The RTVFSSYMLINKOPS structure version. */
871	#define RTVFSSYMLINKOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x5f,1,0)
872
873
874	/**
875	* Creates a new VFS symlink handle.
876	*
877	* @returns IPRT status code
878	* @param pSymlinkOps The symlink operations.
879	* @param cbInstance The size of the instance data.
880	* @param hVfs The VFS handle to associate this symlink object
881	* with. NIL_VFS is ok.
882	* @param hLock Handle to a custom lock to be used with the new
883	* object. The reference is consumed. NIL and
884	* special lock handles are fine.
885	* @param phVfsSym Where to return the new handle.
886	* @param ppvInstance Where to return the pointer to the instance data
887	* (size is @a cbInstance).
888	*/
889	RTDECL(int) RTVfsNewSymlink(PCRTVFSSYMLINKOPS pSymlinkOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
890	PRTVFSSYMLINK phVfsSym, void **ppvInstance);
891
892
893	/**
894	* Gets the private data of a symbolic link.
895	*
896	* @returns Pointer to the private data. NULL if the handle is invalid in some
897	* way.
898	* @param hVfsSym The symlink handle.
899	* @param pSymlinkOps The symlink operations. This servers as a sort
900	* of password.
901	*/
902	RTDECL(void *) RTVfsSymlinkToPrivate(RTVFSSYMLINK hVfsSym, PCRTVFSSYMLINKOPS pSymlinkOps);
903
904	/**
905	* The basis for all I/O objects (files, pipes, sockets, devices, ++).
906	*
907	* @extends RTVFSOBJOPS
908	*/
909	typedef struct RTVFSIOSTREAMOPS
910	{
911	/** The basic object operation. */
912	RTVFSOBJOPS Obj;
913	/** The structure version (RTVFSIOSTREAMOPS_VERSION). */
914	uint32_t uVersion;
915	/** Feature field. */
916	uint32_t fFeatures;
917
918	/**
919	* Reads from the file/stream.
920	*
921	* @returns IPRT status code. See RTVfsIoStrmRead.
922	* @param pvThis The implementation specific file data.
923	* @param off Where to read at, -1 for the current position.
924	* @param pSgBuf Gather buffer for the bytes that are to be read.
925	* @param fBlocking If @c true, the call is blocking, if @c false it
926	* should not block.
927	* @param pcbRead Where return the number of bytes actually read.
928	* This is set it 0 by the caller. If NULL, try read
929	* all and fail if incomplete.
930	* @sa RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
931	* RTVfsFileReadAt, RTFileRead, RTFileReadAt.
932	*/
933	DECLCALLBACKMEMBER(int, pfnRead,(void pvThis, RTFOFF off, PRTSGBUF pSgBuf, bool fBlocking, size_t pcbRead));
934
935	/**
936	* Writes to the file/stream.
937	*
938	* @returns IPRT status code.
939	* @param pvThis The implementation specific file data.
940	* @param off Where to start wrinting, -1 for the current
941	* position.
942	* @param pSgBuf Gather buffers describing the bytes that are to be
943	* written.
944	* @param fBlocking If @c true, the call is blocking, if @c false it
945	* should not block.
946	* @param pcbWritten Where to return the number of bytes actually
947	* written. This is set it 0 by the caller. If
948	* NULL, try write it all and fail if incomplete.
949	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
950	* @sa RTFileWrite, RTFileWriteAt.
951	*/
952	DECLCALLBACKMEMBER(int, pfnWrite,(void pvThis, RTFOFF off, PRTSGBUF pSgBuf, bool fBlocking, size_t pcbWritten));
953
954	/**
955	* Flushes any pending data writes to the stream.
956	*
957	* @returns IPRT status code.
958	* @param pvThis The implementation specific file data.
959	* @sa RTFileFlush.
960	*/
961	DECLCALLBACKMEMBER(int, pfnFlush,(void *pvThis));
962
963	/**
964	* Poll for events.
965	*
966	* @returns IPRT status code.
967	* @param pvThis The implementation specific file data.
968	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
969	* @param cMillies How long to wait for event to eventuate.
970	* @param fIntr Whether the wait is interruptible and can return
971	* VERR_INTERRUPTED (@c true) or if this condition
972	* should be hidden from the caller (@c false).
973	* @param pfRetEvents Where to return the event mask.
974	* @note Optional. If NULL, immediately return all requested non-error
975	* events, waiting for errors works like sleep.
976	* @sa RTPollSetAdd, RTPoll, RTPollNoResume.
977	*/
978	DECLCALLBACKMEMBER(int, pfnPollOne,(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
979	uint32_t *pfRetEvents));
980
981	/**
982	* Tells the current file/stream position.
983	*
984	* @returns IPRT status code.
985	* @param pvThis The implementation specific file data.
986	* @param poffActual Where to return the actual offset.
987	* @sa RTFileTell
988	*/
989	DECLCALLBACKMEMBER(int, pfnTell,(void *pvThis, PRTFOFF poffActual));
990
991	/**
992	* Skips @a cb ahead in the stream.
993	*
994	* @returns IPRT status code.
995	* @param pvThis The implementation specific file data.
996	* @param cb The number bytes to skip.
997	* @remarks This is optional and can be NULL.
998	*/
999	DECLCALLBACKMEMBER(int, pfnSkip,(void *pvThis, RTFOFF cb));
1000
1001	/**
1002	* Fills the stream with @a cb zeros.
1003	*
1004	* @returns IPRT status code.
1005	* @param pvThis The implementation specific file data.
1006	* @param cb The number of zero bytes to insert.
1007	* @remarks This is optional and can be NULL.
1008	*/
1009	DECLCALLBACKMEMBER(int, pfnZeroFill,(void *pvThis, RTFOFF cb));
1010
1011	/** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
1012	uintptr_t uEndMarker;
1013	} RTVFSIOSTREAMOPS;
1014	/** Pointer to const I/O stream operations. */
1015	typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
1016
1017	/** The RTVFSIOSTREAMOPS structure version. */
1018	#define RTVFSIOSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
1019
1020	/** @name RTVFSIOSTREAMOPS::fFeatures
1021	* @{ */
1022	/** No scatter gather lists, thank you. */
1023	#define RTVFSIOSTREAMOPS_FEAT_NO_SG RT_BIT_32(0)
1024	/** Mask of the valid I/O stream feature flags. */
1025	#define RTVFSIOSTREAMOPS_FEAT_VALID_MASK UINT32_C(0x00000001)
1026	/** @} */
1027
1028
1029	/**
1030	* Creates a new VFS I/O stream handle.
1031	*
1032	* @returns IPRT status code
1033	* @param pIoStreamOps The I/O stream operations.
1034	* @param cbInstance The size of the instance data.
1035	* @param fOpen The open flags. The minimum is the access mask.
1036	* @param hVfs The VFS handle to associate this I/O stream
1037	* with. NIL_VFS is ok.
1038	* @param hLock Handle to a custom lock to be used with the new
1039	* object. The reference is consumed. NIL and
1040	* special lock handles are fine.
1041	* @param phVfsIos Where to return the new handle.
1042	* @param ppvInstance Where to return the pointer to the instance data
1043	* (size is @a cbInstance).
1044	*/
1045	RTDECL(int) RTVfsNewIoStream(PCRTVFSIOSTREAMOPS pIoStreamOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1046	PRTVFSIOSTREAM phVfsIos, void **ppvInstance);
1047
1048
1049	/**
1050	* Gets the private data of an I/O stream.
1051	*
1052	* @returns Pointer to the private data. NULL if the handle is invalid in some
1053	* way.
1054	* @param hVfsIos The I/O stream handle.
1055	* @param pIoStreamOps The I/O stream operations. This servers as a
1056	* sort of password.
1057	*/
1058	RTDECL(void *) RTVfsIoStreamToPrivate(RTVFSIOSTREAM hVfsIos, PCRTVFSIOSTREAMOPS pIoStreamOps);
1059
1060
1061	/**
1062	* The file operations.
1063	*
1064	* @extends RTVFSIOSTREAMOPS
1065	* @extends RTVFSOBJSETOPS
1066	*/
1067	typedef struct RTVFSFILEOPS
1068	{
1069	/** The I/O stream and basis object operations. */
1070	RTVFSIOSTREAMOPS Stream;
1071	/** The structure version (RTVFSFILEOPS_VERSION). */
1072	uint32_t uVersion;
1073	/** Reserved field, MBZ. */
1074	uint32_t fReserved;
1075	/** The object setter operations. */
1076	RTVFSOBJSETOPS ObjSet;
1077
1078	/**
1079	* Changes the current file position.
1080	*
1081	* @returns IPRT status code.
1082	* @param pvThis The implementation specific file data.
1083	* @param offSeek The offset to seek.
1084	* @param uMethod The seek method, i.e. what the seek is relative to.
1085	* @param poffActual Where to return the actual offset.
1086	* @sa RTFileSeek
1087	*/
1088	DECLCALLBACKMEMBER(int, pfnSeek,(void *pvThis, RTFOFF offSeek, unsigned uMethod, PRTFOFF poffActual));
1089
1090	/**
1091	* Get the current file size.
1092	*
1093	* @returns IPRT status code.
1094	* @param pvThis The implementation specific file data.
1095	* @param pcbFile Where to store the current file size.
1096	* @sa RTFileQuerySize
1097	*/
1098	DECLCALLBACKMEMBER(int, pfnQuerySize,(void pvThis, uint64_t pcbFile));
1099
1100	/**
1101	* Change the file size.
1102	*
1103	* @returns IPRT status code.
1104	* @retval VERR_ACCESS_DENIED if handle isn't writable.
1105	* @retval VERR_WRITE_PROTECT if read-only file system.
1106	* @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
1107	* theoretically deal with.
1108	* @retval VERR_DISK_FULL if the file system if full.
1109	* @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
1110	* supported by the file system / host operating system.
1111	*
1112	* @param pvThis The implementation specific file data.
1113	* @param pcbFile Where to store the current file size.
1114	* @param fFlags RTVFSFILE_SET_SIZE_F_XXX.
1115	* @note Optional. If NULL, VERR_WRITE_PROTECT will be returned.
1116	* @sa RTFileSetSize, RTFileSetAllocationSize
1117	*/
1118	DECLCALLBACKMEMBER(int, pfnSetSize,(void *pvThis, uint64_t cbFile, uint32_t fFlags));
1119
1120	/**
1121	* Determine the maximum file size.
1122	*
1123	* This won't take amount of freespace into account, just the limitations of the
1124	* underlying file system / host operating system.
1125	*
1126	* @returns IPRT status code.
1127	* @param pvThis The implementation specific file data.
1128	* @param pcbMax Where to return the max file size.
1129	* @note Optional. If NULL, VERR_NOT_IMPLEMENTED will be returned.
1130	* @sa RTFileQueryMaxSizeEx
1131	*/
1132	DECLCALLBACKMEMBER(int, pfnQueryMaxSize,(void pvThis, uint64_t pcbMax));
1133
1134	/** @todo There will be more methods here. */
1135
1136	/** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
1137	uintptr_t uEndMarker;
1138	} RTVFSFILEOPS;
1139	/** Pointer to const file operations. */
1140	typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
1141
1142	/** The RTVFSFILEOPS structure version. */
1143	#define RTVFSFILEOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x7f,2,0)
1144
1145	/**
1146	* Creates a new VFS file handle.
1147	*
1148	* @returns IPRT status code
1149	* @param pFileOps The file operations.
1150	* @param cbInstance The size of the instance data.
1151	* @param fOpen The open flags. The minimum is the access mask.
1152	* @param hVfs The VFS handle to associate this file with.
1153	* NIL_VFS is ok.
1154	* @param hLock Handle to a custom lock to be used with the new
1155	* object. The reference is consumed. NIL and
1156	* special lock handles are fine.
1157	* @param phVfsFile Where to return the new handle.
1158	* @param ppvInstance Where to return the pointer to the instance data
1159	* (size is @a cbInstance).
1160	*/
1161	RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1162	PRTVFSFILE phVfsFile, void **ppvInstance);
1163
1164
1165	/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
1166	* @{ */
1167
1168	/**
1169	* Parsed path.
1170	*/
1171	typedef struct RTVFSPARSEDPATH
1172	{
1173	/** The length of the path in szCopy. */
1174	uint16_t cch;
1175	/** The number of path components. */
1176	uint16_t cComponents;
1177	/** Set if the path ends with slash, indicating that it's a directory
1178	* reference and not a file reference. The slash has been removed from
1179	* the copy. */
1180	bool fDirSlash;
1181	/** Set if absolute. */
1182	bool fAbsolute;
1183	/** The offset where each path component starts, i.e. the char after the
1184	* slash. The array has cComponents + 1 entries, where the final one is
1185	* cch + 1 so that one can always terminate the current component by
1186	* szPath[aoffComponent[i] - 1] = '\0'. */
1187	uint16_t aoffComponents[RTPATH_MAX / 2 + 1];
1188	/** A normalized copy of the path.
1189	* Reserve some extra space so we can be more relaxed about overflow
1190	* checks and terminator paddings, especially when recursing. */
1191	char szPath[RTPATH_MAX];
1192	} RTVFSPARSEDPATH;
1193	/** Pointer to a parsed path. */
1194	typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
1195
1196	/** The max accepted path length.
1197	* This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
1198	* use two terminators and wish be a little bit lazy with checking. */
1199	#define RTVFSPARSEDPATH_MAX (RTPATH_MAX - 4)
1200
1201	/**
1202	* Appends @a pszPath (relative) to the already parsed path @a pPath.
1203	*
1204	* @retval VINF_SUCCESS
1205	* @retval VERR_FILENAME_TOO_LONG
1206	* @retval VERR_INTERNAL_ERROR_4
1207	* @param pPath The parsed path to append @a pszPath onto.
1208	* This is both input and output.
1209	* @param pszPath The path to append. This must be relative.
1210	* @param piRestartComp The component to restart parsing at. This is
1211	* input/output. The input does not have to be
1212	* within the valid range. Optional.
1213	*/
1214	RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char pszPath, uint16_t piRestartComp);
1215
1216	/**
1217	* Parses a path.
1218	*
1219	* @retval VINF_SUCCESS
1220	* @retval VERR_FILENAME_TOO_LONG
1221	* @param pPath Where to store the parsed path.
1222	* @param pszPath The path to parse. Absolute or relative to @a
1223	* pszCwd.
1224	* @param pszCwd The current working directory. Must be
1225	* absolute.
1226	*/
1227	RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char pszPath, const char pszCwd);
1228
1229	/**
1230	* Same as RTVfsParsePath except that it allocates a temporary buffer.
1231	*
1232	* @retval VINF_SUCCESS
1233	* @retval VERR_NO_TMP_MEMORY
1234	* @retval VERR_FILENAME_TOO_LONG
1235	* @param pszPath The path to parse. Absolute or relative to @a
1236	* pszCwd.
1237	* @param pszCwd The current working directory. Must be
1238	* absolute.
1239	* @param ppPath Where to store the pointer to the allocated
1240	* buffer containing the parsed path. This must
1241	* be freed by calling RTVfsParsePathFree. NULL
1242	* will be stored on failured.
1243	*/
1244	RTDECL(int) RTVfsParsePathA(const char pszPath, const char pszCwd, PRTVFSPARSEDPATH *ppPath);
1245
1246	/**
1247	* Frees a buffer returned by RTVfsParsePathA.
1248	*
1249	* @param pPath The parsed path buffer to free. NULL is fine.
1250	*/
1251	RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
1252
1253	/**
1254	* Dummy implementation of RTVFSIOSTREAMOPS::pfnPollOne.
1255	*
1256	* This handles the case where there is no chance any events my be raised and
1257	* all that is required is to wait according to the parameters.
1258	*
1259	* @returns IPRT status code.
1260	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1261	* @param cMillies How long to wait for event to eventuate.
1262	* @param fIntr Whether the wait is interruptible and can return
1263	* VERR_INTERRUPTED (@c true) or if this condition
1264	* should be hidden from the caller (@c false).
1265	* @param pfRetEvents Where to return the event mask.
1266	* @sa RTVFSIOSTREAMOPS::pfnPollOne, RTPollSetAdd, RTPoll, RTPollNoResume.
1267	*/
1268	RTDECL(int) RTVfsUtilDummyPollOne(uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr, uint32_t *pfRetEvents);
1269
1270	/** @} */
1271
1272
1273	/** @defgroup grp_rt_vfs_lowlevel_chain VFS Chains (Low Level)
1274	* @ref grp_rt_vfs_chain
1275	* @{
1276	*/
1277
1278	/** Pointer to a VFS chain element registration record. */
1279	typedef struct RTVFSCHAINELEMENTREG *PRTVFSCHAINELEMENTREG;
1280	/** Pointer to a const VFS chain element registration record. */
1281	typedef struct RTVFSCHAINELEMENTREG const *PCRTVFSCHAINELEMENTREG;
1282
1283	/**
1284	* VFS chain element argument.
1285	*/
1286	typedef struct RTVFSCHAINELEMENTARG
1287	{
1288	/** The string argument value. */
1289	char *psz;
1290	/** The specification offset of this argument. */
1291	uint16_t offSpec;
1292	/** Provider specific value. */
1293	uint64_t uProvider;
1294	} RTVFSCHAINELEMENTARG;
1295	/** Pointer to a VFS chain element argument. */
1296	typedef RTVFSCHAINELEMENTARG *PRTVFSCHAINELEMENTARG;
1297
1298
1299	/**
1300	* VFS chain element specification.
1301	*/
1302	typedef struct RTVFSCHAINELEMSPEC
1303	{
1304	/** The provider name.
1305	* This can be NULL if this is the final component and it's just a path. */
1306	char *pszProvider;
1307	/** The input type, RTVFSOBJTYPE_INVALID if first. */
1308	RTVFSOBJTYPE enmTypeIn;
1309	/** The element type.
1310	* RTVFSOBJTYPE_END if this is the final component and it's just a path. */
1311	RTVFSOBJTYPE enmType;
1312	/** The input spec offset of this element. */
1313	uint16_t offSpec;
1314	/** The length of the input spec. */
1315	uint16_t cchSpec;
1316	/** The number of arguments. */
1317	uint32_t cArgs;
1318	/** Arguments. */
1319	PRTVFSCHAINELEMENTARG paArgs;
1320
1321	/** The provider. */
1322	PCRTVFSCHAINELEMENTREG pProvider;
1323	/** Provider specific value. */
1324	uint64_t uProvider;
1325	/** The object (with reference). */
1326	RTVFSOBJ hVfsObj;
1327	} RTVFSCHAINELEMSPEC;
1328	/** Pointer to a chain element specification. */
1329	typedef RTVFSCHAINELEMSPEC *PRTVFSCHAINELEMSPEC;
1330	/** Pointer to a const chain element specification. */
1331	typedef RTVFSCHAINELEMSPEC const *PCRTVFSCHAINELEMSPEC;
1332
1333
1334	/**
1335	* Parsed VFS chain specification.
1336	*/
1337	typedef struct RTVFSCHAINSPEC
1338	{
1339	/** Open directory flags (RTFILE_O_XXX). */
1340	uint64_t fOpenFile;
1341	/** To be defined. */
1342	uint32_t fOpenDir;
1343	/** The type desired by the caller. */
1344	RTVFSOBJTYPE enmDesiredType;
1345	/** The number of elements. */
1346	uint32_t cElements;
1347	/** The elements. */
1348	PRTVFSCHAINELEMSPEC paElements;
1349	} RTVFSCHAINSPEC;
1350	/** Pointer to a parsed VFS chain specification. */
1351	typedef RTVFSCHAINSPEC *PRTVFSCHAINSPEC;
1352	/** Pointer to a const, parsed VFS chain specification. */
1353	typedef RTVFSCHAINSPEC const *PCRTVFSCHAINSPEC;
1354
1355
1356	/**
1357	* A chain element provider registration record.
1358	*/
1359	typedef struct RTVFSCHAINELEMENTREG
1360	{
1361	/** The version (RTVFSCHAINELEMENTREG_VERSION). */
1362	uint32_t uVersion;
1363	/** Reserved, MBZ. */
1364	uint32_t fReserved;
1365	/** The provider name (unique). */
1366	const char *pszName;
1367	/** For chaining the providers. */
1368	RTLISTNODE ListEntry;
1369	/** Help text. */
1370	const char *pszHelp;
1371
1372	/**
1373	* Checks the element specification.
1374	*
1375	* This is allowed to parse arguments and use pSpec->uProvider and
1376	* pElement->paArgs[].uProvider to store information that pfnInstantiate and
1377	* pfnCanReuseElement may use later on, thus avoiding duplicating work/code.
1378	*
1379	* @returns IPRT status code.
1380	* @param pProviderReg Pointer to the element provider registration.
1381	* @param pSpec The chain specification.
1382	* @param pElement The chain element specification to validate.
1383	* @param poffError Where to return error offset on failure. This is
1384	* set to the pElement->offSpec on input, so it only
1385	* needs to be adjusted if an argument is at fault.
1386	* @param pErrInfo Where to return additional error information, if
1387	* available. Optional.
1388	*/
1389	DECLCALLBACKMEMBER(int, pfnValidate,(PCRTVFSCHAINELEMENTREG pProviderReg, PRTVFSCHAINSPEC pSpec,
1390	PRTVFSCHAINELEMSPEC pElement, uint32_t *poffError, PRTERRINFO pErrInfo));
1391
1392	/**
1393	* Create a VFS object according to the element specification.
1394	*
1395	* @returns IPRT status code.
1396	* @param pProviderReg Pointer to the element provider registration.
1397	* @param pSpec The chain specification.
1398	* @param pElement The chain element specification to instantiate.
1399	* @param hPrevVfsObj Handle to the previous VFS object, NIL_RTVFSOBJ if
1400	* first.
1401	* @param phVfsObj Where to return the VFS object handle.
1402	* @param poffError Where to return error offset on failure. This is
1403	* set to the pElement->offSpec on input, so it only
1404	* needs to be adjusted if an argument is at fault.
1405	* @param pErrInfo Where to return additional error information, if
1406	* available. Optional.
1407	*/
1408	DECLCALLBACKMEMBER(int, pfnInstantiate,(PCRTVFSCHAINELEMENTREG pProviderReg, PCRTVFSCHAINSPEC pSpec,
1409	PCRTVFSCHAINELEMSPEC pElement, RTVFSOBJ hPrevVfsObj,
1410	PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo));
1411
1412	/**
1413	* Determins whether the element can be reused.
1414	*
1415	* This is for handling situations accessing the same file system twice, like
1416	* for both the source and destiation of a copy operation. This allows not only
1417	* sharing resources and avoid doing things twice, but also helps avoid file
1418	* sharing violations and inconsistencies araising from the image being updated
1419	* and read independently.
1420	*
1421	* @returns true if the element from @a pReuseSpec an be reused, false if not.
1422	* @param pProviderReg Pointer to the element provider registration.
1423	* @param pSpec The chain specification.
1424	* @param pElement The chain element specification.
1425	* @param pReuseSpec The chain specification of the existing chain.
1426	* @param pReuseElement The chain element specification of the existing
1427	* element that is being considered for reuse.
1428	*/
1429	DECLCALLBACKMEMBER(bool, pfnCanReuseElement,(PCRTVFSCHAINELEMENTREG pProviderReg,
1430	PCRTVFSCHAINSPEC pSpec, PCRTVFSCHAINELEMSPEC pElement,
1431	PCRTVFSCHAINSPEC pReuseSpec, PCRTVFSCHAINELEMSPEC pReuseElement));
1432
1433	/** End marker (RTVFSCHAINELEMENTREG_VERSION). */
1434	uintptr_t uEndMarker;
1435	} RTVFSCHAINELEMENTREG;
1436
1437	/** The VFS chain element registration record version number. */
1438	#define RTVFSCHAINELEMENTREG_VERSION RT_MAKE_U32_FROM_U8(0xff, 0x7f, 1, 0)
1439
1440
1441	/**
1442	* Parses the specification.
1443	*
1444	* @returns IPRT status code.
1445	* @param pszSpec The specification string to parse.
1446	* @param fFlags Flags, see RTVFSCHAIN_PF_XXX.
1447	* @param enmDesiredType The object type the caller wants to interface with.
1448	* @param ppSpec Where to return the pointer to the parsed
1449	* specification. This must be freed by calling
1450	* RTVfsChainSpecFree. Will always be set (unless
1451	* invalid parameters.)
1452	* @param poffError Where to return the offset into the input
1453	* specification of what's causing trouble. Always
1454	* set, unless this argument causes an invalid pointer
1455	* error.
1456	*/
1457	RTDECL(int) RTVfsChainSpecParse(const char *pszSpec, uint32_t fFlags, RTVFSOBJTYPE enmDesiredType,
1458	PRTVFSCHAINSPEC ppSpec, uint32_t poffError);
1459
1460	/** @name RTVfsChainSpecParse
1461	* @{ */
1462	/** Mask of valid flags. */
1463	#define RTVFSCHAIN_PF_VALID_MASK UINT32_C(0x00000000)
1464	/** @} */
1465
1466	/**
1467	* Checks and setups the chain.
1468	*
1469	* @returns IPRT status code.
1470	* @param pSpec The parsed specification.
1471	* @param pReuseSpec Spec to reuse if applicable. Optional.
1472	* @param phVfsObj Where to return the VFS object.
1473	* @param ppszFinalPath Where to return the pointer to the final path if
1474	* applicable. The caller needs to check whether this
1475	* is NULL or a path, in the former case nothing more
1476	* needs doing, whereas in the latter the caller must
1477	* perform the desired operation(s) on *phVfsObj using
1478	* the final path.
1479	* @param poffError Where to return the offset into the input
1480	* specification of what's causing trouble. Always
1481	* set, unless this argument causes an invalid pointer
1482	* error.
1483	* @param pErrInfo Where to return additional error information, if
1484	* available. Optional.
1485	*/
1486	RTDECL(int) RTVfsChainSpecCheckAndSetup(PRTVFSCHAINSPEC pSpec, PCRTVFSCHAINSPEC pReuseSpec,
1487	PRTVFSOBJ phVfsObj, const char *ppszFinalPath, uint32_t poffError, PRTERRINFO pErrInfo);
1488
1489	/**
1490	* Frees a parsed chain specification.
1491	*
1492	* @param pSpec What RTVfsChainSpecParse returned. NULL is
1493	* quietly ignored.
1494	*/
1495	RTDECL(void) RTVfsChainSpecFree(PRTVFSCHAINSPEC pSpec);
1496
1497	/**
1498	* Registers a chain element provider.
1499	*
1500	* @returns IPRT status code
1501	* @param pRegRec The registration record.
1502	* @param fFromCtor Indicates where we're called from.
1503	*/
1504	RTDECL(int) RTVfsChainElementRegisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromCtor);
1505
1506	/**
1507	* Deregisters a chain element provider.
1508	*
1509	* @returns IPRT status code
1510	* @param pRegRec The registration record.
1511	* @param fFromDtor Indicates where we're called from.
1512	*/
1513	RTDECL(int) RTVfsChainElementDeregisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromDtor);
1514
1515
1516	/** @def RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER
1517	* Automatically registers a chain element provider using a global constructor
1518	* and destructor hack.
1519	*
1520	* @param pRegRec Pointer to the registration record.
1521	* @param name Some unique variable name prefix.
1522	*/
1523
1524	#ifdef __cplusplus
1525	/**
1526	* Class used for registering a VFS chain element provider.
1527	*/
1528	class RTVfsChainElementAutoRegisterHack
1529	{
1530	private:
1531	/** The registration record, NULL if registration failed. */
1532	PRTVFSCHAINELEMENTREG m_pRegRec;
1533
1534	public:
1535	RTVfsChainElementAutoRegisterHack(PRTVFSCHAINELEMENTREG a_pRegRec)
1536	: m_pRegRec(a_pRegRec)
1537	{
1538	int rc = RTVfsChainElementRegisterProvider(m_pRegRec, true);
1539	if (RT_FAILURE(rc))
1540	m_pRegRec = NULL;
1541	}
1542
1543	~RTVfsChainElementAutoRegisterHack()
1544	{
1545	RTVfsChainElementDeregisterProvider(m_pRegRec, true);
1546	m_pRegRec = NULL;
1547	}
1548	};
1549
1550	# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1551	static RTVfsChainElementAutoRegisterHack name ## AutoRegistrationHack(pRegRec)
1552
1553	#else
1554	# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1555	extern void *name ## AutoRegistrationHack = \
1556	&Sorry_but_RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER_does_not_work_in_c_source_files
1557	#endif
1558
1559
1560	/**
1561	* Common worker for the 'stdfile' and 'open' providers for implementing
1562	* RTVFSCHAINELEMENTREG::pfnValidate.
1563	*
1564	* Stores the RTFILE_O_XXX flags in pSpec->uProvider.
1565	*
1566	* @returns IPRT status code.
1567	* @param pSpec The chain specification.
1568	* @param pElement The chain element specification to validate.
1569	* @param poffError Where to return error offset on failure. This is set to
1570	* the pElement->offSpec on input, so it only needs to be
1571	* adjusted if an argument is at fault.
1572	* @param pErrInfo Where to return additional error information, if
1573	* available. Optional.
1574	*/
1575	RTDECL(int) RTVfsChainValidateOpenFileOrIoStream(PRTVFSCHAINSPEC pSpec, PRTVFSCHAINELEMSPEC pElement,
1576	uint32_t *poffError, PRTERRINFO pErrInfo);
1577
1578
1579	/** @} */
1580
1581
1582	/** @} */
1583
1584	RT_C_DECLS_END
1585
1586	#endif /* !IPRT_INCLUDED_vfslowlevel_h */
1587

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

source: vbox/trunk/include/iprt/vfslowlevel.h@ 106814

Download in other formats: