VBoxHDD-newInternal.h@ 13303

Last change on this file since 13303 was 11484, checked in by vboxsync, 16 years ago
Storage/VBoxHDD-new: Add information about configuration settings supported by a backend. Storage/iSCSI: Move initiator name default to backend. Main: Move iSCSI initiator name default to backend.
Property svn:eol-style set to `native`
File size: 20.5 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	* 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	* Check if a file is valid for the backend.
75	*
76	* @returns VBox status code.
77	* @param pszFilename Name of the image file.
78	*/
79	DECLR3CALLBACKMEMBER(int, pfnCheckIfValid, (const char *pszFilename));
80
81	/**
82	* Open a disk image.
83	*
84	* @returns VBox status code.
85	* @param pszFilename Name of the image file to open. Guaranteed to be available and
86	* unchanged during the lifetime of this image.
87	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
88	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
89	* @param pVDIfsImage Pointer to the per-image VD interface list.
90	* @param ppvBackendData Opaque state data for this image.
91	*/
92	DECLR3CALLBACKMEMBER(int, pfnOpen, (const char *pszFilename, unsigned uOpenFlags,
93	PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
94	void **ppvBackendData));
95
96	/**
97	* Create a disk image.
98	*
99	* @returns VBox status code.
100	* @param pszFilename Name of the image file to create. Guaranteed to be available and
101	* unchanged during the lifetime of this image.
102	* @param enmType Image type. Both base and diff image types are valid.
103	* @param cbSize Image size in bytes.
104	* @param uImageFlags Flags specifying special image features.
105	* @param pszComment Pointer to image comment. NULL is ok.
106	* @param pPCHSGeometry Physical drive geometry CHS <= (16383,16,255).
107	* @param pLCHSGeometry Logical drive geometry CHS <= (1024,255,63).
108	* @param pUuid New UUID of the image. Not NULL.
109	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
110	* @param uPercentStart Starting value for progress percentage.
111	* @param uPercentSpan Span for varying progress percentage.
112	* @param pVDIfsDisk Pointer to the per-disk VD interface list.
113	* @param pVDIfsImage Pointer to the per-image VD interface list.
114	* @param pVDIfsOperation Pointer to the per-operation VD interface list.
115	* @param ppvBackendData Opaque state data for this image.
116	*/
117	DECLR3CALLBACKMEMBER(int, pfnCreate, (const char *pszFilename, VDIMAGETYPE enmType,
118	uint64_t cbSize, unsigned uImageFlags,
119	const char *pszComment,
120	PCPDMMEDIAGEOMETRY pPCHSGeometry,
121	PCPDMMEDIAGEOMETRY pLCHSGeometry,
122	PCRTUUID pUuid, unsigned uOpenFlags,
123	unsigned uPercentStart, unsigned uPercentSpan,
124	PVDINTERFACE pVDIfsDisk,
125	PVDINTERFACE pVDIfsImage,
126	PVDINTERFACE pVDIfsOperation,
127	void **ppvBackendData));
128
129	/**
130	* Rename a disk image. Only needs to work as long as the operating
131	* system's rename file functionality is usable. If an attempt is made to
132	* rename an image to a location on another disk/filesystem, this function
133	* may just fail with an appropriate error code (not changing the opened
134	* image data at all). Also works only on images which actually refer to
135	* files (and not for raw disk images).
136	*
137	* @returns VBox status code.
138	* @param pvBackendData Opaque state data for this image.
139	* @param pszFilename New name of the image file. Guaranteed to be available and
140	* unchanged during the lifetime of this image.
141	*/
142	DECLR3CALLBACKMEMBER(int, pfnRename, (void pvBackendData, const char pszFilename));
143
144	/**
145	* Close a disk image.
146	*
147	* @returns VBox status code.
148	* @param pvBackendData Opaque state data for this image.
149	* @param fDelete If true, delete the image from the host disk.
150	*/
151	DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvBackendData, bool fDelete));
152
153	/**
154	* Read data from a disk image. The area read never crosses a block
155	* boundary.
156	*
157	* @returns VBox status code.
158	* @returns VINF_VDI_BLOCK_FREE if this image contains no data for this block.
159	* @returns VINF_VDI_BLOCK_ZERO if this image contains a zero data block.
160	* @param pvBackendData Opaque state data for this image.
161	* @param off Offset to start reading from.
162	* @param pvBuf Where to store the read bits.
163	* @param cbRead Number of bytes to read.
164	* @param pcbActuallyRead Pointer to returned number of bytes read.
165	*/
166	DECLR3CALLBACKMEMBER(int, pfnRead, (void pvBackendData, uint64_t off, void pvBuf,
167	size_t cbRead, size_t *pcbActuallyRead));
168
169	/**
170	* Write data to a disk image. The area written never crosses a block
171	* boundary.
172	*
173	* @returns VBox status code.
174	* @returns VINF_VDI_BLOCK_FREE if this image contains no data for this block and
175	* this is not a full-block write. The write must be repeated with
176	* the correct amount of prefix/postfix data read from the images below
177	* in the image stack. This might not be the most convenient interface,
178	* but it works with arbitrary block sizes, especially when the image
179	* stack uses different block sizes.
180	* @param pvBackendData Opaque state data for this image.
181	* @param off Offset to start writing to.
182	* @param pvBuf Where to retrieve the written bits.
183	* @param cbWrite Number of bytes to write.
184	* @param pcbWriteProcess Pointer to returned number of bytes that could
185	* be processed. In case the function returned
186	* VINF_VDI_BLOCK_FREE this is the number of bytes
187	* that could be written in a full block write,
188	* when prefixed/postfixed by the appropriate
189	* amount of (previously read) padding data.
190	* @param pcbPreRead Pointer to the returned amount of data that must
191	* be prefixed to perform a full block write.
192	* @param pcbPostRead Pointer to the returned amount of data that must
193	* be postfixed to perform a full block write.
194	* @param fWrite Flags which affect write behavior. Combination
195	* of the VD_WRITE_* flags.
196	*/
197	DECLR3CALLBACKMEMBER(int, pfnWrite, (void *pvBackendData, uint64_t off,
198	const void *pvBuf, size_t cbWrite,
199	size_t pcbWriteProcess, size_t pcbPreRead,
200	size_t *pcbPostRead, unsigned fWrite));
201
202	/**
203	* Flush data to disk.
204	*
205	* @returns VBox status code.
206	* @param pvBackendData Opaque state data for this image.
207	*/
208	DECLR3CALLBACKMEMBER(int, pfnFlush, (void *pvBackendData));
209
210	/**
211	* Get the version of a disk image.
212	*
213	* @returns version of disk image.
214	* @param pvBackendData Opaque state data for this image.
215	*/
216	DECLR3CALLBACKMEMBER(unsigned, pfnGetVersion, (void *pvBackendData));
217
218	/**
219	* Get the type information for a disk image.
220	*
221	* @returns VBox status code.
222	* @param pvBackendData Opaque state data for this image.
223	* @param penmType Image type of this image.
224	*/
225	DECLR3CALLBACKMEMBER(int, pfnGetImageType, (void *pvBackendData, PVDIMAGETYPE penmType));
226
227	/**
228	* Get the capacity of a disk image.
229	*
230	* @returns size of disk image in bytes.
231	* @param pvBackendData Opaque state data for this image.
232	*/
233	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize, (void *pvBackendData));
234
235	/**
236	* Get the file size of a disk image.
237	*
238	* @returns size of disk image in bytes.
239	* @param pvBackendData Opaque state data for this image.
240	*/
241	DECLR3CALLBACKMEMBER(uint64_t, pfnGetFileSize, (void *pvBackendData));
242
243	/**
244	* Get virtual disk PCHS geometry stored in a disk image.
245	*
246	* @returns VBox status code.
247	* @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the image.
248	* @param pvBackendData Opaque state data for this image.
249	* @param pPCHSGeometry Where to store the geometry. Not NULL.
250	*/
251	DECLR3CALLBACKMEMBER(int, pfnGetPCHSGeometry, (void *pvBackendData, PPDMMEDIAGEOMETRY pPCHSGeometry));
252
253	/**
254	* Set virtual disk PCHS geometry stored in a disk image.
255	* Only called if geometry is different than before.
256	*
257	* @returns VBox status code.
258	* @param pvBackendData Opaque state data for this image.
259	* @param pPCHSGeometry Where to load the geometry from. Not NULL.
260	*/
261	DECLR3CALLBACKMEMBER(int, pfnSetPCHSGeometry, (void *pvBackendData, PCPDMMEDIAGEOMETRY pPCHSGeometry));
262
263	/**
264	* Get virtual disk LCHS geometry stored in a disk image.
265	*
266	* @returns VBox status code.
267	* @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the image.
268	* @param pvBackendData Opaque state data for this image.
269	* @param pLCHSGeometry Where to store the geometry. Not NULL.
270	*/
271	DECLR3CALLBACKMEMBER(int, pfnGetLCHSGeometry, (void *pvBackendData, PPDMMEDIAGEOMETRY pLCHSGeometry));
272
273	/**
274	* Set virtual disk LCHS geometry stored in a disk image.
275	* Only called if geometry is different than before.
276	*
277	* @returns VBox status code.
278	* @param pvBackendData Opaque state data for this image.
279	* @param pLCHSGeometry Where to load the geometry from. Not NULL.
280	*/
281	DECLR3CALLBACKMEMBER(int, pfnSetLCHSGeometry, (void *pvBackendData, PCPDMMEDIAGEOMETRY pLCHSGeometry));
282
283	/**
284	* Get the image flags of a disk image.
285	*
286	* @returns image flags of disk image.
287	* @param pvBackendData Opaque state data for this image.
288	*/
289	DECLR3CALLBACKMEMBER(unsigned, pfnGetImageFlags, (void *pvBackendData));
290
291	/**
292	* Get the open flags of a disk image.
293	*
294	* @returns open flags of disk image.
295	* @param pvBackendData Opaque state data for this image.
296	*/
297	DECLR3CALLBACKMEMBER(unsigned, pfnGetOpenFlags, (void *pvBackendData));
298
299	/**
300	* Set the open flags of a disk image. May cause the image to be locked
301	* in a different mode or be reopened (which can fail).
302	*
303	* @returns VBox status code.
304	* @param pvBackendData Opaque state data for this image.
305	* @param uOpenFlags New open flags for this image.
306	*/
307	DECLR3CALLBACKMEMBER(int, pfnSetOpenFlags, (void *pvBackendData, unsigned uOpenFlags));
308
309	/**
310	* Get comment of a disk image.
311	*
312	* @returns VBox status code.
313	* @param pvBackendData Opaque state data for this image.
314	* @param pszComment Where to store the comment.
315	* @param cbComment Size of the comment buffer.
316	*/
317	DECLR3CALLBACKMEMBER(int, pfnGetComment, (void pvBackendData, char pszComment, size_t cbComment));
318
319	/**
320	* Set comment of a disk image.
321	*
322	* @returns VBox status code.
323	* @param pvBackendData Opaque state data for this image.
324	* @param pszComment Where to get the comment from. NULL resets comment.
325	* The comment is silently truncated if the image format
326	* limit is exceeded.
327	*/
328	DECLR3CALLBACKMEMBER(int, pfnSetComment, (void pvBackendData, const char pszComment));
329
330	/**
331	* Get UUID of a disk image.
332	*
333	* @returns VBox status code.
334	* @param pvBackendData Opaque state data for this image.
335	* @param pUuid Where to store the image UUID.
336	*/
337	DECLR3CALLBACKMEMBER(int, pfnGetUuid, (void *pvBackendData, PRTUUID pUuid));
338
339	/**
340	* Set UUID of a disk image.
341	*
342	* @returns VBox status code.
343	* @param pvBackendData Opaque state data for this image.
344	* @param pUuid Where to get the image UUID from.
345	*/
346	DECLR3CALLBACKMEMBER(int, pfnSetUuid, (void *pvBackendData, PCRTUUID pUuid));
347
348	/**
349	* Get last modification UUID of a disk image.
350	*
351	* @returns VBox status code.
352	* @param pvBackendData Opaque state data for this image.
353	* @param pUuid Where to store the image modification UUID.
354	*/
355	DECLR3CALLBACKMEMBER(int, pfnGetModificationUuid, (void *pvBackendData, PRTUUID pUuid));
356
357	/**
358	* Set last modification UUID of a disk image.
359	*
360	* @returns VBox status code.
361	* @param pvBackendData Opaque state data for this image.
362	* @param pUuid Where to get the image modification UUID from.
363	*/
364	DECLR3CALLBACKMEMBER(int, pfnSetModificationUuid, (void *pvBackendData, PCRTUUID pUuid));
365
366	/**
367	* Get parent UUID of a disk image.
368	*
369	* @returns VBox status code.
370	* @param pvBackendData Opaque state data for this image.
371	* @param pUuid Where to store the parent image UUID.
372	*/
373	DECLR3CALLBACKMEMBER(int, pfnGetParentUuid, (void *pvBackendData, PRTUUID pUuid));
374
375	/**
376	* Set parent UUID of a disk image.
377	*
378	* @returns VBox status code.
379	* @param pvBackendData Opaque state data for this image.
380	* @param pUuid Where to get the parent image UUID from.
381	*/
382	DECLR3CALLBACKMEMBER(int, pfnSetParentUuid, (void *pvBackendData, PCRTUUID pUuid));
383
384	/**
385	* Get parent modification UUID of a disk image.
386	*
387	* @returns VBox status code.
388	* @param pvBackendData Opaque state data for this image.
389	* @param pUuid Where to store the parent image modification UUID.
390	*/
391	DECLR3CALLBACKMEMBER(int, pfnGetParentModificationUuid, (void *pvBackendData, PRTUUID pUuid));
392
393	/**
394	* Set parent modification UUID of a disk image.
395	*
396	* @returns VBox status code.
397	* @param pvBackendData Opaque state data for this image.
398	* @param pUuid Where to get the parent image modification UUID from.
399	*/
400	DECLR3CALLBACKMEMBER(int, pfnSetParentModificationUuid, (void *pvBackendData, PCRTUUID pUuid));
401
402	/**
403	* Dump information about a disk image.
404	*
405	* @param pvBackendData Opaque state data for this image.
406	*/
407	DECLR3CALLBACKMEMBER(void, pfnDump, (void *pvBackendData));
408
409	/**
410	* Get a time stamp of a disk image.
411	*
412	* @returns VBox status code.
413	* @param pvBackendData Opaque state data for this image.
414	* @param pTimeStamp Where to store the time stamp.
415	*/
416	DECLR3CALLBACKMEMBER(int, pfnGetTimeStamp, (void *pvBackendData, PRTTIMESPEC pTimeStamp));
417
418	/**
419	* Get the parent time stamp of a disk image.
420	*
421	* @returns VBox status code.
422	* @param pvBackendData Opaque state data for this image.
423	* @param pTimeStamp Where to store the time stamp.
424	*/
425	DECLR3CALLBACKMEMBER(int, pfnGetParentTimeStamp, (void *pvBackendData, PRTTIMESPEC pTimeStamp));
426
427	/**
428	* Set the parent time stamp of a disk image.
429	*
430	* @returns VBox status code.
431	* @param pvBackendData Opaque state data for this image.
432	* @param pTimeStamp Where to get the time stamp from.
433	*/
434	DECLR3CALLBACKMEMBER(int, pfnSetParentTimeStamp, (void *pvBackendData, PCRTTIMESPEC pTimeStamp));
435
436	/**
437	* Get the relative path to parent image.
438	*
439	* @returns VBox status code.
440	* @param pvBackendData Opaque state data for this image.
441	* @param pszParentFilename Where to store the path.
442	*/
443	DECLR3CALLBACKMEMBER(int, pfnGetParentFilename, (void pvBackendData, char *ppszParentFilename));
444
445	/**
446	* Set the relative path to parent image.
447	*
448	* @returns VBox status code.
449	* @param pvBackendData Opaque state data for this image.
450	* @param pszParentFilename Where to get the path from.
451	*/
452	DECLR3CALLBACKMEMBER(int, pfnSetParentFilename, (void pvBackendData, const char pszParentFilename));
453
454	/**
455	* Return whether asynchronous I/O operations are supported for this image.
456	*
457	* @returns true if asynchronous I/O is supported
458	* false otherwise.
459	* @param pvBackendData Opaque state data for this image.
460	*/
461	DECLR3CALLBACKMEMBER(bool, pfnIsAsyncIOSupported, (void *pvBackendData));
462
463	/**
464	* Start an asynchronous read request.
465	*
466	* @returns VBox status code.
467	* @param pvBackendData Opaque state data for this image.
468	* @param uOffset The offset of the virtual disk to read from.
469	* @param cbRead How many bytes to read.
470	* @param paSeg Pointer to the segment array.
471	* @param cSeg Number of segments.
472	* @param pvUser Opaque user data.
473	*/
474	DECLR3CALLBACKMEMBER(int, pfnAsyncRead, (void *pvBackendData, uint64_t uOffset, size_t cbRead,
475	PPDMDATASEG paSeg, unsigned cSeg, void *pvUser));
476
477	/**
478	* Start an asynchronous write request.
479	*
480	* @returns VBox status code.
481	* @param pvBackendData Opaque state data for this image.
482	* @param uOffset The offset of the virtual disk to write to.
483	* @param cbWrite How many bytes to write.
484	* @param paSeg Pointer to the segment array.
485	* @param cSeg Number of segments.
486	* @param pvUser Oaque user data-
487	*/
488	DECLR3CALLBACKMEMBER(int, pfnAsyncWrite, (void *pvBackendData, uint64_t uOffset, size_t cbWrite,
489	PPDMDATASEG paSeg, unsigned cSeg, void *pvUser));
490
491	} VBOXHDDBACKEND;
492
493	/** Pointer to VD backend. */
494	typedef VBOXHDDBACKEND *PVBOXHDDBACKEND;
495
496	/** Constant pointer to VD backend. */
497	typedef const VBOXHDDBACKEND *PCVBOXHDDBACKEND;
498
499	/** Initialization entry point. */
500	typedef DECLCALLBACK(int) VBOXHDDFORMATLOAD(PVBOXHDDBACKEND *ppBackendTable);
501	typedef VBOXHDDFORMATLOAD *PFNVBOXHDDFORMATLOAD;
502	#define VBOX_HDDFORMAT_LOAD_NAME "VBoxHDDFormatLoad"
503
504	/** The prefix to identify Storage Plugins. */
505	#define VBOX_HDDFORMAT_PLUGIN_PREFIX "VBoxHDD"
506	/** The size of the prefix excluding the '\0' terminator. */
507	#define VBOX_HDDFORMAT_PLUGIN_PREFIX_LENGTH (sizeof(VBOX_HDDFORMAT_PLUGIN_PREFIX)-1)
508
509	#endif

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

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

Download in other formats: