vfslowlevel.h@ 33945

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

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

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

Download in other formats: