VirtualBox

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

Last change on this file since 66684 was 66652, checked in by vboxsync, 8 years ago

IPRT: Some more fat bits.

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

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