VBoxHDD-newInternal.h@ 9152

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

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

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

Download in other formats: