vfslowlevel.h@ 94311

Last change on this file since 94311 was 94291, checked in by vboxsync, 3 years ago
IPRT,Storage: Adding RTVfsQueryLabel and internally a generic pfnQueryInfoEx method to the RTVFSOBJOPS function table. Untested implementation of the latter for iso/udf. bugref:9781
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 61.1 KB

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

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

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

Download in other formats: