VirtualBox

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

Last change on this file since 23235 was 23235, checked in by vboxsync, 15 years ago

API: fix opening new dvd/floppy images, introduce fallback format
  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Revision Author Id
File size: 12.6 KB
Line 
1/* $Id: MediumImpl.h 23235 2009-09-22 18:15:56Z vboxsync $ */
2/** @file
3 *
4 * VirtualBox COM class implementation
5 */
6
7/*
8 * Copyright (C) 2008-2009 Sun Microsystems, Inc.
9 *
10 * This file is part of VirtualBox Open Source Edition (OSE), as
11 * available from http://www.virtualbox.org. This file is free software;
12 * you can redistribute it and/or modify it under the terms of the GNU
13 * General Public License (GPL) as published by the Free Software
14 * Foundation, in version 2 as it comes in the "COPYING" file of the
15 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
16 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
17 *
18 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
19 * Clara, CA 95054 USA or visit http://www.sun.com if you need
20 * additional information or have any questions.
21 */
22
23#ifndef ____H_MEDIUMIMPL
24#define ____H_MEDIUMIMPL
25
26#include "VirtualBoxBase.h"
27
28#include <VBox/com/SupportErrorInfo.h>
29
30#include <VBox/VBoxHDD.h>
31
32class VirtualBox;
33class Progress;
34
35namespace settings
36{
37 struct Medium;
38}
39
40////////////////////////////////////////////////////////////////////////////////
41
42/**
43 * Medium component class for all media types.
44 */
45class ATL_NO_VTABLE Medium :
46 public VirtualBoxBaseWithTypedChildren<Medium>,
47 public com::SupportErrorInfoImpl<Medium, IMedium>,
48 public VirtualBoxSupportTranslation<Medium>,
49 VBOX_SCRIPTABLE_IMPL(IMedium)
50{
51public:
52
53 typedef VirtualBoxBaseWithTypedChildren<Medium>::DependentChildren List;
54
55 class MergeChain;
56 class ImageChain;
57
58 VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(Medium)
59
60 DECLARE_NOT_AGGREGATABLE(Medium)
61
62 DECLARE_PROTECT_FINAL_CONSTRUCT()
63
64 BEGIN_COM_MAP(Medium)
65 COM_INTERFACE_ENTRY(ISupportErrorInfo)
66 COM_INTERFACE_ENTRY(IMedium)
67 END_COM_MAP()
68
69 DECLARE_EMPTY_CTOR_DTOR(Medium)
70
71 enum HDDOpenMode { OpenReadWrite, OpenReadOnly };
72 // have to use a special enum for the overloaded init() below;
73 // can't use AccessMode_T from XIDL because that's mapped to an int
74 // and would be ambiguous
75
76 // public initializer/uninitializer for internal purposes only
77 HRESULT init(VirtualBox *aVirtualBox,
78 CBSTR aFormat,
79 CBSTR aLocation);
80 HRESULT init(VirtualBox *aVirtualBox,
81 CBSTR aLocation,
82 HDDOpenMode enOpenMode,
83 DeviceType_T aDeviceType,
84 BOOL aSetImageId,
85 const Guid &aImageId,
86 BOOL aSetParentId,
87 const Guid &aParentId);
88 // initializer used when loading settings
89 HRESULT init(VirtualBox *aVirtualBox,
90 Medium *aParent,
91 DeviceType_T aType,
92 const settings::Medium &data);
93 // initializer for host floppy/DVD
94 HRESULT init(VirtualBox *aVirtualBox,
95 DeviceType_T aType,
96 CBSTR aLocation,
97 CBSTR aDescription = NULL);
98 void uninit();
99
100 // IMedium properties
101 STDMETHOD(COMGETTER(Id))(BSTR *aId);
102 STDMETHOD(COMGETTER(Description))(BSTR *aDescription);
103 STDMETHOD(COMSETTER(Description))(IN_BSTR aDescription);
104 STDMETHOD(COMGETTER(State))(MediumState_T *aState);
105 STDMETHOD(COMGETTER(Location))(BSTR *aLocation);
106 STDMETHOD(COMSETTER(Location))(IN_BSTR aLocation);
107 STDMETHOD(COMGETTER(Name))(BSTR *aName);
108 STDMETHOD(COMGETTER(HostDrive))(BOOL *aHostDrive);
109 STDMETHOD(COMGETTER(Size))(ULONG64 *aSize);
110 STDMETHOD(COMGETTER(Format))(BSTR *aFormat);
111 STDMETHOD(COMGETTER(Type))(MediumType_T *aType);
112 STDMETHOD(COMSETTER(Type))(MediumType_T aType);
113 STDMETHOD(COMGETTER(Parent))(IMedium **aParent);
114 STDMETHOD(COMGETTER(Children))(ComSafeArrayOut(IMedium *, aChildren));
115 STDMETHOD(COMGETTER(Base))(IMedium **aBase);
116 STDMETHOD(COMGETTER(ReadOnly))(BOOL *aReadOnly);
117 STDMETHOD(COMGETTER(LogicalSize))(ULONG64 *aLogicalSize);
118 STDMETHOD(COMGETTER(AutoReset))(BOOL *aAutoReset);
119 STDMETHOD(COMSETTER(AutoReset))(BOOL aAutoReset);
120 STDMETHOD(COMGETTER(LastAccessError))(BSTR *aLastAccessError);
121 STDMETHOD(COMGETTER(MachineIds))(ComSafeArrayOut(BSTR, aMachineIds));
122
123 // IMedium methods
124 STDMETHOD(GetSnapshotIds)(IN_BSTR aMachineId,
125 ComSafeArrayOut(BSTR, aSnapshotIds));
126 STDMETHOD(LockRead)(MediumState_T *aState);
127 STDMETHOD(UnlockRead)(MediumState_T *aState);
128 STDMETHOD(LockWrite)(MediumState_T *aState);
129 STDMETHOD(UnlockWrite)(MediumState_T *aState);
130 STDMETHOD(Close)();
131 STDMETHOD(GetProperty)(IN_BSTR aName, BSTR *aValue);
132 STDMETHOD(SetProperty)(IN_BSTR aName, IN_BSTR aValue);
133 STDMETHOD(GetProperties)(IN_BSTR aNames,
134 ComSafeArrayOut(BSTR, aReturnNames),
135 ComSafeArrayOut(BSTR, aReturnValues));
136 STDMETHOD(SetProperties)(ComSafeArrayIn(IN_BSTR, aNames),
137 ComSafeArrayIn(IN_BSTR, aValues));
138 STDMETHOD(CreateBaseStorage)(ULONG64 aLogicalSize,
139 MediumVariant_T aVariant,
140 IProgress **aProgress);
141 STDMETHOD(DeleteStorage)(IProgress **aProgress);
142 STDMETHOD(CreateDiffStorage)(IMedium *aTarget,
143 MediumVariant_T aVariant,
144 IProgress **aProgress);
145 STDMETHOD(MergeTo)(IN_BSTR aTargetId, IProgress **aProgress);
146 STDMETHOD(CloneTo)(IMedium *aTarget, MediumVariant_T aVariant,
147 IMedium *aParent, IProgress **aProgress);
148 STDMETHOD(Compact)(IProgress **aProgress);
149 STDMETHOD(Reset)(IProgress **aProgress);
150
151 // public methods for internal purposes only
152
153 HRESULT FinalConstruct();
154 void FinalRelease();
155
156 HRESULT updatePath(const char *aOldPath, const char *aNewPath);
157
158 HRESULT attachTo(const Guid &aMachineId,
159 const Guid &aSnapshotId = Guid::Empty);
160 HRESULT detachFrom(const Guid &aMachineId,
161 const Guid &aSnapshotId = Guid::Empty);
162
163 const Guid& id() const;
164 MediumState_T state() const;
165 const Bstr& location() const;
166 const Bstr& locationFull() const;
167// const BackRefList& backRefs() const;
168
169 const Guid* getFirstMachineBackrefId() const;
170 const Guid* getFirstMachineBackrefSnapshotId() const;
171
172 bool isAttachedTo(const Guid &aMachineId);
173
174 /**
175 * Shortcut to VirtualBoxBaseWithTypedChildrenNEXT::dependentChildren().
176 */
177 const List &children() const { return dependentChildren(); }
178
179 void updatePaths(const char *aOldPath, const char *aNewPath);
180
181 ComObjPtr<Medium> base(uint32_t *aLevel = NULL);
182
183 bool isReadOnly();
184
185 HRESULT saveSettings(settings::Medium &data);
186
187 HRESULT compareLocationTo(const char *aLocation, int &aResult);
188
189 /**
190 * Shortcut to #deleteStorage() that doesn't wait for operation completion
191 * and implies the progress object will be used for waiting.
192 */
193 HRESULT deleteStorageNoWait(ComObjPtr<Progress> &aProgress)
194 { return deleteStorage(&aProgress, false /* aWait */); }
195
196 /**
197 * Shortcut to #deleteStorage() that wait for operation completion by
198 * blocking the current thread.
199 */
200 HRESULT deleteStorageAndWait(ComObjPtr<Progress> *aProgress = NULL)
201 { return deleteStorage(aProgress, true /* aWait */); }
202
203 /**
204 * Shortcut to #createDiffStorage() that doesn't wait for operation
205 * completion and implies the progress object will be used for waiting.
206 */
207 HRESULT createDiffStorageNoWait(ComObjPtr<Medium> &aTarget,
208 MediumVariant_T aVariant,
209 ComObjPtr<Progress> &aProgress)
210 { return createDiffStorage(aTarget, aVariant, &aProgress, false /* aWait */); }
211
212 /**
213 * Shortcut to #createDiffStorage() that wait for operation completion by
214 * blocking the current thread.
215 */
216 HRESULT createDiffStorageAndWait(ComObjPtr<Medium> &aTarget,
217 MediumVariant_T aVariant,
218 ComObjPtr<Progress> *aProgress = NULL)
219 { return createDiffStorage(aTarget, aVariant, aProgress, true /* aWait */); }
220
221 HRESULT prepareMergeTo(Medium *aTarget, MergeChain * &aChain,
222 bool aIgnoreAttachments = false);
223
224 /**
225 * Shortcut to #mergeTo() that doesn't wait for operation completion and
226 * implies the progress object will be used for waiting.
227 */
228 HRESULT mergeToNoWait(MergeChain *aChain,
229 ComObjPtr<Progress> &aProgress)
230 { return mergeTo(aChain, &aProgress, false /* aWait */); }
231
232 /**
233 * Shortcut to #mergeTo() that wait for operation completion by
234 * blocking the current thread.
235 */
236 HRESULT mergeToAndWait(MergeChain *aChain,
237 ComObjPtr<Progress> *aProgress = NULL)
238 { return mergeTo(aChain, aProgress, true /* aWait */); }
239
240 void cancelMergeTo(MergeChain *aChain);
241
242 Utf8Str name();
243
244 HRESULT prepareDiscard(MergeChain * &aChain);
245 HRESULT discard(ComObjPtr<Progress> &aProgress, MergeChain *aChain);
246 void cancelDiscard(MergeChain *aChain);
247
248 /** Returns a preferred format for a differencing hard disk. */
249 Bstr preferredDiffFormat();
250
251 // unsafe inline public methods for internal purposes only (ensure there is
252 // a caller and a read lock before calling them!)
253
254 ComObjPtr<Medium> parent() const { return static_cast<Medium *>(mParent); }
255 MediumType_T type() const;
256
257 /** For com::SupportErrorInfoImpl. */
258 static const char *ComponentName() { return "Medium"; }
259
260protected:
261
262 // protected initializer/uninitializer for internal purposes only
263 HRESULT protectedInit(VirtualBox *aVirtualBox,
264 CBSTR aLocation,
265 const Guid &aId);
266 HRESULT protectedInit(VirtualBox *aVirtualBox,
267 const settings::Medium &data);
268 void protectedUninit();
269
270 HRESULT queryInfo();
271
272 /**
273 * Performs extra checks if the medium can be closed and returns S_OK in
274 * this case. Otherwise, returns a respective error message. Called by
275 * Close() from within this object's AutoMayUninitSpan and from under
276 * mVirtualBox write lock.
277 */
278 HRESULT canClose();
279
280 /**
281 * Performs extra checks if the medium can be attached to the specified
282 * VM and shapshot at the given time and returns S_OK in this case.
283 * Otherwise, returns a respective error message. Called by attachTo() from
284 * within this object's AutoWriteLock.
285 */
286 HRESULT canAttach(const Guid & /* aMachineId */,
287 const Guid & /* aSnapshotId */);
288
289 /**
290 * Unregisters this medium with mVirtualBox. Called by Close() from within
291 * this object's AutoMayUninitSpan and from under mVirtualBox write lock.
292 */
293 HRESULT unregisterWithVirtualBox();
294
295 HRESULT setStateError();
296
297 /** weak VirtualBox parent */
298 const ComObjPtr<VirtualBox, ComWeakRef> mVirtualBox;
299
300 HRESULT deleteStorage(ComObjPtr<Progress> *aProgress, bool aWait);
301
302 HRESULT createDiffStorage(ComObjPtr<Medium> &aTarget,
303 MediumVariant_T aVariant,
304 ComObjPtr<Progress> *aProgress,
305 bool aWait);
306
307 HRESULT mergeTo(MergeChain *aChain,
308 ComObjPtr<Progress> *aProgress,
309 bool aWait);
310
311 RWLockHandle* treeLock();
312
313 /** Reimplements VirtualBoxWithTypedChildren::childrenLock() to return
314 * treeLock(). */
315 RWLockHandle *childrenLock() { return treeLock(); }
316
317private:
318
319 HRESULT setLocation(const Utf8Str &aLocation, const Utf8Str &aFormat = Utf8Str());
320 HRESULT setFormat(CBSTR aFormat);
321
322 Utf8Str vdError(int aVRC);
323
324 static DECLCALLBACK(void) vdErrorCall(void *pvUser, int rc, RT_SRC_POS_DECL,
325 const char *pszFormat, va_list va);
326
327 static DECLCALLBACK(int) vdProgressCall(PVM /* pVM */, unsigned uPercent,
328 void *pvUser);
329
330 static DECLCALLBACK(bool) vdConfigAreKeysValid(void *pvUser,
331 const char *pszzValid);
332 static DECLCALLBACK(int) vdConfigQuerySize(void *pvUser, const char *pszName,
333 size_t *pcbValue);
334 static DECLCALLBACK(int) vdConfigQuery(void *pvUser, const char *pszName,
335 char *pszValue, size_t cchValue);
336
337 static DECLCALLBACK(int) taskThread(RTTHREAD thread, void *pvUser);
338
339 /** weak parent */
340 ComObjPtr<Medium, ComWeakRef> mParent;
341
342 struct Task;
343 friend struct Task;
344
345 struct Data; // opaque data struct, defined in MediumImpl.cpp
346 Data *m;
347};
348
349#endif /* ____H_MEDIUMIMPL */
350
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