vfslowlevel.h@ 74653

Last change on this file since 74653 was 73108, checked in by vboxsync, 6 years ago
Corrected definition (type + docs) of RTVFSOBJSETOPS::offObjOps (no longer negative as that caused narrow warnings with gcc).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 58.7 KB

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

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

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

Download in other formats: