vfslowlevel.h@ 69828

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

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

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

Download in other formats: