VBoxHDD-Internal.h@ 16873

Last change on this file since 16873 was 16873, checked in by vboxsync, 16 years ago
Storage/VBoxHDD: eliminate the obsolete "-new" part of the name.
Property svn:eol-style set to `native`
File size: 21.7 KB

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

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

source: vbox/trunk/src/VBox/Devices/Storage/VBoxHDD-Internal.h@ 16873

Download in other formats: