vfslowlevel.h@ 68113

Last change on this file since 68113 was 67186, checked in by vboxsync, 8 years ago
IPRT: Added RTVfsFsStrmToNormalDir, RTVfsFsStrmToDirUndo, RTVfsDirOpenFileAsIoStream, and RTVfsFsStreamToPrivate.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 54.1 KB

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

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

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

Download in other formats: