vd-plugin.h@ 41201

Last change on this file since 41201 was 39519, checked in by vboxsync, 13 years ago
VD: API to repair corrupted images
Property svn:eol-style set to `native`
File size: 30.2 KB

Line
1	/** @file
2	* Internal hard disk format support API for VBoxHDD.
3	*/
4
5	/*
6	* Copyright (C) 2006-2011 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 __VBoxHDD_Plugin_h__
27	#define __VBoxHDD_Plugin_h__
28
29	#include <VBox/vd.h>
30	#include <VBox/vd-ifs-internal.h>
31
32
33	/** @name VBox HDD backend write flags
34	* @{
35	*/
36	/** Do not allocate a new block on this write. This is just an advisory
37	* flag. The backend may still decide in some circumstances that it wants
38	* to ignore this flag (which may cause extra dynamic image expansion). */
39	#define VD_WRITE_NO_ALLOC RT_BIT(1)
40	/** @}*/
41
42	/** @name VBox HDD backend discard flags
43	* @{
44	*/
45	/** Don't discard block but mark the given range as unused
46	* (usually by writing 0's to it).
47	* This doesn't require the range to be aligned on a block boundary but
48	* the image size might not be decreased. */
49	#define VD_DISCARD_MARK_UNUSED RT_BIT(0)
50	/** @}*/
51
52
53	/**
54	* Image format backend interface used by VBox HDD Container implementation.
55	*/
56	typedef struct VBOXHDDBACKEND
57	{
58	/**
59	* The name of the backend (constant string).
60	*/
61	const char *pszBackendName;
62
63	/**
64	* The size of the structure.
65	*/
66	uint32_t cbSize;
67
68	/**
69	* The capabilities of the backend.
70	*/
71	uint64_t uBackendCaps;
72
73	/**
74	* Pointer to a NULL-terminated array, containing the supported
75	* file extensions. Note that some backends do not work on files, so this
76	* pointer may just contain NULL.
77	*/
78	PCVDFILEEXTENSION paFileExtensions;
79
80	/**
81	* Pointer to an array of structs describing each supported config key.
82	* Terminated by a NULL config key. Note that some backends do not support
83	* the configuration interface, so this pointer may just contain NULL.
84	* Mandatory if the backend sets VD_CAP_CONFIG.
85	*/
86	PCVDCONFIGINFO paConfigInfo;
87
88	/**
89	* Handle of loaded plugin library, NIL_RTLDRMOD for static backends.
90	*/
91	RTLDRMOD hPlugin;
92
93	/**
94	* Check if a file is valid for the backend.
95	*
96	* @returns VBox status code.
97	* @param pszFilename Name of the image file.
98	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
99	* @param pVDIfsImage Pointer to the per-image VD interface list.
100	* @param penmType Returns the supported device type on success.
101	*/
102	DECLR3CALLBACKMEMBER(int, pfnCheckIfValid, (const char *pszFilename, PVDINTERFACE pVDIfsDisk,
103	PVDINTERFACE pVDIfsImage, VDTYPE *penmType));
104
105	/**
106	* Open a disk image.
107	*
108	* @returns VBox status code.
109	* @param pszFilename Name of the image file to open. Guaranteed to be available and
110	* unchanged during the lifetime of this image.
111	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
112	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
113	* @param pVDIfsImage Pointer to the per-image VD interface list.
114	* @param enmType Requested type of the image.
115	* @param ppBackendData Opaque state data for this image.
116	*/
117	DECLR3CALLBACKMEMBER(int, pfnOpen, (const char *pszFilename, unsigned uOpenFlags,
118	PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
119	VDTYPE enmType, void **ppBackendData));
120
121	/**
122	* Create a disk image.
123	*
124	* @returns VBox status code.
125	* @param pszFilename Name of the image file to create. Guaranteed to be available and
126	* unchanged during the lifetime of this image.
127	* @param cbSize Image size in bytes.
128	* @param uImageFlags Flags specifying special image features.
129	* @param pszComment Pointer to image comment. NULL is ok.
130	* @param pPCHSGeometry Physical drive geometry CHS <= (16383,16,255).
131	* @param pLCHSGeometry Logical drive geometry CHS <= (1024,255,63).
132	* @param pUuid New UUID of the image. Not NULL.
133	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
134	* @param uPercentStart Starting value for progress percentage.
135	* @param uPercentSpan Span for varying progress percentage.
136	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
137	* @param pVDIfsImage Pointer to the per-image VD interface list.
138	* @param pVDIfsOperation Pointer to the per-operation VD interface list.
139	* @param ppBackendData Opaque state data for this image.
140	*/
141	DECLR3CALLBACKMEMBER(int, pfnCreate, (const char *pszFilename, uint64_t cbSize,
142	unsigned uImageFlags, const char *pszComment,
143	PCVDGEOMETRY pPCHSGeometry,
144	PCVDGEOMETRY pLCHSGeometry,
145	PCRTUUID pUuid, unsigned uOpenFlags,
146	unsigned uPercentStart, unsigned uPercentSpan,
147	PVDINTERFACE pVDIfsDisk,
148	PVDINTERFACE pVDIfsImage,
149	PVDINTERFACE pVDIfsOperation,
150	void **ppBackendData));
151
152	/**
153	* Rename a disk image. Only needs to work as long as the operating
154	* system's rename file functionality is usable. If an attempt is made to
155	* rename an image to a location on another disk/filesystem, this function
156	* may just fail with an appropriate error code (not changing the opened
157	* image data at all). Also works only on images which actually refer to
158	* regular files. May be NULL.
159	*
160	* @returns VBox status code.
161	* @param pBackendData Opaque state data for this image.
162	* @param pszFilename New name of the image file. Guaranteed to be available and
163	* unchanged during the lifetime of this image.
164	*/
165	DECLR3CALLBACKMEMBER(int, pfnRename, (void pBackendData, const char pszFilename));
166
167	/**
168	* Close a disk image.
169	*
170	* @returns VBox status code.
171	* @param pBackendData Opaque state data for this image.
172	* @param fDelete If true, delete the image from the host disk.
173	*/
174	DECLR3CALLBACKMEMBER(int, pfnClose, (void *pBackendData, bool fDelete));
175
176	/**
177	* Read data from a disk image. The area read never crosses a block
178	* boundary.
179	*
180	* @returns VBox status code.
181	* @returns VERR_VD_BLOCK_FREE if this image contains no data for this block.
182	* @param pBackendData Opaque state data for this image.
183	* @param uOffset Offset to start reading from.
184	* @param pvBuf Where to store the read bits.
185	* @param cbRead Number of bytes to read.
186	* @param pcbActuallyRead Pointer to returned number of bytes read.
187	*/
188	DECLR3CALLBACKMEMBER(int, pfnRead, (void pBackendData, uint64_t uOffset, void pvBuf,
189	size_t cbRead, size_t *pcbActuallyRead));
190
191	/**
192	* Write data to a disk image. The area written never crosses a block
193	* boundary.
194	*
195	* @returns VBox status code.
196	* @returns VERR_VD_BLOCK_FREE if this image contains no data for this block and
197	* this is not a full-block write. The write must be repeated with
198	* the correct amount of prefix/postfix data read from the images below
199	* in the image stack. This might not be the most convenient interface,
200	* but it works with arbitrary block sizes, especially when the image
201	* stack uses different block sizes.
202	* @param pBackendData Opaque state data for this image.
203	* @param uOffset Offset to start writing to.
204	* @param pvBuf Where to retrieve the written bits.
205	* @param cbWrite Number of bytes to write.
206	* @param pcbWriteProcess Pointer to returned number of bytes that could
207	* be processed. In case the function returned
208	* VERR_VD_BLOCK_FREE this is the number of bytes
209	* that could be written in a full block write,
210	* when prefixed/postfixed by the appropriate
211	* amount of (previously read) padding data.
212	* @param pcbPreRead Pointer to the returned amount of data that must
213	* be prefixed to perform a full block write.
214	* @param pcbPostRead Pointer to the returned amount of data that must
215	* be postfixed to perform a full block write.
216	* @param fWrite Flags which affect write behavior. Combination
217	* of the VD_WRITE_* flags.
218	*/
219	DECLR3CALLBACKMEMBER(int, pfnWrite, (void *pBackendData, uint64_t uOffset,
220	const void *pvBuf, size_t cbWrite,
221	size_t pcbWriteProcess, size_t pcbPreRead,
222	size_t *pcbPostRead, unsigned fWrite));
223
224	/**
225	* Flush data to disk.
226	*
227	* @returns VBox status code.
228	* @param pBackendData Opaque state data for this image.
229	*/
230	DECLR3CALLBACKMEMBER(int, pfnFlush, (void *pBackendData));
231
232	/**
233	* Get the version of a disk image.
234	*
235	* @returns version of disk image.
236	* @param pBackendData Opaque state data for this image.
237	*/
238	DECLR3CALLBACKMEMBER(unsigned, pfnGetVersion, (void *pBackendData));
239
240	/**
241	* Get the capacity of a disk image.
242	*
243	* @returns size of disk image in bytes.
244	* @param pBackendData Opaque state data for this image.
245	*/
246	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize, (void *pBackendData));
247
248	/**
249	* Get the file size of a disk image.
250	*
251	* @returns size of disk image in bytes.
252	* @param pBackendData Opaque state data for this image.
253	*/
254	DECLR3CALLBACKMEMBER(uint64_t, pfnGetFileSize, (void *pBackendData));
255
256	/**
257	* Get virtual disk PCHS geometry stored in a disk image.
258	*
259	* @returns VBox status code.
260	* @returns VERR_VD_GEOMETRY_NOT_SET if no geometry present in the image.
261	* @param pBackendData Opaque state data for this image.
262	* @param pPCHSGeometry Where to store the geometry. Not NULL.
263	*/
264	DECLR3CALLBACKMEMBER(int, pfnGetPCHSGeometry, (void *pBackendData, PVDGEOMETRY pPCHSGeometry));
265
266	/**
267	* Set virtual disk PCHS geometry stored in a disk image.
268	* Only called if geometry is different than before.
269	*
270	* @returns VBox status code.
271	* @param pBackendData Opaque state data for this image.
272	* @param pPCHSGeometry Where to load the geometry from. Not NULL.
273	*/
274	DECLR3CALLBACKMEMBER(int, pfnSetPCHSGeometry, (void *pBackendData, PCVDGEOMETRY pPCHSGeometry));
275
276	/**
277	* Get virtual disk LCHS geometry stored in a disk image.
278	*
279	* @returns VBox status code.
280	* @returns VERR_VD_GEOMETRY_NOT_SET if no geometry present in the image.
281	* @param pBackendData Opaque state data for this image.
282	* @param pLCHSGeometry Where to store the geometry. Not NULL.
283	*/
284	DECLR3CALLBACKMEMBER(int, pfnGetLCHSGeometry, (void *pBackendData, PVDGEOMETRY pLCHSGeometry));
285
286	/**
287	* Set virtual disk LCHS geometry stored in a disk image.
288	* Only called if geometry is different than before.
289	*
290	* @returns VBox status code.
291	* @param pBackendData Opaque state data for this image.
292	* @param pLCHSGeometry Where to load the geometry from. Not NULL.
293	*/
294	DECLR3CALLBACKMEMBER(int, pfnSetLCHSGeometry, (void *pBackendData, PCVDGEOMETRY pLCHSGeometry));
295
296	/**
297	* Get the image flags of a disk image.
298	*
299	* @returns image flags of disk image.
300	* @param pBackendData Opaque state data for this image.
301	*/
302	DECLR3CALLBACKMEMBER(unsigned, pfnGetImageFlags, (void *pBackendData));
303
304	/**
305	* Get the open flags of a disk image.
306	*
307	* @returns open flags of disk image.
308	* @param pBackendData Opaque state data for this image.
309	*/
310	DECLR3CALLBACKMEMBER(unsigned, pfnGetOpenFlags, (void *pBackendData));
311
312	/**
313	* Set the open flags of a disk image. May cause the image to be locked
314	* in a different mode or be reopened (which can fail).
315	*
316	* @returns VBox status code.
317	* @param pBackendData Opaque state data for this image.
318	* @param uOpenFlags New open flags for this image.
319	*/
320	DECLR3CALLBACKMEMBER(int, pfnSetOpenFlags, (void *pBackendData, unsigned uOpenFlags));
321
322	/**
323	* Get comment of a disk image.
324	*
325	* @returns VBox status code.
326	* @param pBackendData Opaque state data for this image.
327	* @param pszComment Where to store the comment.
328	* @param cbComment Size of the comment buffer.
329	*/
330	DECLR3CALLBACKMEMBER(int, pfnGetComment, (void pBackendData, char pszComment, size_t cbComment));
331
332	/**
333	* Set comment of a disk image.
334	*
335	* @returns VBox status code.
336	* @param pBackendData Opaque state data for this image.
337	* @param pszComment Where to get the comment from. NULL resets comment.
338	* The comment is silently truncated if the image format
339	* limit is exceeded.
340	*/
341	DECLR3CALLBACKMEMBER(int, pfnSetComment, (void pBackendData, const char pszComment));
342
343	/**
344	* Get UUID of a disk image.
345	*
346	* @returns VBox status code.
347	* @param pBackendData Opaque state data for this image.
348	* @param pUuid Where to store the image UUID.
349	*/
350	DECLR3CALLBACKMEMBER(int, pfnGetUuid, (void *pBackendData, PRTUUID pUuid));
351
352	/**
353	* Set UUID of a disk image.
354	*
355	* @returns VBox status code.
356	* @param pBackendData Opaque state data for this image.
357	* @param pUuid Where to get the image UUID from.
358	*/
359	DECLR3CALLBACKMEMBER(int, pfnSetUuid, (void *pBackendData, PCRTUUID pUuid));
360
361	/**
362	* Get last modification UUID of a disk image.
363	*
364	* @returns VBox status code.
365	* @param pBackendData Opaque state data for this image.
366	* @param pUuid Where to store the image modification UUID.
367	*/
368	DECLR3CALLBACKMEMBER(int, pfnGetModificationUuid, (void *pBackendData, PRTUUID pUuid));
369
370	/**
371	* Set last modification UUID of a disk image.
372	*
373	* @returns VBox status code.
374	* @param pBackendData Opaque state data for this image.
375	* @param pUuid Where to get the image modification UUID from.
376	*/
377	DECLR3CALLBACKMEMBER(int, pfnSetModificationUuid, (void *pBackendData, PCRTUUID pUuid));
378
379	/**
380	* Get parent UUID of a disk image.
381	*
382	* @returns VBox status code.
383	* @param pBackendData Opaque state data for this image.
384	* @param pUuid Where to store the parent image UUID.
385	*/
386	DECLR3CALLBACKMEMBER(int, pfnGetParentUuid, (void *pBackendData, PRTUUID pUuid));
387
388	/**
389	* Set parent UUID of a disk image.
390	*
391	* @returns VBox status code.
392	* @param pBackendData Opaque state data for this image.
393	* @param pUuid Where to get the parent image UUID from.
394	*/
395	DECLR3CALLBACKMEMBER(int, pfnSetParentUuid, (void *pBackendData, PCRTUUID pUuid));
396
397	/**
398	* Get parent modification UUID of a disk image.
399	*
400	* @returns VBox status code.
401	* @param pBackendData Opaque state data for this image.
402	* @param pUuid Where to store the parent image modification UUID.
403	*/
404	DECLR3CALLBACKMEMBER(int, pfnGetParentModificationUuid, (void *pBackendData, PRTUUID pUuid));
405
406	/**
407	* Set parent modification UUID of a disk image.
408	*
409	* @returns VBox status code.
410	* @param pBackendData Opaque state data for this image.
411	* @param pUuid Where to get the parent image modification UUID from.
412	*/
413	DECLR3CALLBACKMEMBER(int, pfnSetParentModificationUuid, (void *pBackendData, PCRTUUID pUuid));
414
415	/**
416	* Dump information about a disk image.
417	*
418	* @param pBackendData Opaque state data for this image.
419	*/
420	DECLR3CALLBACKMEMBER(void, pfnDump, (void *pBackendData));
421
422	/**
423	* Get a time stamp of a disk image. May be NULL.
424	*
425	* @returns VBox status code.
426	* @param pBackendData Opaque state data for this image.
427	* @param pTimeStamp Where to store the time stamp.
428	*/
429	DECLR3CALLBACKMEMBER(int, pfnGetTimeStamp, (void *pBackendData, PRTTIMESPEC pTimeStamp));
430
431	/**
432	* Get the parent time stamp of a disk image. May be NULL.
433	*
434	* @returns VBox status code.
435	* @param pBackendData Opaque state data for this image.
436	* @param pTimeStamp Where to store the time stamp.
437	*/
438	DECLR3CALLBACKMEMBER(int, pfnGetParentTimeStamp, (void *pBackendData, PRTTIMESPEC pTimeStamp));
439
440	/**
441	* Set the parent time stamp of a disk image. May be NULL.
442	*
443	* @returns VBox status code.
444	* @param pBackendData Opaque state data for this image.
445	* @param pTimeStamp Where to get the time stamp from.
446	*/
447	DECLR3CALLBACKMEMBER(int, pfnSetParentTimeStamp, (void *pBackendData, PCRTTIMESPEC pTimeStamp));
448
449	/**
450	* Get the relative path to parent image. May be NULL.
451	*
452	* @returns VBox status code.
453	* @param pBackendData Opaque state data for this image.
454	* @param pszParentFilename Where to store the path.
455	*/
456	DECLR3CALLBACKMEMBER(int, pfnGetParentFilename, (void pBackendData, char *ppszParentFilename));
457
458	/**
459	* Set the relative path to parent image. May be NULL.
460	*
461	* @returns VBox status code.
462	* @param pBackendData Opaque state data for this image.
463	* @param pszParentFilename Where to get the path from.
464	*/
465	DECLR3CALLBACKMEMBER(int, pfnSetParentFilename, (void pBackendData, const char pszParentFilename));
466
467	/**
468	* Start an asynchronous read request.
469	*
470	* @returns VBox status code.
471	* @param pBackendData Opaque state data for this image.
472	* @param uOffset The offset of the virtual disk to read from.
473	* @param cbRead How many bytes to read.
474	* @param pIoCtx I/O context associated with this request.
475	* @param pcbActuallyRead Pointer to returned number of bytes read.
476	*/
477	DECLR3CALLBACKMEMBER(int, pfnAsyncRead, (void *pBackendData, uint64_t uOffset, size_t cbRead,
478	PVDIOCTX pIoCtx, size_t *pcbActuallyRead));
479
480	/**
481	* Start an asynchronous write request.
482	*
483	* @returns VBox status code.
484	* @param pBackendData Opaque state data for this image.
485	* @param uOffset The offset of the virtual disk to write to.
486	* @param cbWrite How many bytes to write.
487	* @param pIoCtx I/O context associated with this request.
488	* @param pcbWriteProcess Pointer to returned number of bytes that could
489	* be processed. In case the function returned
490	* VERR_VD_BLOCK_FREE this is the number of bytes
491	* that could be written in a full block write,
492	* when prefixed/postfixed by the appropriate
493	* amount of (previously read) padding data.
494	* @param pcbPreRead Pointer to the returned amount of data that must
495	* be prefixed to perform a full block write.
496	* @param pcbPostRead Pointer to the returned amount of data that must
497	* be postfixed to perform a full block write.
498	* @param fWrite Flags which affect write behavior. Combination
499	* of the VD_WRITE_* flags.
500	*/
501	DECLR3CALLBACKMEMBER(int, pfnAsyncWrite, (void *pBackendData, uint64_t uOffset, size_t cbWrite,
502	PVDIOCTX pIoCtx,
503	size_t pcbWriteProcess, size_t pcbPreRead,
504	size_t *pcbPostRead, unsigned fWrite));
505
506	/**
507	* Flush data to disk.
508	*
509	* @returns VBox status code.
510	* @param pBackendData Opaque state data for this image.
511	* @param pIoCtx I/O context associated with this request.
512	*/
513	DECLR3CALLBACKMEMBER(int, pfnAsyncFlush, (void *pBackendData, PVDIOCTX pIoCtx));
514
515	/** Returns a human readable hard disk location string given a
516	* set of hard disk configuration keys. The returned string is an
517	* equivalent of the full file path for image-based hard disks.
518	* Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */
519	DECLR3CALLBACKMEMBER(int, pfnComposeLocation, (PVDINTERFACE pConfig, char **pszLocation));
520
521	/** Returns a human readable hard disk name string given a
522	* set of hard disk configuration keys. The returned string is an
523	* equivalent of the file name part in the full file path for
524	* image-based hard disks. Mandatory for backends with no
525	* VD_CAP_FILE and NULL otherwise. */
526	DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
527
528	/**
529	* Compact the image. The pointer may be NULL, indicating that this
530	* isn't supported yet (for file-based images) or not necessary.
531	*
532	* @returns VBox status code.
533	* @returns VERR_NOT_SUPPORTED if this image cannot be compacted yet.
534	* @param pBackendData Opaque state data for this image.
535	* @param uPercentStart Starting value for progress percentage.
536	* @param uPercentSpan Span for varying progress percentage.
537	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
538	* @param pVDIfsImage Pointer to the per-image VD interface list.
539	* @param pVDIfsOperation Pointer to the per-operation VD interface list.
540	*/
541	DECLR3CALLBACKMEMBER(int, pfnCompact, (void *pBackendData,
542	unsigned uPercentStart, unsigned uPercentSpan,
543	PVDINTERFACE pVDIfsDisk,
544	PVDINTERFACE pVDIfsImage,
545	PVDINTERFACE pVDIfsOperation));
546
547	/**
548	* Resize the image. The pointer may be NULL, indicating that this
549	* isn't supported yet (for file-based images) or not necessary.
550	*
551	* @returns VBox status code.
552	* @returns VERR_NOT_SUPPORTED if this image cannot be resized yet.
553	* @param pBackendData Opaque state data for this image.
554	* @param cbSize New size of the image.
555	* @param pPCHSGeometry Pointer to the new physical disk geometry <= (16383,16,63). Not NULL.
556	* @param pLCHSGeometry Pointer to the new logical disk geometry <= (x,255,63). Not NULL.
557	* @param uPercentStart Starting value for progress percentage.
558	* @param uPercentSpan Span for varying progress percentage.
559	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
560	* @param pVDIfsImage Pointer to the per-image VD interface list.
561	* @param pVDIfsOperation Pointer to the per-operation VD interface list.
562	*/
563	DECLR3CALLBACKMEMBER(int, pfnResize, (void *pBackendData,
564	uint64_t cbSize,
565	PCVDGEOMETRY pPCHSGeometry,
566	PCVDGEOMETRY pLCHSGeometry,
567	unsigned uPercentStart, unsigned uPercentSpan,
568	PVDINTERFACE pVDIfsDisk,
569	PVDINTERFACE pVDIfsImage,
570	PVDINTERFACE pVDIfsOperation));
571
572	/**
573	* Discards the given amount of bytes decreasing the size of the image if possible.
574	*
575	* @returns VBox status code.
576	* @retval VERR_VD_DISCARD_ALIGNMENT_NOT_MET if the range doesn't meet the required alignment
577	* for the discard.
578	* @param pBackendData Opaque state data for this image.
579	* @param uOffset The offset of the first byte to discard.
580	* @param cbDiscard How many bytes to discard.
581	* @param pcbPreAllocated Pointer to the returned amount of bytes that must
582	* be discarded before the range to perform a full
583	* block discard.
584	* @param pcbPostAllocated Pointer to the returned amount of bytes that must
585	* be discarded after the range to perform a full
586	* block discard.
587	* @param pcbActuallyDiscarded Pointer to the returned amount of bytes which
588	* could be actually discarded.
589	* @param ppbmAllocationBitmap Where to store the pointer to the allocation bitmap
590	* if VERR_VD_DISCARD_ALIGNMENT_NOT_MET is returned or NULL
591	* if the allocation bitmap should be returned.
592	* @param fDiscard Flags which affect discard behavior. Combination
593	* of the VD_DISCARD_* flags.
594	*/
595	DECLR3CALLBACKMEMBER(int, pfnDiscard, (void *pBackendData,
596	uint64_t uOffset, size_t cbDiscard,
597	size_t *pcbPreAllocated,
598	size_t *pcbPostAllocated,
599	size_t *pcbActuallyDiscarded,
600	void **ppbmAllocationBitmap,
601	unsigned fDiscard));
602
603	/**
604	* Discards the given amount of bytes decreasing the size of the image if possible
605	* callback version for asynchronous I/O.
606	*
607	* @returns VBox status code.
608	* @retval VERR_VD_DISCARD_ALIGNMENT_NOT_MET if the range doesn't meet the required alignment
609	* for the discard.
610	* @param pBackendData Opaque state data for this image.
611	* @param pIoCtx I/O context associated with this request.
612	* @param uOffset The offset of the first byte to discard.
613	* @param cbDiscard How many bytes to discard.
614	* @param pcbPreAllocated Pointer to the returned amount of bytes that must
615	* be discarded before the range to perform a full
616	* block discard.
617	* @param pcbPostAllocated Pointer to the returned amount of bytes that must
618	* be discarded after the range to perform a full
619	* block discard.
620	* @param pcbActuallyDiscarded Pointer to the returned amount of bytes which
621	* could be actually discarded.
622	* @param ppbmAllocationBitmap Where to store the pointer to the allocation bitmap
623	* if VERR_VD_DISCARD_ALIGNMENT_NOT_MET is returned or NULL
624	* if the allocation bitmap should be returned.
625	* @param fDiscard Flags which affect discard behavior. Combination
626	* of the VD_DISCARD_* flags.
627	*/
628	DECLR3CALLBACKMEMBER(int, pfnAsyncDiscard, (void *pBackendData, PVDIOCTX pIoCtx,
629	uint64_t uOffset, size_t cbDiscard,
630	size_t *pcbPreAllocated,
631	size_t *pcbPostAllocated,
632	size_t *pcbActuallyDiscarded,
633	void **ppbmAllocationBitmap,
634	unsigned fDiscard));
635
636	/**
637	* Try to repair the given image.
638	*
639	* @returns VBox status code.
640	* @param pszFilename Name of the image file.
641	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
642	* @param pVDIfsImage Pointer to the per-image VD interface list.
643	* @param fFlags Combination of the VD_REPAIR_* flags.
644	*/
645	DECLR3CALLBACKMEMBER(int, pfnRepair, (const char *pszFilename, PVDINTERFACE pVDIfsDisk,
646	PVDINTERFACE pVDIfsImage, uint32_t fFlags));
647
648	} VBOXHDDBACKEND;
649
650	/** Pointer to VD backend. */
651	typedef VBOXHDDBACKEND *PVBOXHDDBACKEND;
652
653	/** Constant pointer to VD backend. */
654	typedef const VBOXHDDBACKEND *PCVBOXHDDBACKEND;
655
656	/** @copydoc VBOXHDDBACKEND::pfnComposeLocation */
657	DECLINLINE(int) genericFileComposeLocation(PVDINTERFACE pConfig, char **pszLocation)
658	{
659	*pszLocation = NULL;
660	return VINF_SUCCESS;
661	}
662	/** @copydoc VBOXHDDBACKEND::pfnComposeName */
663	DECLINLINE(int) genericFileComposeName(PVDINTERFACE pConfig, char **pszName)
664	{
665	*pszName = NULL;
666	return VINF_SUCCESS;
667	}
668
669	/** Initialization entry point. */
670	typedef DECLCALLBACK(int) VBOXHDDFORMATLOAD(PVBOXHDDBACKEND *ppBackendTable);
671	typedef VBOXHDDFORMATLOAD *PFNVBOXHDDFORMATLOAD;
672	#define VBOX_HDDFORMAT_LOAD_NAME "VBoxHDDFormatLoad"
673
674	/** The prefix to identify Storage Plugins. */
675	#define VBOX_HDDFORMAT_PLUGIN_PREFIX "VBoxHDD"
676	/** The size of the prefix excluding the '\\0' terminator. */
677	#define VBOX_HDDFORMAT_PLUGIN_PREFIX_LENGTH (sizeof(VBOX_HDDFORMAT_PLUGIN_PREFIX)-1)
678
679	#endif

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

source: vbox/trunk/include/VBox/vd-plugin.h@ 41201

Download in other formats: