VirtualBox

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

最後變更 在這個檔案從69753是 69716,由 vboxsync 提交於 7 年 前

IPRT: More work on directory relative APIs (NT mainly) and VFS; introducing RTMkDir (test) tool.

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

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette