VBoxHDD-newInternal.h@ 7894

Last change on this file since 7894 was 7780, checked in by vboxsync, 17 years ago
Add function to query all available VD backends, together with their capabilities. Also added a flag to the write operation (purely a dummy at the moment).
Property svn:eol-style set to `native`
File size: 15.6 KB

Line
1	/** @file
2	* Internal header file for VBox HDD Container.
3	*/
4
5	/*
6	* Copyright (C) 2006-2008 innotek GmbH
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
17	#ifndef __VBoxHDD_newInternal_h__
18
19
20	#include <VBox/pdm.h>
21	#include <VBox/VBoxHDD-new.h>
22
23
24	/** @name VBox HDD backend write flags
25	* @{
26	*/
27	/** Do not allocate a new block on this write. */
28	#define VD_WRITE_NO_ALLOC RT_BIT(1)
29	/** @}*/
30
31
32	/**
33	* Image format backend interface used by VBox HDD Container implementation.
34	*/
35	typedef struct VBOXHDDBACKEND
36	{
37	/**
38	* The name of the backend (constant string).
39	*/
40	const char *pszBackendName;
41
42	/**
43	* The size of the structure.
44	*/
45	uint32_t cbSize;
46
47	/**
48	* The capabilities of the backend.
49	*/
50	uint64_t uBackendCaps;
51
52	/**
53	* Check if a file is valid for the backend.
54	*
55	* @returns VBox status code.
56	* @param pszFilename Name of the image file.
57	*/
58	DECLR3CALLBACKMEMBER(int, pfnCheckIfValid, (const char *pszFilename));
59
60	/**
61	* Open a disk image.
62	*
63	* @returns VBox status code.
64	* @param pszFilename Name of the image file to open. Guaranteed to be available and
65	* unchanged during the lifetime of this image.
66	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
67	* @param pfnError Callback for setting extended error information.
68	* @param pvErrorUser Opaque parameter for pfnError.
69	* @param ppvBackendData Opaque state data for this image.
70	*/
71	DECLR3CALLBACKMEMBER(int, pfnOpen, (const char pszFilename, unsigned uOpenFlags, PFNVDERROR pfnError, void pvErrorUser, void **ppvBackendData));
72
73	/**
74	* Create a disk image.
75	*
76	* @returns VBox status code.
77	* @param pszFilename Name of the image file to create. Guaranteed to be available and
78	* unchanged during the lifetime of this image.
79	* @param enmType Image type. Both base and diff image types are valid.
80	* @param cbSize Image size in bytes.
81	* @param uImageFlags Flags specifying special image features.
82	* @param pszComment Pointer to image comment. NULL is ok.
83	* @param pPCHSGeometry Physical drive geometry CHS <= (16383,16,255).
84	* @param pLCHSGeometry Logical drive geometry CHS <= (1024,255,63).
85	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
86	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
87	* @param pvUser User argument for the progress callback.
88	* @param uPercentStart Starting value for progress percentage.
89	* @param uPercentSpan Span for varying progress percentage.
90	* @param pfnError Callback for setting extended error information.
91	* @param pvErrorUser Opaque parameter for pfnError.
92	* @param ppvBackendData Opaque state data for this image.
93	*/
94	DECLR3CALLBACKMEMBER(int, pfnCreate, (const char pszFilename, VDIMAGETYPE enmType, uint64_t cbSize, unsigned uImageFlags, const char pszComment, PCPDMMEDIAGEOMETRY pPCHSGeometry, PCPDMMEDIAGEOMETRY pLCHSGeometry, unsigned uOpenFlags, PFNVMPROGRESS pfnProgress, void pvUser, unsigned uPercentStart, unsigned uPercentSpan, PFNVDERROR pfnError, void pvErrorUser, void **ppvBackendData));
95
96	/**
97	* Rename a disk image. Only needs to work as long as the operating
98	* system's rename file functionality is usable. If an attempt is made to
99	* rename an image to a location on another disk/filesystem, this function
100	* may just fail with an appropriate error code (not changing the opened
101	* image data at all). Also works only on images which actually refer to
102	* files (and not for raw disk images).
103	*
104	* @returns VBox status code.
105	* @param pvBackendData Opaque state data for this image.
106	* @param pszFilename New name of the image file. Guaranteed to be available and
107	* unchanged during the lifetime of this image.
108	*/
109	DECLR3CALLBACKMEMBER(int, pfnRename, (void pvBackendData, const char pszFilename));
110
111	/**
112	* Close a disk image.
113	*
114	* @returns VBox status code.
115	* @param pvBackendData Opaque state data for this image.
116	* @param fDelete If true, delete the image from the host disk.
117	*/
118	DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvBackendData, bool fDelete));
119
120	/**
121	* Read data from a disk image. The area read never crosses a block
122	* boundary.
123	*
124	* @returns VBox status code.
125	* @returns VINF_VDI_BLOCK_FREE if this image contains no data for this block.
126	* @returns VINF_VDI_BLOCK_ZERO if this image contains a zero data block.
127	* @param pvBackendData Opaque state data for this image.
128	* @param off Offset to start reading from.
129	* @param pvBuf Where to store the read bits.
130	* @param cbRead Number of bytes to read.
131	* @param pcbActuallyRead Pointer to returned number of bytes read.
132	*/
133	DECLR3CALLBACKMEMBER(int, pfnRead, (void pvBackendData, uint64_t off, void pvBuf, size_t cbRead, size_t *pcbActuallyRead));
134
135	/**
136	* Write data to a disk image. The area written never crosses a block
137	* boundary.
138	*
139	* @returns VBox status code.
140	* @returns VINF_VDI_BLOCK_FREE if this image contains no data for this block and
141	* this is not a full-block write. The write must be repeated with
142	* the correct amount of prefix/postfix data read from the images below
143	* in the image stack. This might not be the most convenient interface,
144	* but it works with arbitrary block sizes, especially when the image
145	* stack uses different block sizes.
146	* @param pvBackendData Opaque state data for this image.
147	* @param off Offset to start writing to.
148	* @param pvBuf Where to retrieve the written bits.
149	* @param cbWrite Number of bytes to write.
150	* @param pcbWriteProcess Pointer to returned number of bytes that could
151	* be processed. In case the function returned
152	* VINF_VDI_BLOCK_FREE this is the number of bytes
153	* that could be written in a full block write,
154	* when prefixed/postfixed by the appropriate
155	* amount of (previously read) padding data.
156	* @param pcbPreRead Pointer to the returned amount of data that must
157	* be prefixed to perform a full block write.
158	* @param pcbPostRead Pointer to the returned amount of data that must
159	* be postfixed to perform a full block write.
160	* @param fWrite Flags which affect write behavior. Combination
161	* of the VD_WRITE_* flags.
162	*/
163	DECLR3CALLBACKMEMBER(int, pfnWrite, (void pvBackendData, uint64_t off, const void pvBuf, size_t cbWrite, size_t pcbWriteProcess, size_t pcbPreRead, size_t *pcbPostRead, unsigned fWrite));
164
165	/**
166	* Flush data to disk.
167	*
168	* @returns VBox status code.
169	* @param pvBackendData Opaque state data for this image.
170	*/
171	DECLR3CALLBACKMEMBER(int, pfnFlush, (void *pvBackendData));
172
173	/**
174	* Get the version of a disk image.
175	*
176	* @returns version of disk image.
177	* @param pvBackendData Opaque state data for this image.
178	*/
179	DECLR3CALLBACKMEMBER(unsigned, pfnGetVersion, (void *pvBackendData));
180
181	/**
182	* Get the type information for a disk image.
183	*
184	* @returns VBox status code.
185	* @param pvBackendData Opaque state data for this image.
186	* @param penmType Image type of this image.
187	*/
188	DECLR3CALLBACKMEMBER(int, pfnGetImageType, (void *pvBackendData, PVDIMAGETYPE penmType));
189
190	/**
191	* Get the capacity of a disk image.
192	*
193	* @returns size of disk image in bytes.
194	* @param pvBackendData Opaque state data for this image.
195	*/
196	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize, (void *pvBackendData));
197
198	/**
199	* Get the file size of a disk image.
200	*
201	* @returns size of disk image in bytes.
202	* @param pvBackendData Opaque state data for this image.
203	*/
204	DECLR3CALLBACKMEMBER(uint64_t, pfnGetFileSize, (void *pvBackendData));
205
206	/**
207	* Get virtual disk PCHS geometry stored in a disk image.
208	*
209	* @returns VBox status code.
210	* @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the image.
211	* @param pvBackendData Opaque state data for this image.
212	* @param pPCHSGeometry Where to store the geometry. Not NULL.
213	*/
214	DECLR3CALLBACKMEMBER(int, pfnGetPCHSGeometry, (void *pvBackendData, PPDMMEDIAGEOMETRY pPCHSGeometry));
215
216	/**
217	* Set virtual disk PCHS geometry stored in a disk image.
218	* Only called if geometry is different than before.
219	*
220	* @returns VBox status code.
221	* @param pvBackendData Opaque state data for this image.
222	* @param pPCHSGeometry Where to load the geometry from. Not NULL.
223	*/
224	DECLR3CALLBACKMEMBER(int, pfnSetPCHSGeometry, (void *pvBackendData, PCPDMMEDIAGEOMETRY pPCHSGeometry));
225
226	/**
227	* Get virtual disk LCHS geometry stored in a disk image.
228	*
229	* @returns VBox status code.
230	* @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the image.
231	* @param pvBackendData Opaque state data for this image.
232	* @param pLCHSGeometry Where to store the geometry. Not NULL.
233	*/
234	DECLR3CALLBACKMEMBER(int, pfnGetLCHSGeometry, (void *pvBackendData, PPDMMEDIAGEOMETRY pLCHSGeometry));
235
236	/**
237	* Set virtual disk LCHS geometry stored in a disk image.
238	* Only called if geometry is different than before.
239	*
240	* @returns VBox status code.
241	* @param pvBackendData Opaque state data for this image.
242	* @param pLCHSGeometry Where to load the geometry from. Not NULL.
243	*/
244	DECLR3CALLBACKMEMBER(int, pfnSetLCHSGeometry, (void *pvBackendData, PCPDMMEDIAGEOMETRY pLCHSGeometry));
245
246	/**
247	* Get the image flags of a disk image.
248	*
249	* @returns image flags of disk image.
250	* @param pvBackendData Opaque state data for this image.
251	*/
252	DECLR3CALLBACKMEMBER(unsigned, pfnGetImageFlags, (void *pvBackendData));
253
254	/**
255	* Get the open flags of a disk image.
256	*
257	* @returns open flags of disk image.
258	* @param pvBackendData Opaque state data for this image.
259	*/
260	DECLR3CALLBACKMEMBER(unsigned, pfnGetOpenFlags, (void *pvBackendData));
261
262	/**
263	* Set the open flags of a disk image. May cause the image to be locked
264	* in a different mode or be reopened (which can fail).
265	*
266	* @returns VBox status code.
267	* @param pvBackendData Opaque state data for this image.
268	* @param uOpenFlags New open flags for this image.
269	*/
270	DECLR3CALLBACKMEMBER(int, pfnSetOpenFlags, (void *pvBackendData, unsigned uOpenFlags));
271
272	/**
273	* Get comment of a disk image.
274	*
275	* @returns VBox status code.
276	* @param pvBackendData Opaque state data for this image.
277	* @param pszComment Where to store the comment.
278	* @param cbComment Size of the comment buffer.
279	*/
280	DECLR3CALLBACKMEMBER(int, pfnGetComment, (void pvBackendData, char pszComment, size_t cbComment));
281
282	/**
283	* Set comment of a disk image.
284	*
285	* @returns VBox status code.
286	* @param pvBackendData Opaque state data for this image.
287	* @param pszComment Where to get the comment from. NULL resets comment.
288	* The comment is silently truncated if the image format
289	* limit is exceeded.
290	*/
291	DECLR3CALLBACKMEMBER(int, pfnSetComment, (void pvBackendData, const char pszComment));
292
293	/**
294	* Get UUID of a disk image.
295	*
296	* @returns VBox status code.
297	* @param pvBackendData Opaque state data for this image.
298	* @param pUuid Where to store the image UUID.
299	*/
300	DECLR3CALLBACKMEMBER(int, pfnGetUuid, (void *pvBackendData, PRTUUID pUuid));
301
302	/**
303	* Set UUID of a disk image.
304	*
305	* @returns VBox status code.
306	* @param pvBackendData Opaque state data for this image.
307	* @param pUuid Where to get the image UUID from.
308	*/
309	DECLR3CALLBACKMEMBER(int, pfnSetUuid, (void *pvBackendData, PCRTUUID pUuid));
310
311	/**
312	* Get last modification UUID of a disk image.
313	*
314	* @returns VBox status code.
315	* @param pvBackendData Opaque state data for this image.
316	* @param pUuid Where to store the image modification UUID.
317	*/
318	DECLR3CALLBACKMEMBER(int, pfnGetModificationUuid, (void *pvBackendData, PRTUUID pUuid));
319
320	/**
321	* Set last modification UUID of a disk image.
322	*
323	* @returns VBox status code.
324	* @param pvBackendData Opaque state data for this image.
325	* @param pUuid Where to get the image modification UUID from.
326	*/
327	DECLR3CALLBACKMEMBER(int, pfnSetModificationUuid, (void *pvBackendData, PCRTUUID pUuid));
328
329	/**
330	* Get parent UUID of a disk image.
331	*
332	* @returns VBox status code.
333	* @param pvBackendData Opaque state data for this image.
334	* @param pUuid Where to store the parent image UUID.
335	*/
336	DECLR3CALLBACKMEMBER(int, pfnGetParentUuid, (void *pvBackendData, PRTUUID pUuid));
337
338	/**
339	* Set parent UUID of a disk image.
340	*
341	* @returns VBox status code.
342	* @param pvBackendData Opaque state data for this image.
343	* @param pUuid Where to get the parent image UUID from.
344	*/
345	DECLR3CALLBACKMEMBER(int, pfnSetParentUuid, (void *pvBackendData, PCRTUUID pUuid));
346
347	/**
348	* Get parent modification UUID of a disk image.
349	*
350	* @returns VBox status code.
351	* @param pvBackendData Opaque state data for this image.
352	* @param pUuid Where to store the parent image modification UUID.
353	*/
354	DECLR3CALLBACKMEMBER(int, pfnGetParentModificationUuid, (void *pvBackendData, PRTUUID pUuid));
355
356	/**
357	* Set parent modification UUID of a disk image.
358	*
359	* @returns VBox status code.
360	* @param pvBackendData Opaque state data for this image.
361	* @param pUuid Where to get the parent image modification UUID from.
362	*/
363	DECLR3CALLBACKMEMBER(int, pfnSetParentModificationUuid, (void *pvBackendData, PCRTUUID pUuid));
364
365	/**
366	* Dump information about a disk image.
367	*
368	* @param pvBackendData Opaque state data for this image.
369	*/
370	DECLR3CALLBACKMEMBER(void, pfnDump, (void *pvBackendData));
371
372	} VBOXHDDBACKEND;
373
374	/** Pointer to VD backend. */
375	typedef VBOXHDDBACKEND *PVBOXHDDBACKEND;
376
377	/** Constant pointer to VD backend. */
378	typedef const VBOXHDDBACKEND *PCVBOXHDDBACKEND;
379
380	/** Initialization entry point. */
381	typedef DECLCALLBACK(int) VBOXHDDFORMATLOAD(PVBOXHDDBACKEND *ppBackendTable);
382	typedef VBOXHDDFORMATLOAD *PFNVBOXHDDFORMATLOAD;
383	#define VBOX_HDDFORMAT_LOAD_NAME "VBoxHDDFormatLoad"
384
385	/** The prefix to identify Storage Plugins. */
386	#define VBOX_HDDFORMAT_PLUGIN_PREFIX "VBoxHDD"
387	/** The size of the prefix excluding the '\0' terminator. */
388	#define VBOX_HDDFORMAT_PLUGIN_PREFIX_LENGTH (sizeof(VBOX_HDDFORMAT_PLUGIN_PREFIX)-1)
389
390	#endif

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

source: vbox/trunk/src/VBox/Devices/Storage/VBoxHDD-newInternal.h@ 7894

Download in other formats: