vfslowlevel.h@ 33903

Last change on this file since 33903 was 33903, checked in by vboxsync, 14 years ago
iprt: More VFS and gunzip code.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 26.3 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/param.h>
31
32
33	RT_C_DECLS_BEGIN
34
35	/** @defgroup grp_rt_vfs_lowlevel RTVfs - Low-level Interface.
36	* @ingroup grp_rt_vfs
37	* @{
38	*/
39
40	/**
41	* The VFS operations.
42	*/
43	typedef struct RTVFSOPS
44	{
45	/** The structure version (RTVFSOPS_VERSION). */
46	uint32_t uVersion;
47	/** The virtual file system feature mask. */
48	uint32_t fFeatures;
49	/** The name of the operations. */
50	const char *pszName;
51
52	/**
53	* Destructor.
54	*
55	* @param pvThis The implementation specific data.
56	*/
57	DECLCALLBACKMEMBER(void, pfnDestroy)(void *pvThis);
58
59	/**
60	* Opens the root directory.
61	*
62	* @returns IPRT status code.
63	* @param pvThis The implementation specific data.
64	* @param phVfsDir Where to return the handle to the root directory.
65	*/
66	DECLCALLBACKMEMBER(int, pfnOpenRoot)(void *pvThis, PRTVFSDIR phVfsDir);
67
68	/** @todo There will be more methods here to optimize opening and
69	* querying. */
70
71	#if 0
72	/**
73	* Optional entry point for optimizing path traversal within the file system.
74	*
75	* @returns IPRT status code.
76	* @param pvThis The implementation specific data.
77	* @param pszPath The path to resolve.
78	* @param poffPath The current path offset on input, what we've
79	* traversed to on successful return.
80	* @param phVfs??? Return handle to what we've traversed.
81	* @param p??? Return other stuff...
82	*/
83	DECLCALLBACKMEMBER(int, pfnTraverse)(void pvThis, const char pszPath, size_t poffPath, PRTVFS??? phVfs?, ??? p???);
84	#endif
85
86	/** Marks the end of the structure (RTVFSOPS_VERSION). */
87	uintptr_t uEndMarker;
88	} RTVFSOPS;
89	/** Pointer to constant VFS operations. */
90	typedef RTVFSOPS const *PCRTVFSOPS;
91
92	/** The RTVFSOPS structure version. */
93	#define RTVFSOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x0f,1,0)
94
95	/** @name RTVFSOPS::fFeatures
96	* @{ */
97	/** The VFS supports attaching other systems. */
98	#define RTVFSOPS_FEAT_ATTACH RT_BIT_32(0)
99	/** @} */
100
101
102	/**
103	* The object type.
104	*/
105	typedef enum RTVFSOBJTYPE
106	{
107	/** Invalid type. */
108	RTVFSOBJTYPE_INVALID = 0,
109	/** Directory. */
110	RTVFSOBJTYPE_DIR,
111	/** Pure I/O stream. */
112	RTVFSOBJTYPE_IOSTREAM,
113	/** File. */
114	RTVFSOBJTYPE_FILE,
115	/** Symbolic link. */
116	RTVFSOBJTYPE_SYMLINK,
117	/** End of valid object types. */
118	RTVFSOBJTYPE_END,
119	/** Pure I/O stream. */
120	RTVFSOBJTYPE_32BIT_HACK = 0x7fffffff
121	} RTVFSOBJTYPE;
122
123	/**
124	* The basis for all virtual file system objects except RTVFS.
125	*/
126	typedef struct RTVFSOBJOPS
127	{
128	/** The structure version (RTVFSOBJOPS_VERSION). */
129	uint32_t uVersion;
130	/** The object type for type introspection. */
131	RTVFSOBJTYPE enmType;
132	/** The name of the operations. */
133	const char *pszName;
134
135	/**
136	* Close the object.
137	*
138	* @returns IPRT status code.
139	* @param pvThis The implementation specific file data.
140	*/
141	DECLCALLBACKMEMBER(int, pfnClose)(void *pvThis);
142
143	/**
144	* Get information about the file.
145	*
146	* @returns IPRT status code.
147	* @param pvThis The implementation specific file data.
148	* @param pObjInfo Where to return the object info on success.
149	* @param enmAddAttr Which set of additional attributes to request.
150	* @sa RTFileQueryInfo
151	*/
152	DECLCALLBACKMEMBER(int, pfnQueryInfo)(void *pvThis, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
153
154	/** Marks the end of the structure (RTVFSOBJOPS_VERSION). */
155	uintptr_t uEndMarker;
156	} RTVFSOBJOPS;
157	/** Pointer to constant VFS object operations. */
158	typedef RTVFSOBJOPS const *PCRTVFSOBJOPS;
159
160	/** The RTVFSOBJOPS structure version. */
161	#define RTVFSOBJOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x1f,1,0)
162
163
164	/**
165	* Additional operations for setting object attributes.
166	*/
167	typedef struct RTVFSOBJSETOPS
168	{
169	/** The structure version (RTVFSOBJSETOPS_VERSION). */
170	uint32_t uVersion;
171	/** The offset to the RTVFSOBJOPS structure. */
172	int32_t offObjOps;
173
174	/**
175	* Set the unix style owner and group.
176	*
177	* @returns IPRT status code.
178	* @param pvThis The implementation specific file data.
179	* @param fMode The new mode bits.
180	* @param fMask The mask indicating which bits we are
181	* changing.
182	* @sa RTFileSetMode
183	*/
184	DECLCALLBACKMEMBER(int, pfnSetMode)(void *pvThis, RTFMODE fMode, RTFMODE fMask);
185
186	/**
187	* Set the timestamps associated with the object.
188	*
189	* @returns IPRT status code.
190	* @param pvThis The implementation specific file data.
191	* @param pAccessTime Pointer to the new access time. NULL if not
192	* to be changed.
193	* @param pModificationTime Pointer to the new modifcation time. NULL if
194	* not to be changed.
195	* @param pChangeTime Pointer to the new change time. NULL if not
196	* to be changed.
197	* @param pBirthTime Pointer to the new time of birth. NULL if
198	* not to be changed.
199	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
200	* host OS or underlying VFS provider.
201	* @sa RTFileSetTimes
202	*/
203	DECLCALLBACKMEMBER(int, pfnSetTimes)(void *pvThis, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
204	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
205
206	/**
207	* Set the unix style owner and group.
208	*
209	* @returns IPRT status code.
210	* @param pvThis The implementation specific file data.
211	* @param uid The user ID of the new owner. NIL_RTUID if
212	* unchanged.
213	* @param gid The group ID of the new owner group. NIL_RTGID if
214	* unchanged.
215	* @sa RTFileSetOwner
216	*/
217	DECLCALLBACKMEMBER(int, pfnSetOwner)(void *pvThis, RTUID uid, RTGID gid);
218
219	/** Marks the end of the structure (RTVFSOBJSETOPS_VERSION). */
220	uintptr_t uEndMarker;
221	} RTVFSOBJSETOPS;
222	/** Pointer to const object attribute setter operations. */
223	typedef RTVFSOBJSETOPS const *PCRTVFSOBJSETOPS;
224
225	/** The RTVFSOBJSETOPS structure version. */
226	#define RTVFSOBJSETOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x2f,1,0)
227
228
229	/**
230	* The directory operations.
231	*
232	* @extends RTVFSOBJOPS
233	* @extends RTVFSOBJSETOPS
234	*/
235	typedef struct RTVFSDIROPS
236	{
237	/** The basic object operation. */
238	RTVFSOBJOPS Obj;
239	/** The structure version (RTVFSDIROPS_VERSION). */
240	uint32_t uVersion;
241	/** Reserved field, MBZ. */
242	uint32_t fReserved;
243	/** The object setter operations. */
244	RTVFSOBJSETOPS ObjSet;
245
246	/**
247	* Opens a directory entry for traversal purposes.
248	*
249	* Method which sole purpose is helping the path traversal. Only one of
250	* the three output variables will be set, the others will left untouched
251	* (caller sets them to NIL).
252	*
253	* @returns IPRT status code.
254	* @retval VERR_PATH_NOT_FOUND if @a pszEntry was not found.
255	* @param pvThis The implementation specific directory data.
256	* @param pszEntry The name of the directory entry to remove.
257	* @param phVfsDir If not NULL and it is a directory, open it and
258	* return the handle here.
259	* @param phVfsSymlink If not NULL and it is a symbolic link, open it
260	* and return the handle here.
261	* @param phVfsMounted If not NULL and it is a mounted VFS directory,
262	* reference it and return the handle here.
263	* @todo Should com dir, symlinks and mount points using some common
264	* ancestor "class".
265	*/
266	DECLCALLBACKMEMBER(int, pfnTraversalOpen)(void pvThis, const char pszEntry, PRTVFSDIR phVfsDir,
267	PRTVFSSYMLINK phVfsSymlink, PRTVFS phVfsMounted);
268
269	/**
270	* Open or create a file.
271	*
272	* @returns IPRT status code.
273	* @param pvThis The implementation specific directory data.
274	* @param pszFilename The name of the immediate file to open or create.
275	* @param fOpen The open flags (RTFILE_O_XXX).
276	* @param phVfsFile Where to return the thandle to the opened file.
277	* @sa RTFileOpen.
278	*/
279	DECLCALLBACKMEMBER(int, pfnOpenFile)(void pvThis, const char pszFilename, uint32_t fOpen, PRTVFSFILE phVfsFile);
280
281	/**
282	* Open an existing subdirectory.
283	*
284	* @returns IPRT status code.
285	* @param pvThis The implementation specific directory data.
286	* @param pszSubDir The name of the immediate subdirectory to open.
287	* @param phVfsDir Where to return the handle to the opened directory.
288	* @sa RTDirOpen.
289	*/
290	DECLCALLBACKMEMBER(int, pfnOpenDir)(void pvThis, const char pszSubDir, PRTVFSDIR phVfsDir);
291
292	/**
293	* Creates a new subdirectory.
294	*
295	* @returns IPRT status code.
296	* @param pvThis The implementation specific directory data.
297	* @param pszSubDir The name of the immediate subdirectory to create.
298	* @param fMode The mode mask of the new directory.
299	* @param phVfsDir Where to optionally return the handle to the newly
300	* create directory.
301	* @sa RTDirCreate.
302	*/
303	DECLCALLBACKMEMBER(int, pfnCreateDir)(void pvThis, const char pszSubDir, RTFMODE fMode, PRTVFSDIR phVfsDir);
304
305	/**
306	* Opens an existing symbolic link.
307	*
308	* @returns IPRT status code.
309	* @param pvThis The implementation specific directory data.
310	* @param pszSymlink The name of the immediate symbolic link to open.
311	* @param phVfsSymlink Where to optionally return the handle to the
312	* newly create symbolic link.
313	* @sa RTSymlinkCreate.
314	*/
315	DECLCALLBACKMEMBER(int, pfnOpenSymlink)(void pvThis, const char pszSymlink, PRTVFSSYMLINK phVfsSymlink);
316
317	/**
318	* Creates a new symbolic link.
319	*
320	* @returns IPRT status code.
321	* @param pvThis The implementation specific directory data.
322	* @param pszSymlink The name of the immediate symbolic link to create.
323	* @param pszTarget The symbolic link target.
324	* @param enmType The symbolic link type.
325	* @param phVfsSymlink Where to optionally return the handle to the
326	* newly create symbolic link.
327	* @sa RTSymlinkCreate.
328	*/
329	DECLCALLBACKMEMBER(int, pfnCreateSymlink)(void pvThis, const char pszSymlink, const char *pszTarget,
330	RTSYMLINKTYPE enmType, PRTVFSSYMLINK phVfsSymlink);
331
332	/**
333	* Removes a directory entry.
334	*
335	* @returns IPRT status code.
336	* @param pvThis The implementation specific directory data.
337	* @param pszEntry The name of the directory entry to remove.
338	* @param fType If non-zero, this restricts the type of the entry to
339	* the object type indicated by the mask
340	* (RTFS_TYPE_XXX).
341	* @sa RTFileRemove, RTDirRemove, RTSymlinkRemove.
342	*/
343	DECLCALLBACKMEMBER(int, pfnUnlinkEntry)(void pvThis, const char pszEntry, RTFMODE fType, PRTVFSDIR phVfsDir);
344
345	/**
346	* Rewind the directory stream so that the next read returns the first
347	* entry.
348	*
349	* @returns IPRT status code.
350	* @param pvThis The implementation specific directory data.
351	*/
352	DECLCALLBACKMEMBER(int, pfnRewindDir)(void *pvThis);
353
354	/**
355	* Rewind the directory stream so that the next read returns the first
356	* entry.
357	*
358	* @returns IPRT status code.
359	* @param pvThis The implementation specific directory data.
360	* @param pDirEntry Output buffer.
361	* @param pcbDirEntry Complicated, see RTDirReadEx.
362	* @param enmAddAttr Which set of additional attributes to request.
363	* @sa RTDirReadEx
364	*/
365	DECLCALLBACKMEMBER(int, pfnReadDir)(void pvThis, PRTDIRENTRYEX pDirEntry, size_t pcbDirEntry, RTFSOBJATTRADD enmAddAttr);
366
367
368	/** Marks the end of the structure (RTVFSDIROPS_VERSION). */
369	uintptr_t uEndMarker;
370	} RTVFSDIROPS;
371	/** Pointer to const directory operations. */
372	typedef RTVFSDIROPS const *PCRTVFSDIROPS;
373	/** The RTVFSDIROPS structure version. */
374	#define RTVFSDIROPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x3f,1,0)
375
376
377	/**
378	* The symbolic link operations.
379	*
380	* @extends RTVFSOBJOPS
381	* @extends RTVFSOBJSETOPS
382	*/
383	typedef struct RTVFSSYMLINKOPS
384	{
385	/** The basic object operation. */
386	RTVFSOBJOPS Obj;
387	/** The structure version (RTVFSSYMLINKOPS_VERSION). */
388	uint32_t uVersion;
389	/** Reserved field, MBZ. */
390	uint32_t fReserved;
391	/** The object setter operations. */
392	RTVFSOBJSETOPS ObjSet;
393
394	/**
395	* Read the symbolic link target.
396	*
397	* @returns IPRT status code.
398	* @param pvThis The implementation specific symbolic link data.
399	* @param pszTarget The target buffer.
400	* @param cbTarget The size of the target buffer.
401	* @sa RTSymlinkRead
402	*/
403	DECLCALLBACKMEMBER(int, pfnRead)(void pvThis, char pszTarget, size_t cbTarget);
404
405	/** Marks the end of the structure (RTVFSSYMLINKOPS_VERSION). */
406	uintptr_t uEndMarker;
407	} RTVFSSYMLINKOPS;
408	/** Pointer to const symbolic link operations. */
409	typedef RTVFSSYMLINKOPS const *PCRTVFSSYMLINKOPS;
410	/** The RTVFSSYMLINKOPS structure version. */
411	#define RTVFSSYMLINKOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x4f,1,0)
412
413
414	/**
415	* The basis for all I/O objects (files, pipes, sockets, devices, ++).
416	*
417	* @extends RTVFSOBJOPS
418	*/
419	typedef struct RTVFSIOSTREAMOPS
420	{
421	/** The basic object operation. */
422	RTVFSOBJOPS Obj;
423	/** The structure version (RTVFSIOSTREAMOPS_VERSION). */
424	uint32_t uVersion;
425	/** Reserved field, MBZ. */
426	uint32_t fReserved;
427
428	/**
429	* Reads from the file/stream.
430	*
431	* @returns IPRT status code. See RTVfsIoStrmRead.
432	* @param pvThis The implementation specific file data.
433	* @param off Where to read at, -1 for the current position.
434	* @param pSgBuf Gather buffer describing the bytes that are to be
435	* written.
436	* @param fBlocking If @c true, the call is blocking, if @c false it
437	* should not block.
438	* @param pcbRead Where return the number of bytes actually read.
439	* This is set it 0 by the caller. If NULL, try read
440	* all and fail if incomplete.
441	* @sa RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
442	* RTVfsFileReadAt, RTFileRead, RTFileReadAt.
443	*/
444	DECLCALLBACKMEMBER(int, pfnRead)(void pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t pcbRead);
445
446	/**
447	* Writes to the file/stream.
448	*
449	* @returns IPRT status code.
450	* @param pvThis The implementation specific file data.
451	* @param off Where to start wrinting, -1 for the current
452	* position.
453	* @param pSgBuf Gather buffers 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 pcbWritten Where to return the number of bytes actually
458	* written. This is set it 0 by the caller. If
459	* NULL, try write it all and fail if incomplete.
460	* @sa RTFileWrite, RTFileWriteAt.
461	*/
462	DECLCALLBACKMEMBER(int, pfnWrite)(void pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t pcbWritten);
463
464	/**
465	* Flushes any pending data writes to the stream.
466	*
467	* @returns IPRT status code.
468	* @param pvThis The implementation specific file data.
469	* @sa RTFileFlush.
470	*/
471	DECLCALLBACKMEMBER(int, pfnFlush)(void *pvThis);
472
473	/**
474	* Poll for events.
475	*
476	* @returns IPRT status code.
477	* @param pvThis The implementation specific file data.
478	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
479	* @param cMillies How long to wait for event to eventuate.
480	* @param fIntr Whether the wait is interruptible and can return
481	* VERR_INTERRUPTED (@c true) or if this condition
482	* should be hidden from the caller (@c false).
483	* @param pfRetEvents Where to return the event mask.
484	* @sa RTPollSetAdd, RTPoll, RTPollNoResume.
485	*/
486	DECLCALLBACKMEMBER(int, pfnPollOne)(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
487	uint32_t *pfRetEvents);
488
489	/**
490	* Tells the current file/stream position.
491	*
492	* @returns IPRT status code.
493	* @param pvThis The implementation specific file data.
494	* @param poffActual Where to return the actual offset.
495	* @sa RTFileTell
496	*/
497	DECLCALLBACKMEMBER(int, pfnTell)(void *pvThis, PRTFOFF poffActual);
498
499	/**
500	* Skips @a cb ahead in the stream.
501	*
502	* @returns IPRT status code.
503	* @param pvThis The implementation specific file data.
504	* @param cb The number bytes to skip.
505	* @remarks This is optional and can be NULL.
506	*/
507	DECLCALLBACKMEMBER(int, pfnSkip)(void *pvThis, RTFOFF cb);
508
509	/**
510	* Fills the stream with @a cb zeros.
511	*
512	* @returns IPRT status code.
513	* @param pvThis The implementation specific file data.
514	* @param cb The number of zero bytes to insert.
515	* @remarks This is optional and can be NULL.
516	*/
517	DECLCALLBACKMEMBER(int, pfnZeroFill)(void *pvThis, RTFOFF cb);
518
519	/** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
520	uintptr_t uEndMarker;
521	} RTVFSIOSTREAMOPS;
522	/** Pointer to const I/O stream operations. */
523	typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
524
525	/** The RTVFSIOSTREAMOPS structure version. */
526	#define RTVFSIOSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x5f,1,0)
527
528
529	/**
530	* Creates a new VFS I/O stream handle.
531	*
532	* @returns IPRT status code
533	* @param pIoStreamOps The I/O stream operations.
534	* @param cbInstance The size of the instance data.
535	* @param fOpen The open flags. The minimum is the access mask.
536	* @param hVfs The VFS handle to associate this file with.
537	* NIL_VFS is ok.
538	* @param hSemRW The read-write semaphore to use to protect the
539	* handle if this differs from the one the VFS
540	* uses. NIL_RTSEMRW is ok if no locking is
541	* desired.
542	* @param phVfsIos Where to return the new handle.
543	* @param ppvInstance Where to return the pointer to the instance data
544	* (size is @a cbInstance).
545	*/
546	RTDECL(int) RTVfsNewIoStream(PCRTVFSIOSTREAMOPS pIoStreamOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTSEMRW hSemRW,
547	PRTVFSIOSTREAM phVfsIos, void **ppvInstance);
548
549
550	/**
551	* The file operations.
552	*
553	* @extends RTVFSIOSTREAMOPS
554	* @extends RTVFSOBJSETOPS
555	*/
556	typedef struct RTVFSFILEOPS
557	{
558	/** The I/O stream and basis object operations. */
559	RTVFSIOSTREAMOPS Stream;
560	/** The structure version (RTVFSFILEOPS_VERSION). */
561	uint32_t uVersion;
562	/** Reserved field, MBZ. */
563	uint32_t fReserved;
564	/** The object setter operations. */
565	RTVFSOBJSETOPS ObjSet;
566
567	/**
568	* Changes the current file position.
569	*
570	* @returns IPRT status code.
571	* @param pvThis The implementation specific file data.
572	* @param offSeek The offset to seek.
573	* @param uMethod The seek method, i.e. what the seek is relative to.
574	* @param poffActual Where to return the actual offset.
575	* @sa RTFileSeek
576	*/
577	DECLCALLBACKMEMBER(int, pfnSeek)(void *pvThis, RTFOFF offSeek, unsigned uMethod, PRTFOFF poffActual);
578
579	/**
580	* Get the current file/stream size.
581	*
582	* @returns IPRT status code.
583	* @param pvThis The implementation specific file data.
584	* @param pcbFile Where to store the current file size.
585	* @sa RTFileGetSize
586	*/
587	DECLCALLBACKMEMBER(int, pfnQuerySize)(void pvThis, uint64_t pcbFile);
588
589	/** @todo There will be more methods here. */
590
591	/** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
592	uintptr_t uEndMarker;
593	} RTVFSFILEOPS;
594	/** Pointer to const file operations. */
595	typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
596
597	/** The RTVFSFILEOPS structure version. */
598	#define RTVFSFILEOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
599
600	/**
601	* Creates a new VFS file handle.
602	*
603	* @returns IPRT status code
604	* @param pFileOps The file operations.
605	* @param cbInstance The size of the instance data.
606	* @param fOpen The open flags. The minimum is the access mask.
607	* @param hVfs The VFS handle to associate this file with.
608	* NIL_VFS is ok.
609	* @param phVfsFile Where to return the new handle.
610	* @param ppvInstance Where to return the pointer to the instance data
611	* (size is @a cbInstance).
612	*/
613	RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs,
614	PRTVFSFILE phVfsFile, void **ppvInstance);
615
616
617	/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
618	* @{ */
619
620	/**
621	* Parsed path.
622	*/
623	typedef struct RTVFSPARSEDPATH
624	{
625	/** The length of the path in szCopy. */
626	uint16_t cch;
627	/** The number of path components. */
628	uint16_t cComponents;
629	/** Set if the path ends with slash, indicating that it's a directory
630	* reference and not a file reference. The slash has been removed from
631	* the copy. */
632	bool fDirSlash;
633	/** The offset where each path component starts, i.e. the char after the
634	* slash. The array has cComponents + 1 entries, where the final one is
635	* cch + 1 so that one can always terminate the current component by
636	* szPath[aoffComponent[i] - 1] = '\0'. */
637	uint16_t aoffComponents[RTPATH_MAX / 2 + 1];
638	/** A normalized copy of the path.
639	* Reserve some extra space so we can be more relaxed about overflow
640	* checks and terminator paddings, especially when recursing. */
641	char szPath[RTPATH_MAX];
642	} RTVFSPARSEDPATH;
643	/** Pointer to a parsed path. */
644	typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
645
646	/** The max accepted path length.
647	* This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
648	* use two terminators and wish be a little bit lazy with checking. */
649	#define RTVFSPARSEDPATH_MAX (RTPATH_MAX - 4)
650
651	/**
652	* Appends @a pszPath (relative) to the already parsed path @a pPath.
653	*
654	* @retval VINF_SUCCESS
655	* @retval VERR_FILENAME_TOO_LONG
656	* @retval VERR_INTERNAL_ERROR_4
657	* @param pPath The parsed path to append @a pszPath onto.
658	* This is both input and output.
659	* @param pszPath The path to append. This must be relative.
660	* @param piRestartComp The component to restart parsing at. This is
661	* input/output. The input does not have to be
662	* within the valid range. Optional.
663	*/
664	RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char pszPath, uint16_t piRestartComp);
665
666	/**
667	* Parses a path.
668	*
669	* @retval VINF_SUCCESS
670	* @retval VERR_FILENAME_TOO_LONG
671	* @param pPath Where to store the parsed path.
672	* @param pszPath The path to parse. Absolute or relative to @a
673	* pszCwd.
674	* @param pszCwd The current working directory. Must be
675	* absolute.
676	*/
677	RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char pszPath, const char pszCwd);
678
679	/**
680	* Same as RTVfsParsePath except that it allocates a temporary buffer.
681	*
682	* @retval VINF_SUCCESS
683	* @retval VERR_NO_TMP_MEMORY
684	* @retval VERR_FILENAME_TOO_LONG
685	* @param pszPath The path to parse. Absolute or relative to @a
686	* pszCwd.
687	* @param pszCwd The current working directory. Must be
688	* absolute.
689	* @param ppPath Where to store the pointer to the allocated
690	* buffer containing the parsed path. This must
691	* be freed by calling RTVfsParsePathFree. NULL
692	* will be stored on failured.
693	*/
694	RTDECL(int) RTVfsParsePathA(const char pszPath, const char pszCwd, PRTVFSPARSEDPATH *ppPath);
695
696	/**
697	* Frees a buffer returned by RTVfsParsePathA.
698	*
699	* @param pPath The parsed path buffer to free. NULL is fine.
700	*/
701	RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
702
703	/** @} */
704
705	/** @} */
706
707	RT_C_DECLS_END
708
709	#endif /* !___iprt_vfslowlevel_h */
710
711
712
713

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

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

Download in other formats: