VBoxHDD-new.h@ 7781

Last change on this file since 7781 was 7781, checked in by vboxsync, 17 years ago
Forgotten header file.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 29.3 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	/** @name VBox HDD container backend capability flags
179	* @{
180	*/
181	/** Supports UUIDs as expected by VirtualBox code. */
182	#define VD_CAP_UUID RT_BIT(0)
183	/** Supports creating fixed size images, allocating all space instantly. */
184	#define VD_CAP_CREATE_FIXED RT_BIT(1)
185	/** Supports creating dynamically growing images, allocating space on demand. */
186	#define VD_CAP_CREATE_DYNAMIC RT_BIT(2)
187	/** Supports creating images split in chunks of a bit less than 2GBytes. */
188	#define VD_CAP_CREATE_SPLIT_2G RT_BIT(3)
189	/** Supports being used as differencing image format backend. */
190	#define VD_CAP_DIFF RT_BIT(4)
191	/** @}*/
192
193
194	/**
195	* Data structure for returning a list of backend capabilities.
196	*/
197	typedef struct VDBACKENDINFO
198	{
199	/** Name of the backend. */
200	char *pszBackend;
201	/** Capabilities of the backend (a combination of the VD_CAP_* flags). */
202	uint64_t uBackendCaps;
203	} VDBACKENDINFO, *PVDBACKENDINFO;
204
205
206	/**
207	* Error message callback.
208	*
209	* @param pvUser The opaque data passed on container creation.
210	* @param rc The VBox error code.
211	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
212	* @param pszFormat Error message format string.
213	* @param va Error message arguments.
214	*/
215	typedef DECLCALLBACK(void) FNVDERROR(void pvUser, int rc, RT_SRC_POS_DECL, const char pszFormat, va_list va);
216	/** Pointer to a FNVDERROR(). */
217	typedef FNVDERROR *PFNVDERROR;
218
219
220	/**
221	* VBox HDD Container main structure.
222	*/
223	/* Forward declaration, VBOXHDD structure is visible only inside VBox HDD module. */
224	struct VBOXHDD;
225	typedef struct VBOXHDD VBOXHDD;
226	typedef VBOXHDD *PVBOXHDD;
227
228
229	/**
230	* Lists all HDD backends and their capabilities in a caller-provided buffer.
231	* Free all returned names with RTStrFree() when you no longer need them.
232	*
233	* @returns VBox status code.
234	* VERR_BUFFER_OVERFLOW if not enough space is passed.
235	* @param cEntriesAlloc Number of list entries available.
236	* @param pEntries Pointer to array for the entries.
237	* @param pcEntriesUsed Number of entries returned.
238	*/
239	VBOXDDU_DECL(int) VDBackendInfo(unsigned cEntriesAlloc, PVDBACKENDINFO pEntries,
240	unsigned *pcEntriesUsed);
241
242
243	/**
244	* Allocates and initializes an empty HDD container.
245	* No image files are opened.
246	*
247	* @returns VBox status code.
248	* @param pfnError Callback for setting extended error information.
249	* @param pvErrorUser Opaque parameter for pfnError.
250	* @param ppDisk Where to store the reference to HDD container.
251	*/
252	VBOXDDU_DECL(int) VDCreate(PFNVDERROR pfnError, void *pvErrorUser,
253	PVBOXHDD *ppDisk);
254
255	/**
256	* Destroys HDD container.
257	* If container has opened image files they will be closed.
258	*
259	* @param pDisk Pointer to HDD container.
260	*/
261	VBOXDDU_DECL(void) VDDestroy(PVBOXHDD pDisk);
262
263	/**
264	* Try to get the backend name which can use this image.
265	*
266	* @returns VBox status code.
267	* @param pszFilename Name of the image file for which the backend is queried.
268	* @param ppszFormat Receives pointer of the UTF-8 string which contains the format name.
269	* The returned pointer must be freed using RTStrFree().
270	*/
271	VBOXDDU_DECL(int) VDGetFormat(const char pszFilename, char *ppszFormat);
272
273	/**
274	* Opens an image file.
275	*
276	* The first opened image file in HDD container must have a base image type,
277	* others (next opened images) must be differencing or undo images.
278	* Linkage is checked for differencing image to be consistent with the previously opened image.
279	* When another differencing image is opened and the last image was opened in read/write access
280	* mode, then the last image is reopened in read-only with deny write sharing mode. This allows
281	* other processes to use images in read-only mode too.
282	*
283	* Note that the image is opened in read-only mode if a read/write open is not possible.
284	* Use VDIsReadOnly to check open mode.
285	*
286	* @returns VBox status code.
287	* @param pDisk Pointer to HDD container.
288	* @param pszBackend Name of the image file backend to use.
289	* @param pszFilename Name of the image file to open.
290	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
291	*/
292	VBOXDDU_DECL(int) VDOpen(PVBOXHDD pDisk, const char *pszBackend,
293	const char *pszFilename, unsigned uOpenFlags);
294
295	/**
296	* Creates and opens a new base image file.
297	*
298	* @returns VBox status code.
299	* @param pDisk Pointer to HDD container.
300	* @param pszBackend Name of the image file backend to use.
301	* @param pszFilename Name of the image file to create.
302	* @param enmType Image type, only base image types are acceptable.
303	* @param cbSize Image size in bytes.
304	* @param uImageFlags Flags specifying special image features.
305	* @param pszComment Pointer to image comment. NULL is ok.
306	* @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL.
307	* @param pLCHSGeometry Pointer to logical disk geometry <= (1024,255,63). Not NULL.
308	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
309	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
310	* @param pvUser User argument for the progress callback.
311	*/
312	VBOXDDU_DECL(int) VDCreateBase(PVBOXHDD pDisk, const char *pszBackend,
313	const char *pszFilename, VDIMAGETYPE enmType,
314	uint64_t cbSize, unsigned uImageFlags,
315	const char *pszComment,
316	PCPDMMEDIAGEOMETRY pPCHSGeometry,
317	PCPDMMEDIAGEOMETRY pLCHSGeometry,
318	unsigned uOpenFlags, PFNVMPROGRESS pfnProgress,
319	void *pvUser);
320
321	/**
322	* Creates and opens a new differencing image file in HDD container.
323	* See comments for VDOpen function about differencing images.
324	*
325	* @returns VBox status code.
326	* @param pDisk Pointer to HDD container.
327	* @param pszBackend Name of the image file backend to use.
328	* @param pszFilename Name of the differencing image file to create.
329	* @param uImageFlags Flags specifying special image features.
330	* @param pszComment Pointer to image comment. NULL is ok.
331	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
332	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
333	* @param pvUser User argument for the progress callback.
334	*/
335	VBOXDDU_DECL(int) VDCreateDiff(PVBOXHDD pDisk, const char *pszBackend,
336	const char *pszFilename, unsigned uImageFlags,
337	const char *pszComment, unsigned uOpenFlags,
338	PFNVMPROGRESS pfnProgress, void *pvUser);
339
340	/**
341	* Merges two images (not necessarily with direct parent/child relationship).
342	* As a side effect the source image and potentially the other images which
343	* are also merged to the destination are deleted from both the disk and the
344	* images in the HDD container.
345	*
346	* @returns VBox status code.
347	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
348	* @param pDisk Pointer to HDD container.
349	* @param nImageFrom Name of the image file to merge from.
350	* @param nImageTo Name of the image file to merge to.
351	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
352	* @param pvUser User argument for the progress callback.
353	*/
354	VBOXDDU_DECL(int) VDMerge(PVBOXHDD pDisk, unsigned nImageFrom,
355	unsigned nImageTo, PFNVMPROGRESS pfnProgress,
356	void *pvUser);
357
358	/**
359	* Copies an image from one HDD container to another.
360	* The copy is opened in the target HDD container.
361	* It is possible to convert between different image formats, because the
362	* backend for the destination may be different from the source.
363	* If both the source and destination reference the same HDD container,
364	* then the image is moved (by copying/deleting or renaming) to the new location.
365	* The source container is unchanged if the move operation fails, otherwise
366	* the image at the new location is opened in the same way as the old one was.
367	*
368	* @returns VBox status code.
369	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
370	* @param pDiskFrom Pointer to source HDD container.
371	* @param nImage Image number, counts from 0. 0 is always base image of container.
372	* @param pDiskTo Pointer to destination HDD container.
373	* @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source).
374	* @param pszFilename New name of the image (may be NULL if pDiskFrom == pDiskTo).
375	* @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
376	* @param cbSize New image size (0 means leave unchanged).
377	* @param pfnProgress Progress callback. Optional. NULL if not to be used.
378	* @param pvUser User argument for the progress callback.
379	*/
380	VBOXDDU_DECL(int) VDCopy(PVBOXHDD pDiskFrom, unsigned nImage, PVBOXHDD pDiskTo,
381	const char pszBackend, const char pszFilename,
382	bool fMoveByRename, uint64_t cbSize,
383	PFNVMPROGRESS pfnProgress, void *pvUser);
384
385	/**
386	* Closes the last opened image file in HDD container.
387	* If previous image file was opened in read-only mode (that is normal) and closing image
388	* was opened in read-write mode (the whole disk was in read-write mode) - the previous image
389	* will be reopened in read/write mode.
390	*
391	* @returns VBox status code.
392	* @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
393	* @param pDisk Pointer to HDD container.
394	* @param fDelete If true, delete the image from the host disk.
395	*/
396	VBOXDDU_DECL(int) VDClose(PVBOXHDD pDisk, bool fDelete);
397
398	/**
399	* Closes all opened image files in HDD container.
400	*
401	* @returns VBox status code.
402	* @param pDisk Pointer to HDD container.
403	*/
404	VBOXDDU_DECL(int) VDCloseAll(PVBOXHDD pDisk);
405
406	/**
407	* Read data from virtual HDD.
408	*
409	* @returns VBox status code.
410	* @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
411	* @param pDisk Pointer to HDD container.
412	* @param uOffset Offset of first reading byte from start of disk.
413	* @param pvBuf Pointer to buffer for reading data.
414	* @param cbRead Number of bytes to read.
415	*/
416	VBOXDDU_DECL(int) VDRead(PVBOXHDD pDisk, uint64_t uOffset, void *pvBuf, size_t cbRead);
417
418	/**
419	* Write data to virtual HDD.
420	*
421	* @returns VBox status code.
422	* @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
423	* @param pDisk Pointer to HDD container.
424	* @param uOffset Offset of first writing byte from start of disk.
425	* @param pvBuf Pointer to buffer for writing data.
426	* @param cbWrite Number of bytes to write.
427	*/
428	VBOXDDU_DECL(int) VDWrite(PVBOXHDD pDisk, uint64_t uOffset, const void *pvBuf, size_t cbWrite);
429
430	/**
431	* Make sure the on disk representation of a virtual HDD is up to date.
432	*
433	* @returns VBox status code.
434	* @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
435	* @param pDisk Pointer to HDD container.
436	*/
437	VBOXDDU_DECL(int) VDFlush(PVBOXHDD pDisk);
438
439	/**
440	* Get number of opened images in HDD container.
441	*
442	* @returns Number of opened images for HDD container. 0 if no images have been opened.
443	* @param pDisk Pointer to HDD container.
444	*/
445	VBOXDDU_DECL(unsigned) VDGetCount(PVBOXHDD pDisk);
446
447	/**
448	* Get read/write mode of HDD container.
449	*
450	* @returns Virtual disk ReadOnly status.
451	* @returns true if no image is opened in HDD container.
452	* @param pDisk Pointer to HDD container.
453	*/
454	VBOXDDU_DECL(bool) VDIsReadOnly(PVBOXHDD pDisk);
455
456	/**
457	* Get total capacity of an image in HDD container.
458	*
459	* @returns Virtual disk size in bytes.
460	* @returns 0 if image with specified number was not opened.
461	* @param pDisk Pointer to HDD container.
462	* @param nImage Image number, counts from 0. 0 is always base image of container.
463	*/
464	VBOXDDU_DECL(uint64_t) VDGetSize(PVBOXHDD pDisk, unsigned nImage);
465
466	/**
467	* Get total file size of an image in HDD container.
468	*
469	* @returns Virtual disk size in bytes.
470	* @returns 0 if image with specified number was not opened.
471	* @param pDisk Pointer to HDD container.
472	* @param nImage Image number, counts from 0. 0 is always base image of container.
473	*/
474	VBOXDDU_DECL(uint64_t) VDGetFileSize(PVBOXHDD pDisk, unsigned nImage);
475
476	/**
477	* Get virtual disk PCHS geometry of an image in HDD container.
478	*
479	* @returns VBox status code.
480	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
481	* @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the HDD container.
482	* @param pDisk Pointer to HDD container.
483	* @param nImage Image number, counts from 0. 0 is always base image of container.
484	* @param pPCHSGeometry Where to store PCHS geometry. Not NULL.
485	*/
486	VBOXDDU_DECL(int) VDGetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
487	PPDMMEDIAGEOMETRY pPCHSGeometry);
488
489	/**
490	* Store virtual disk PCHS geometry of an image in HDD container.
491	*
492	* @returns VBox status code.
493	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
494	* @param pDisk Pointer to HDD container.
495	* @param nImage Image number, counts from 0. 0 is always base image of container.
496	* @param pPCHSGeometry Where to load PCHS geometry from. Not NULL.
497	*/
498	VBOXDDU_DECL(int) VDSetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
499	PCPDMMEDIAGEOMETRY pPCHSGeometry);
500
501	/**
502	* Get virtual disk LCHS geometry of an image in HDD container.
503	*
504	* @returns VBox status code.
505	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
506	* @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the HDD container.
507	* @param pDisk Pointer to HDD container.
508	* @param nImage Image number, counts from 0. 0 is always base image of container.
509	* @param pLCHSGeometry Where to store LCHS geometry. Not NULL.
510	*/
511	VBOXDDU_DECL(int) VDGetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
512	PPDMMEDIAGEOMETRY pLCHSGeometry);
513
514	/**
515	* Store virtual disk LCHS geometry of an 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 pLCHSGeometry Where to load LCHS geometry from. Not NULL.
522	*/
523	VBOXDDU_DECL(int) VDSetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
524	PCPDMMEDIAGEOMETRY pLCHSGeometry);
525
526	/**
527	* Get version of image in HDD container.
528	*
529	* @returns VBox status code.
530	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
531	* @param pDisk Pointer to HDD container.
532	* @param nImage Image number, counts from 0. 0 is always base image of container.
533	* @param puVersion Where to store the image version.
534	*/
535	VBOXDDU_DECL(int) VDGetVersion(PVBOXHDD pDisk, unsigned nImage,
536	unsigned *puVersion);
537
538	/**
539	* Get type of image in HDD container.
540	*
541	* @returns VBox status code.
542	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
543	* @param pDisk Pointer to HDD container.
544	* @param nImage Image number, counts from 0. 0 is always base image of container.
545	* @param penmType Where to store the image type.
546	*/
547	VBOXDDU_DECL(int) VDGetImageType(PVBOXHDD pDisk, unsigned nImage,
548	PVDIMAGETYPE penmType);
549
550	/**
551	* Get flags of image in HDD container.
552	*
553	* @returns VBox status code.
554	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
555	* @param pDisk Pointer to HDD container.
556	* @param nImage Image number, counts from 0. 0 is always base image of container.
557	* @param puImageFlags Where to store the image flags.
558	*/
559	VBOXDDU_DECL(int) VDGetImageFlags(PVBOXHDD pDisk, unsigned nImage, unsigned *puImageFlags);
560
561	/**
562	* Get open flags of image in HDD container.
563	*
564	* @returns VBox status code.
565	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
566	* @param pDisk Pointer to HDD container.
567	* @param nImage Image number, counts from 0. 0 is always base image of container.
568	* @param puOpenFlags Where to store the image open flags.
569	*/
570	VBOXDDU_DECL(int) VDGetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
571	unsigned *puOpenFlags);
572
573	/**
574	* Set open flags of image in HDD container.
575	* This operation may cause file locking changes and/or files being reopened.
576	* Note that in case of unrecoverable error all images in HDD container will be closed.
577	*
578	* @returns VBox status code.
579	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
580	* @param pDisk Pointer to HDD container.
581	* @param nImage Image number, counts from 0. 0 is always base image of container.
582	* @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
583	*/
584	VBOXDDU_DECL(int) VDSetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
585	unsigned uOpenFlags);
586
587	/**
588	* Get base filename of image in HDD container. Some image formats use
589	* other filenames as well, so don't use this for anything but informational
590	* purposes.
591	*
592	* @returns VBox status code.
593	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
594	* @returns VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
595	* @param pDisk Pointer to HDD container.
596	* @param nImage Image number, counts from 0. 0 is always base image of container.
597	* @param pszFilename Where to store the image file name.
598	* @param cbFilename Size of buffer pszFilename points to.
599	*/
600	VBOXDDU_DECL(int) VDGetFilename(PVBOXHDD pDisk, unsigned nImage,
601	char *pszFilename, unsigned cbFilename);
602
603	/**
604	* Get the comment line of image in HDD container.
605	*
606	* @returns VBox status code.
607	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
608	* @returns VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
609	* @param pDisk Pointer to HDD container.
610	* @param nImage Image number, counts from 0. 0 is always base image of container.
611	* @param pszComment Where to store the comment string of image. NULL is ok.
612	* @param cbComment The size of pszComment buffer. 0 is ok.
613	*/
614	VBOXDDU_DECL(int) VDGetComment(PVBOXHDD pDisk, unsigned nImage,
615	char *pszComment, unsigned cbComment);
616
617	/**
618	* Changes the comment line of image in HDD container.
619	*
620	* @returns VBox status code.
621	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
622	* @param pDisk Pointer to HDD container.
623	* @param nImage Image number, counts from 0. 0 is always base image of container.
624	* @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment.
625	*/
626	VBOXDDU_DECL(int) VDSetComment(PVBOXHDD pDisk, unsigned nImage,
627	const char *pszComment);
628
629	/**
630	* Get UUID of image in HDD container.
631	*
632	* @returns VBox status code.
633	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
634	* @param pDisk Pointer to HDD container.
635	* @param nImage Image number, counts from 0. 0 is always base image of container.
636	* @param pUuid Where to store the image UUID.
637	*/
638	VBOXDDU_DECL(int) VDGetUuid(PVBOXHDD pDisk, unsigned nImage, PRTUUID pUuid);
639
640	/**
641	* Set the image's UUID. Should not be used by normal applications.
642	*
643	* @returns VBox status code.
644	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
645	* @param pDisk Pointer to HDD container.
646	* @param nImage Image number, counts from 0. 0 is always base image of container.
647	* @param pUuid New UUID of the image. If NULL, a new UUID is created.
648	*/
649	VBOXDDU_DECL(int) VDSetUuid(PVBOXHDD pDisk, unsigned nImage, PCRTUUID pUuid);
650
651	/**
652	* Get last modification UUID of image in HDD container.
653	*
654	* @returns VBox status code.
655	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
656	* @param pDisk Pointer to HDD container.
657	* @param nImage Image number, counts from 0. 0 is always base image of container.
658	* @param pUuid Where to store the image modification UUID.
659	*/
660	VBOXDDU_DECL(int) VDGetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
661	PRTUUID pUuid);
662
663	/**
664	* Set the image's last modification UUID. Should not be used by normal applications.
665	*
666	* @returns VBox status code.
667	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
668	* @param pDisk Pointer to HDD container.
669	* @param nImage Image number, counts from 0. 0 is always base image of container.
670	* @param pUuid New modification UUID of the image. If NULL, a new UUID is created.
671	*/
672	VBOXDDU_DECL(int) VDSetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
673	PCRTUUID pUuid);
674
675	/**
676	* Get parent UUID of image in HDD container.
677	*
678	* @returns VBox status code.
679	* @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
680	* @param pDisk Pointer to HDD container.
681	* @param nImage Image number, counts from 0. 0 is always base image of the container.
682	* @param pUuid Where to store the parent image UUID.
683	*/
684	VBOXDDU_DECL(int) VDGetParentUuid(PVBOXHDD pDisk, unsigned nImage,
685	PRTUUID pUuid);
686
687	/**
688	* Set the image's parent UUID. Should not be used by normal applications.
689	*
690	* @returns VBox status code.
691	* @param pDisk Pointer to HDD container.
692	* @param nImage Image number, counts from 0. 0 is always base image of container.
693	* @param pUuid New parent UUID of the image. If NULL, a new UUID is created.
694	*/
695	VBOXDDU_DECL(int) VDSetParentUuid(PVBOXHDD pDisk, unsigned nImage,
696	PCRTUUID pUuid);
697
698
699	/**
700	* Debug helper - dumps all opened images in HDD container into the log file.
701	*
702	* @param pDisk Pointer to HDD container.
703	*/
704	VBOXDDU_DECL(void) VDDumpImages(PVBOXHDD pDisk);
705
706	__END_DECLS
707
708	/** @} */
709
710	#endif

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

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

Download in other formats: