vfslowlevel.h@ 99802

Last change on this file since 99802 was 98103, checked in by vboxsync, 2 years 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.6 KB

Line
1	/** @file
2	* IPRT - Virtual Filesystem.
3	*/
4
5	/*
6	* Copyright (C) 2010-2023 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 describing the bytes that are to be
925	* written.
926	* @param fBlocking If @c true, the call is blocking, if @c false it
927	* should not block.
928	* @param pcbRead Where return the number of bytes actually read.
929	* This is set it 0 by the caller. If NULL, try read
930	* all and fail if incomplete.
931	* @sa RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
932	* RTVfsFileReadAt, RTFileRead, RTFileReadAt.
933	*/
934	DECLCALLBACKMEMBER(int, pfnRead,(void pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t pcbRead));
935
936	/**
937	* Writes to the file/stream.
938	*
939	* @returns IPRT status code.
940	* @param pvThis The implementation specific file data.
941	* @param off Where to start wrinting, -1 for the current
942	* position.
943	* @param pSgBuf Gather buffers describing the bytes that are to be
944	* written.
945	* @param fBlocking If @c true, the call is blocking, if @c false it
946	* should not block.
947	* @param pcbWritten Where to return the number of bytes actually
948	* written. This is set it 0 by the caller. If
949	* NULL, try write it all and fail if incomplete.
950	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
951	* @sa RTFileWrite, RTFileWriteAt.
952	*/
953	DECLCALLBACKMEMBER(int, pfnWrite,(void pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t pcbWritten));
954
955	/**
956	* Flushes any pending data writes to the stream.
957	*
958	* @returns IPRT status code.
959	* @param pvThis The implementation specific file data.
960	* @sa RTFileFlush.
961	*/
962	DECLCALLBACKMEMBER(int, pfnFlush,(void *pvThis));
963
964	/**
965	* Poll for events.
966	*
967	* @returns IPRT status code.
968	* @param pvThis The implementation specific file data.
969	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
970	* @param cMillies How long to wait for event to eventuate.
971	* @param fIntr Whether the wait is interruptible and can return
972	* VERR_INTERRUPTED (@c true) or if this condition
973	* should be hidden from the caller (@c false).
974	* @param pfRetEvents Where to return the event mask.
975	* @note Optional. If NULL, immediately return all requested non-error
976	* events, waiting for errors works like sleep.
977	* @sa RTPollSetAdd, RTPoll, RTPollNoResume.
978	*/
979	DECLCALLBACKMEMBER(int, pfnPollOne,(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
980	uint32_t *pfRetEvents));
981
982	/**
983	* Tells the current file/stream position.
984	*
985	* @returns IPRT status code.
986	* @param pvThis The implementation specific file data.
987	* @param poffActual Where to return the actual offset.
988	* @sa RTFileTell
989	*/
990	DECLCALLBACKMEMBER(int, pfnTell,(void *pvThis, PRTFOFF poffActual));
991
992	/**
993	* Skips @a cb ahead in the stream.
994	*
995	* @returns IPRT status code.
996	* @param pvThis The implementation specific file data.
997	* @param cb The number bytes to skip.
998	* @remarks This is optional and can be NULL.
999	*/
1000	DECLCALLBACKMEMBER(int, pfnSkip,(void *pvThis, RTFOFF cb));
1001
1002	/**
1003	* Fills the stream with @a cb zeros.
1004	*
1005	* @returns IPRT status code.
1006	* @param pvThis The implementation specific file data.
1007	* @param cb The number of zero bytes to insert.
1008	* @remarks This is optional and can be NULL.
1009	*/
1010	DECLCALLBACKMEMBER(int, pfnZeroFill,(void *pvThis, RTFOFF cb));
1011
1012	/** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
1013	uintptr_t uEndMarker;
1014	} RTVFSIOSTREAMOPS;
1015	/** Pointer to const I/O stream operations. */
1016	typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
1017
1018	/** The RTVFSIOSTREAMOPS structure version. */
1019	#define RTVFSIOSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
1020
1021	/** @name RTVFSIOSTREAMOPS::fFeatures
1022	* @{ */
1023	/** No scatter gather lists, thank you. */
1024	#define RTVFSIOSTREAMOPS_FEAT_NO_SG RT_BIT_32(0)
1025	/** Mask of the valid I/O stream feature flags. */
1026	#define RTVFSIOSTREAMOPS_FEAT_VALID_MASK UINT32_C(0x00000001)
1027	/** @} */
1028
1029
1030	/**
1031	* Creates a new VFS I/O stream handle.
1032	*
1033	* @returns IPRT status code
1034	* @param pIoStreamOps The I/O stream operations.
1035	* @param cbInstance The size of the instance data.
1036	* @param fOpen The open flags. The minimum is the access mask.
1037	* @param hVfs The VFS handle to associate this I/O stream
1038	* with. NIL_VFS is ok.
1039	* @param hLock Handle to a custom lock to be used with the new
1040	* object. The reference is consumed. NIL and
1041	* special lock handles are fine.
1042	* @param phVfsIos Where to return the new handle.
1043	* @param ppvInstance Where to return the pointer to the instance data
1044	* (size is @a cbInstance).
1045	*/
1046	RTDECL(int) RTVfsNewIoStream(PCRTVFSIOSTREAMOPS pIoStreamOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1047	PRTVFSIOSTREAM phVfsIos, void **ppvInstance);
1048
1049
1050	/**
1051	* Gets the private data of an I/O stream.
1052	*
1053	* @returns Pointer to the private data. NULL if the handle is invalid in some
1054	* way.
1055	* @param hVfsIos The I/O stream handle.
1056	* @param pIoStreamOps The I/O stream operations. This servers as a
1057	* sort of password.
1058	*/
1059	RTDECL(void *) RTVfsIoStreamToPrivate(RTVFSIOSTREAM hVfsIos, PCRTVFSIOSTREAMOPS pIoStreamOps);
1060
1061
1062	/**
1063	* The file operations.
1064	*
1065	* @extends RTVFSIOSTREAMOPS
1066	* @extends RTVFSOBJSETOPS
1067	*/
1068	typedef struct RTVFSFILEOPS
1069	{
1070	/** The I/O stream and basis object operations. */
1071	RTVFSIOSTREAMOPS Stream;
1072	/** The structure version (RTVFSFILEOPS_VERSION). */
1073	uint32_t uVersion;
1074	/** Reserved field, MBZ. */
1075	uint32_t fReserved;
1076	/** The object setter operations. */
1077	RTVFSOBJSETOPS ObjSet;
1078
1079	/**
1080	* Changes the current file position.
1081	*
1082	* @returns IPRT status code.
1083	* @param pvThis The implementation specific file data.
1084	* @param offSeek The offset to seek.
1085	* @param uMethod The seek method, i.e. what the seek is relative to.
1086	* @param poffActual Where to return the actual offset.
1087	* @sa RTFileSeek
1088	*/
1089	DECLCALLBACKMEMBER(int, pfnSeek,(void *pvThis, RTFOFF offSeek, unsigned uMethod, PRTFOFF poffActual));
1090
1091	/**
1092	* Get the current file size.
1093	*
1094	* @returns IPRT status code.
1095	* @param pvThis The implementation specific file data.
1096	* @param pcbFile Where to store the current file size.
1097	* @sa RTFileQuerySize
1098	*/
1099	DECLCALLBACKMEMBER(int, pfnQuerySize,(void pvThis, uint64_t pcbFile));
1100
1101	/**
1102	* Change the file size.
1103	*
1104	* @returns IPRT status code.
1105	* @retval VERR_ACCESS_DENIED if handle isn't writable.
1106	* @retval VERR_WRITE_PROTECT if read-only file system.
1107	* @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
1108	* theoretically deal with.
1109	* @retval VERR_DISK_FULL if the file system if full.
1110	* @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
1111	* supported by the file system / host operating system.
1112	*
1113	* @param pvThis The implementation specific file data.
1114	* @param pcbFile Where to store the current file size.
1115	* @param fFlags RTVFSFILE_SET_SIZE_F_XXX.
1116	* @note Optional. If NULL, VERR_WRITE_PROTECT will be returned.
1117	* @sa RTFileSetSize, RTFileSetAllocationSize
1118	*/
1119	DECLCALLBACKMEMBER(int, pfnSetSize,(void *pvThis, uint64_t cbFile, uint32_t fFlags));
1120
1121	/**
1122	* Determine the maximum file size.
1123	*
1124	* This won't take amount of freespace into account, just the limitations of the
1125	* underlying file system / host operating system.
1126	*
1127	* @returns IPRT status code.
1128	* @param pvThis The implementation specific file data.
1129	* @param pcbMax Where to return the max file size.
1130	* @note Optional. If NULL, VERR_NOT_IMPLEMENTED will be returned.
1131	* @sa RTFileQueryMaxSizeEx
1132	*/
1133	DECLCALLBACKMEMBER(int, pfnQueryMaxSize,(void pvThis, uint64_t pcbMax));
1134
1135	/** @todo There will be more methods here. */
1136
1137	/** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
1138	uintptr_t uEndMarker;
1139	} RTVFSFILEOPS;
1140	/** Pointer to const file operations. */
1141	typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
1142
1143	/** The RTVFSFILEOPS structure version. */
1144	#define RTVFSFILEOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x7f,2,0)
1145
1146	/**
1147	* Creates a new VFS file handle.
1148	*
1149	* @returns IPRT status code
1150	* @param pFileOps The file operations.
1151	* @param cbInstance The size of the instance data.
1152	* @param fOpen The open flags. The minimum is the access mask.
1153	* @param hVfs The VFS handle to associate this file with.
1154	* NIL_VFS is ok.
1155	* @param hLock Handle to a custom lock to be used with the new
1156	* object. The reference is consumed. NIL and
1157	* special lock handles are fine.
1158	* @param phVfsFile Where to return the new handle.
1159	* @param ppvInstance Where to return the pointer to the instance data
1160	* (size is @a cbInstance).
1161	*/
1162	RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1163	PRTVFSFILE phVfsFile, void **ppvInstance);
1164
1165
1166	/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
1167	* @{ */
1168
1169	/**
1170	* Parsed path.
1171	*/
1172	typedef struct RTVFSPARSEDPATH
1173	{
1174	/** The length of the path in szCopy. */
1175	uint16_t cch;
1176	/** The number of path components. */
1177	uint16_t cComponents;
1178	/** Set if the path ends with slash, indicating that it's a directory
1179	* reference and not a file reference. The slash has been removed from
1180	* the copy. */
1181	bool fDirSlash;
1182	/** Set if absolute. */
1183	bool fAbsolute;
1184	/** The offset where each path component starts, i.e. the char after the
1185	* slash. The array has cComponents + 1 entries, where the final one is
1186	* cch + 1 so that one can always terminate the current component by
1187	* szPath[aoffComponent[i] - 1] = '\0'. */
1188	uint16_t aoffComponents[RTPATH_MAX / 2 + 1];
1189	/** A normalized copy of the path.
1190	* Reserve some extra space so we can be more relaxed about overflow
1191	* checks and terminator paddings, especially when recursing. */
1192	char szPath[RTPATH_MAX];
1193	} RTVFSPARSEDPATH;
1194	/** Pointer to a parsed path. */
1195	typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
1196
1197	/** The max accepted path length.
1198	* This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
1199	* use two terminators and wish be a little bit lazy with checking. */
1200	#define RTVFSPARSEDPATH_MAX (RTPATH_MAX - 4)
1201
1202	/**
1203	* Appends @a pszPath (relative) to the already parsed path @a pPath.
1204	*
1205	* @retval VINF_SUCCESS
1206	* @retval VERR_FILENAME_TOO_LONG
1207	* @retval VERR_INTERNAL_ERROR_4
1208	* @param pPath The parsed path to append @a pszPath onto.
1209	* This is both input and output.
1210	* @param pszPath The path to append. This must be relative.
1211	* @param piRestartComp The component to restart parsing at. This is
1212	* input/output. The input does not have to be
1213	* within the valid range. Optional.
1214	*/
1215	RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char pszPath, uint16_t piRestartComp);
1216
1217	/**
1218	* Parses a path.
1219	*
1220	* @retval VINF_SUCCESS
1221	* @retval VERR_FILENAME_TOO_LONG
1222	* @param pPath Where to store the parsed path.
1223	* @param pszPath The path to parse. Absolute or relative to @a
1224	* pszCwd.
1225	* @param pszCwd The current working directory. Must be
1226	* absolute.
1227	*/
1228	RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char pszPath, const char pszCwd);
1229
1230	/**
1231	* Same as RTVfsParsePath except that it allocates a temporary buffer.
1232	*
1233	* @retval VINF_SUCCESS
1234	* @retval VERR_NO_TMP_MEMORY
1235	* @retval VERR_FILENAME_TOO_LONG
1236	* @param pszPath The path to parse. Absolute or relative to @a
1237	* pszCwd.
1238	* @param pszCwd The current working directory. Must be
1239	* absolute.
1240	* @param ppPath Where to store the pointer to the allocated
1241	* buffer containing the parsed path. This must
1242	* be freed by calling RTVfsParsePathFree. NULL
1243	* will be stored on failured.
1244	*/
1245	RTDECL(int) RTVfsParsePathA(const char pszPath, const char pszCwd, PRTVFSPARSEDPATH *ppPath);
1246
1247	/**
1248	* Frees a buffer returned by RTVfsParsePathA.
1249	*
1250	* @param pPath The parsed path buffer to free. NULL is fine.
1251	*/
1252	RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
1253
1254	/**
1255	* Dummy implementation of RTVFSIOSTREAMOPS::pfnPollOne.
1256	*
1257	* This handles the case where there is no chance any events my be raised and
1258	* all that is required is to wait according to the parameters.
1259	*
1260	* @returns IPRT status code.
1261	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1262	* @param cMillies How long to wait for event to eventuate.
1263	* @param fIntr Whether the wait is interruptible and can return
1264	* VERR_INTERRUPTED (@c true) or if this condition
1265	* should be hidden from the caller (@c false).
1266	* @param pfRetEvents Where to return the event mask.
1267	* @sa RTVFSIOSTREAMOPS::pfnPollOne, RTPollSetAdd, RTPoll, RTPollNoResume.
1268	*/
1269	RTDECL(int) RTVfsUtilDummyPollOne(uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr, uint32_t *pfRetEvents);
1270
1271	/** @} */
1272
1273
1274	/** @defgroup grp_rt_vfs_lowlevel_chain VFS Chains (Low Level)
1275	* @ref grp_rt_vfs_chain
1276	* @{
1277	*/
1278
1279	/** Pointer to a VFS chain element registration record. */
1280	typedef struct RTVFSCHAINELEMENTREG *PRTVFSCHAINELEMENTREG;
1281	/** Pointer to a const VFS chain element registration record. */
1282	typedef struct RTVFSCHAINELEMENTREG const *PCRTVFSCHAINELEMENTREG;
1283
1284	/**
1285	* VFS chain element argument.
1286	*/
1287	typedef struct RTVFSCHAINELEMENTARG
1288	{
1289	/** The string argument value. */
1290	char *psz;
1291	/** The specification offset of this argument. */
1292	uint16_t offSpec;
1293	/** Provider specific value. */
1294	uint64_t uProvider;
1295	} RTVFSCHAINELEMENTARG;
1296	/** Pointer to a VFS chain element argument. */
1297	typedef RTVFSCHAINELEMENTARG *PRTVFSCHAINELEMENTARG;
1298
1299
1300	/**
1301	* VFS chain element specification.
1302	*/
1303	typedef struct RTVFSCHAINELEMSPEC
1304	{
1305	/** The provider name.
1306	* This can be NULL if this is the final component and it's just a path. */
1307	char *pszProvider;
1308	/** The input type, RTVFSOBJTYPE_INVALID if first. */
1309	RTVFSOBJTYPE enmTypeIn;
1310	/** The element type.
1311	* RTVFSOBJTYPE_END if this is the final component and it's just a path. */
1312	RTVFSOBJTYPE enmType;
1313	/** The input spec offset of this element. */
1314	uint16_t offSpec;
1315	/** The length of the input spec. */
1316	uint16_t cchSpec;
1317	/** The number of arguments. */
1318	uint32_t cArgs;
1319	/** Arguments. */
1320	PRTVFSCHAINELEMENTARG paArgs;
1321
1322	/** The provider. */
1323	PCRTVFSCHAINELEMENTREG pProvider;
1324	/** Provider specific value. */
1325	uint64_t uProvider;
1326	/** The object (with reference). */
1327	RTVFSOBJ hVfsObj;
1328	} RTVFSCHAINELEMSPEC;
1329	/** Pointer to a chain element specification. */
1330	typedef RTVFSCHAINELEMSPEC *PRTVFSCHAINELEMSPEC;
1331	/** Pointer to a const chain element specification. */
1332	typedef RTVFSCHAINELEMSPEC const *PCRTVFSCHAINELEMSPEC;
1333
1334
1335	/**
1336	* Parsed VFS chain specification.
1337	*/
1338	typedef struct RTVFSCHAINSPEC
1339	{
1340	/** Open directory flags (RTFILE_O_XXX). */
1341	uint64_t fOpenFile;
1342	/** To be defined. */
1343	uint32_t fOpenDir;
1344	/** The type desired by the caller. */
1345	RTVFSOBJTYPE enmDesiredType;
1346	/** The number of elements. */
1347	uint32_t cElements;
1348	/** The elements. */
1349	PRTVFSCHAINELEMSPEC paElements;
1350	} RTVFSCHAINSPEC;
1351	/** Pointer to a parsed VFS chain specification. */
1352	typedef RTVFSCHAINSPEC *PRTVFSCHAINSPEC;
1353	/** Pointer to a const, parsed VFS chain specification. */
1354	typedef RTVFSCHAINSPEC const *PCRTVFSCHAINSPEC;
1355
1356
1357	/**
1358	* A chain element provider registration record.
1359	*/
1360	typedef struct RTVFSCHAINELEMENTREG
1361	{
1362	/** The version (RTVFSCHAINELEMENTREG_VERSION). */
1363	uint32_t uVersion;
1364	/** Reserved, MBZ. */
1365	uint32_t fReserved;
1366	/** The provider name (unique). */
1367	const char *pszName;
1368	/** For chaining the providers. */
1369	RTLISTNODE ListEntry;
1370	/** Help text. */
1371	const char *pszHelp;
1372
1373	/**
1374	* Checks the element specification.
1375	*
1376	* This is allowed to parse arguments and use pSpec->uProvider and
1377	* pElement->paArgs[].uProvider to store information that pfnInstantiate and
1378	* pfnCanReuseElement may use later on, thus avoiding duplicating work/code.
1379	*
1380	* @returns IPRT status code.
1381	* @param pProviderReg Pointer to the element provider registration.
1382	* @param pSpec The chain specification.
1383	* @param pElement The chain element specification to validate.
1384	* @param poffError Where to return error offset on failure. This is
1385	* set to the pElement->offSpec on input, so it only
1386	* needs to be adjusted if an argument is at fault.
1387	* @param pErrInfo Where to return additional error information, if
1388	* available. Optional.
1389	*/
1390	DECLCALLBACKMEMBER(int, pfnValidate,(PCRTVFSCHAINELEMENTREG pProviderReg, PRTVFSCHAINSPEC pSpec,
1391	PRTVFSCHAINELEMSPEC pElement, uint32_t *poffError, PRTERRINFO pErrInfo));
1392
1393	/**
1394	* Create a VFS object according to the element specification.
1395	*
1396	* @returns IPRT status code.
1397	* @param pProviderReg Pointer to the element provider registration.
1398	* @param pSpec The chain specification.
1399	* @param pElement The chain element specification to instantiate.
1400	* @param hPrevVfsObj Handle to the previous VFS object, NIL_RTVFSOBJ if
1401	* first.
1402	* @param phVfsObj Where to return the VFS object handle.
1403	* @param poffError Where to return error offset on failure. This is
1404	* set to the pElement->offSpec on input, so it only
1405	* needs to be adjusted if an argument is at fault.
1406	* @param pErrInfo Where to return additional error information, if
1407	* available. Optional.
1408	*/
1409	DECLCALLBACKMEMBER(int, pfnInstantiate,(PCRTVFSCHAINELEMENTREG pProviderReg, PCRTVFSCHAINSPEC pSpec,
1410	PCRTVFSCHAINELEMSPEC pElement, RTVFSOBJ hPrevVfsObj,
1411	PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo));
1412
1413	/**
1414	* Determins whether the element can be reused.
1415	*
1416	* This is for handling situations accessing the same file system twice, like
1417	* for both the source and destiation of a copy operation. This allows not only
1418	* sharing resources and avoid doing things twice, but also helps avoid file
1419	* sharing violations and inconsistencies araising from the image being updated
1420	* and read independently.
1421	*
1422	* @returns true if the element from @a pReuseSpec an be reused, false if not.
1423	* @param pProviderReg Pointer to the element provider registration.
1424	* @param pSpec The chain specification.
1425	* @param pElement The chain element specification.
1426	* @param pReuseSpec The chain specification of the existing chain.
1427	* @param pReuseElement The chain element specification of the existing
1428	* element that is being considered for reuse.
1429	*/
1430	DECLCALLBACKMEMBER(bool, pfnCanReuseElement,(PCRTVFSCHAINELEMENTREG pProviderReg,
1431	PCRTVFSCHAINSPEC pSpec, PCRTVFSCHAINELEMSPEC pElement,
1432	PCRTVFSCHAINSPEC pReuseSpec, PCRTVFSCHAINELEMSPEC pReuseElement));
1433
1434	/** End marker (RTVFSCHAINELEMENTREG_VERSION). */
1435	uintptr_t uEndMarker;
1436	} RTVFSCHAINELEMENTREG;
1437
1438	/** The VFS chain element registration record version number. */
1439	#define RTVFSCHAINELEMENTREG_VERSION RT_MAKE_U32_FROM_U8(0xff, 0x7f, 1, 0)
1440
1441
1442	/**
1443	* Parses the specification.
1444	*
1445	* @returns IPRT status code.
1446	* @param pszSpec The specification string to parse.
1447	* @param fFlags Flags, see RTVFSCHAIN_PF_XXX.
1448	* @param enmDesiredType The object type the caller wants to interface with.
1449	* @param ppSpec Where to return the pointer to the parsed
1450	* specification. This must be freed by calling
1451	* RTVfsChainSpecFree. Will always be set (unless
1452	* invalid parameters.)
1453	* @param poffError Where to return the offset into the input
1454	* specification of what's causing trouble. Always
1455	* set, unless this argument causes an invalid pointer
1456	* error.
1457	*/
1458	RTDECL(int) RTVfsChainSpecParse(const char *pszSpec, uint32_t fFlags, RTVFSOBJTYPE enmDesiredType,
1459	PRTVFSCHAINSPEC ppSpec, uint32_t poffError);
1460
1461	/** @name RTVfsChainSpecParse
1462	* @{ */
1463	/** Mask of valid flags. */
1464	#define RTVFSCHAIN_PF_VALID_MASK UINT32_C(0x00000000)
1465	/** @} */
1466
1467	/**
1468	* Checks and setups the chain.
1469	*
1470	* @returns IPRT status code.
1471	* @param pSpec The parsed specification.
1472	* @param pReuseSpec Spec to reuse if applicable. Optional.
1473	* @param phVfsObj Where to return the VFS object.
1474	* @param ppszFinalPath Where to return the pointer to the final path if
1475	* applicable. The caller needs to check whether this
1476	* is NULL or a path, in the former case nothing more
1477	* needs doing, whereas in the latter the caller must
1478	* perform the desired operation(s) on *phVfsObj using
1479	* the final path.
1480	* @param poffError Where to return the offset into the input
1481	* specification of what's causing trouble. Always
1482	* set, unless this argument causes an invalid pointer
1483	* error.
1484	* @param pErrInfo Where to return additional error information, if
1485	* available. Optional.
1486	*/
1487	RTDECL(int) RTVfsChainSpecCheckAndSetup(PRTVFSCHAINSPEC pSpec, PCRTVFSCHAINSPEC pReuseSpec,
1488	PRTVFSOBJ phVfsObj, const char *ppszFinalPath, uint32_t poffError, PRTERRINFO pErrInfo);
1489
1490	/**
1491	* Frees a parsed chain specification.
1492	*
1493	* @param pSpec What RTVfsChainSpecParse returned. NULL is
1494	* quietly ignored.
1495	*/
1496	RTDECL(void) RTVfsChainSpecFree(PRTVFSCHAINSPEC pSpec);
1497
1498	/**
1499	* Registers a chain element provider.
1500	*
1501	* @returns IPRT status code
1502	* @param pRegRec The registration record.
1503	* @param fFromCtor Indicates where we're called from.
1504	*/
1505	RTDECL(int) RTVfsChainElementRegisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromCtor);
1506
1507	/**
1508	* Deregisters a chain element provider.
1509	*
1510	* @returns IPRT status code
1511	* @param pRegRec The registration record.
1512	* @param fFromDtor Indicates where we're called from.
1513	*/
1514	RTDECL(int) RTVfsChainElementDeregisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromDtor);
1515
1516
1517	/** @def RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER
1518	* Automatically registers a chain element provider using a global constructor
1519	* and destructor hack.
1520	*
1521	* @param pRegRec Pointer to the registration record.
1522	* @param name Some unique variable name prefix.
1523	*/
1524
1525	#ifdef __cplusplus
1526	/**
1527	* Class used for registering a VFS chain element provider.
1528	*/
1529	class RTVfsChainElementAutoRegisterHack
1530	{
1531	private:
1532	/** The registration record, NULL if registration failed. */
1533	PRTVFSCHAINELEMENTREG m_pRegRec;
1534
1535	public:
1536	RTVfsChainElementAutoRegisterHack(PRTVFSCHAINELEMENTREG a_pRegRec)
1537	: m_pRegRec(a_pRegRec)
1538	{
1539	int rc = RTVfsChainElementRegisterProvider(m_pRegRec, true);
1540	if (RT_FAILURE(rc))
1541	m_pRegRec = NULL;
1542	}
1543
1544	~RTVfsChainElementAutoRegisterHack()
1545	{
1546	RTVfsChainElementDeregisterProvider(m_pRegRec, true);
1547	m_pRegRec = NULL;
1548	}
1549	};
1550
1551	# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1552	static RTVfsChainElementAutoRegisterHack name ## AutoRegistrationHack(pRegRec)
1553
1554	#else
1555	# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1556	extern void *name ## AutoRegistrationHack = \
1557	&Sorry_but_RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER_does_not_work_in_c_source_files
1558	#endif
1559
1560
1561	/**
1562	* Common worker for the 'stdfile' and 'open' providers for implementing
1563	* RTVFSCHAINELEMENTREG::pfnValidate.
1564	*
1565	* Stores the RTFILE_O_XXX flags in pSpec->uProvider.
1566	*
1567	* @returns IPRT status code.
1568	* @param pSpec The chain specification.
1569	* @param pElement The chain element specification to validate.
1570	* @param poffError Where to return error offset on failure. This is set to
1571	* the pElement->offSpec on input, so it only needs to be
1572	* adjusted if an argument is at fault.
1573	* @param pErrInfo Where to return additional error information, if
1574	* available. Optional.
1575	*/
1576	RTDECL(int) RTVfsChainValidateOpenFileOrIoStream(PRTVFSCHAINSPEC pSpec, PRTVFSCHAINELEMSPEC pElement,
1577	uint32_t *poffError, PRTERRINFO pErrInfo);
1578
1579
1580	/** @} */
1581
1582
1583	/** @} */
1584
1585	RT_C_DECLS_END
1586
1587	#endif /* !IPRT_INCLUDED_vfslowlevel_h */
1588

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

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

Download in other formats: