vfslowlevel.h@ 33973

Last change on this file since 33973 was 33973, checked in by vboxsync, 14 years ago
vfs: the gunzip stream works, except for some double frees somewhere.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.2 KB

Line
1	/** @file
2	* IPRT - Virtual Filesystem.
3	*/
4
5	/*
6	* Copyright (C) 2010 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	* The VFS operations.
44	*/
45	typedef struct RTVFSOPS
46	{
47	/** The structure version (RTVFSOPS_VERSION). */
48	uint32_t uVersion;
49	/** The virtual file system feature mask. */
50	uint32_t fFeatures;
51	/** The name of the operations. */
52	const char *pszName;
53
54	/**
55	* Destructor.
56	*
57	* @param pvThis The implementation specific data.
58	*/
59	DECLCALLBACKMEMBER(void, pfnDestroy)(void *pvThis);
60
61	/**
62	* Opens the root directory.
63	*
64	* @returns IPRT status code.
65	* @param pvThis The implementation specific data.
66	* @param phVfsDir Where to return the handle to the root directory.
67	*/
68	DECLCALLBACKMEMBER(int, pfnOpenRoot)(void *pvThis, PRTVFSDIR phVfsDir);
69
70	/** @todo There will be more methods here to optimize opening and
71	* querying. */
72
73	#if 0
74	/**
75	* Optional entry point for optimizing path traversal within the file system.
76	*
77	* @returns IPRT status code.
78	* @param pvThis The implementation specific data.
79	* @param pszPath The path to resolve.
80	* @param poffPath The current path offset on input, what we've
81	* traversed to on successful return.
82	* @param phVfs??? Return handle to what we've traversed.
83	* @param p??? Return other stuff...
84	*/
85	DECLCALLBACKMEMBER(int, pfnTraverse)(void pvThis, const char pszPath, size_t poffPath, PRTVFS??? phVfs?, ??? p???);
86	#endif
87
88	/** Marks the end of the structure (RTVFSOPS_VERSION). */
89	uintptr_t uEndMarker;
90	} RTVFSOPS;
91	/** Pointer to constant VFS operations. */
92	typedef RTVFSOPS const *PCRTVFSOPS;
93
94	/** The RTVFSOPS structure version. */
95	#define RTVFSOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x0f,1,0)
96
97	/** @name RTVFSOPS::fFeatures
98	* @{ */
99	/** The VFS supports attaching other systems. */
100	#define RTVFSOPS_FEAT_ATTACH RT_BIT_32(0)
101	/** @} */
102
103
104	/**
105	* The basis for all virtual file system objects except RTVFS.
106	*/
107	typedef struct RTVFSOBJOPS
108	{
109	/** The structure version (RTVFSOBJOPS_VERSION). */
110	uint32_t uVersion;
111	/** The object type for type introspection. */
112	RTVFSOBJTYPE enmType;
113	/** The name of the operations. */
114	const char *pszName;
115
116	/**
117	* Close the object.
118	*
119	* @returns IPRT status code.
120	* @param pvThis The implementation specific file data.
121	*/
122	DECLCALLBACKMEMBER(int, pfnClose)(void *pvThis);
123
124	/**
125	* Get information about the file.
126	*
127	* @returns IPRT status code.
128	* @param pvThis The implementation specific file data.
129	* @param pObjInfo Where to return the object info on success.
130	* @param enmAddAttr Which set of additional attributes to request.
131	* @sa RTFileQueryInfo
132	*/
133	DECLCALLBACKMEMBER(int, pfnQueryInfo)(void *pvThis, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
134
135	/** Marks the end of the structure (RTVFSOBJOPS_VERSION). */
136	uintptr_t uEndMarker;
137	} RTVFSOBJOPS;
138	/** Pointer to constant VFS object operations. */
139	typedef RTVFSOBJOPS const *PCRTVFSOBJOPS;
140
141	/** The RTVFSOBJOPS structure version. */
142	#define RTVFSOBJOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x1f,1,0)
143
144
145	/**
146	* Additional operations for setting object attributes.
147	*/
148	typedef struct RTVFSOBJSETOPS
149	{
150	/** The structure version (RTVFSOBJSETOPS_VERSION). */
151	uint32_t uVersion;
152	/** The offset to the RTVFSOBJOPS structure. */
153	int32_t offObjOps;
154
155	/**
156	* Set the unix style owner and group.
157	*
158	* @returns IPRT status code.
159	* @param pvThis The implementation specific file data.
160	* @param fMode The new mode bits.
161	* @param fMask The mask indicating which bits we are
162	* changing.
163	* @sa RTFileSetMode
164	*/
165	DECLCALLBACKMEMBER(int, pfnSetMode)(void *pvThis, RTFMODE fMode, RTFMODE fMask);
166
167	/**
168	* Set the timestamps associated with the object.
169	*
170	* @returns IPRT status code.
171	* @param pvThis The implementation specific file data.
172	* @param pAccessTime Pointer to the new access time. NULL if not
173	* to be changed.
174	* @param pModificationTime Pointer to the new modifcation time. NULL if
175	* not to be changed.
176	* @param pChangeTime Pointer to the new change time. NULL if not
177	* to be changed.
178	* @param pBirthTime Pointer to the new time of birth. NULL if
179	* not to be changed.
180	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
181	* host OS or underlying VFS provider.
182	* @sa RTFileSetTimes
183	*/
184	DECLCALLBACKMEMBER(int, pfnSetTimes)(void *pvThis, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
185	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
186
187	/**
188	* Set the unix style owner and group.
189	*
190	* @returns IPRT status code.
191	* @param pvThis The implementation specific file data.
192	* @param uid The user ID of the new owner. NIL_RTUID if
193	* unchanged.
194	* @param gid The group ID of the new owner group. NIL_RTGID if
195	* unchanged.
196	* @sa RTFileSetOwner
197	*/
198	DECLCALLBACKMEMBER(int, pfnSetOwner)(void *pvThis, RTUID uid, RTGID gid);
199
200	/** Marks the end of the structure (RTVFSOBJSETOPS_VERSION). */
201	uintptr_t uEndMarker;
202	} RTVFSOBJSETOPS;
203	/** Pointer to const object attribute setter operations. */
204	typedef RTVFSOBJSETOPS const *PCRTVFSOBJSETOPS;
205
206	/** The RTVFSOBJSETOPS structure version. */
207	#define RTVFSOBJSETOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x2f,1,0)
208
209
210	/**
211	* The filesystem stream operations.
212	*
213	* @extends RTVFSOBJOPS
214	*/
215	typedef struct RTVFSFSSTREAMOPS
216	{
217	/** The basic object operation. */
218	RTVFSOBJOPS Obj;
219	/** The structure version (RTVFSFSSTREAMOPS_VERSION). */
220	uint32_t uVersion;
221	/** Reserved field, MBZ. */
222	uint32_t fReserved;
223
224	/**
225	* Gets the next object in the stream.
226	*
227	* @returns IPRT status code.
228	* @retval VINF_SUCCESS if a new object was retrieved.
229	* @retval VERR_EOF when there are no more objects.
230	* @param pvThis The implementation specific directory data.
231	* @param ppszName Where to return the object name. Must be freed by
232	* calling RTStrFree.
233	* @param penmType Where to return the object type.
234	* @param hVfsObj Where to return the object handle (referenced).
235	* This must be cast to the desired type before use.
236	*/
237	DECLCALLBACKMEMBER(int, pfnNext)(void pvThis, char ppszName, RTVFSOBJTYPE penmType, PRTVFSOBJ phVfsObj);
238
239	/** Marks the end of the structure (RTVFSFSSTREAMOPS_VERSION). */
240	uintptr_t uEndMarker;
241	} RTVFSFSSTREAMOPS;
242	/** Pointer to const object attribute setter operations. */
243	typedef RTVFSFSSTREAMOPS const *PCRTVFSFSSTREAMOPS;
244
245	/** The RTVFSFSSTREAMOPS structure version. */
246	#define RTVFSFSSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x3f,1,0)
247
248
249	/**
250	* The directory operations.
251	*
252	* @extends RTVFSOBJOPS
253	* @extends RTVFSOBJSETOPS
254	*/
255	typedef struct RTVFSDIROPS
256	{
257	/** The basic object operation. */
258	RTVFSOBJOPS Obj;
259	/** The structure version (RTVFSDIROPS_VERSION). */
260	uint32_t uVersion;
261	/** Reserved field, MBZ. */
262	uint32_t fReserved;
263	/** The object setter operations. */
264	RTVFSOBJSETOPS ObjSet;
265
266	/**
267	* Opens a directory entry for traversal purposes.
268	*
269	* Method which sole purpose is helping the path traversal. Only one of
270	* the three output variables will be set, the others will left untouched
271	* (caller sets them to NIL).
272	*
273	* @returns IPRT status code.
274	* @retval VERR_PATH_NOT_FOUND if @a pszEntry was not found.
275	* @param pvThis The implementation specific directory data.
276	* @param pszEntry The name of the directory entry to remove.
277	* @param phVfsDir If not NULL and it is a directory, open it and
278	* return the handle here.
279	* @param phVfsSymlink If not NULL and it is a symbolic link, open it
280	* and return the handle here.
281	* @param phVfsMounted If not NULL and it is a mounted VFS directory,
282	* reference it and return the handle here.
283	* @todo Should com dir, symlinks and mount points using some common
284	* ancestor "class".
285	*/
286	DECLCALLBACKMEMBER(int, pfnTraversalOpen)(void pvThis, const char pszEntry, PRTVFSDIR phVfsDir,
287	PRTVFSSYMLINK phVfsSymlink, PRTVFS phVfsMounted);
288
289	/**
290	* Open or create a file.
291	*
292	* @returns IPRT status code.
293	* @param pvThis The implementation specific directory data.
294	* @param pszFilename The name of the immediate file to open or create.
295	* @param fOpen The open flags (RTFILE_O_XXX).
296	* @param phVfsFile Where to return the thandle to the opened file.
297	* @sa RTFileOpen.
298	*/
299	DECLCALLBACKMEMBER(int, pfnOpenFile)(void pvThis, const char pszFilename, uint32_t fOpen, PRTVFSFILE phVfsFile);
300
301	/**
302	* Open an existing subdirectory.
303	*
304	* @returns IPRT status code.
305	* @param pvThis The implementation specific directory data.
306	* @param pszSubDir The name of the immediate subdirectory to open.
307	* @param phVfsDir Where to return the handle to the opened directory.
308	* @sa RTDirOpen.
309	*/
310	DECLCALLBACKMEMBER(int, pfnOpenDir)(void pvThis, const char pszSubDir, PRTVFSDIR phVfsDir);
311
312	/**
313	* Creates a new subdirectory.
314	*
315	* @returns IPRT status code.
316	* @param pvThis The implementation specific directory data.
317	* @param pszSubDir The name of the immediate subdirectory to create.
318	* @param fMode The mode mask of the new directory.
319	* @param phVfsDir Where to optionally return the handle to the newly
320	* create directory.
321	* @sa RTDirCreate.
322	*/
323	DECLCALLBACKMEMBER(int, pfnCreateDir)(void pvThis, const char pszSubDir, RTFMODE fMode, PRTVFSDIR phVfsDir);
324
325	/**
326	* Opens an existing symbolic link.
327	*
328	* @returns IPRT status code.
329	* @param pvThis The implementation specific directory data.
330	* @param pszSymlink The name of the immediate symbolic link to open.
331	* @param phVfsSymlink Where to optionally return the handle to the
332	* newly create symbolic link.
333	* @sa RTSymlinkCreate.
334	*/
335	DECLCALLBACKMEMBER(int, pfnOpenSymlink)(void pvThis, const char pszSymlink, PRTVFSSYMLINK phVfsSymlink);
336
337	/**
338	* Creates a new symbolic link.
339	*
340	* @returns IPRT status code.
341	* @param pvThis The implementation specific directory data.
342	* @param pszSymlink The name of the immediate symbolic link to create.
343	* @param pszTarget The symbolic link target.
344	* @param enmType The symbolic link type.
345	* @param phVfsSymlink Where to optionally return the handle to the
346	* newly create symbolic link.
347	* @sa RTSymlinkCreate.
348	*/
349	DECLCALLBACKMEMBER(int, pfnCreateSymlink)(void pvThis, const char pszSymlink, const char *pszTarget,
350	RTSYMLINKTYPE enmType, PRTVFSSYMLINK phVfsSymlink);
351
352	/**
353	* Removes a directory entry.
354	*
355	* @returns IPRT status code.
356	* @param pvThis The implementation specific directory data.
357	* @param pszEntry The name of the directory entry to remove.
358	* @param fType If non-zero, this restricts the type of the entry to
359	* the object type indicated by the mask
360	* (RTFS_TYPE_XXX).
361	* @sa RTFileRemove, RTDirRemove, RTSymlinkRemove.
362	*/
363	DECLCALLBACKMEMBER(int, pfnUnlinkEntry)(void pvThis, const char pszEntry, RTFMODE fType, PRTVFSDIR phVfsDir);
364
365	/**
366	* Rewind the directory stream so that the next read returns the first
367	* entry.
368	*
369	* @returns IPRT status code.
370	* @param pvThis The implementation specific directory data.
371	*/
372	DECLCALLBACKMEMBER(int, pfnRewindDir)(void *pvThis);
373
374	/**
375	* Rewind the directory stream so that the next read returns the first
376	* entry.
377	*
378	* @returns IPRT status code.
379	* @param pvThis The implementation specific directory data.
380	* @param pDirEntry Output buffer.
381	* @param pcbDirEntry Complicated, see RTDirReadEx.
382	* @param enmAddAttr Which set of additional attributes to request.
383	* @sa RTDirReadEx
384	*/
385	DECLCALLBACKMEMBER(int, pfnReadDir)(void pvThis, PRTDIRENTRYEX pDirEntry, size_t pcbDirEntry, RTFSOBJATTRADD enmAddAttr);
386
387	/** Marks the end of the structure (RTVFSDIROPS_VERSION). */
388	uintptr_t uEndMarker;
389	} RTVFSDIROPS;
390	/** Pointer to const directory operations. */
391	typedef RTVFSDIROPS const *PCRTVFSDIROPS;
392	/** The RTVFSDIROPS structure version. */
393	#define RTVFSDIROPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x4f,1,0)
394
395
396	/**
397	* The symbolic link operations.
398	*
399	* @extends RTVFSOBJOPS
400	* @extends RTVFSOBJSETOPS
401	*/
402	typedef struct RTVFSSYMLINKOPS
403	{
404	/** The basic object operation. */
405	RTVFSOBJOPS Obj;
406	/** The structure version (RTVFSSYMLINKOPS_VERSION). */
407	uint32_t uVersion;
408	/** Reserved field, MBZ. */
409	uint32_t fReserved;
410	/** The object setter operations. */
411	RTVFSOBJSETOPS ObjSet;
412
413	/**
414	* Read the symbolic link target.
415	*
416	* @returns IPRT status code.
417	* @param pvThis The implementation specific symbolic link data.
418	* @param pszTarget The target buffer.
419	* @param cbTarget The size of the target buffer.
420	* @sa RTSymlinkRead
421	*/
422	DECLCALLBACKMEMBER(int, pfnRead)(void pvThis, char pszTarget, size_t cbTarget);
423
424	/** Marks the end of the structure (RTVFSSYMLINKOPS_VERSION). */
425	uintptr_t uEndMarker;
426	} RTVFSSYMLINKOPS;
427	/** Pointer to const symbolic link operations. */
428	typedef RTVFSSYMLINKOPS const *PCRTVFSSYMLINKOPS;
429	/** The RTVFSSYMLINKOPS structure version. */
430	#define RTVFSSYMLINKOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x5f,1,0)
431
432
433	/**
434	* The basis for all I/O objects (files, pipes, sockets, devices, ++).
435	*
436	* @extends RTVFSOBJOPS
437	*/
438	typedef struct RTVFSIOSTREAMOPS
439	{
440	/** The basic object operation. */
441	RTVFSOBJOPS Obj;
442	/** The structure version (RTVFSIOSTREAMOPS_VERSION). */
443	uint32_t uVersion;
444	/** Reserved field, MBZ. */
445	uint32_t fReserved;
446
447	/**
448	* Reads from the file/stream.
449	*
450	* @returns IPRT status code. See RTVfsIoStrmRead.
451	* @param pvThis The implementation specific file data.
452	* @param off Where to read at, -1 for the current position.
453	* @param pSgBuf Gather buffer describing the bytes that are to be
454	* written.
455	* @param fBlocking If @c true, the call is blocking, if @c false it
456	* should not block.
457	* @param pcbRead Where return the number of bytes actually read.
458	* This is set it 0 by the caller. If NULL, try read
459	* all and fail if incomplete.
460	* @sa RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
461	* RTVfsFileReadAt, RTFileRead, RTFileReadAt.
462	*/
463	DECLCALLBACKMEMBER(int, pfnRead)(void pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t pcbRead);
464
465	/**
466	* Writes to the file/stream.
467	*
468	* @returns IPRT status code.
469	* @param pvThis The implementation specific file data.
470	* @param off Where to start wrinting, -1 for the current
471	* position.
472	* @param pSgBuf Gather buffers describing the bytes that are to be
473	* written.
474	* @param fBlocking If @c true, the call is blocking, if @c false it
475	* should not block.
476	* @param pcbWritten Where to return the number of bytes actually
477	* written. This is set it 0 by the caller. If
478	* NULL, try write it all and fail if incomplete.
479	* @sa RTFileWrite, RTFileWriteAt.
480	*/
481	DECLCALLBACKMEMBER(int, pfnWrite)(void pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t pcbWritten);
482
483	/**
484	* Flushes any pending data writes to the stream.
485	*
486	* @returns IPRT status code.
487	* @param pvThis The implementation specific file data.
488	* @sa RTFileFlush.
489	*/
490	DECLCALLBACKMEMBER(int, pfnFlush)(void *pvThis);
491
492	/**
493	* Poll for events.
494	*
495	* @returns IPRT status code.
496	* @param pvThis The implementation specific file data.
497	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
498	* @param cMillies How long to wait for event to eventuate.
499	* @param fIntr Whether the wait is interruptible and can return
500	* VERR_INTERRUPTED (@c true) or if this condition
501	* should be hidden from the caller (@c false).
502	* @param pfRetEvents Where to return the event mask.
503	* @sa RTPollSetAdd, RTPoll, RTPollNoResume.
504	*/
505	DECLCALLBACKMEMBER(int, pfnPollOne)(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
506	uint32_t *pfRetEvents);
507
508	/**
509	* Tells the current file/stream position.
510	*
511	* @returns IPRT status code.
512	* @param pvThis The implementation specific file data.
513	* @param poffActual Where to return the actual offset.
514	* @sa RTFileTell
515	*/
516	DECLCALLBACKMEMBER(int, pfnTell)(void *pvThis, PRTFOFF poffActual);
517
518	/**
519	* Skips @a cb ahead in the stream.
520	*
521	* @returns IPRT status code.
522	* @param pvThis The implementation specific file data.
523	* @param cb The number bytes to skip.
524	* @remarks This is optional and can be NULL.
525	*/
526	DECLCALLBACKMEMBER(int, pfnSkip)(void *pvThis, RTFOFF cb);
527
528	/**
529	* Fills the stream with @a cb zeros.
530	*
531	* @returns IPRT status code.
532	* @param pvThis The implementation specific file data.
533	* @param cb The number of zero bytes to insert.
534	* @remarks This is optional and can be NULL.
535	*/
536	DECLCALLBACKMEMBER(int, pfnZeroFill)(void *pvThis, RTFOFF cb);
537
538	/** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
539	uintptr_t uEndMarker;
540	} RTVFSIOSTREAMOPS;
541	/** Pointer to const I/O stream operations. */
542	typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
543
544	/** The RTVFSIOSTREAMOPS structure version. */
545	#define RTVFSIOSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
546
547
548	/**
549	* Creates a new VFS I/O stream handle.
550	*
551	* @returns IPRT status code
552	* @param pIoStreamOps The I/O stream operations.
553	* @param cbInstance The size of the instance data.
554	* @param fOpen The open flags. The minimum is the access mask.
555	* @param hVfs The VFS handle to associate this file with.
556	* NIL_VFS is ok.
557	* @param hSemRW The read-write semaphore to use to protect the
558	* handle if this differs from the one the VFS
559	* uses. NIL_RTSEMRW is ok if no locking is
560	* desired.
561	* @param phVfsIos Where to return the new handle.
562	* @param ppvInstance Where to return the pointer to the instance data
563	* (size is @a cbInstance).
564	*/
565	RTDECL(int) RTVfsNewIoStream(PCRTVFSIOSTREAMOPS pIoStreamOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTSEMRW hSemRW,
566	PRTVFSIOSTREAM phVfsIos, void **ppvInstance);
567
568
569	/**
570	* The file operations.
571	*
572	* @extends RTVFSIOSTREAMOPS
573	* @extends RTVFSOBJSETOPS
574	*/
575	typedef struct RTVFSFILEOPS
576	{
577	/** The I/O stream and basis object operations. */
578	RTVFSIOSTREAMOPS Stream;
579	/** The structure version (RTVFSFILEOPS_VERSION). */
580	uint32_t uVersion;
581	/** Reserved field, MBZ. */
582	uint32_t fReserved;
583	/** The object setter operations. */
584	RTVFSOBJSETOPS ObjSet;
585
586	/**
587	* Changes the current file position.
588	*
589	* @returns IPRT status code.
590	* @param pvThis The implementation specific file data.
591	* @param offSeek The offset to seek.
592	* @param uMethod The seek method, i.e. what the seek is relative to.
593	* @param poffActual Where to return the actual offset.
594	* @sa RTFileSeek
595	*/
596	DECLCALLBACKMEMBER(int, pfnSeek)(void *pvThis, RTFOFF offSeek, unsigned uMethod, PRTFOFF poffActual);
597
598	/**
599	* Get the current file/stream size.
600	*
601	* @returns IPRT status code.
602	* @param pvThis The implementation specific file data.
603	* @param pcbFile Where to store the current file size.
604	* @sa RTFileGetSize
605	*/
606	DECLCALLBACKMEMBER(int, pfnQuerySize)(void pvThis, uint64_t pcbFile);
607
608	/** @todo There will be more methods here. */
609
610	/** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
611	uintptr_t uEndMarker;
612	} RTVFSFILEOPS;
613	/** Pointer to const file operations. */
614	typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
615
616	/** The RTVFSFILEOPS structure version. */
617	#define RTVFSFILEOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x7f,1,0)
618
619	/**
620	* Creates a new VFS file handle.
621	*
622	* @returns IPRT status code
623	* @param pFileOps The file operations.
624	* @param cbInstance The size of the instance data.
625	* @param fOpen The open flags. The minimum is the access mask.
626	* @param hVfs The VFS handle to associate this file with.
627	* NIL_VFS is ok.
628	* @param phVfsFile Where to return the new handle.
629	* @param ppvInstance Where to return the pointer to the instance data
630	* (size is @a cbInstance).
631	*/
632	RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs,
633	PRTVFSFILE phVfsFile, void **ppvInstance);
634
635
636	/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
637	* @{ */
638
639	/**
640	* Parsed path.
641	*/
642	typedef struct RTVFSPARSEDPATH
643	{
644	/** The length of the path in szCopy. */
645	uint16_t cch;
646	/** The number of path components. */
647	uint16_t cComponents;
648	/** Set if the path ends with slash, indicating that it's a directory
649	* reference and not a file reference. The slash has been removed from
650	* the copy. */
651	bool fDirSlash;
652	/** The offset where each path component starts, i.e. the char after the
653	* slash. The array has cComponents + 1 entries, where the final one is
654	* cch + 1 so that one can always terminate the current component by
655	* szPath[aoffComponent[i] - 1] = '\0'. */
656	uint16_t aoffComponents[RTPATH_MAX / 2 + 1];
657	/** A normalized copy of the path.
658	* Reserve some extra space so we can be more relaxed about overflow
659	* checks and terminator paddings, especially when recursing. */
660	char szPath[RTPATH_MAX];
661	} RTVFSPARSEDPATH;
662	/** Pointer to a parsed path. */
663	typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
664
665	/** The max accepted path length.
666	* This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
667	* use two terminators and wish be a little bit lazy with checking. */
668	#define RTVFSPARSEDPATH_MAX (RTPATH_MAX - 4)
669
670	/**
671	* Appends @a pszPath (relative) to the already parsed path @a pPath.
672	*
673	* @retval VINF_SUCCESS
674	* @retval VERR_FILENAME_TOO_LONG
675	* @retval VERR_INTERNAL_ERROR_4
676	* @param pPath The parsed path to append @a pszPath onto.
677	* This is both input and output.
678	* @param pszPath The path to append. This must be relative.
679	* @param piRestartComp The component to restart parsing at. This is
680	* input/output. The input does not have to be
681	* within the valid range. Optional.
682	*/
683	RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char pszPath, uint16_t piRestartComp);
684
685	/**
686	* Parses a path.
687	*
688	* @retval VINF_SUCCESS
689	* @retval VERR_FILENAME_TOO_LONG
690	* @param pPath Where to store the parsed path.
691	* @param pszPath The path to parse. Absolute or relative to @a
692	* pszCwd.
693	* @param pszCwd The current working directory. Must be
694	* absolute.
695	*/
696	RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char pszPath, const char pszCwd);
697
698	/**
699	* Same as RTVfsParsePath except that it allocates a temporary buffer.
700	*
701	* @retval VINF_SUCCESS
702	* @retval VERR_NO_TMP_MEMORY
703	* @retval VERR_FILENAME_TOO_LONG
704	* @param pszPath The path to parse. Absolute or relative to @a
705	* pszCwd.
706	* @param pszCwd The current working directory. Must be
707	* absolute.
708	* @param ppPath Where to store the pointer to the allocated
709	* buffer containing the parsed path. This must
710	* be freed by calling RTVfsParsePathFree. NULL
711	* will be stored on failured.
712	*/
713	RTDECL(int) RTVfsParsePathA(const char pszPath, const char pszCwd, PRTVFSPARSEDPATH *ppPath);
714
715	/**
716	* Frees a buffer returned by RTVfsParsePathA.
717	*
718	* @param pPath The parsed path buffer to free. NULL is fine.
719	*/
720	RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
721
722	/** @} */
723
724
725	/** @defgroup grp_rt_vfs_lowlevel_chain VFS Chains
726	* @ref grp_rt_vfs_chain
727	* @{
728	*/
729
730
731	/**
732	* Chain element input actions.
733	*/
734	typedef enum RTVFSCHAINACTION
735	{
736	/** Invalid action. */
737	RTVFSCHAINACTION_INVALID = 0,
738	/** No action (start of the chain). */
739	RTVFSCHAINACTION_NONE,
740	/** Passive filtering (expressed by pipe symbol). */
741	RTVFSCHAINACTION_PASSIVE,
742	/** Push filtering (expressed by redirection-out symbol). */
743	RTVFSCHAINACTION_PUSH,
744	/** The end of the valid actions. */
745	RTVFSCHAINACTION_END,
746	/** Make sure it's a 32-bit type. */
747	RTVFSCHAINACTION_32BIT_HACK = 0x7fffffff
748	} RTVFSCHAINACTION;
749
750
751	/**
752	* VFS chain element specification.
753	*/
754	typedef struct RTVFSCHAINELEMSPEC
755	{
756	/** The provider name. */
757	char *pszProvider;
758	/** The input type. */
759	RTVFSOBJTYPE enmTypeIn;
760	/** The output type. */
761	RTVFSOBJTYPE enmTypeOut;
762	/** The action to take (or not). */
763	RTVFSCHAINACTION enmAction;
764	/** The number of arguments. */
765	uint32_t cArgs;
766	/** Arguments. */
767	char **papszArgs;
768	} RTVFSCHAINELEMSPEC;
769	/** Pointer to a chain element specification. */
770	typedef RTVFSCHAINELEMSPEC *PRTVFSCHAINELEMSPEC;
771	/** Pointer to a const chain element specification. */
772	typedef RTVFSCHAINELEMSPEC const *PCRTVFSCHAINELEMSPEC;
773
774
775	/**
776	* Parsed VFS chain specification.
777	*/
778	typedef struct RTVFSCHAINSPEC
779	{
780	/** The action element, UINT32_MAX if none.
781	* Currently we only support one action element (RTVFSCHAINACTION_PASSIVE
782	* is not considered). */
783	uint32_t iActionElement;
784	/** The number of elements. */
785	uint32_t cElements;
786	/** The elements. */
787	PRTVFSCHAINELEMSPEC paElements;
788	} RTVFSCHAINSPEC;
789	/** Pointer to a parsed VFS chain specification. */
790	typedef RTVFSCHAINSPEC *PRTVFSCHAINSPEC;
791	/** Pointer to a const, parsed VFS chain specification. */
792	typedef RTVFSCHAINSPEC const *PCRTVFSCHAINSPEC;
793
794
795	/**
796	* A chain element provider registration record.
797	*/
798	typedef struct RTVFSCHAINELEMENTREG
799	{
800	/** The version (RTVFSCHAINELEMENTREG_VERSION). */
801	uint32_t uVersion;
802	/** Reserved, MBZ. */
803	uint32_t fReserved;
804	/** The provider name (unique). */
805	const char *pszName;
806	/** For chaining the providers. */
807	RTLISTNODE ListEntry;
808
809	/**
810	* Create a VFS from the given chain element specficiation.
811	*
812	* @returns IPRT status code.
813	* @param pSpec The chain element specification.
814	* @param phVfs Where to returned the VFS handle.
815	*/
816	DECLCALLBACKMEMBER(int, pfnOpenVfs)( PCRTVFSCHAINELEMSPEC pSpec, PRTVFS phVfs);
817
818	/**
819	* Open a directory from the given chain element specficiation.
820	*
821	* @returns IPRT status code.
822	* @param pSpec The chain element specification.
823	* @param phVfsDir Where to returned the directory handle.
824	*/
825	DECLCALLBACKMEMBER(int, pfnOpenDir)( PCRTVFSCHAINELEMSPEC pSpec, PRTVFSDIR phVfsDir);
826
827	/**
828	* Open a file from the given chain element specficiation.
829	*
830	* @returns IPRT status code.
831	* @param pSpec The chain element specification.
832	* @param fOpen The open flag. Can be zero and the
833	* specification may modify it.
834	* @param phVfsFile Where to returned the file handle.
835	*/
836	DECLCALLBACKMEMBER(int, pfnOpenFile)( PCRTVFSCHAINELEMSPEC pSpec, uint32_t fOpen, PRTVFSFILE phVfsFile);
837
838	/**
839	* Open a symlink from the given chain element specficiation.
840	*
841	* @returns IPRT status code.
842	* @param pSpec The chain element specification.
843	* @param phVfsSym Where to returned the symlink handle.
844	*/
845	DECLCALLBACKMEMBER(int, pfnOpenSymlink)( PCRTVFSCHAINELEMSPEC pSpec, PRTVFSSYMLINK phVfsSym);
846
847	/**
848	* Open a I/O stream from the given chain element specficiation.
849	*
850	* @returns IPRT status code.
851	* @param pSpec The chain element specification.
852	* @param fOpen The open flag. Can be zero and the
853	* specification may modify it.
854	* @param phVfsIos Where to returned the I/O stream handle.
855	*/
856	DECLCALLBACKMEMBER(int, pfnOpenIoStream)(PCRTVFSCHAINELEMSPEC pSpec, uint32_t fOpen, PRTVFSIOSTREAM phVfsIos);
857
858	/**
859	* Open a filesystem stream from the given chain element specficiation.
860	*
861	* @returns IPRT status code.
862	* @param pSpec The chain element specification.
863	* @param phVfsFss Where to returned the filesystem stream handle.
864	*/
865	DECLCALLBACKMEMBER(int, pfnOpenFsStream)(PCRTVFSCHAINELEMSPEC pSpec, PRTVFSFSSTREAM phVfsFss);
866
867	/** End marker (RTVFSCHAINELEMENTREG_VERSION). */
868	uintptr_t uEndMarker;
869	} RTVFSCHAINELEMENTREG;
870	/** Pointer to a VFS chain element registration record. */
871	typedef RTVFSCHAINELEMENTREG *PRTVFSCHAINELEMENTREG;
872	/** Pointer to a const VFS chain element registration record. */
873	typedef RTVFSCHAINELEMENTREG const *PCRTVFSCHAINELEMENTREG;
874
875	/** The VFS chain element registration record version number. */
876	#define RTVFSCHAINELEMENTREG_VERSION RT_MAKE_U32_FROM_U8(0xff, 0x7f, 1, 0)
877
878
879	/**
880	* Parses the specification.
881	*
882	* @returns IPRT status code.
883	* @param pszSpec The specification string to parse.
884	* @param fFlags Flags, see RTVFSCHAIN_PF_XXX.
885	* @param enmLeadingAction The only allowed leading action type.
886	* @param enmTrailingAction The only allowed trailing action type.
887	* @param ppSpec Where to return the pointer to the parsed
888	* specification. This must be freed by calling
889	* RTVfsChainSpecFree. Will always be set (unless
890	* invalid parameters.)
891	* @param ppszError On failure, this will point at the error
892	* location in @a pszSpec. Optional.
893	*/
894	RTDECL(int) RTVfsChainSpecParse(const char *pszSpec, RTVFSCHAINACTION enmLeadingAction,
895	RTVFSCHAINACTION enmTrailingAction,
896	PRTVFSCHAINSPEC ppSpec, const char ppszError);
897
898	/** @name RTVfsChainSpecParse
899	* @{ */
900	/** No real action is permitted, i.e. only passive filtering (aka pipe). */
901	#define RTVFSCHAIN_PF_NO_REAL_ACTION RT_BIT_32(0)
902	/** The specified leading action is optional. */
903	#define RTVFSCHAIN_PF_LEADING_ACTION_OPTIONAL RT_BIT_32(1)
904	/** The specified trailing action is optional. */
905	#define RTVFSCHAIN_PF_TRAILING_ACTION_OPTIONAL RT_BIT_32(2)
906	/** Mask of valid flags. */
907	#define RTVFSCHAIN_PF_VALID_MASK UINT32_C(0x00000007)
908	/** @}*/
909
910	/**
911	* Frees a parsed chain specification.
912	*
913	* @param pSpec What RTVfsChainSpecParse returned. NULL is
914	* quietly ignored.
915	*/
916	RTDECL(void) RTVfsChainSpecFree(PRTVFSCHAINSPEC pSpec);
917
918	/**
919	* Registers a chain element provider.
920	*
921	* @returns IPRT status code
922	* @param pRegRec The registration record.
923	* @param fFromCtor Indicates where we're called from.
924	*/
925	RTDECL(int) RTVfsChainElementRegisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromCtor);
926
927	/**
928	* Deregisters a chain element provider.
929	*
930	* @returns IPRT status code
931	* @param pRegRec The registration record.
932	* @param fFromDtor Indicates where we're called from.
933	*/
934	RTDECL(int) RTVfsChainElementDeregisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromDtor);
935
936
937	/** @def RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER
938	* Automatically registers a chain element provider using a global constructor
939	* and destructor hack.
940	*
941	* @param pRegRec Pointer to the registration record.
942	* @param name Some unique variable name prefix.
943	*/
944
945	#ifdef __cplusplus
946	/**
947	* Class used for registering a VFS chain element provider.
948	*/
949	class RTVfsChainElementAutoRegisterHack
950	{
951	private:
952	/** The registration record, NULL if registration failed. */
953	PRTVFSCHAINELEMENTREG m_pRegRec;
954
955	public:
956	RTVfsChainElementAutoRegisterHack(PRTVFSCHAINELEMENTREG a_pRegRec)
957	: m_pRegRec(a_pRegRec)
958	{
959	int rc = RTVfsChainElementRegisterProvider(m_pRegRec, true);
960	if (RT_FAILURE(rc))
961	m_pRegRec = NULL;
962	}
963
964	~RTVfsChainElementAutoRegisterHack()
965	{
966	RTVfsChainElementDeregisterProvider(m_pRegRec, true);
967	m_pRegRec = NULL;
968	}
969	};
970
971	# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
972	static RTVfsChainElementAutoRegisterHack name ## AutoRegistrationHack(pRegRec)
973
974	#else
975	# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
976	extern void *name ## AutoRegistrationHack = \
977	&Sorry_but_RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER_does_not_work_in_c_source_files
978	#endif
979
980
981	/** @} */
982
983
984	/** @} */
985
986	RT_C_DECLS_END
987
988	#endif /* !___iprt_vfslowlevel_h */
989

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

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

Download in other formats: