VBoxHDD-Plugin.h@ 23746

Last change on this file since 23746 was 23266, checked in by vboxsync, 15 years ago
export to OSE
File size: 22.5 KB

Line
1	/** @file
2	* Internal hard disk format support API for VBoxHDD.
3	*/
4
5	/*
6	* Copyright (C) 2006-2009 Sun Microsystems, Inc.
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	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26	* Clara, CA 95054 USA or visit http://www.sun.com if you need
27	* additional information or have any questions.
28	*/
29
30	#ifndef __VBoxHDD_Internal_h__
31
32
33	#include <VBox/pdm.h>
34	#include <VBox/VBoxHDD.h>
35
36
37	/** @name VBox HDD backend write flags
38	* @{
39	*/
40	/** Do not allocate a new block on this write. This is just an advisory
41	* flag. The backend may still decide in some circumstances that it wants
42	* to ignore this flag (which may cause extra dynamic image expansion). */
43	#define VD_WRITE_NO_ALLOC RT_BIT(1)
44	/** @}*/
45
46
47	/**
48	* Image format backend interface used by VBox HDD Container implementation.
49	*/
50	typedef struct VBOXHDDBACKEND
51	{
52	/**
53	* The name of the backend (constant string).
54	*/
55	const char *pszBackendName;
56
57	/**
58	* The size of the structure.
59	*/
60	uint32_t cbSize;
61
62	/**
63	* The capabilities of the backend.
64	*/
65	uint64_t uBackendCaps;
66
67	/**
68	* Pointer to a NULL-terminated array of strings, containing the supported
69	* file extensions. Note that some backends do not work on files, so this
70	* pointer may just contain NULL.
71	*/
72	const char * const *papszFileExtensions;
73
74	/**
75	* Pointer to an array of structs describing each supported config key.
76	* Terminated by a NULL config key. Note that some backends do not support
77	* the configuration interface, so this pointer may just contain NULL.
78	* Mandatory if the backend sets VD_CAP_CONFIG.
79	*/
80	PCVDCONFIGINFO paConfigInfo;
81
82	/**
83	* Handle of loaded plugin library, NIL_RTLDRMOD for static backends.
84	*/
85	RTLDRMOD hPlugin;
86
87	/**
88	* Check if a file is valid for the backend.
89	*
90	* @returns VBox status code.
91	* @param pszFilename Name of the image file.
92	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
93	*/
94	DECLR3CALLBACKMEMBER(int, pfnCheckIfValid, (const char *pszFilename, PVDINTERFACE pVDIfsDisk));
95
96	/**
97	* Open a disk image.
98	*
99	* @returns VBox status code.
100	* @param pszFilename Name of the image file to open. Guaranteed to be available and
101	* unchanged during the lifetime of this image.
102	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
103	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
104	* @param pVDIfsImage Pointer to the per-image VD interface list.
105	* @param ppvBackendData Opaque state data for this image.
106	*/
107	DECLR3CALLBACKMEMBER(int, pfnOpen, (const char *pszFilename, unsigned uOpenFlags,
108	PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
109	void **ppvBackendData));
110
111	/**
112	* Create a disk image.
113	*
114	* @returns VBox status code.
115	* @param pszFilename Name of the image file to create. Guaranteed to be available and
116	* unchanged during the lifetime of this image.
117	* @param cbSize Image size in bytes.
118	* @param uImageFlags Flags specifying special image features.
119	* @param pszComment Pointer to image comment. NULL is ok.
120	* @param pPCHSGeometry Physical drive geometry CHS <= (16383,16,255).
121	* @param pLCHSGeometry Logical drive geometry CHS <= (1024,255,63).
122	* @param pUuid New UUID of the image. Not NULL.
123	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
124	* @param uPercentStart Starting value for progress percentage.
125	* @param uPercentSpan Span for varying progress percentage.
126	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
127	* @param pVDIfsImage Pointer to the per-image VD interface list.
128	* @param pVDIfsOperation Pointer to the per-operation VD interface list.
129	* @param ppvBackendData Opaque state data for this image.
130	*/
131	DECLR3CALLBACKMEMBER(int, pfnCreate, (const char *pszFilename, uint64_t cbSize,
132	unsigned uImageFlags, const char *pszComment,
133	PCPDMMEDIAGEOMETRY pPCHSGeometry,
134	PCPDMMEDIAGEOMETRY pLCHSGeometry,
135	PCRTUUID pUuid, unsigned uOpenFlags,
136	unsigned uPercentStart, unsigned uPercentSpan,
137	PVDINTERFACE pVDIfsDisk,
138	PVDINTERFACE pVDIfsImage,
139	PVDINTERFACE pVDIfsOperation,
140	void **ppvBackendData));
141
142	/**
143	* Rename a disk image. Only needs to work as long as the operating
144	* system's rename file functionality is usable. If an attempt is made to
145	* rename an image to a location on another disk/filesystem, this function
146	* may just fail with an appropriate error code (not changing the opened
147	* image data at all). Also works only on images which actually refer to
148	* files (and not for raw disk images).
149	*
150	* @returns VBox status code.
151	* @param pvBackendData Opaque state data for this image.
152	* @param pszFilename New name of the image file. Guaranteed to be available and
153	* unchanged during the lifetime of this image.
154	*/
155	DECLR3CALLBACKMEMBER(int, pfnRename, (void pvBackendData, const char pszFilename));
156
157	/**
158	* Close a disk image.
159	*
160	* @returns VBox status code.
161	* @param pvBackendData Opaque state data for this image.
162	* @param fDelete If true, delete the image from the host disk.
163	*/
164	DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvBackendData, bool fDelete));
165
166	/**
167	* Read data from a disk image. The area read never crosses a block
168	* boundary.
169	*
170	* @returns VBox status code.
171	* @returns VERR_VD_BLOCK_FREE if this image contains no data for this block.
172	* @param pvBackendData Opaque state data for this image.
173	* @param uOffset Offset to start reading from.
174	* @param pvBuf Where to store the read bits.
175	* @param cbRead Number of bytes to read.
176	* @param pcbActuallyRead Pointer to returned number of bytes read.
177	*/
178	DECLR3CALLBACKMEMBER(int, pfnRead, (void pvBackendData, uint64_t uOffset, void pvBuf,
179	size_t cbRead, size_t *pcbActuallyRead));
180
181	/**
182	* Write data to a disk image. The area written never crosses a block
183	* boundary.
184	*
185	* @returns VBox status code.
186	* @returns VERR_VD_BLOCK_FREE if this image contains no data for this block and
187	* this is not a full-block write. The write must be repeated with
188	* the correct amount of prefix/postfix data read from the images below
189	* in the image stack. This might not be the most convenient interface,
190	* but it works with arbitrary block sizes, especially when the image
191	* stack uses different block sizes.
192	* @param pvBackendData Opaque state data for this image.
193	* @param uOffset Offset to start writing to.
194	* @param pvBuf Where to retrieve the written bits.
195	* @param cbWrite Number of bytes to write.
196	* @param pcbWriteProcess Pointer to returned number of bytes that could
197	* be processed. In case the function returned
198	* VERR_VD_BLOCK_FREE this is the number of bytes
199	* that could be written in a full block write,
200	* when prefixed/postfixed by the appropriate
201	* amount of (previously read) padding data.
202	* @param pcbPreRead Pointer to the returned amount of data that must
203	* be prefixed to perform a full block write.
204	* @param pcbPostRead Pointer to the returned amount of data that must
205	* be postfixed to perform a full block write.
206	* @param fWrite Flags which affect write behavior. Combination
207	* of the VD_WRITE_* flags.
208	*/
209	DECLR3CALLBACKMEMBER(int, pfnWrite, (void *pvBackendData, uint64_t uOffset,
210	const void *pvBuf, size_t cbWrite,
211	size_t pcbWriteProcess, size_t pcbPreRead,
212	size_t *pcbPostRead, unsigned fWrite));
213
214	/**
215	* Flush data to disk.
216	*
217	* @returns VBox status code.
218	* @param pvBackendData Opaque state data for this image.
219	*/
220	DECLR3CALLBACKMEMBER(int, pfnFlush, (void *pvBackendData));
221
222	/**
223	* Get the version of a disk image.
224	*
225	* @returns version of disk image.
226	* @param pvBackendData Opaque state data for this image.
227	*/
228	DECLR3CALLBACKMEMBER(unsigned, pfnGetVersion, (void *pvBackendData));
229
230	/**
231	* Get the capacity of a disk image.
232	*
233	* @returns size of disk image in bytes.
234	* @param pvBackendData Opaque state data for this image.
235	*/
236	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize, (void *pvBackendData));
237
238	/**
239	* Get the file size of a disk image.
240	*
241	* @returns size of disk image in bytes.
242	* @param pvBackendData Opaque state data for this image.
243	*/
244	DECLR3CALLBACKMEMBER(uint64_t, pfnGetFileSize, (void *pvBackendData));
245
246	/**
247	* Get virtual disk PCHS geometry stored in a disk image.
248	*
249	* @returns VBox status code.
250	* @returns VERR_VD_GEOMETRY_NOT_SET if no geometry present in the image.
251	* @param pvBackendData Opaque state data for this image.
252	* @param pPCHSGeometry Where to store the geometry. Not NULL.
253	*/
254	DECLR3CALLBACKMEMBER(int, pfnGetPCHSGeometry, (void *pvBackendData, PPDMMEDIAGEOMETRY pPCHSGeometry));
255
256	/**
257	* Set virtual disk PCHS geometry stored in a disk image.
258	* Only called if geometry is different than before.
259	*
260	* @returns VBox status code.
261	* @param pvBackendData Opaque state data for this image.
262	* @param pPCHSGeometry Where to load the geometry from. Not NULL.
263	*/
264	DECLR3CALLBACKMEMBER(int, pfnSetPCHSGeometry, (void *pvBackendData, PCPDMMEDIAGEOMETRY pPCHSGeometry));
265
266	/**
267	* Get virtual disk LCHS geometry stored in a disk image.
268	*
269	* @returns VBox status code.
270	* @returns VERR_VD_GEOMETRY_NOT_SET if no geometry present in the image.
271	* @param pvBackendData Opaque state data for this image.
272	* @param pLCHSGeometry Where to store the geometry. Not NULL.
273	*/
274	DECLR3CALLBACKMEMBER(int, pfnGetLCHSGeometry, (void *pvBackendData, PPDMMEDIAGEOMETRY pLCHSGeometry));
275
276	/**
277	* Set virtual disk LCHS geometry stored in a disk image.
278	* Only called if geometry is different than before.
279	*
280	* @returns VBox status code.
281	* @param pvBackendData Opaque state data for this image.
282	* @param pLCHSGeometry Where to load the geometry from. Not NULL.
283	*/
284	DECLR3CALLBACKMEMBER(int, pfnSetLCHSGeometry, (void *pvBackendData, PCPDMMEDIAGEOMETRY pLCHSGeometry));
285
286	/**
287	* Get the image flags of a disk image.
288	*
289	* @returns image flags of disk image.
290	* @param pvBackendData Opaque state data for this image.
291	*/
292	DECLR3CALLBACKMEMBER(unsigned, pfnGetImageFlags, (void *pvBackendData));
293
294	/**
295	* Get the open flags of a disk image.
296	*
297	* @returns open flags of disk image.
298	* @param pvBackendData Opaque state data for this image.
299	*/
300	DECLR3CALLBACKMEMBER(unsigned, pfnGetOpenFlags, (void *pvBackendData));
301
302	/**
303	* Set the open flags of a disk image. May cause the image to be locked
304	* in a different mode or be reopened (which can fail).
305	*
306	* @returns VBox status code.
307	* @param pvBackendData Opaque state data for this image.
308	* @param uOpenFlags New open flags for this image.
309	*/
310	DECLR3CALLBACKMEMBER(int, pfnSetOpenFlags, (void *pvBackendData, unsigned uOpenFlags));
311
312	/**
313	* Get comment of a disk image.
314	*
315	* @returns VBox status code.
316	* @param pvBackendData Opaque state data for this image.
317	* @param pszComment Where to store the comment.
318	* @param cbComment Size of the comment buffer.
319	*/
320	DECLR3CALLBACKMEMBER(int, pfnGetComment, (void pvBackendData, char pszComment, size_t cbComment));
321
322	/**
323	* Set comment of a disk image.
324	*
325	* @returns VBox status code.
326	* @param pvBackendData Opaque state data for this image.
327	* @param pszComment Where to get the comment from. NULL resets comment.
328	* The comment is silently truncated if the image format
329	* limit is exceeded.
330	*/
331	DECLR3CALLBACKMEMBER(int, pfnSetComment, (void pvBackendData, const char pszComment));
332
333	/**
334	* Get UUID of a disk image.
335	*
336	* @returns VBox status code.
337	* @param pvBackendData Opaque state data for this image.
338	* @param pUuid Where to store the image UUID.
339	*/
340	DECLR3CALLBACKMEMBER(int, pfnGetUuid, (void *pvBackendData, PRTUUID pUuid));
341
342	/**
343	* Set UUID of a disk image.
344	*
345	* @returns VBox status code.
346	* @param pvBackendData Opaque state data for this image.
347	* @param pUuid Where to get the image UUID from.
348	*/
349	DECLR3CALLBACKMEMBER(int, pfnSetUuid, (void *pvBackendData, PCRTUUID pUuid));
350
351	/**
352	* Get last modification UUID of a disk image.
353	*
354	* @returns VBox status code.
355	* @param pvBackendData Opaque state data for this image.
356	* @param pUuid Where to store the image modification UUID.
357	*/
358	DECLR3CALLBACKMEMBER(int, pfnGetModificationUuid, (void *pvBackendData, PRTUUID pUuid));
359
360	/**
361	* Set last modification UUID of a disk image.
362	*
363	* @returns VBox status code.
364	* @param pvBackendData Opaque state data for this image.
365	* @param pUuid Where to get the image modification UUID from.
366	*/
367	DECLR3CALLBACKMEMBER(int, pfnSetModificationUuid, (void *pvBackendData, PCRTUUID pUuid));
368
369	/**
370	* Get parent UUID of a disk image.
371	*
372	* @returns VBox status code.
373	* @param pvBackendData Opaque state data for this image.
374	* @param pUuid Where to store the parent image UUID.
375	*/
376	DECLR3CALLBACKMEMBER(int, pfnGetParentUuid, (void *pvBackendData, PRTUUID pUuid));
377
378	/**
379	* Set parent UUID of a disk image.
380	*
381	* @returns VBox status code.
382	* @param pvBackendData Opaque state data for this image.
383	* @param pUuid Where to get the parent image UUID from.
384	*/
385	DECLR3CALLBACKMEMBER(int, pfnSetParentUuid, (void *pvBackendData, PCRTUUID pUuid));
386
387	/**
388	* Get parent modification UUID of a disk image.
389	*
390	* @returns VBox status code.
391	* @param pvBackendData Opaque state data for this image.
392	* @param pUuid Where to store the parent image modification UUID.
393	*/
394	DECLR3CALLBACKMEMBER(int, pfnGetParentModificationUuid, (void *pvBackendData, PRTUUID pUuid));
395
396	/**
397	* Set parent modification UUID of a disk image.
398	*
399	* @returns VBox status code.
400	* @param pvBackendData Opaque state data for this image.
401	* @param pUuid Where to get the parent image modification UUID from.
402	*/
403	DECLR3CALLBACKMEMBER(int, pfnSetParentModificationUuid, (void *pvBackendData, PCRTUUID pUuid));
404
405	/**
406	* Dump information about a disk image.
407	*
408	* @param pvBackendData Opaque state data for this image.
409	*/
410	DECLR3CALLBACKMEMBER(void, pfnDump, (void *pvBackendData));
411
412	/**
413	* Get a time stamp of a disk image.
414	*
415	* @returns VBox status code.
416	* @param pvBackendData Opaque state data for this image.
417	* @param pTimeStamp Where to store the time stamp.
418	*/
419	DECLR3CALLBACKMEMBER(int, pfnGetTimeStamp, (void *pvBackendData, PRTTIMESPEC pTimeStamp));
420
421	/**
422	* Get the parent time stamp of a disk image.
423	*
424	* @returns VBox status code.
425	* @param pvBackendData Opaque state data for this image.
426	* @param pTimeStamp Where to store the time stamp.
427	*/
428	DECLR3CALLBACKMEMBER(int, pfnGetParentTimeStamp, (void *pvBackendData, PRTTIMESPEC pTimeStamp));
429
430	/**
431	* Set the parent time stamp of a disk image.
432	*
433	* @returns VBox status code.
434	* @param pvBackendData Opaque state data for this image.
435	* @param pTimeStamp Where to get the time stamp from.
436	*/
437	DECLR3CALLBACKMEMBER(int, pfnSetParentTimeStamp, (void *pvBackendData, PCRTTIMESPEC pTimeStamp));
438
439	/**
440	* Get the relative path to parent image.
441	*
442	* @returns VBox status code.
443	* @param pvBackendData Opaque state data for this image.
444	* @param pszParentFilename Where to store the path.
445	*/
446	DECLR3CALLBACKMEMBER(int, pfnGetParentFilename, (void pvBackendData, char *ppszParentFilename));
447
448	/**
449	* Set the relative path to parent image.
450	*
451	* @returns VBox status code.
452	* @param pvBackendData Opaque state data for this image.
453	* @param pszParentFilename Where to get the path from.
454	*/
455	DECLR3CALLBACKMEMBER(int, pfnSetParentFilename, (void pvBackendData, const char pszParentFilename));
456
457	/**
458	* Return whether asynchronous I/O operations are supported for this image.
459	*
460	* @returns true if asynchronous I/O is supported
461	* false otherwise.
462	* @param pvBackendData Opaque state data for this image.
463	*/
464	DECLR3CALLBACKMEMBER(bool, pfnIsAsyncIOSupported, (void *pvBackendData));
465
466	/**
467	* Start an asynchronous read request.
468	*
469	* @returns VBox status code.
470	* @param pvBackendData Opaque state data for this image.
471	* @param uOffset The offset of the virtual disk to read from.
472	* @param cbRead How many bytes to read.
473	* @param paSeg Pointer to the segment array.
474	* @param cSeg Number of segments.
475	* @param pvUser Opaque user data.
476	*/
477	DECLR3CALLBACKMEMBER(int, pfnAsyncRead, (void *pvBackendData, uint64_t uOffset, size_t cbRead,
478	PPDMDATASEG paSeg, unsigned cSeg, void *pvUser));
479
480	/**
481	* Start an asynchronous write request.
482	*
483	* @returns VBox status code.
484	* @param pvBackendData 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 paSeg Pointer to the segment array.
488	* @param cSeg Number of segments.
489	* @param pvUser Oaque user data-
490	*/
491	DECLR3CALLBACKMEMBER(int, pfnAsyncWrite, (void *pvBackendData, uint64_t uOffset, size_t cbWrite,
492	PPDMDATASEG paSeg, unsigned cSeg, void *pvUser));
493
494	/** Returns a human readable hard disk location string given a
495	* set of hard disk configuration keys. The returned string is an
496	* equivalent of the full file path for image-based hard disks.
497	* Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */
498	DECLR3CALLBACKMEMBER(int, pfnComposeLocation, (PVDINTERFACE pConfig, char **pszLocation));
499
500	/** Returns a human readable hard disk name string given a
501	* set of hard disk configuration keys. The returned string is an
502	* equivalent of the file name part in the full file path for
503	* image-based hard disks. Mandatory for backends with no
504	* VD_CAP_FILE and NULL otherwise. */
505	DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
506
507	/**
508	* Compact the image. The pointer may be NULL, indicating that this
509	* isn't supported yet (for file-based images) or not necessary.
510	*
511	* @returns VBox status code.
512	* @returns VERR_NOT_SUPPORTED if this image cannot be compacted yet.
513	* @param pvBackendData Opaque state data for this image.
514	* @param uPercentStart Starting value for progress percentage.
515	* @param uPercentSpan Span for varying progress percentage.
516	* @param pVDIfsOperation Pointer to the per-operation VD interface list.
517	*/
518	DECLR3CALLBACKMEMBER(int, pfnCompact, (void *pvBackendData,
519	unsigned uPercentStart, unsigned uPercentSpan,
520	PVDINTERFACE pVDIfsOperation));
521
522	} VBOXHDDBACKEND;
523
524	/** Pointer to VD backend. */
525	typedef VBOXHDDBACKEND *PVBOXHDDBACKEND;
526
527	/** Constant pointer to VD backend. */
528	typedef const VBOXHDDBACKEND *PCVBOXHDDBACKEND;
529
530	/** @copydoc VBOXHDDBACKEND::pfnComposeLocation */
531	DECLINLINE(int) genericFileComposeLocation(PVDINTERFACE pConfig, char **pszLocation)
532	{
533	*pszLocation = NULL;
534	return VINF_SUCCESS;
535	}
536	/** @copydoc VBOXHDDBACKEND::pfnComposeName */
537	DECLINLINE(int) genericFileComposeName(PVDINTERFACE pConfig, char **pszName)
538	{
539	*pszName = NULL;
540	return VINF_SUCCESS;
541	}
542
543	/** Initialization entry point. */
544	typedef DECLCALLBACK(int) VBOXHDDFORMATLOAD(PVBOXHDDBACKEND *ppBackendTable);
545	typedef VBOXHDDFORMATLOAD *PFNVBOXHDDFORMATLOAD;
546	#define VBOX_HDDFORMAT_LOAD_NAME "VBoxHDDFormatLoad"
547
548	/** The prefix to identify Storage Plugins. */
549	#define VBOX_HDDFORMAT_PLUGIN_PREFIX "VBoxHDD"
550	/** The size of the prefix excluding the '\0' terminator. */
551	#define VBOX_HDDFORMAT_PLUGIN_PREFIX_LENGTH (sizeof(VBOX_HDDFORMAT_PLUGIN_PREFIX)-1)
552
553	#endif

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

source: vbox/trunk/include/VBox/VBoxHDD-Plugin.h@ 23746

Download in other formats: