vfslowlevel.h@ 66599

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

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

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

Download in other formats: