VBoxHDD-new.h@ 10518

Last change on this file since 10518 was 10467, checked in by vboxsync, 16 years ago
Provide CAP_FILE flag for backends operating on files.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 29.8 KB

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

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

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

Download in other formats: