VirtualBox

source: vbox/trunk/include/VBox/vd-cache-backend.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 13.7 KB
Line 
1/** @file
2 * Internal hard disk format support API for VBoxHDD cache images.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef VBOX_INCLUDED_vd_cache_backend_h
37#define VBOX_INCLUDED_vd_cache_backend_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <VBox/vd.h>
43#include <VBox/vd-common.h>
44#include <VBox/vd-ifs-internal.h>
45
46/**
47 * Cache format backend interface used by VBox HDD Container implementation.
48 */
49typedef struct VDCACHEBACKEND
50{
51 /** Structure version. VD_CACHEBACKEND_VERSION defines the current version. */
52 uint32_t u32Version;
53 /** The name of the backend (constant string). */
54 const char *pszBackendName;
55 /** The capabilities of the backend. */
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 * Probes the given image.
75 *
76 * @returns VBox status code.
77 * @param pszFilename Name of the image file.
78 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
79 * @param pVDIfsImage Pointer to the per-image VD interface list.
80 */
81 DECLR3CALLBACKMEMBER(int, pfnProbe, (const char *pszFilename, PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage));
82
83 /**
84 * Open a cache image.
85 *
86 * @returns VBox status code.
87 * @param pszFilename Name of the image file to open. Guaranteed to be available and
88 * unchanged during the lifetime of this image.
89 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
90 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
91 * @param pVDIfsImage Pointer to the per-image VD interface list.
92 * @param ppBackendData Opaque state data for this image.
93 */
94 DECLR3CALLBACKMEMBER(int, pfnOpen, (const char *pszFilename, unsigned uOpenFlags,
95 PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
96 void **ppBackendData));
97
98 /**
99 * Create a cache image.
100 *
101 * @returns VBox status code.
102 * @param pszFilename Name of the image file to create. Guaranteed to be available and
103 * unchanged during the lifetime of this image.
104 * @param cbSize Image size in bytes.
105 * @param uImageFlags Flags specifying special image features.
106 * @param pszComment Pointer to image comment. NULL is ok.
107 * @param pUuid New UUID of the image. Not NULL.
108 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
109 * @param uPercentStart Starting value for progress percentage.
110 * @param uPercentSpan Span for varying progress percentage.
111 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
112 * @param pVDIfsImage Pointer to the per-image VD interface list.
113 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
114 * @param ppBackendData Opaque state data for this image.
115 */
116 DECLR3CALLBACKMEMBER(int, pfnCreate, (const char *pszFilename, uint64_t cbSize,
117 unsigned uImageFlags, const char *pszComment,
118 PCRTUUID pUuid, unsigned uOpenFlags,
119 unsigned uPercentStart, unsigned uPercentSpan,
120 PVDINTERFACE pVDIfsDisk,
121 PVDINTERFACE pVDIfsImage,
122 PVDINTERFACE pVDIfsOperation,
123 void **ppBackendData));
124
125 /**
126 * Close a cache image.
127 *
128 * @returns VBox status code.
129 * @param pBackendData Opaque state data for this image.
130 * @param fDelete If true, delete the image from the host disk.
131 */
132 DECLR3CALLBACKMEMBER(int, pfnClose, (void *pBackendData, bool fDelete));
133
134 /**
135 * Start a read request.
136 *
137 * @returns VBox status code.
138 * @param pBackendData Opaque state data for this image.
139 * @param uOffset The offset of the virtual disk to read from.
140 * @param cbToRead How many bytes to read.
141 * @param pIoCtx I/O context associated with this request.
142 * @param pcbActuallyRead Pointer to returned number of bytes read.
143 */
144 DECLR3CALLBACKMEMBER(int, pfnRead, (void *pBackendData, uint64_t uOffset, size_t cbToRead,
145 PVDIOCTX pIoCtx, size_t *pcbActuallyRead));
146
147 /**
148 * Start a write request.
149 *
150 * @returns VBox status code.
151 * @param pBackendData Opaque state data for this image.
152 * @param uOffset The offset of the virtual disk to write to.
153 * @param cbToWrite How many bytes to write.
154 * @param pIoCtx I/O context associated with this request.
155 * @param pcbWriteProcess Pointer to returned number of bytes that could
156 * be processed. In case the function returned
157 * VERR_VD_BLOCK_FREE this is the number of bytes
158 * that could be written in a full block write,
159 * when prefixed/postfixed by the appropriate
160 * amount of (previously read) padding data.
161 */
162 DECLR3CALLBACKMEMBER(int, pfnWrite, (void *pBackendData, uint64_t uOffset, size_t cbToWrite,
163 PVDIOCTX pIoCtx, size_t *pcbWriteProcess));
164
165 /**
166 * Flush data to disk.
167 *
168 * @returns VBox status code.
169 * @param pBackendData Opaque state data for this image.
170 * @param pIoCtx I/O context associated with this request.
171 */
172 DECLR3CALLBACKMEMBER(int, pfnFlush, (void *pBackendData, PVDIOCTX pIoCtx));
173
174 /**
175 * Discards the given amount of bytes from the cache.
176 *
177 * @returns VBox status code.
178 * @retval VERR_VD_DISCARD_ALIGNMENT_NOT_MET if the range doesn't meet the required alignment
179 * for the discard.
180 * @param pBackendData Opaque state data for this image.
181 * @param pIoCtx I/O context associated with this request.
182 * @param uOffset The offset of the first byte to discard.
183 * @param cbDiscard How many bytes to discard.
184 */
185 DECLR3CALLBACKMEMBER(int, pfnDiscard, (void *pBackendData, PVDIOCTX pIoCtx,
186 uint64_t uOffset, size_t cbDiscard,
187 size_t *pcbPreAllocated,
188 size_t *pcbPostAllocated,
189 size_t *pcbActuallyDiscarded,
190 void **ppbmAllocationBitmap,
191 unsigned fDiscard));
192
193 /**
194 * Get the version of a cache image.
195 *
196 * @returns version of cache image.
197 * @param pBackendData Opaque state data for this image.
198 */
199 DECLR3CALLBACKMEMBER(unsigned, pfnGetVersion, (void *pBackendData));
200
201 /**
202 * Get the capacity of a cache image.
203 *
204 * @returns size of cache image in bytes.
205 * @param pBackendData Opaque state data for this image.
206 */
207 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize, (void *pBackendData));
208
209 /**
210 * Get the file size of a cache image.
211 *
212 * @returns size of cache image in bytes.
213 * @param pBackendData Opaque state data for this image.
214 */
215 DECLR3CALLBACKMEMBER(uint64_t, pfnGetFileSize, (void *pBackendData));
216
217 /**
218 * Get the image flags of a cache image.
219 *
220 * @returns image flags of cache image.
221 * @param pBackendData Opaque state data for this image.
222 */
223 DECLR3CALLBACKMEMBER(unsigned, pfnGetImageFlags, (void *pBackendData));
224
225 /**
226 * Get the open flags of a cache image.
227 *
228 * @returns open flags of cache image.
229 * @param pBackendData Opaque state data for this image.
230 */
231 DECLR3CALLBACKMEMBER(unsigned, pfnGetOpenFlags, (void *pBackendData));
232
233 /**
234 * Set the open flags of a cache image. May cause the image to be locked
235 * in a different mode or be reopened (which can fail).
236 *
237 * @returns VBox status code.
238 * @param pBackendData Opaque state data for this image.
239 * @param uOpenFlags New open flags for this image.
240 */
241 DECLR3CALLBACKMEMBER(int, pfnSetOpenFlags, (void *pBackendData, unsigned uOpenFlags));
242
243 /**
244 * Get comment of a cache image.
245 *
246 * @returns VBox status code.
247 * @param pBackendData Opaque state data for this image.
248 * @param pszComment Where to store the comment.
249 * @param cbComment Size of the comment buffer.
250 */
251 DECLR3CALLBACKMEMBER(int, pfnGetComment, (void *pBackendData, char *pszComment, size_t cbComment));
252
253 /**
254 * Set comment of a cache image.
255 *
256 * @returns VBox status code.
257 * @param pBackendData Opaque state data for this image.
258 * @param pszComment Where to get the comment from. NULL resets comment.
259 * The comment is silently truncated if the image format
260 * limit is exceeded.
261 */
262 DECLR3CALLBACKMEMBER(int, pfnSetComment, (void *pBackendData, const char *pszComment));
263
264 /**
265 * Get UUID of a cache image.
266 *
267 * @returns VBox status code.
268 * @param pBackendData Opaque state data for this image.
269 * @param pUuid Where to store the image UUID.
270 */
271 DECLR3CALLBACKMEMBER(int, pfnGetUuid, (void *pBackendData, PRTUUID pUuid));
272
273 /**
274 * Set UUID of a cache image.
275 *
276 * @returns VBox status code.
277 * @param pBackendData Opaque state data for this image.
278 * @param pUuid Where to get the image UUID from.
279 */
280 DECLR3CALLBACKMEMBER(int, pfnSetUuid, (void *pBackendData, PCRTUUID pUuid));
281
282 /**
283 * Get last modification UUID of a cache image.
284 *
285 * @returns VBox status code.
286 * @param pBackendData Opaque state data for this image.
287 * @param pUuid Where to store the image modification UUID.
288 */
289 DECLR3CALLBACKMEMBER(int, pfnGetModificationUuid, (void *pBackendData, PRTUUID pUuid));
290
291 /**
292 * Set last modification UUID of a cache image.
293 *
294 * @returns VBox status code.
295 * @param pBackendData Opaque state data for this image.
296 * @param pUuid Where to get the image modification UUID from.
297 */
298 DECLR3CALLBACKMEMBER(int, pfnSetModificationUuid, (void *pBackendData, PCRTUUID pUuid));
299
300 /**
301 * Dump information about a cache image.
302 *
303 * @param pBackendData Opaque state data for this image.
304 */
305 DECLR3CALLBACKMEMBER(void, pfnDump, (void *pBackendData));
306
307 /** Returns a human readable hard disk location string given a
308 * set of hard disk configuration keys. The returned string is an
309 * equivalent of the full file path for image-based hard disks.
310 * Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */
311 DECLR3CALLBACKMEMBER(int, pfnComposeLocation, (PVDINTERFACE pConfig, char **pszLocation));
312
313 /** Returns a human readable hard disk name string given a
314 * set of hard disk configuration keys. The returned string is an
315 * equivalent of the file name part in the full file path for
316 * image-based hard disks. Mandatory for backends with no
317 * VD_CAP_FILE and NULL otherwise. */
318 DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
319
320 /** Initialization safty marker. */
321 uint32_t u32VersionEnd;
322
323} VDCACHEBACKEND;
324/** Pointer to VD cache backend. */
325typedef VDCACHEBACKEND *PVDCACHEBACKEND;
326/** Constant pointer to VD backend. */
327typedef const VDCACHEBACKEND *PCVDCACHEBACKEND;
328
329/** The current version of the VDCACHEBACKEND structure. */
330#define VD_CACHEBACKEND_VERSION VD_VERSION_MAKE(0xff03, 1, 0)
331
332#endif /* !VBOX_INCLUDED_vd_cache_backend_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette