VBoxHDD-new.h@ 7200

Last change on this file since 7200 was 6291, checked in by vboxsync, 17 years ago

Big virtual disk changeset containing several modifications

remove the always buggy translation setting and replace it with two sets of geometries, physical and logical
complete vmdk creation (fixed/dynamic variants, both split in 2G chunks and single file)
implemented VBoxHDD-new generic snapshot support, i.e. diff image creation and image merging (completely untested, I'm pretty sure there are bugs)
assorted changes which generalize the VBoxHDD-new interfaces (both externally and internally)

Property svn:eol-style set to native
Property svn:keywords set to Author Date Id Revision

File size: 27.5 KB

Line
1	/** @file
2	* VBox HDD Container API.
3	* Will replace VBoxHDD.h.
4	*/
5
6	/*
7	* Copyright (C) 2006-2008 innotek GmbH
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* The contents of this file may alternatively be used under the terms
18	* of the Common Development and Distribution License Version 1.0
19	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20	* VirtualBox OSE distribution, in which case the provisions of the
21	* CDDL are applicable instead of those of the GPL.
22	*
23	* You may elect to license modified versions of this file under the
24	* terms and conditions of either the GPL or the CDDL or both.
25	*/
26
27	#ifndef ___VBox_VD_h
28	#define ___VBox_VD_h
29
30	#include <VBox/cdefs.h>
31	#include <VBox/types.h>
32	#include <VBox/pdm.h>
33
34	__BEGIN_DECLS
35
36	#ifdef IN_RING0
37	# error "There are no VBox HDD Container APIs available in Ring-0 Host Context!"
38	#endif
39
40	/** @defgroup grp_vd VBox HDD Container
41	* @{
42	*/
43
44	/** Current VMDK image version. */
45	#define VMDK_IMAGE_VERSION (0x0001)
46
47	/** Current VDI image major version. */
48	#define VDI_IMAGE_VERSION_MAJOR (0x0001)
49	/** Current VDI image minor version. */
50	#define VDI_IMAGE_VERSION_MINOR (0x0001)
51	/** Current VDI image version. */
52	#define VDI_IMAGE_VERSION ((VDI_IMAGE_VERSION_MAJOR << 16) \| VDI_IMAGE_VERSION_MINOR)
53
54	/** Get VDI major version from combined version. */
55	#define VDI_GET_VERSION_MAJOR(uVer) ((uVer) >> 16)
56	/** Get VDI minor version from combined version. */
57	#define VDI_GET_VERSION_MINOR(uVer) ((uVer) & 0xffff)
58
59	/** Placeholder for specifying the last opened image. */
60	#define VD_LAST_IMAGE 0xffffffffU
61
62	/** @name VBox HDD container image types
63	* @{ */
64	typedef enum VDIMAGETYPE
65	{
66	/** Normal dynamically growing base image file. */
67	VD_IMAGE_TYPE_NORMAL = 1,
68	/** Preallocated base image file of a fixed size. */
69	VD_IMAGE_TYPE_FIXED,
70	/** Dynamically growing image file for undo/commit changes support. */
71	VD_IMAGE_TYPE_UNDO,
72	/** Dynamically growing image file for differencing support. */
73	VD_IMAGE_TYPE_DIFF,
74
75	/** First valid image type value. */
76	VD_IMAGE_TYPE_FIRST = VD_IMAGE_TYPE_NORMAL,
77	/** Last valid image type value. */
78	VD_IMAGE_TYPE_LAST = VD_IMAGE_TYPE_DIFF
79	} VDIMAGETYPE;
80	/** Pointer to VBox HDD container image type. */
81	typedef VDIMAGETYPE *PVDIMAGETYPE;
82	/** @} */
83
84	/** @name VBox HDD container image flags
85	* @{
86	*/
87	/** No flags. */
88	#define VD_IMAGE_FLAGS_NONE (0)
89	/** VMDK: Split image into 2GB extents. */
90	#define VD_VMDK_IMAGE_FLAGS_SPLIT_2G (0x0001)
91	/** VMDK: Raw disk image (giving access to a number of host partitions). */
92	#define VD_VMDK_IMAGE_FLAGS_RAWDISK (0x0002)
93	/** VDI: Fill new blocks with zeroes while expanding image file. Only valid
94	* for newly created images, never set for opened existing images. */
95	#define VD_VDI_IMAGE_FLAGS_ZERO_EXPAND (0x0100)
96
97	/** Mask of valid image flags for VMDK. */
98	#define VD_VMDK_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_NONE \| VD_VMDK_IMAGE_FLAGS_SPLIT_2G \| VD_VMDK_IMAGE_FLAGS_RAWDISK)
99
100	/** Mask of valid image flags for VDI. */
101	#define VD_VDI_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_NONE \| VD_VDI_IMAGE_FLAGS_ZERO_EXPAND)
102
103	/** Mask of all valid image flags for all formats. */
104	#define VD_IMAGE_FLAGS_MASK (VD_VMDK_IMAGE_FLAGS_MASK \| VD_VDI_IMAGE_FLAGS_MASK)
105
106	/** Default image flags. */
107	#define VD_IMAGE_FLAGS_DEFAULT (VD_IMAGE_FLAGS_NONE)
108	/** @} */
109
110
111	/**
112	* Auxiliary type for describing partitions on raw disks.
113	*/
114	typedef struct VBOXHDDRAWPART
115	{
116	/** Device to use for this partition. Can be the disk device if the offset
117	* field is set appropriately. If this is NULL, then this partition will
118	* not be accessible to the guest. The size of the partition must still
119	* be set correctly. */
120	const char *pszRawDevice;
121	/** Offset where the partition data starts in this device. */
122	uint64_t uPartitionStartOffset;
123	/** Offset where the partition data starts in the disk. */
124	uint64_t uPartitionStart;
125	/** Size of the partition. */
126	uint64_t cbPartition;
127	/** Size of the partitioning info to prepend. */
128	uint64_t cbPartitionData;
129	/** Offset where the partitioning info starts in the disk. */
130	uint64_t uPartitionDataStart;
131	/** Pointer to the partitioning info to prepend. */
132	const void *pvPartitionData;
133	} VBOXHDDRAWPART, *PVBOXHDDRAWPART;
134
135	/**
136	* Auxiliary data structure for creating raw disks.
137	*/
138	typedef struct VBOXHDDRAW
139	{
140	/** Signature for structure. Must be 'R', 'A', 'W', '\0'. Actually a trick
141	* to make logging of the comment string produce sensible results. */
142	char szSignature[4];
143	/** Flag whether access to full disk should be given (ignoring the
144	* partition information below). */
145	bool fRawDisk;
146	/** Filename for the raw disk. Ignored for partitioned raw disks.
147	* For Linux e.g. /dev/sda, and for Windows e.g. \\.\PhysicalDisk0. */
148	const char *pszRawDisk;
149	/** Number of entries in the partitions array. */
150	unsigned cPartitions;
151	/** Pointer to the partitions array. */
152	PVBOXHDDRAWPART pPartitions;
153	} VBOXHDDRAW, *PVBOXHDDRAW;
154
155	/** @name VBox HDD container image open mode flags
156	* @{
157	*/
158	/** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */
159	#define VD_OPEN_FLAGS_NORMAL 0
160	/** Open image in read-only mode with sharing access with others. */
161	#define VD_OPEN_FLAGS_READONLY RT_BIT(0)
162	/** Honor zero block writes instead of ignoring them whenever possible.
163	* This is not supported by all formats. It is silently ignored in this case. */
164	#define VD_OPEN_FLAGS_HONOR_ZEROES RT_BIT(1)
165	/** Honor writes of the same data instead of ignoring whenever possible.
166	* This is handled generically, and is only meaningful for differential image
167	* formats. It is silently ignored otherwise. */
168	#define VD_OPEN_FLAGS_HONOR_SAME RT_BIT(2)
169	/** Do not perform the base/diff image check on open. This internally implies
170	* opening the image as readonly. Images opened with this flag should only be
171	* used for querying information, and nothing else. */
172	#define VD_OPEN_FLAGS_INFO RT_BIT(3)
173	/** Mask of valid flags. */
174	#define VD_OPEN_FLAGS_MASK (VD_OPEN_FLAGS_NORMAL \| VD_OPEN_FLAGS_READONLY \| VD_OPEN_FLAGS_HONOR_ZEROES \| VD_OPEN_FLAGS_HONOR_SAME \| VD_OPEN_FLAGS_INFO)
175	/** @}*/
176
177	/**
178	* Error message callback.
179	*
180	* @param pvUser The opaque data passed on container creation.
181	* @param rc The VBox error code.
182	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
183	* @param pszFormat Error message format string.
184	* @param va Error message arguments.
185	*/
186	typedef DECLCALLBACK(void) FNVDERROR(void pvUser, int rc, RT_SRC_POS_DECL, const char pszFormat, va_list va);
187	/** Pointer to a FNVDERROR(). */
188	typedef FNVDERROR *PFNVDERROR;
189
190
191	/**
192	* VBox HDD Container main structure.
193	*/
194	/* Forward declaration, VBOXHDD structure is visible only inside VBox HDD module. */
195	struct VBOXHDD;
196	typedef struct VBOXHDD VBOXHDD;
197	typedef VBOXHDD *PVBOXHDD;
198
199	/**
200	* Allocates and initializes an empty HDD container.
201	* No image files are opened.
202	*
203	* @returns VBox status code.
204	* @param pszBackend Name of the image file backend to use.
205	* @param pfnError Callback for setting extended error information.
206	* @param pvErrorUser Opaque parameter for pfnError.
207	* @param ppDisk Where to store the reference to HDD container.
208	*/
209	VBOXDDU_DECL(int) VDCreate(const char *pszBackend, PFNVDERROR pfnError,
210	void pvErrorUser, PVBOXHDD ppDisk);
211
212	/**
213	* Destroys HDD container.
214	* If container has opened image files they will be closed.
215	*
216	* @param pDisk Pointer to HDD container.
217	*/
218	VBOXDDU_DECL(void) VDDestroy(PVBOXHDD pDisk);
219
220	/**
221	* Try to get the backend name which can use this image.
222	*
223	* @returns VBox status code.
224	* @param pszFilename Name of the image file for which the backend is queried.
225	* @param ppszFormat Receives pointer of the UTF-8 string which contains the format name.
226	* The returned pointer must be freed using RTStrFree().
227	*/
228	VBOXDDU_DECL(int) VDGetFormat(const char pszFilename, char *ppszFormat);
229
230	/**
231	* Opens an image file.
232	*
233	* The first opened image file in HDD container must have a base image type,
234	* others (next opened images) must be differencing or undo images.
235	* Linkage is checked for differencing image to be consistent with the previously opened image.
236	* When another differencing image is opened and the last image was opened in read/write access
237	* mode, then the last image is reopened in read-only with deny write sharing mode. This allows
238	* other processes to use images in read-only mode too.
239	*
240	* Note that the image is opened in read-only mode if a read/write open is not possible.
241	* Use VDIsReadOnly to check open mode.
242	*
243	* @returns VBox status code.
244	* @param pDisk Pointer to HDD container.
245	* @param pszFilename Name of the image file to open.
246	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
247	*/
248	VBOXDDU_DECL(int) VDOpen(PVBOXHDD pDisk, const char *pszFilename,
249	unsigned uOpenFlags);
250
251	/**
252	* Creates and opens a new base image file.
253	*
254	* @returns VBox status code.
255	* @param pDisk Pointer to HDD container.
256	* @param pszFilename Name of the image file to create.
257	* @param enmType Image type, only base image types are acceptable.
258	* @param cbSize Image size in bytes.
259	* @param uImageFlags Flags specifying special image features.
260	* @param pszComment Pointer to image comment. NULL is ok.
261	* @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL.
262	* @param pLCHSGeometry Pointer to logical disk geometry <= (1024,255,63). Not NULL.
263	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
264	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
265	* @param pvUser User argument for the progress callback.
266	*/
267	VBOXDDU_DECL(int) VDCreateBase(PVBOXHDD pDisk, const char *pszFilename,
268	VDIMAGETYPE enmType, uint64_t cbSize,
269	unsigned uImageFlags, const char *pszComment,
270	PCPDMMEDIAGEOMETRY pPCHSGeometry,
271	PCPDMMEDIAGEOMETRY pLCHSGeometry,
272	unsigned uOpenFlags, PFNVMPROGRESS pfnProgress,
273	void *pvUser);
274
275	/**
276	* Creates and opens a new differencing image file in HDD container.
277	* See comments for VDOpen function about differencing images.
278	*
279	* @returns VBox status code.
280	* @param pDisk Pointer to HDD container.
281	* @param pszFilename Name of the differencing image file to create.
282	* @param uImageFlags Flags specifying special image features.
283	* @param pszComment Pointer to image comment. NULL is ok.
284	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
285	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
286	* @param pvUser User argument for the progress callback.
287	*/
288	VBOXDDU_DECL(int) VDCreateDiff(PVBOXHDD pDisk, const char *pszFilename,
289	unsigned uImageFlags, const char *pszComment,
290	unsigned uOpenFlags, PFNVMPROGRESS pfnProgress,
291	void *pvUser);
292
293	/**
294	* Merges two images (not necessarily with direct parent/child relationship).
295	* As a side effect the source image and potentially the other images which
296	* are also merged to the destination are deleted from both the disk and the
297	* images in the HDD container.
298	*
299	* @returns VBox status code.
300	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
301	* @param pDisk Pointer to HDD container.
302	* @param nImageFrom Name of the image file to merge from.
303	* @param nImageTo Name of the image file to merge to.
304	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
305	* @param pvUser User argument for the progress callback.
306	*/
307	VBOXDDU_DECL(int) VDMerge(PVBOXHDD pDisk, unsigned nImageFrom,
308	unsigned nImageTo, PFNVMPROGRESS pfnProgress,
309	void *pvUser);
310
311	/**
312	* Copies an image from one HDD container to another.
313	* The copy is opened in the target HDD container.
314	* It is possible to convert between different image formats, because the
315	* backend for the destination HDD container may be different from the
316	* source container.
317	* If both the source and destination reference the same HDD container,
318	* then the image is moved (by copying/deleting or renaming) to the new location.
319	* The source container is unchanged if the move operation fails, otherwise
320	* the image at the new location is opened in the same way as the old one was.
321	*
322	* @returns VBox status code.
323	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
324	* @param pDiskFrom Pointer to source HDD container.
325	* @param nImage Image number, counts from 0. 0 is always base image of container.
326	* @param pDiskTo Pointer to destination HDD container.
327	* @param pszFilename New name of the image (may be NULL if pDiskFrom == pDiskTo).
328	* @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
329	* @param cbSize New image size (0 means leave unchanged).
330	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
331	* @param pvUser User argument for the progress callback.
332	*/
333	VBOXDDU_DECL(int) VDCopy(PVBOXHDD pDiskFrom, unsigned nImage, PVBOXHDD pDiskTo,
334	const char *pszFilename, bool fMoveByRename,
335	uint64_t cbSize, PFNVMPROGRESS pfnProgress,
336	void *pvUser);
337
338	/**
339	* Closes the last opened image file in HDD container.
340	* If previous image file was opened in read-only mode (that is normal) and closing image
341	* was opened in read-write mode (the whole disk was in read-write mode) - the previous image
342	* will be reopened in read/write mode.
343	*
344	* @returns VBox status code.
345	* @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
346	* @param pDisk Pointer to HDD container.
347	* @param fDelete If true, delete the image from the host disk.
348	*/
349	VBOXDDU_DECL(int) VDClose(PVBOXHDD pDisk, bool fDelete);
350
351	/**
352	* Closes all opened image files in HDD container.
353	*
354	* @returns VBox status code.
355	* @param pDisk Pointer to HDD container.
356	*/
357	VBOXDDU_DECL(int) VDCloseAll(PVBOXHDD pDisk);
358
359	/**
360	* Read data from virtual HDD.
361	*
362	* @returns VBox status code.
363	* @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
364	* @param pDisk Pointer to HDD container.
365	* @param uOffset Offset of first reading byte from start of disk.
366	* @param pvBuf Pointer to buffer for reading data.
367	* @param cbRead Number of bytes to read.
368	*/
369	VBOXDDU_DECL(int) VDRead(PVBOXHDD pDisk, uint64_t uOffset, void *pvBuf, size_t cbRead);
370
371	/**
372	* Write data to virtual HDD.
373	*
374	* @returns VBox status code.
375	* @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
376	* @param pDisk Pointer to HDD container.
377	* @param uOffset Offset of first writing byte from start of disk.
378	* @param pvBuf Pointer to buffer for writing data.
379	* @param cbWrite Number of bytes to write.
380	*/
381	VBOXDDU_DECL(int) VDWrite(PVBOXHDD pDisk, uint64_t uOffset, const void *pvBuf, size_t cbWrite);
382
383	/**
384	* Make sure the on disk representation of a virtual HDD is up to date.
385	*
386	* @returns VBox status code.
387	* @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
388	* @param pDisk Pointer to HDD container.
389	*/
390	VBOXDDU_DECL(int) VDFlush(PVBOXHDD pDisk);
391
392	/**
393	* Get number of opened images in HDD container.
394	*
395	* @returns Number of opened images for HDD container. 0 if no images have been opened.
396	* @param pDisk Pointer to HDD container.
397	*/
398	VBOXDDU_DECL(unsigned) VDGetCount(PVBOXHDD pDisk);
399
400	/**
401	* Get read/write mode of HDD container.
402	*
403	* @returns Virtual disk ReadOnly status.
404	* @returns true if no image is opened in HDD container.
405	* @param pDisk Pointer to HDD container.
406	*/
407	VBOXDDU_DECL(bool) VDIsReadOnly(PVBOXHDD pDisk);
408
409	/**
410	* Get total capacity of an image in HDD container.
411	*
412	* @returns Virtual disk size in bytes.
413	* @returns 0 if image with specified number was not opened.
414	* @param pDisk Pointer to HDD container.
415	* @param nImage Image number, counts from 0. 0 is always base image of container.
416	*/
417	VBOXDDU_DECL(uint64_t) VDGetSize(PVBOXHDD pDisk, unsigned nImage);
418
419	/**
420	* Get total file size of an image in HDD container.
421	*
422	* @returns Virtual disk size in bytes.
423	* @returns 0 if image with specified number was not opened.
424	* @param pDisk Pointer to HDD container.
425	* @param nImage Image number, counts from 0. 0 is always base image of container.
426	*/
427	VBOXDDU_DECL(uint64_t) VDGetFileSize(PVBOXHDD pDisk, unsigned nImage);
428
429	/**
430	* Get virtual disk PCHS geometry of an image in HDD container.
431	*
432	* @returns VBox status code.
433	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
434	* @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the HDD container.
435	* @param pDisk Pointer to HDD container.
436	* @param nImage Image number, counts from 0. 0 is always base image of container.
437	* @param pPCHSGeometry Where to store PCHS geometry. Not NULL.
438	*/
439	VBOXDDU_DECL(int) VDGetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
440	PPDMMEDIAGEOMETRY pPCHSGeometry);
441
442	/**
443	* Store virtual disk PCHS geometry of an image in HDD container.
444	*
445	* @returns VBox status code.
446	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
447	* @param pDisk Pointer to HDD container.
448	* @param nImage Image number, counts from 0. 0 is always base image of container.
449	* @param pPCHSGeometry Where to load PCHS geometry from. Not NULL.
450	*/
451	VBOXDDU_DECL(int) VDSetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
452	PCPDMMEDIAGEOMETRY pPCHSGeometry);
453
454	/**
455	* Get virtual disk LCHS geometry of an image in HDD container.
456	*
457	* @returns VBox status code.
458	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
459	* @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the HDD container.
460	* @param pDisk Pointer to HDD container.
461	* @param nImage Image number, counts from 0. 0 is always base image of container.
462	* @param pLCHSGeometry Where to store LCHS geometry. Not NULL.
463	*/
464	VBOXDDU_DECL(int) VDGetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
465	PPDMMEDIAGEOMETRY pLCHSGeometry);
466
467	/**
468	* Store virtual disk LCHS geometry of an image in HDD container.
469	*
470	* @returns VBox status code.
471	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
472	* @param pDisk Pointer to HDD container.
473	* @param nImage Image number, counts from 0. 0 is always base image of container.
474	* @param pLCHSGeometry Where to load LCHS geometry from. Not NULL.
475	*/
476	VBOXDDU_DECL(int) VDSetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
477	PCPDMMEDIAGEOMETRY pLCHSGeometry);
478
479	/**
480	* Get version of image in HDD container.
481	*
482	* @returns VBox status code.
483	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
484	* @param pDisk Pointer to HDD container.
485	* @param nImage Image number, counts from 0. 0 is always base image of container.
486	* @param puVersion Where to store the image version.
487	*/
488	VBOXDDU_DECL(int) VDGetVersion(PVBOXHDD pDisk, unsigned nImage,
489	unsigned *puVersion);
490
491	/**
492	* Get type of image in HDD container.
493	*
494	* @returns VBox status code.
495	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
496	* @param pDisk Pointer to HDD container.
497	* @param nImage Image number, counts from 0. 0 is always base image of container.
498	* @param penmType Where to store the image type.
499	*/
500	VBOXDDU_DECL(int) VDGetImageType(PVBOXHDD pDisk, unsigned nImage,
501	PVDIMAGETYPE penmType);
502
503	/**
504	* Get flags of image in HDD container.
505	*
506	* @returns VBox status code.
507	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
508	* @param pDisk Pointer to HDD container.
509	* @param nImage Image number, counts from 0. 0 is always base image of container.
510	* @param puImageFlags Where to store the image flags.
511	*/
512	VBOXDDU_DECL(int) VDGetImageFlags(PVBOXHDD pDisk, unsigned nImage, unsigned *puImageFlags);
513
514	/**
515	* Get open flags of image in HDD container.
516	*
517	* @returns VBox status code.
518	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
519	* @param pDisk Pointer to HDD container.
520	* @param nImage Image number, counts from 0. 0 is always base image of container.
521	* @param puOpenFlags Where to store the image open flags.
522	*/
523	VBOXDDU_DECL(int) VDGetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
524	unsigned *puOpenFlags);
525
526	/**
527	* Set open flags of image in HDD container.
528	* This operation may cause file locking changes and/or files being reopened.
529	* Note that in case of unrecoverable error all images in HDD container will be closed.
530	*
531	* @returns VBox status code.
532	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
533	* @param pDisk Pointer to HDD container.
534	* @param nImage Image number, counts from 0. 0 is always base image of container.
535	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
536	*/
537	VBOXDDU_DECL(int) VDSetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
538	unsigned uOpenFlags);
539
540	/**
541	* Get base filename of image in HDD container. Some image formats use
542	* other filenames as well, so don't use this for anything but informational
543	* purposes.
544	*
545	* @returns VBox status code.
546	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
547	* @returns VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
548	* @param pDisk Pointer to HDD container.
549	* @param nImage Image number, counts from 0. 0 is always base image of container.
550	* @param pszFilename Where to store the image file name.
551	* @param cbFilename Size of buffer pszFilename points to.
552	*/
553	VBOXDDU_DECL(int) VDGetFilename(PVBOXHDD pDisk, unsigned nImage,
554	char *pszFilename, unsigned cbFilename);
555
556	/**
557	* Get the comment line of image in HDD container.
558	*
559	* @returns VBox status code.
560	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
561	* @returns VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
562	* @param pDisk Pointer to HDD container.
563	* @param nImage Image number, counts from 0. 0 is always base image of container.
564	* @param pszComment Where to store the comment string of image. NULL is ok.
565	* @param cbComment The size of pszComment buffer. 0 is ok.
566	*/
567	VBOXDDU_DECL(int) VDGetComment(PVBOXHDD pDisk, unsigned nImage,
568	char *pszComment, unsigned cbComment);
569
570	/**
571	* Changes the comment line of image in HDD container.
572	*
573	* @returns VBox status code.
574	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
575	* @param pDisk Pointer to HDD container.
576	* @param nImage Image number, counts from 0. 0 is always base image of container.
577	* @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment.
578	*/
579	VBOXDDU_DECL(int) VDSetComment(PVBOXHDD pDisk, unsigned nImage,
580	const char *pszComment);
581
582	/**
583	* Get UUID of image in HDD container.
584	*
585	* @returns VBox status code.
586	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
587	* @param pDisk Pointer to HDD container.
588	* @param nImage Image number, counts from 0. 0 is always base image of container.
589	* @param pUuid Where to store the image UUID.
590	*/
591	VBOXDDU_DECL(int) VDGetUuid(PVBOXHDD pDisk, unsigned nImage, PRTUUID pUuid);
592
593	/**
594	* Set the image's UUID. Should not be used by normal applications.
595	*
596	* @returns VBox status code.
597	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
598	* @param pDisk Pointer to HDD container.
599	* @param nImage Image number, counts from 0. 0 is always base image of container.
600	* @param pUuid New UUID of the image. If NULL, a new UUID is created.
601	*/
602	VBOXDDU_DECL(int) VDSetUuid(PVBOXHDD pDisk, unsigned nImage, PCRTUUID pUuid);
603
604	/**
605	* Get last modification UUID of image in HDD container.
606	*
607	* @returns VBox status code.
608	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
609	* @param pDisk Pointer to HDD container.
610	* @param nImage Image number, counts from 0. 0 is always base image of container.
611	* @param pUuid Where to store the image modification UUID.
612	*/
613	VBOXDDU_DECL(int) VDGetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
614	PRTUUID pUuid);
615
616	/**
617	* Set the image's last modification UUID. Should not be used by normal applications.
618	*
619	* @returns VBox status code.
620	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
621	* @param pDisk Pointer to HDD container.
622	* @param nImage Image number, counts from 0. 0 is always base image of container.
623	* @param pUuid New modification UUID of the image. If NULL, a new UUID is created.
624	*/
625	VBOXDDU_DECL(int) VDSetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
626	PCRTUUID pUuid);
627
628	/**
629	* Get parent UUID of image in HDD container.
630	*
631	* @returns VBox status code.
632	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
633	* @param pDisk Pointer to HDD container.
634	* @param nImage Image number, counts from 0. 0 is always base image of the container.
635	* @param pUuid Where to store the parent image UUID.
636	*/
637	VBOXDDU_DECL(int) VDGetParentUuid(PVBOXHDD pDisk, unsigned nImage,
638	PRTUUID pUuid);
639
640	/**
641	* Set the image's parent UUID. Should not be used by normal applications.
642	*
643	* @returns VBox status code.
644	* @param pDisk Pointer to HDD container.
645	* @param nImage Image number, counts from 0. 0 is always base image of container.
646	* @param pUuid New parent UUID of the image. If NULL, a new UUID is created.
647	*/
648	VBOXDDU_DECL(int) VDSetParentUuid(PVBOXHDD pDisk, unsigned nImage,
649	PCRTUUID pUuid);
650
651
652	/**
653	* Debug helper - dumps all opened images in HDD container into the log file.
654	*
655	* @param pDisk Pointer to HDD container.
656	*/
657	VBOXDDU_DECL(void) VDDumpImages(PVBOXHDD pDisk);
658
659	__END_DECLS
660
661	/** @} */
662
663	#endif

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

source: vbox/trunk/include/VBox/VBoxHDD-new.h@ 7200

Download in other formats: