VirtualBox

source: vbox/trunk/src/VBox/Main/include/MediumImpl.h@ 33451

Last change on this file since 33451 was 33339, checked in by vboxsync, 14 years ago

Main/Medium: more parameter clarifications
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 14.8 KB
Line 
1/* $Id: MediumImpl.h 33339 2010-10-22 10:53:07Z vboxsync $ */
2
3/** @file
4 *
5 * VirtualBox COM class implementation
6 */
7
8/*
9 * Copyright (C) 2008-2010 Oracle Corporation
10 *
11 * This file is part of VirtualBox Open Source Edition (OSE), as
12 * available from http://www.virtualbox.org. This file is free software;
13 * you can redistribute it and/or modify it under the terms of the GNU
14 * General Public License (GPL) as published by the Free Software
15 * Foundation, in version 2 as it comes in the "COPYING" file of the
16 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18 */
19
20#ifndef ____H_MEDIUMIMPL
21#define ____H_MEDIUMIMPL
22
23#include <VBox/VBoxHDD.h>
24
25#include "VirtualBoxBase.h"
26#include "MediumLock.h"
27
28class Progress;
29class MediumFormat;
30
31namespace settings
32{
33 struct Medium;
34}
35
36////////////////////////////////////////////////////////////////////////////////
37
38/**
39 * Medium component class for all media types.
40 */
41class ATL_NO_VTABLE Medium :
42 public VirtualBoxBase,
43 VBOX_SCRIPTABLE_IMPL(IMedium)
44{
45public:
46 VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(Medium, IMedium)
47
48 DECLARE_NOT_AGGREGATABLE(Medium)
49
50 DECLARE_PROTECT_FINAL_CONSTRUCT()
51
52 BEGIN_COM_MAP(Medium)
53 COM_INTERFACE_ENTRY(ISupportErrorInfo)
54 COM_INTERFACE_ENTRY(IMedium)
55 COM_INTERFACE_ENTRY(IDispatch)
56 END_COM_MAP()
57
58 DECLARE_EMPTY_CTOR_DTOR(Medium)
59
60 HRESULT FinalConstruct();
61 void FinalRelease();
62
63 enum HDDOpenMode { OpenReadWrite, OpenReadOnly };
64 // have to use a special enum for the overloaded init() below;
65 // can't use AccessMode_T from XIDL because that's mapped to an int
66 // and would be ambiguous
67
68 // public initializer/uninitializer for internal purposes only
69
70 // initializer to create empty medium (VirtualBox::CreateHardDisk())
71 HRESULT init(VirtualBox *aVirtualBox,
72 const Utf8Str &aFormat,
73 const Utf8Str &aLocation,
74 const Guid &uuidMachineRegistry,
75 bool *pfNeedsGlobalSaveSettings);
76
77 // initializer for opening existing media
78 // (VirtualBox::OpenMedium(); Machine::AttachDevice())
79 HRESULT init(VirtualBox *aVirtualBox,
80 const Utf8Str &aLocation,
81 HDDOpenMode enOpenMode,
82 DeviceType_T aDeviceType);
83
84 // initializer used when loading settings
85 HRESULT init(VirtualBox *aVirtualBox,
86 Medium *aParent,
87 DeviceType_T aDeviceType,
88 const Guid &uuidMachineRegistry,
89 const settings::Medium &data,
90 const Utf8Str &strMachineFolder);
91
92 // initializer for host floppy/DVD
93 HRESULT init(VirtualBox *aVirtualBox,
94 DeviceType_T aDeviceType,
95 const Utf8Str &aLocation,
96 const Utf8Str &aDescription = Utf8Str::Empty);
97
98 void uninit();
99
100 void deparent();
101 void setParent(const ComObjPtr<Medium> &pParent);
102
103 // IMedium properties
104 STDMETHOD(COMGETTER(Id))(BSTR *aId);
105 STDMETHOD(COMGETTER(Description))(BSTR *aDescription);
106 STDMETHOD(COMSETTER(Description))(IN_BSTR aDescription);
107 STDMETHOD(COMGETTER(State))(MediumState_T *aState);
108 STDMETHOD(COMGETTER(Variant))(MediumVariant_T *aVariant);
109 STDMETHOD(COMGETTER(Location))(BSTR *aLocation);
110 STDMETHOD(COMSETTER(Location))(IN_BSTR aLocation);
111 STDMETHOD(COMGETTER(Name))(BSTR *aName);
112 STDMETHOD(COMGETTER(DeviceType))(DeviceType_T *aDeviceType);
113 STDMETHOD(COMGETTER(HostDrive))(BOOL *aHostDrive);
114 STDMETHOD(COMGETTER(Size))(LONG64 *aSize);
115 STDMETHOD(COMGETTER(Format))(BSTR *aFormat);
116 STDMETHOD(COMGETTER(MediumFormat))(IMediumFormat **aMediumFormat);
117 STDMETHOD(COMGETTER(Type))(MediumType_T *aType);
118 STDMETHOD(COMSETTER(Type))(MediumType_T aType);
119 STDMETHOD(COMGETTER(Parent))(IMedium **aParent);
120 STDMETHOD(COMGETTER(Children))(ComSafeArrayOut(IMedium *, aChildren));
121 STDMETHOD(COMGETTER(Base))(IMedium **aBase);
122 STDMETHOD(COMGETTER(ReadOnly))(BOOL *aReadOnly);
123 STDMETHOD(COMGETTER(LogicalSize))(LONG64 *aLogicalSize);
124 STDMETHOD(COMGETTER(AutoReset))(BOOL *aAutoReset);
125 STDMETHOD(COMSETTER(AutoReset))(BOOL aAutoReset);
126 STDMETHOD(COMGETTER(LastAccessError))(BSTR *aLastAccessError);
127 STDMETHOD(COMGETTER(MachineIds))(ComSafeArrayOut(BSTR, aMachineIds));
128
129 // IMedium methods
130 STDMETHOD(SetIDs)(BOOL aSetImageId, IN_BSTR aImageId,
131 BOOL aSetParentId, IN_BSTR aParentId);
132 STDMETHOD(RefreshState)(MediumState_T *aState);
133 STDMETHOD(GetSnapshotIds)(IN_BSTR aMachineId,
134 ComSafeArrayOut(BSTR, aSnapshotIds));
135 STDMETHOD(LockRead)(MediumState_T *aState);
136 STDMETHOD(UnlockRead)(MediumState_T *aState);
137 STDMETHOD(LockWrite)(MediumState_T *aState);
138 STDMETHOD(UnlockWrite)(MediumState_T *aState);
139 STDMETHOD(Close)();
140 STDMETHOD(GetProperty)(IN_BSTR aName, BSTR *aValue);
141 STDMETHOD(SetProperty)(IN_BSTR aName, IN_BSTR aValue);
142 STDMETHOD(GetProperties)(IN_BSTR aNames,
143 ComSafeArrayOut(BSTR, aReturnNames),
144 ComSafeArrayOut(BSTR, aReturnValues));
145 STDMETHOD(SetProperties)(ComSafeArrayIn(IN_BSTR, aNames),
146 ComSafeArrayIn(IN_BSTR, aValues));
147 STDMETHOD(CreateBaseStorage)(LONG64 aLogicalSize,
148 MediumVariant_T aVariant,
149 IProgress **aProgress);
150 STDMETHOD(DeleteStorage)(IProgress **aProgress);
151 STDMETHOD(CreateDiffStorage)(IMedium *aTarget,
152 MediumVariant_T aVariant,
153 IProgress **aProgress);
154 STDMETHOD(MergeTo)(IMedium *aTarget, IProgress **aProgress);
155 STDMETHOD(CloneTo)(IMedium *aTarget, MediumVariant_T aVariant,
156 IMedium *aParent, IProgress **aProgress);
157 STDMETHOD(Compact)(IProgress **aProgress);
158 STDMETHOD(Resize)(LONG64 aLogicalSize, IProgress **aProgress);
159 STDMETHOD(Reset)(IProgress **aProgress);
160
161 // unsafe methods for internal purposes only (ensure there is
162 // a caller and a read lock before calling them!)
163 const ComObjPtr<Medium>& getParent() const;
164 const MediaList& getChildren() const;
165
166 const Guid& getId() const;
167 MediumState_T getState() const;
168 MediumVariant_T getVariant() const;
169 bool isHostDrive() const;
170 const Utf8Str& getLocationFull() const;
171 const Utf8Str& getFormat() const;
172 const ComObjPtr<MediumFormat> & getMediumFormat() const;
173 uint64_t getSize() const;
174 DeviceType_T getDeviceType() const;
175 MediumType_T getType() const;
176 Utf8Str getName();
177
178 bool addRegistry(const Guid& id,
179 bool *pfNeedsSaveSettings);
180 bool isInRegistry(const Guid& id);
181 const Guid& getFirstRegistryMachineId() const;
182
183 HRESULT addBackReference(const Guid &aMachineId,
184 const Guid &aSnapshotId = Guid::Empty);
185 HRESULT removeBackReference(const Guid &aMachineId,
186 const Guid &aSnapshotId = Guid::Empty);
187
188 const Guid* getFirstMachineBackrefId() const;
189 const Guid* getFirstMachineBackrefSnapshotId() const;
190
191#ifdef DEBUG
192 void dumpBackRefs();
193#endif
194
195 HRESULT updatePath(const Utf8Str &strOldPath, const Utf8Str &strNewPath);
196
197 ComObjPtr<Medium> getBase(uint32_t *aLevel = NULL);
198
199 bool isReadOnly();
200
201 HRESULT saveSettings(settings::Medium &data,
202 const Utf8Str &strHardDiskFolder);
203
204 HRESULT createMediumLockList(bool fFailIfInaccessible,
205 bool fMediumLockWrite,
206 Medium *pToBeParent,
207 MediumLockList &mediumLockList);
208
209 HRESULT createDiffStorage(ComObjPtr<Medium> &aTarget,
210 MediumVariant_T aVariant,
211 MediumLockList *pMediumLockList,
212 ComObjPtr<Progress> *aProgress,
213 bool aWait,
214 bool *pfNeedsGlobalSaveSettings);
215
216 HRESULT close(bool *pfNeedsGlobalSaveSettings, AutoCaller &autoCaller);
217 HRESULT deleteStorage(ComObjPtr<Progress> *aProgress, bool aWait, bool *pfNeedsGlobalSaveSettings);
218 HRESULT markForDeletion();
219 HRESULT unmarkForDeletion();
220 HRESULT markLockedForDeletion();
221 HRESULT unmarkLockedForDeletion();
222
223 HRESULT prepareMergeTo(const ComObjPtr<Medium> &pTarget,
224 const Guid *aMachineId,
225 const Guid *aSnapshotId,
226 bool fLockMedia,
227 bool &fMergeForward,
228 ComObjPtr<Medium> &pParentForTarget,
229 MediaList &aChildrenToReparent,
230 MediumLockList * &aMediumLockList);
231 HRESULT mergeTo(const ComObjPtr<Medium> &pTarget,
232 bool fMergeForward,
233 const ComObjPtr<Medium> &pParentForTarget,
234 const MediaList &aChildrenToReparent,
235 MediumLockList *aMediumLockList,
236 ComObjPtr<Progress> *aProgress,
237 bool aWait,
238 bool *pfNeedsGlobalSaveSettings);
239 void cancelMergeTo(const MediaList &aChildrenToReparent,
240 MediumLockList *aMediumLockList);
241
242 HRESULT fixParentUuidOfChildren(const MediaList &childrenToReparent);
243
244 /**
245 * Used by IAppliance to export disk images.
246 *
247 * @param aFilename Filename to create (UTF8).
248 * @param aFormat Medium format for creating @a aFilename.
249 * @param aVariant Which exact image format variant to use
250 * for the destination image.
251 * @param aVDImageIOCallbacks Pointer to the callback table for a
252 * VDINTERFACEIO interface. May be NULL.
253 * @param aVDImageIOUser Opaque data for the callbacks.
254 * @param aProgress Progress object to use.
255 * @return
256 * @note The source format is defined by the Medium instance.
257 */
258 HRESULT exportFile(const char *aFilename,
259 const ComObjPtr<MediumFormat> &aFormat,
260 MediumVariant_T aVariant,
261 void *aVDImageIOCallbacks, void *aVDImageIOUser,
262 const ComObjPtr<Progress> &aProgress);
263 /**
264 * Used by IAppliance to import disk images.
265 *
266 * @param aFilename Filename to read (UTF8).
267 * @param aFormat Medium format for reading @a aFilename.
268 * @param aVariant Which exact image format variant to use
269 * for the destination image.
270 * @param aVDImageIOCallbacks Pointer to the callback table for a
271 * VDINTERFACEIO interface. May be NULL.
272 * @param aVDImageIOUser Opaque data for the callbacks.
273 * @param aParent Parent medium. May be NULL.
274 * @param aProgress Progress object to use.
275 * @return
276 * @note The destination format is defined by the Medium instance.
277 */
278 HRESULT importFile(const char *aFilename,
279 const ComObjPtr<MediumFormat> &aFormat,
280 MediumVariant_T aVariant,
281 void *aVDImageIOCallbacks, void *aVDImageIOUser,
282 const ComObjPtr<Medium> &aParent,
283 const ComObjPtr<Progress> &aProgress);
284
285 /** Returns a preferred format for a differencing hard disk. */
286 Utf8Str getPreferredDiffFormat();
287
288private:
289
290 HRESULT queryInfo(bool fSetImageId, bool fSetParentId);
291
292 HRESULT canClose();
293 HRESULT unregisterWithVirtualBox(bool *pfNeedsGlobalSaveSettings);
294
295 HRESULT setStateError();
296
297 HRESULT setLocation(const Utf8Str &aLocation, const Utf8Str &aFormat = Utf8Str::Empty);
298 HRESULT setFormat(const Utf8Str &aFormat);
299
300 Utf8Str vdError(int aVRC);
301
302 static DECLCALLBACK(void) vdErrorCall(void *pvUser, int rc, RT_SRC_POS_DECL,
303 const char *pszFormat, va_list va);
304
305 static DECLCALLBACK(bool) vdConfigAreKeysValid(void *pvUser,
306 const char *pszzValid);
307 static DECLCALLBACK(int) vdConfigQuerySize(void *pvUser, const char *pszName,
308 size_t *pcbValue);
309 static DECLCALLBACK(int) vdConfigQuery(void *pvUser, const char *pszName,
310 char *pszValue, size_t cchValue);
311
312 static DECLCALLBACK(int) vdTcpSocketCreate(uint32_t fFlags, PVDSOCKET pSock);
313 static DECLCALLBACK(int) vdTcpSocketDestroy(VDSOCKET Sock);
314 static DECLCALLBACK(int) vdTcpClientConnect(VDSOCKET Sock, const char *pszAddress, uint32_t uPort);
315 static DECLCALLBACK(int) vdTcpClientClose(VDSOCKET Sock);
316 static DECLCALLBACK(bool) vdTcpIsClientConnected(VDSOCKET Sock);
317 static DECLCALLBACK(int) vdTcpSelectOne(VDSOCKET Sock, RTMSINTERVAL cMillies);
318 static DECLCALLBACK(int) vdTcpRead(VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead);
319 static DECLCALLBACK(int) vdTcpWrite(VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer);
320 static DECLCALLBACK(int) vdTcpSgWrite(VDSOCKET Sock, PCRTSGBUF pSgBuf);
321 static DECLCALLBACK(int) vdTcpFlush(VDSOCKET Sock);
322 static DECLCALLBACK(int) vdTcpSetSendCoalescing(VDSOCKET Sock, bool fEnable);
323 static DECLCALLBACK(int) vdTcpGetLocalAddress(VDSOCKET Sock, PRTNETADDR pAddr);
324 static DECLCALLBACK(int) vdTcpGetPeerAddress(VDSOCKET Sock, PRTNETADDR pAddr);
325
326 class Task;
327 class CreateBaseTask;
328 class CreateDiffTask;
329 class CloneTask;
330 class CompactTask;
331 class ResizeTask;
332 class ResetTask;
333 class DeleteTask;
334 class MergeTask;
335 class ExportTask;
336 class ImportTask;
337 friend class Task;
338 friend class CreateBaseTask;
339 friend class CreateDiffTask;
340 friend class CloneTask;
341 friend class CompactTask;
342 friend class ResizeTask;
343 friend class ResetTask;
344 friend class DeleteTask;
345 friend class MergeTask;
346 friend class ExportTask;
347 friend class ImportTask;
348
349 HRESULT startThread(Medium::Task *pTask);
350 HRESULT runNow(Medium::Task *pTask, bool *pfNeedsGlobalSaveSettings);
351
352 HRESULT taskCreateBaseHandler(Medium::CreateBaseTask &task);
353 HRESULT taskCreateDiffHandler(Medium::CreateDiffTask &task);
354 HRESULT taskMergeHandler(Medium::MergeTask &task);
355 HRESULT taskCloneHandler(Medium::CloneTask &task);
356 HRESULT taskDeleteHandler(Medium::DeleteTask &task);
357 HRESULT taskResetHandler(Medium::ResetTask &task);
358 HRESULT taskCompactHandler(Medium::CompactTask &task);
359 HRESULT taskResizeHandler(Medium::ResizeTask &task);
360 HRESULT taskExportHandler(Medium::ExportTask &task);
361 HRESULT taskImportHandler(Medium::ImportTask &task);
362
363 struct Data; // opaque data struct, defined in MediumImpl.cpp
364 Data *m;
365};
366
367#endif /* ____H_MEDIUMIMPL */
368
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