vboxwrappers.py@ 103025

Last change on this file since 103025 was 101067, checked in by vboxsync, 15 months ago
Validation Kit: Build fix for VBox < 7.1. bugref:10384
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 150.7 KB

Line
1	# -- coding: utf-8 --
2	# $Id: vboxwrappers.py 101067 2023-09-08 12:56:08Z vboxsync $
3	# pylint: disable=too-many-lines
4
5	"""
6	VirtualBox Wrapper Classes
7	"""
8
9	__copyright__ = \
10	"""
11	Copyright (C) 2010-2023 Oracle and/or its affiliates.
12
13	This file is part of VirtualBox base platform packages, as
14	available from https://www.virtualbox.org.
15
16	This program is free software; you can redistribute it and/or
17	modify it under the terms of the GNU General Public License
18	as published by the Free Software Foundation, in version 3 of the
19	License.
20
21	This program is distributed in the hope that it will be useful, but
22	WITHOUT ANY WARRANTY; without even the implied warranty of
23	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24	General Public License for more details.
25
26	You should have received a copy of the GNU General Public License
27	along with this program; if not, see <https://www.gnu.org/licenses>.
28
29	The contents of this file may alternatively be used under the terms
30	of the Common Development and Distribution License Version 1.0
31	(CDDL), a copy of it is provided in the "COPYING.CDDL" file included
32	in the VirtualBox distribution, in which case the provisions of the
33	CDDL are applicable instead of those of the GPL.
34
35	You may elect to license modified versions of this file under the
36	terms and conditions of either the GPL or the CDDL or both.
37
38	SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
39	"""
40	__version__ = "$Revision: 101067 $"
41
42
43	# Standard Python imports.
44	import os;
45	import socket;
46	import sys;
47	import uuid;
48
49	# Validation Kit imports.
50	from common import utils;
51	from common import netutils;
52	from testdriver import base;
53	from testdriver import reporter;
54	from testdriver import txsclient;
55	from testdriver import vboxcon;
56	from testdriver import vbox;
57	from testdriver.base import TdTaskBase;
58
59
60	def _ControllerNameToBusAndType(sController):
61	""" Translate a controller name to a storage bus. """
62	if sController == "IDE Controller":
63	eBus = vboxcon.StorageBus_IDE;
64	eType = vboxcon.StorageControllerType_PIIX4;
65	elif sController == "SATA Controller":
66	eBus = vboxcon.StorageBus_SATA;
67	eType = vboxcon.StorageControllerType_IntelAhci;
68	elif sController == "Floppy Controller":
69	eType = vboxcon.StorageControllerType_I82078;
70	eBus = vboxcon.StorageBus_Floppy;
71	elif sController == "SAS Controller":
72	eBus = vboxcon.StorageBus_SAS;
73	eType = vboxcon.StorageControllerType_LsiLogicSas;
74	elif sController == "SCSI Controller":
75	eBus = vboxcon.StorageBus_SCSI;
76	eType = vboxcon.StorageControllerType_LsiLogic;
77	elif sController == "BusLogic SCSI Controller":
78	eBus = vboxcon.StorageBus_SCSI;
79	eType = vboxcon.StorageControllerType_BusLogic;
80	elif sController == "NVMe Controller":
81	eBus = vboxcon.StorageBus_PCIe;
82	eType = vboxcon.StorageControllerType_NVMe;
83	elif sController == "VirtIO SCSI Controller":
84	eBus = vboxcon.StorageBus_VirtioSCSI;
85	eType = vboxcon.StorageControllerType_VirtioSCSI;
86	else:
87	eBus = vboxcon.StorageBus_Null;
88	eType = vboxcon.StorageControllerType_Null;
89	return (eBus, eType);
90
91
92	def _nameMachineState(eState):
93	""" Gets the name (string) of a machine state."""
94	if eState == vboxcon.MachineState_PoweredOff: return 'PoweredOff';
95	if eState == vboxcon.MachineState_Saved: return 'Saved';
96	if eState == vboxcon.MachineState_Teleported: return 'Teleported';
97	if eState == vboxcon.MachineState_Aborted: return 'Aborted';
98	if eState == vboxcon.MachineState_Running: return 'Running';
99	if eState == vboxcon.MachineState_Paused: return 'Paused';
100	if eState == vboxcon.MachineState_Stuck: return 'GuruMeditation';
101	if eState == vboxcon.MachineState_Teleporting: return 'Teleporting';
102	if eState == vboxcon.MachineState_LiveSnapshotting: return 'LiveSnapshotting';
103	if eState == vboxcon.MachineState_Starting: return 'Starting';
104	if eState == vboxcon.MachineState_Stopping: return 'Stopping';
105	if eState == vboxcon.MachineState_Saving: return 'Saving';
106	if eState == vboxcon.MachineState_Restoring: return 'Restoring';
107	if eState == vboxcon.MachineState_TeleportingPausedVM: return 'TeleportingPausedVM';
108	if eState == vboxcon.MachineState_TeleportingIn: return 'TeleportingIn';
109	if eState == vboxcon.MachineState_DeletingSnapshotOnline: return 'DeletingSnapshotOnline';
110	if eState == vboxcon.MachineState_DeletingSnapshotPaused: return 'DeletingSnapshotPaused';
111	if eState == vboxcon.MachineState_RestoringSnapshot: return 'RestoringSnapshot';
112	if eState == vboxcon.MachineState_DeletingSnapshot: return 'DeletingSnapshot';
113	if eState == vboxcon.MachineState_SettingUp: return 'SettingUp';
114	if hasattr(vboxcon, 'MachineState_FaultTolerantSyncing'):
115	if eState == vboxcon.MachineState_FaultTolerantSyncing: return 'FaultTolerantSyncing';
116	if hasattr(vboxcon, 'MachineState_AbortedSaved'): # since r147033 / 7.0
117	if eState == vboxcon.MachineState_AbortedSaved: return 'Aborted-Saved';
118	return 'Unknown-%s' % (eState,);
119
120
121	class VirtualBoxWrapper(object): # pylint: disable=too-few-public-methods
122	"""
123	Wrapper around the IVirtualBox object that adds some (hopefully) useful
124	utility methods
125
126	The real object can be accessed thru the o member. That said, members can
127	be accessed directly as well.
128	"""
129
130	def __init__(self, oVBox, oVBoxMgr, fpApiVer, oTstDrv):
131	self.o = oVBox;
132	self.oVBoxMgr = oVBoxMgr;
133	self.fpApiVer = fpApiVer;
134	self.oTstDrv = oTstDrv;
135
136	def __getattr__(self, sName):
137	# Try ourselves first.
138	try:
139	oAttr = self.__dict__[sName];
140	except:
141	#try:
142	# oAttr = dir(self)[sName];
143	#except AttributeError:
144	oAttr = getattr(self.o, sName);
145	return oAttr;
146
147	#
148	# Utilities.
149	#
150
151	def registerDerivedEventHandler(self, oSubClass, dArgs = None):
152	"""
153	Create an instance of the given VirtualBoxEventHandlerBase sub-class
154	and register it.
155
156	The new instance is returned on success. None is returned on error.
157	"""
158	dArgsCopy = dArgs.copy() if dArgs is not None else {};
159	dArgsCopy['oVBox'] = self;
160	return oSubClass.registerDerivedEventHandler(self.oVBoxMgr, self.fpApiVer, oSubClass, dArgsCopy,
161	self.o, 'IVirtualBox', 'IVirtualBoxCallback');
162
163	def deleteHdByLocation(self, sHdLocation):
164	"""
165	Deletes a disk image from the host, given it's location.
166	Returns True on success and False on failure. Error information is logged.
167	"""
168	try:
169	oIMedium = self.o.findHardDisk(sHdLocation);
170	except:
171	try:
172	if self.fpApiVer >= 4.1:
173	oIMedium = self.o.openMedium(sHdLocation, vboxcon.DeviceType_HardDisk,
174	vboxcon.AccessMode_ReadWrite, False);
175	elif self.fpApiVer >= 4.0:
176	oIMedium = self.o.openMedium(sHdLocation, vboxcon.DeviceType_HardDisk,
177	vboxcon.AccessMode_ReadWrite);
178	else:
179	oIMedium = self.o.openHardDisk(sHdLocation, vboxcon.AccessMode_ReadOnly, False, "", False, "");
180	except:
181	return reporter.errorXcpt('failed to open hd "%s"' % (sHdLocation));
182	return self.deleteHdByMedium(oIMedium)
183
184	def deleteHdByMedium(self, oIMedium):
185	"""
186	Deletes a disk image from the host, given an IMedium reference.
187	Returns True on success and False on failure. Error information is logged.
188	"""
189	try: oProgressCom = oIMedium.deleteStorage();
190	except: return reporter.errorXcpt('deleteStorage() for disk %s failed' % (oIMedium,));
191	try: oProgress = ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oTstDrv, 'delete disk %s' % (oIMedium.location));
192	except: return reporter.errorXcpt();
193	oProgress.wait();
194	oProgress.logResult();
195	return oProgress.isSuccess();
196
197
198
199	class ProgressWrapper(TdTaskBase):
200	"""
201	Wrapper around a progress object for making it a task and providing useful
202	utility methods.
203	The real progress object can be accessed thru the o member.
204	"""
205
206	def __init__(self, oProgress, oVBoxMgr, oTstDrv, sName):
207	TdTaskBase.__init__(self, utils.getCallerName());
208	self.o = oProgress;
209	self.oVBoxMgr = oVBoxMgr;
210	self.oTstDrv = oTstDrv;
211	self.sName = sName;
212
213	def toString(self):
214	return '<%s sName=%s, oProgress=%s >' \
215	% (TdTaskBase.toString(self), self.sName, self.o);
216
217	#
218	# TdTaskBase overrides.
219	#
220
221	def pollTask(self, fLocked = False):
222	"""
223	Overrides TdTaskBase.pollTask().
224
225	This method returns False until the progress object has completed.
226	"""
227	self.doQuickApiTest();
228	try:
229	try:
230	if self.o.completed:
231	return True;
232	except:
233	pass;
234	finally:
235	self.oTstDrv.processPendingEvents();
236	return False;
237
238	def waitForTask(self, cMsTimeout = 0):
239	"""
240	Overrides TdTaskBase.waitForTask().
241	Process XPCOM/COM events while waiting.
242	"""
243	msStart = base.timestampMilli();
244	fState = self.pollTask(False);
245	while not fState:
246	cMsElapsed = base.timestampMilli() - msStart;
247	if cMsElapsed > cMsTimeout:
248	break;
249	cMsToWait = cMsTimeout - cMsElapsed;
250	cMsToWait = min(cMsToWait, 500);
251	try:
252	self.o.waitForCompletion(cMsToWait);
253	except KeyboardInterrupt: raise;
254	except: pass;
255	if self.fnProcessEvents:
256	self.fnProcessEvents();
257	reporter.doPollWork('ProgressWrapper.waitForTask');
258	fState = self.pollTask(False);
259	return fState;
260
261	#
262	# Utility methods.
263	#
264
265	def isSuccess(self):
266	"""
267	Tests if the progress object completed successfully.
268	Returns True on success, False on failure or incomplete.
269	"""
270	if not self.isCompleted():
271	return False;
272	return self.getResult() >= 0;
273
274	def isCompleted(self):
275	"""
276	Wrapper around IProgress.completed.
277	"""
278	return self.pollTask();
279
280	def isCancelable(self):
281	"""
282	Wrapper around IProgress.cancelable.
283	"""
284	try:
285	fRc = self.o.cancelable;
286	except:
287	reporter.logXcpt();
288	fRc = False;
289	return fRc;
290
291	def wasCanceled(self):
292	"""
293	Wrapper around IProgress.canceled.
294	"""
295	try:
296	fRc = self.o.canceled;
297	except:
298	reporter.logXcpt(self.sName);
299	fRc = False;
300	return fRc;
301
302	def cancel(self):
303	"""
304	Wrapper around IProgress.cancel()
305	Returns True on success, False on failure (logged as error).
306	"""
307	try:
308	self.o.cancel();
309	except:
310	reporter.errorXcpt(self.sName);
311	return False;
312	return True;
313
314	def getResult(self):
315	"""
316	Wrapper around IProgress.resultCode.
317	"""
318	try:
319	iRc = self.o.resultCode;
320	except:
321	reporter.logXcpt(self.sName);
322	iRc = -1;
323	return iRc;
324
325	def getErrInfoResultCode(self):
326	"""
327	Wrapper around IProgress.errorInfo.resultCode.
328
329	Returns the string on success, -1 on bad objects (logged as error), and
330	-2 on missing errorInfo object.
331	"""
332	iRc = -1;
333	try:
334	oErrInfo = self.o.errorInfo;
335	except:
336	reporter.errorXcpt(self.sName);
337	else:
338	if oErrInfo is None:
339	iRc = -2;
340	else:
341	try:
342	iRc = oErrInfo.resultCode;
343	except:
344	reporter.errorXcpt();
345	return iRc;
346
347	def getErrInfoText(self):
348	"""
349	Wrapper around IProgress.errorInfo.text.
350
351	Returns the string on success, None on failure. Missing errorInfo is
352	not logged as an error, all other failures are.
353	"""
354	sText = None;
355	try:
356	oErrInfo = self.o.errorInfo;
357	except:
358	reporter.log2Xcpt(self.sName);
359	else:
360	if oErrInfo is not None:
361	try:
362	sText = oErrInfo.text;
363	except:
364	reporter.errorXcpt();
365	return sText;
366
367	def stringifyErrorInfo(self):
368	"""
369	Formats IProgress.errorInfo into a string.
370	"""
371	try:
372	oErrInfo = self.o.errorInfo;
373	except:
374	reporter.logXcpt(self.sName);
375	sErr = 'no error info';
376	else:
377	sErr = vbox.stringifyErrorInfo(oErrInfo);
378	return sErr;
379
380	def stringifyResult(self):
381	"""
382	Stringify the result.
383	"""
384	if self.isCompleted():
385	if self.wasCanceled():
386	sRet = 'Progress %s: Canceled, hrc=%s' % (self.sName, vbox.ComError.toString(self.getResult()));
387	elif self.getResult() == 0:
388	sRet = 'Progress %s: Success' % (self.sName,);
389	elif self.getResult() > 0:
390	sRet = 'Progress %s: Success (hrc=%s)' % (self.sName, vbox.ComError.toString(self.getResult()));
391	else:
392	sRet = 'Progress %s: Failed! %s' % (self.sName, self.stringifyErrorInfo());
393	else:
394	sRet = 'Progress %s: Not completed yet...' % (self.sName);
395	return sRet;
396
397	def logResult(self, fIgnoreErrors = False):
398	"""
399	Logs the result, failure logged as error unless fIgnoreErrors is True.
400	Return True on success, False on failure (and fIgnoreErrors is false).
401	"""
402	sText = self.stringifyResult();
403	if self.isCompleted() and self.getResult() < 0 and fIgnoreErrors is False:
404	return reporter.error(sText);
405	reporter.log(sText);
406	return True;
407
408	def waitOnProgress(self, cMsInterval = 1000):
409	"""
410	See vbox.TestDriver.waitOnProgress.
411	"""
412	self.doQuickApiTest();
413	return self.oTstDrv.waitOnProgress(self.o, cMsInterval);
414
415	def wait(self, cMsTimeout = 60000, fErrorOnTimeout = True, cMsInterval = 1000):
416	"""
417	Wait on the progress object for a while.
418
419	Returns the resultCode of the progress object if completed.
420	Returns -1 on timeout, logged as error if fErrorOnTimeout is set.
421	Returns -2 is the progress object is invalid or waitForCompletion
422	fails (logged as errors).
423	"""
424	msStart = base.timestampMilli();
425	while True:
426	self.oTstDrv.processPendingEvents();
427	self.doQuickApiTest();
428	try:
429	if self.o.completed:
430	break;
431	except:
432	reporter.errorXcpt(self.sName);
433	return -2;
434	self.oTstDrv.processPendingEvents();
435
436	cMsElapsed = base.timestampMilli() - msStart;
437	if cMsElapsed > cMsTimeout:
438	if fErrorOnTimeout:
439	reporter.error('Timing out after waiting for %u s on "%s"' % (cMsTimeout / 1000, self.sName))
440	return -1;
441
442	try:
443	self.o.waitForCompletion(cMsInterval);
444	except:
445	reporter.errorXcpt(self.sName);
446	return -2;
447	reporter.doPollWork('ProgressWrapper.wait');
448
449	try:
450	rc = self.o.resultCode;
451	except:
452	rc = -2;
453	reporter.errorXcpt(self.sName);
454	self.oTstDrv.processPendingEvents();
455	return rc;
456
457	def waitForOperation(self, iOperation, cMsTimeout = 60000, fErrorOnTimeout = True, cMsInterval = 1000, \
458	fIgnoreErrors = False):
459	"""
460	Wait for the completion of a operation.
461
462	Negative iOperation values are relative to operationCount (this
463	property may changed at runtime).
464
465	Returns 0 if the operation completed normally.
466	Returns -1 on timeout, logged as error if fErrorOnTimeout is set.
467	Returns -2 is the progress object is invalid or waitForCompletion
468	fails (logged as errors).
469	Returns -3 if if the operation completed with an error, this is logged
470	as an error.
471	"""
472	msStart = base.timestampMilli();
473	while True:
474	self.oTstDrv.processPendingEvents();
475	self.doQuickApiTest();
476	try:
477	iCurrentOperation = self.o.operation;
478	cOperations = self.o.operationCount;
479	if iOperation >= 0:
480	iRealOperation = iOperation;
481	else:
482	iRealOperation = cOperations + iOperation;
483
484	if iCurrentOperation > iRealOperation:
485	return 0;
486	if iCurrentOperation == iRealOperation \
487	and iRealOperation >= cOperations - 1 \
488	and self.o.completed:
489	if self.o.resultCode < 0:
490	self.logResult(fIgnoreErrors);
491	return -3;
492	return 0;
493	except:
494	if fIgnoreErrors:
495	reporter.logXcpt();
496	else:
497	reporter.errorXcpt();
498	return -2;
499	self.oTstDrv.processPendingEvents();
500
501	cMsElapsed = base.timestampMilli() - msStart;
502	if cMsElapsed > cMsTimeout:
503	if fErrorOnTimeout:
504	if fIgnoreErrors:
505	reporter.log('Timing out after waiting for %s s on "%s" operation %d' \
506	% (cMsTimeout / 1000, self.sName, iOperation))
507	else:
508	reporter.error('Timing out after waiting for %s s on "%s" operation %d' \
509	% (cMsTimeout / 1000, self.sName, iOperation))
510	return -1;
511
512	try:
513	self.o.waitForOperationCompletion(iRealOperation, cMsInterval);
514	except:
515	if fIgnoreErrors:
516	reporter.logXcpt(self.sName);
517	else:
518	reporter.errorXcpt(self.sName);
519	return -2;
520	reporter.doPollWork('ProgressWrapper.waitForOperation');
521	# Not reached.
522	return -3; # Make pylin happy (for now).
523
524	def doQuickApiTest(self):
525	"""
526	Queries everything that is stable and easy to get at and checks that
527	they don't throw errors.
528	"""
529	if True is True: # pylint: disable=comparison-with-itself,comparison-of-constants
530	try:
531	iPct = self.o.operationPercent;
532	sDesc = self.o.description;
533	fCancelable = self.o.cancelable;
534	cSecsRemain = self.o.timeRemaining;
535	fCanceled = self.o.canceled;
536	fCompleted = self.o.completed;
537	iOp = self.o.operation;
538	cOps = self.o.operationCount;
539	iOpPct = self.o.operationPercent;
540	sOpDesc = self.o.operationDescription;
541	except:
542	reporter.errorXcpt('%s: %s' % (self.sName, self.o,));
543	return False;
544	try:
545	# Very noisy -- only enable for debugging purposes.
546	#reporter.log2('%s: op=%u/%u/%s: %u%%; total=%u%% cancel=%s/%s compl=%s rem=%us; desc=%s' \
547	# % (self.sName, iOp, cOps, sOpDesc, iOpPct, iPct, fCanceled, fCancelable, fCompleted, \
548	# cSecsRemain, sDesc));
549	_ = iPct; _ = sDesc; _ = fCancelable; _ = cSecsRemain; _ = fCanceled; _ = fCompleted; _ = iOp;
550	_ = cOps; _ = iOpPct; _ = sOpDesc;
551	except:
552	reporter.errorXcpt();
553	return False;
554
555	return True;
556
557
558	class SessionWrapper(TdTaskBase):
559	"""
560	Wrapper around a machine session. The real session object can be accessed
561	thru the o member (short is good, right :-).
562	"""
563
564	def __init__(self, oSession, oVM, oVBox, oVBoxMgr, oTstDrv, fRemoteSession, sFallbackName = None, sLogFile = None):
565	"""
566	Initializes the session wrapper.
567	"""
568	TdTaskBase.__init__(self, utils.getCallerName());
569	self.o = oSession;
570	self.oVBox = oVBox;
571	self.oVBoxMgr = oVBoxMgr;
572	self.oVM = oVM; # Not the session machine. Useful backdoor...
573	self.oTstDrv = oTstDrv;
574	self.fpApiVer = oTstDrv.fpApiVer;
575	self.fRemoteSession = fRemoteSession;
576	self.sLogFile = sLogFile;
577	self.oConsoleEventHandler = None;
578	self.uPid = None;
579	self.fPidFile = True;
580	self.fHostMemoryLow = False; # see signalHostMemoryLow; read-only for outsiders.
581
582	try:
583	self.sName = oSession.machine.name;
584	except:
585	if sFallbackName is not None:
586	self.sName = sFallbackName;
587	else:
588	try: self.sName = str(oSession.machine);
589	except: self.sName = 'is-this-vm-already-off'
590
591	try:
592	self.sUuid = oSession.machine.id;
593	except:
594	self.sUuid = None;
595
596	# Try cache the SessionPID.
597	self.getPid();
598
599	def __del__(self):
600	"""
601	Destructor that makes sure the callbacks are deregistered and
602	that the session is closed.
603	"""
604	self.deregisterEventHandlerForTask();
605
606	if self.o is not None:
607	try:
608	self.close();
609	reporter.log('close session %s' % (self.o));
610	except:
611	pass;
612	self.o = None;
613
614	TdTaskBase.__del__(self);
615
616	def toString(self):
617	return '<%s: sUuid=%s, sName=%s, uPid=%s, sDbgCreated=%s, fRemoteSession=%s, oSession=%s,' \
618	' oConsoleEventHandler=%s, oVM=%s >' \
619	% (type(self).__name__, self.sUuid, self.sName, self.uPid, self.sDbgCreated, self.fRemoteSession,
620	self.o, self.oConsoleEventHandler, self.oVM,);
621
622	def __str__(self):
623	return self.toString();
624
625	#
626	# TdTaskBase overrides.
627	#
628
629	def __pollTask(self):
630	""" Internal poller """
631	# Poll for events after doing the remote GetState call, otherwise we
632	# might end up sleepless because XPCOM queues a cleanup event.
633	try:
634	try:
635	eState = self.o.machine.state;
636	except Exception as oXcpt:
637	if vbox.ComError.notEqual(oXcpt, vbox.ComError.E_UNEXPECTED):
638	reporter.logXcpt();
639	return True;
640	finally:
641	self.oTstDrv.processPendingEvents();
642
643	# Switch
644	if eState == vboxcon.MachineState_Running:
645	return False;
646	if eState == vboxcon.MachineState_Paused:
647	return False;
648	if eState == vboxcon.MachineState_Teleporting:
649	return False;
650	if eState == vboxcon.MachineState_LiveSnapshotting:
651	return False;
652	if eState == vboxcon.MachineState_Starting:
653	return False;
654	if eState == vboxcon.MachineState_Stopping:
655	return False;
656	if eState == vboxcon.MachineState_Saving:
657	return False;
658	if eState == vboxcon.MachineState_Restoring:
659	return False;
660	if eState == vboxcon.MachineState_TeleportingPausedVM:
661	return False;
662	if eState == vboxcon.MachineState_TeleportingIn:
663	return False;
664
665	# Beeep fudge!
666	if self.fpApiVer < 3.2 \
667	and eState == vboxcon.MachineState_PoweredOff \
668	and self.getAgeAsMs() < 3000:
669	return False;
670
671	reporter.log('SessionWrapper::pollTask: eState=%s' % (eState));
672	return True;
673
674
675	def pollTask(self, fLocked = False):
676	"""
677	Overrides TdTaskBase.pollTask().
678
679	This method returns False while the VM is online and running normally.
680	"""
681
682	# Call super to check if the task was signalled by runtime error or similar,
683	# if not then check the VM state via __pollTask.
684	fRc = super(SessionWrapper, self).pollTask(fLocked);
685	if not fRc:
686	fRc = self.__pollTask();
687
688	# HACK ALERT: Lazily try registering the console event handler if
689	# we're not ready.
690	if not fRc and self.oConsoleEventHandler is None:
691	self.registerEventHandlerForTask();
692
693	# HACK ALERT: Lazily try get the PID and add it to the PID file.
694	if not fRc and self.uPid is None:
695	self.getPid();
696
697	return fRc;
698
699	def waitForTask(self, cMsTimeout = 0):
700	"""
701	Overrides TdTaskBase.waitForTask().
702	Process XPCOM/COM events while waiting.
703	"""
704	msStart = base.timestampMilli();
705	fState = self.pollTask(False);
706	while not fState:
707	cMsElapsed = base.timestampMilli() - msStart;
708	if cMsElapsed > cMsTimeout:
709	break;
710	cMsSleep = cMsTimeout - cMsElapsed;
711	cMsSleep = min(cMsSleep, 10000);
712	try: self.oVBoxMgr.waitForEvents(cMsSleep);
713	except KeyboardInterrupt: raise;
714	except: pass;
715	if self.fnProcessEvents:
716	self.fnProcessEvents();
717	reporter.doPollWork('SessionWrapper.waitForTask');
718	fState = self.pollTask(False);
719	return fState;
720
721	def setTaskOwner(self, oOwner):
722	"""
723	HACK ALERT!
724	Overrides TdTaskBase.setTaskOwner() so we can try call
725	registerEventHandlerForTask() again when when the testdriver calls
726	addTask() after VM has been spawned. Related to pollTask() above.
727
728	The testdriver must not add the task too early for this to work!
729	"""
730	if oOwner is not None:
731	self.registerEventHandlerForTask()
732	return TdTaskBase.setTaskOwner(self, oOwner);
733
734
735	#
736	# Task helpers.
737	#
738
739	def registerEventHandlerForTask(self):
740	"""
741	Registers the console event handlers for working the task state.
742	"""
743	if self.oConsoleEventHandler is not None:
744	return True;
745	self.oConsoleEventHandler = self.registerDerivedEventHandler(vbox.SessionConsoleEventHandler, {}, False);
746	return self.oConsoleEventHandler is not None;
747
748	def deregisterEventHandlerForTask(self):
749	"""
750	Deregisters the console event handlers.
751	"""
752	if self.oConsoleEventHandler is not None:
753	self.oConsoleEventHandler.unregister();
754	self.oConsoleEventHandler = None;
755
756	def signalHostMemoryLow(self):
757	"""
758	Used by a runtime error event handler to indicate that we're low on memory.
759	Signals the task.
760	"""
761	self.fHostMemoryLow = True;
762	self.signalTask();
763	return True;
764
765	def needsPoweringOff(self):
766	"""
767	Examins the machine state to see if the VM needs powering off.
768	"""
769	try:
770	try:
771	eState = self.o.machine.state;
772	except Exception as oXcpt:
773	if vbox.ComError.notEqual(oXcpt, vbox.ComError.E_UNEXPECTED):
774	reporter.logXcpt();
775	return False;
776	finally:
777	self.oTstDrv.processPendingEvents();
778
779	# Switch
780	if eState == vboxcon.MachineState_Running:
781	return True;
782	if eState == vboxcon.MachineState_Paused:
783	return True;
784	if eState == vboxcon.MachineState_Stuck:
785	return True;
786	if eState == vboxcon.MachineState_Teleporting:
787	return True;
788	if eState == vboxcon.MachineState_LiveSnapshotting:
789	return True;
790	if eState == vboxcon.MachineState_Starting:
791	return True;
792	if eState == vboxcon.MachineState_Saving:
793	return True;
794	if eState == vboxcon.MachineState_Restoring:
795	return True;
796	if eState == vboxcon.MachineState_TeleportingPausedVM:
797	return True;
798	if eState == vboxcon.MachineState_TeleportingIn:
799	return True;
800	if hasattr(vboxcon, 'MachineState_FaultTolerantSyncing'):
801	if eState == vboxcon.MachineState_FaultTolerantSyncing:
802	return True;
803	return False;
804
805	def assertPoweredOff(self):
806	"""
807	Asserts that the VM is powered off, reporting an error if not.
808	Returns True if powered off, False + error msg if not.
809	"""
810	try:
811	try:
812	eState = self.oVM.state;
813	except Exception:
814	reporter.errorXcpt();
815	return True;
816	finally:
817	self.oTstDrv.processPendingEvents();
818
819	if eState == vboxcon.MachineState_PoweredOff:
820	return True;
821	reporter.error('Expected machine state "PoweredOff", machine is in the "%s" state instead.'
822	% (_nameMachineState(eState),));
823	return False;
824
825	def getMachineStateWithName(self):
826	"""
827	Gets the current machine state both as a constant number/whatever and
828	as a human readable string. On error, the constants will be set to
829	None and the string will be the error message.
830	"""
831	try:
832	eState = self.oVM.state;
833	except:
834	return (None, '[error getting state: %s]' % (self.oVBoxMgr.xcptToString(),));
835	finally:
836	self.oTstDrv.processPendingEvents();
837	return (eState, _nameMachineState(eState));
838
839	def reportPrematureTermination(self, sPrefix = ''):
840	"""
841	Reports a premature virtual machine termination.
842	Returns False to facilitate simpler error paths.
843	"""
844
845	reporter.error(sPrefix + 'The virtual machine terminated prematurely!!');
846	(enmState, sStateNm) = self.getMachineStateWithName();
847	reporter.error(sPrefix + 'Machine state: %s' % (sStateNm,));
848
849	if enmState is not None \
850	and enmState == vboxcon.MachineState_Aborted \
851	and self.uPid is not None:
852	#
853	# Look for process crash info.
854	#
855	def addCrashFile(sLogFile, fBinary):
856	""" processCollectCrashInfo callback. """
857	reporter.addLogFile(sLogFile, 'crash/dump/vm' if fBinary else 'crash/report/vm');
858	utils.processCollectCrashInfo(self.uPid, reporter.log, addCrashFile);
859
860	return False;
861
862
863
864	#
865	# ISession / IMachine / ISomethingOrAnother wrappers.
866	#
867
868	def close(self):
869	"""
870	Closes the session if it's open and removes it from the
871	vbox.TestDriver.aoRemoteSessions list.
872	Returns success indicator.
873	"""
874	fRc = True;
875	if self.o is not None:
876	# Get the pid in case we need to kill the process later on.
877	self.getPid();
878
879	# Try close it.
880	try:
881	if self.fpApiVer < 3.3:
882	self.o.close();
883	else:
884	self.o.unlockMachine();
885	self.o = None;
886	except KeyboardInterrupt:
887	raise;
888	except:
889	# Kludge to ignore VBoxSVC's closing of our session when the
890	# direct session closes / VM process terminates. Fun!
891	try: fIgnore = self.o.state == vboxcon.SessionState_Unlocked;
892	except: fIgnore = False;
893	if fIgnore:
894	self.o = None; # Must prevent a retry during GC.
895	else:
896	reporter.errorXcpt('ISession::unlockMachine failed on %s' % (self.o));
897	fRc = False;
898
899	# Remove it from the remote session list if applicable (not 100% clean).
900	if fRc and self.fRemoteSession:
901	try:
902	if self in self.oTstDrv.aoRemoteSessions:
903	reporter.log2('SessionWrapper::close: Removing myself from oTstDrv.aoRemoteSessions');
904	self.oTstDrv.aoRemoteSessions.remove(self)
905	except:
906	reporter.logXcpt();
907
908	if self.uPid is not None and self.fPidFile:
909	self.oTstDrv.pidFileRemove(self.uPid);
910	self.fPidFile = False;
911
912	# It's only logical to deregister the event handler after the session
913	# is closed. It also avoids circular references between the session
914	# and the listener, which causes trouble with garbage collection.
915	self.deregisterEventHandlerForTask();
916
917	self.oTstDrv.processPendingEvents();
918	return fRc;
919
920	def saveSettings(self, fClose = False):
921	"""
922	Saves the settings and optionally closes the session.
923	Returns success indicator.
924	"""
925	try:
926	try:
927	self.o.machine.saveSettings();
928	except:
929	reporter.errorXcpt('saveSettings failed on %s' % (self.o));
930	return False;
931	finally:
932	self.oTstDrv.processPendingEvents();
933	if fClose:
934	return self.close();
935	return True;
936
937	def discardSettings(self, fClose = False):
938	"""
939	Discards the settings and optionally closes the session.
940	"""
941	try:
942	try:
943	self.o.machine.discardSettings();
944	except:
945	reporter.errorXcpt('discardSettings failed on %s' % (self.o));
946	return False;
947	finally:
948	self.oTstDrv.processPendingEvents();
949	if fClose:
950	return self.close();
951	return True;
952
953	def isPlatformArch(self, enmPlatformArch):
954	"""
955	Returns if the machine is of the given platform architecture or not.
956	"""
957	if not self.o:
958	return False;
959	if self.fpApiVer >= 7.1:
960	return self.o.machine.platform.architecture == enmPlatformArch;
961	return enmPlatformArch == vboxcon.PlatformArchitecture_x86; # VBox < 7.1 only supported x86.
962
963	def isPlatformARM(self):
964	"""
965	Returns if the machine is of the ARM platform architecture or not.
966	"""
967	if self.fpApiVer >= 7.1:
968	return self.isPlatformArch(vboxcon.PlatformArchitecture_ARM);
969	return False; # For VBox < 7.1 this always is false (x86 only).
970
971	def isPlatformX86(self):
972	"""
973	Returns if the machine is of the x86 platform architecture or not.
974	"""
975	if self.fpApiVer >= 7.1:
976	return self.isPlatformArch(vboxcon.PlatformArchitecture_x86);
977	return True; # For VBox < 7.1 this always is true (x86 only).
978
979	def enableVirtExX86(self, fEnable):
980	"""
981	Enables or disables AMD-V/VT-x. x86 only.
982	Returns True on success and False on failure. Error information is logged.
983
984	Ignored on non-x86 platform architectures.
985	"""
986	if not self.isPlatformX86(): return True;
987	# Enable/disable it.
988	fRc = True;
989	try:
990	if self.fpApiVer >= 7.1:
991	self.o.machine.platform.x86.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_Enabled, fEnable);
992	else:
993	self.o.machine.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_Enabled, fEnable);
994	except:
995	reporter.errorXcpt('failed to set HWVirtExPropertyType_Enabled=%s for "%s"' % (fEnable, self.sName));
996	fRc = False;
997	else:
998	reporter.log('set HWVirtExPropertyType_Enabled=%s for "%s"' % (fEnable, self.sName));
999
1000	# Force/unforce it.
1001	if fRc and hasattr(vboxcon, 'HWVirtExPropertyType_Force'):
1002	try:
1003	if self.fpApiVer >= 7.1:
1004	self.o.machine.platform.x86.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_Force, fEnable);
1005	else:
1006	self.o.machine.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_Force, fEnable);
1007	except:
1008	reporter.errorXcpt('failed to set HWVirtExPropertyType_Force=%s for "%s"' % (fEnable, self.sName));
1009	fRc = False;
1010	else:
1011	reporter.log('set HWVirtExPropertyType_Force=%s for "%s"' % (fEnable, self.sName));
1012	else:
1013	reporter.log('Warning! vboxcon has no HWVirtExPropertyType_Force attribute.');
1014	## @todo Modify CFGM to do the same for old VBox versions?
1015
1016	self.oTstDrv.processPendingEvents();
1017	return fRc;
1018
1019	def enableNestedPagingX86(self, fEnable):
1020	"""
1021	Enables or disables nested paging. x86 only.
1022	Returns True on success and False on failure. Error information is logged.
1023
1024	Ignored on non-x86 platform architectures.
1025	"""
1026	if not self.isPlatformX86(): return True;
1027	## @todo Add/remove force CFGM thing, we don't want fallback logic when testing.
1028	fRc = True;
1029	try:
1030	if self.fpApiVer >= 7.1:
1031	self.o.machine.platform.x86.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_NestedPaging, fEnable);
1032	else:
1033	self.o.machine.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_NestedPaging, fEnable);
1034	except:
1035	reporter.errorXcpt('failed to set HWVirtExPropertyType_NestedPaging=%s for "%s"' % (fEnable, self.sName));
1036	fRc = False;
1037	else:
1038	reporter.log('set HWVirtExPropertyType_NestedPaging=%s for "%s"' % (fEnable, self.sName));
1039	self.oTstDrv.processPendingEvents();
1040	return fRc;
1041
1042	def enableLongModeX86(self, fEnable):
1043	"""
1044	Enables or disables LongMode. x86 only.
1045	Returns True on success and False on failure. Error information is logged.
1046
1047	Ignored on non-x86 platform architectures.
1048	"""
1049	if not self.isPlatformX86(): return True;
1050	# Supported.
1051	if self.fpApiVer < 4.2 or not hasattr(vboxcon, 'HWVirtExPropertyType_LongMode'):
1052	return True;
1053
1054	# Enable/disable it.
1055	fRc = True;
1056	try:
1057	if self.fpApiVer >= 7.1:
1058	self.o.machine.platform.x86.setCPUProperty(vboxcon.CPUPropertyTypeX86_LongMode, fEnable);
1059	else:
1060	self.o.machine.setCPUProperty(vboxcon.CPUPropertyType_LongMode, fEnable);
1061	except:
1062	reporter.errorXcpt('failed to set CPUPropertyType_LongMode=%s for "%s"' % (fEnable, self.sName));
1063	fRc = False;
1064	else:
1065	reporter.log('set CPUPropertyType_LongMode=%s for "%s"' % (fEnable, self.sName));
1066	self.oTstDrv.processPendingEvents();
1067	return fRc;
1068
1069	def enableNestedHwVirtX86(self, fEnable):
1070	"""
1071	Enables or disables Nested Hardware-Virtualization. x86 only.
1072	Returns True on success and False on failure. Error information is logged.
1073
1074	Ignored on non-x86 platform architectures.
1075	"""
1076	if not self.isPlatformX86(): return True;
1077	# Supported.
1078	if self.fpApiVer < 5.3 or not hasattr(vboxcon, 'CPUPropertyType_HWVirt'):
1079	return True;
1080
1081	# Enable/disable it.
1082	fRc = True;
1083	try:
1084	if self.fpApiVer >= 7.1:
1085	self.o.machine.platform.x86.setCPUProperty(vboxcon.CPUPropertyTypeX86_HWVirt, fEnable);
1086	else:
1087	self.o.machine.setCPUProperty(vboxcon.CPUPropertyType_HWVirt, fEnable);
1088	except:
1089	reporter.errorXcpt('failed to set CPUPropertyType_HWVirt=%s for "%s"' % (fEnable, self.sName));
1090	fRc = False;
1091	else:
1092	reporter.log('set CPUPropertyType_HWVirt=%s for "%s"' % (fEnable, self.sName));
1093	self.oTstDrv.processPendingEvents();
1094	return fRc;
1095
1096	def enablePaeX86(self, fEnable):
1097	"""
1098	Enables or disables PAE. x86 only.
1099	Returns True on success and False on failure. Error information is logged.
1100
1101	Ignored on non-x86 platform architectures.
1102	"""
1103	if not self.isPlatformX86(): return True;
1104	fRc = True;
1105	try:
1106	if self.fpApiVer >= 7.1:
1107	self.o.machine.platform.x86.setCPUProperty(vboxcon.CPUPropertyTypeX86_PAE, fEnable);
1108	elif self.fpApiVer >= 3.2: # great, ain't it?
1109	self.o.machine.setCPUProperty(vboxcon.CPUPropertyType_PAE, fEnable);
1110	else:
1111	self.o.machine.setCpuProperty(vboxcon.CpuPropertyType_PAE, fEnable);
1112	except:
1113	reporter.errorXcpt('failed to set CPUPropertyType_PAE=%s for "%s"' % (fEnable, self.sName));
1114	fRc = False;
1115	else:
1116	reporter.log('set CPUPropertyType_PAE=%s for "%s"' % (fEnable, self.sName));
1117	self.oTstDrv.processPendingEvents();
1118	return fRc;
1119
1120	def enableIoApic(self, fEnable):
1121	"""
1122	Enables or disables the IO-APIC.
1123	Returns True on success and False on failure. Error information is logged.
1124	"""
1125	fRc = True;
1126	try:
1127	if self.fpApiVer >= 7.1:
1128	self.o.machine.firmwareSettings.IOAPICEnabled = fEnable;
1129	else:
1130	self.o.machine.BIOSSettings.IOAPICEnabled = fEnable;
1131	except:
1132	reporter.errorXcpt('failed to set firmwareSettings.IOAPICEnabled=%s for "%s"' % (fEnable, self.sName));
1133	fRc = False;
1134	else:
1135	reporter.log('set firmwareSettings.IOAPICEnabled=%s for "%s"' % (fEnable, self.sName));
1136	self.oTstDrv.processPendingEvents();
1137	return fRc;
1138
1139	def enableHpetX86(self, fEnable):
1140	"""
1141	Enables or disables the HPET. x86 only.
1142	Returns True on success and False on failure. Error information is logged.
1143
1144	Ignored on non-x86 platform architectures.
1145	"""
1146	if not self.isPlatformX86(): return True;
1147	fRc = True;
1148	try:
1149	if self.fpApiVer >= 7.1:
1150	self.o.machine.platform.x86.HPETEnabled = fEnable;
1151	elif self.fpApiVer >= 4.2:
1152	self.o.machine.HPETEnabled = fEnable;
1153	else:
1154	self.o.machine.hpetEnabled = fEnable;
1155	except:
1156	reporter.errorXcpt('failed to set HpetEnabled=%s for "%s"' % (fEnable, self.sName));
1157	fRc = False;
1158	else:
1159	reporter.log('set HpetEnabled=%s for "%s"' % (fEnable, self.sName));
1160	self.oTstDrv.processPendingEvents();
1161	return fRc;
1162
1163	def enableUsbHid(self, fEnable):
1164	"""
1165	Enables or disables the USB HID.
1166	Returns True on success and False on failure. Error information is logged.
1167	"""
1168	fRc = True;
1169	try:
1170	if fEnable:
1171	if self.fpApiVer >= 4.3:
1172	cOhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_OHCI);
1173	if cOhciCtls == 0:
1174	self.o.machine.addUSBController('OHCI', vboxcon.USBControllerType_OHCI);
1175	else:
1176	self.o.machine.usbController.enabled = True;
1177
1178	if self.fpApiVer >= 4.2:
1179	self.o.machine.pointingHIDType = vboxcon.PointingHIDType_ComboMouse;
1180	self.o.machine.keyboardHIDType = vboxcon.KeyboardHIDType_ComboKeyboard;
1181	else:
1182	self.o.machine.pointingHidType = vboxcon.PointingHidType_ComboMouse;
1183	self.o.machine.keyboardHidType = vboxcon.KeyboardHidType_ComboKeyboard;
1184	else:
1185	if self.fpApiVer >= 4.2:
1186	self.o.machine.pointingHIDType = vboxcon.PointingHIDType_PS2Mouse;
1187	self.o.machine.keyboardHIDType = vboxcon.KeyboardHIDType_PS2Keyboard;
1188	else:
1189	self.o.machine.pointingHidType = vboxcon.PointingHidType_PS2Mouse;
1190	self.o.machine.keyboardHidType = vboxcon.KeyboardHidType_PS2Keyboard;
1191	except:
1192	reporter.errorXcpt('failed to change UsbHid to %s for "%s"' % (fEnable, self.sName));
1193	fRc = False;
1194	else:
1195	reporter.log('changed UsbHid to %s for "%s"' % (fEnable, self.sName));
1196	self.oTstDrv.processPendingEvents();
1197	return fRc;
1198
1199	def enableUsbOhci(self, fEnable):
1200	"""
1201	Enables or disables the USB OHCI controller.
1202	Returns True on success and False on failure. Error information is logged.
1203	"""
1204	fRc = True;
1205	try:
1206	if fEnable:
1207	if self.fpApiVer >= 4.3:
1208	cOhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_OHCI);
1209	if cOhciCtls == 0:
1210	self.o.machine.addUSBController('OHCI', vboxcon.USBControllerType_OHCI);
1211	else:
1212	self.o.machine.usbController.enabled = True;
1213	else:
1214	if self.fpApiVer >= 4.3:
1215	cOhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_OHCI);
1216	if cOhciCtls == 1:
1217	self.o.machine.removeUSBController('OHCI');
1218	else:
1219	self.o.machine.usbController.enabled = False;
1220	except:
1221	reporter.errorXcpt('failed to change OHCI to %s for "%s"' % (fEnable, self.sName));
1222	fRc = False;
1223	else:
1224	reporter.log('changed OHCI to %s for "%s"' % (fEnable, self.sName));
1225	self.oTstDrv.processPendingEvents();
1226	return fRc;
1227
1228	def enableUsbEhci(self, fEnable):
1229	"""
1230	Enables or disables the USB EHCI controller, enables also OHCI if it is still disabled.
1231	Returns True on success and False on failure. Error information is logged.
1232	"""
1233	fRc = True;
1234	try:
1235	if fEnable:
1236	if self.fpApiVer >= 4.3:
1237	cOhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_OHCI);
1238	if cOhciCtls == 0:
1239	self.o.machine.addUSBController('OHCI', vboxcon.USBControllerType_OHCI);
1240
1241	cEhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_EHCI);
1242	if cEhciCtls == 0:
1243	self.o.machine.addUSBController('EHCI', vboxcon.USBControllerType_EHCI);
1244	else:
1245	self.o.machine.usbController.enabled = True;
1246	self.o.machine.usbController.enabledEHCI = True;
1247	else:
1248	if self.fpApiVer >= 4.3:
1249	cEhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_EHCI);
1250	if cEhciCtls == 1:
1251	self.o.machine.removeUSBController('EHCI');
1252	else:
1253	self.o.machine.usbController.enabledEHCI = False;
1254	except:
1255	reporter.errorXcpt('failed to change EHCI to %s for "%s"' % (fEnable, self.sName));
1256	fRc = False;
1257	else:
1258	reporter.log('changed EHCI to %s for "%s"' % (fEnable, self.sName));
1259	self.oTstDrv.processPendingEvents();
1260	return fRc;
1261
1262	def enableUsbXhci(self, fEnable):
1263	"""
1264	Enables or disables the USB XHCI controller. Error information is logged.
1265	"""
1266	fRc = True;
1267	try:
1268	if fEnable:
1269	cXhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_XHCI);
1270	if cXhciCtls == 0:
1271	self.o.machine.addUSBController('XHCI', vboxcon.USBControllerType_XHCI);
1272	else:
1273	cXhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_XHCI);
1274	if cXhciCtls == 1:
1275	self.o.machine.removeUSBController('XHCI');
1276	except:
1277	reporter.errorXcpt('failed to change XHCI to %s for "%s"' % (fEnable, self.sName));
1278	fRc = False;
1279	else:
1280	reporter.log('changed XHCI to %s for "%s"' % (fEnable, self.sName));
1281	self.oTstDrv.processPendingEvents();
1282	return fRc;
1283
1284	def setFirmwareType(self, eType):
1285	"""
1286	Sets the firmware type.
1287	Returns True on success and False on failure. Error information is logged.
1288	"""
1289	fRc = True;
1290	try:
1291	if self.fpApiVer >= 7.1:
1292	self.o.machine.firmwareSettings.firmwareType = eType;
1293	else:
1294	self.o.machine.firmwareType = eType;
1295	except:
1296	reporter.errorXcpt('failed to set firmwareType=%s for "%s"' % (eType, self.sName));
1297	fRc = False;
1298	else:
1299	reporter.log('set firmwareType=%s for "%s"' % (eType, self.sName));
1300	self.oTstDrv.processPendingEvents();
1301	return fRc;
1302
1303	def enableSecureBoot(self, fEnable, sUefiMokPathPrefix = None):
1304	"""
1305	Enables or disables Secure Boot. Error information is logged.
1306	"""
1307
1308	if self.fpApiVer >= 7.0:
1309
1310	fRc = True;
1311	try:
1312	self.o.machine.nonVolatileStore.initUefiVariableStore(0);
1313
1314	# Enroll necessary keys and signatures in case if Secure Boot needs to be turned ON.
1315	if fEnable:
1316	self.o.machine.nonVolatileStore.uefiVariableStore.enrollDefaultMsSignatures();
1317	self.o.machine.nonVolatileStore.uefiVariableStore.enrollOraclePlatformKey();
1318	if sUefiMokPathPrefix:
1319	if self.oTstDrv.uRevision >= 156564: # Backported IUefiVariableStore::addSignatureToMok() to 7.0.
1320	sFullName = self.oTstDrv.getFullResourceName(sUefiMokPathPrefix) + '.der';
1321	with open(sFullName, "rb") as der_file:
1322	self.o.machine.nonVolatileStore.uefiVariableStore.addSignatureToMok(bytearray(der_file.read()), \
1323	uuid.uuid4().hex, \
1324	vboxcon.SignatureType_X509);
1325	else:
1326	reporter.log('Warning: Enrolling own keys / signatures only available for 7.0 >= r156564. ' \
1327	'Guest Additions installation might fail!');
1328
1329	self.o.machine.nonVolatileStore.uefiVariableStore.secureBootEnabled = fEnable;
1330	except:
1331	reporter.errorXcpt('failed to change Secure Boot to %s for "%s"' % (fEnable, self.sName));
1332	fRc = False;
1333	else:
1334	reporter.log('changed Secure Boot to %s for "%s"' % (fEnable, self.sName));
1335	self.oTstDrv.processPendingEvents();
1336
1337	else:
1338	reporter.log('Secure Boot is only supported for API 7.0 or newer');
1339	fRc = False;
1340
1341	return fRc;
1342
1343	def setChipsetType(self, eType):
1344	"""
1345	Sets the chipset type.
1346	Returns True on success and False on failure. Error information is logged.
1347	"""
1348	fRc = True;
1349	try:
1350	if self.fpApiVer >= 7.1:
1351	self.o.machine.platform.chipsetType = eType;
1352	else:
1353	self.o.machine.chipsetType = eType;
1354	except:
1355	reporter.errorXcpt('failed to set chipsetType=%s for "%s"' % (eType, self.sName));
1356	fRc = False;
1357	else:
1358	reporter.log('set chipsetType=%s for "%s"' % (eType, self.sName));
1359	self.oTstDrv.processPendingEvents();
1360	return fRc;
1361
1362	def setIommuType(self, eType):
1363	"""
1364	Sets the IOMMU type.
1365	Returns True on success and False on failure. Error information is logged.
1366	"""
1367	# Supported.
1368	if self.fpApiVer < 6.2 or not hasattr(vboxcon, 'IommuType_Intel') or not hasattr(vboxcon, 'IommuType_AMD'):
1369	return True;
1370	fRc = True;
1371	try:
1372	if self.fpApiVer >= 7.1:
1373	self.o.machine.platform.iommuType = eType;
1374	else:
1375	self.o.machine.iommuType = eType;
1376	except:
1377	reporter.errorXcpt('failed to set iommuType=%s for "%s"' % (eType, self.sName));
1378	fRc = False;
1379	else:
1380	reporter.log('set iommuType=%s for "%s"' % (eType, self.sName));
1381	self.oTstDrv.processPendingEvents();
1382	return fRc;
1383
1384	def setupBootLogo(self, fEnable, cMsLogoDisplay = 0):
1385	"""
1386	Sets up the boot logo. fEnable toggles the fade and boot menu
1387	settings as well as the mode.
1388	"""
1389	fRc = True;
1390	try:
1391	if self.fpApiVer >= 7.1:
1392	fwSettings = self.o.machine.firmwareSettings;
1393	if fEnable:
1394	fwSettings.bootMenuMode = vboxcon.FirmwareBootMenuMode_Disabled;
1395	else:
1396	fwSettings.bootMenuMode = vboxcon.FirmwareBootMenuMode_MessageAndMenu;
1397	else:
1398	fwSettings = self.o.machine.BIOSSettings;
1399	if fEnable:
1400	fwSettings.bootMenuMode = vboxcon.BIOSBootMenuMode_Disabled;
1401	else:
1402	fwSettings.bootMenuMode = vboxcon.BIOSBootMenuMode_MessageAndMenu;
1403	fwSettings.logoFadeIn = not fEnable;
1404	fwSettings.logoFadeOut = not fEnable;
1405	fwSettings.logoDisplayTime = cMsLogoDisplay;
1406	except:
1407	reporter.errorXcpt('failed to set logoFadeIn/logoFadeOut/bootMenuMode=%s for "%s"' % (fEnable, self.sName));
1408	fRc = False;
1409	else:
1410	reporter.log('set logoFadeIn/logoFadeOut/bootMenuMode=%s for "%s"' % (fEnable, self.sName));
1411	self.oTstDrv.processPendingEvents();
1412	return fRc;
1413
1414	def setupVrdp(self, fEnable, uPort = None):
1415	"""
1416	Configures VRDP.
1417	"""
1418	fRc = True;
1419	try:
1420	if self.fpApiVer >= 4.0:
1421	self.o.machine.VRDEServer.enabled = fEnable;
1422	else:
1423	self.o.machine.VRDPServer.enabled = fEnable;
1424	except:
1425	reporter.errorXcpt('failed to set VRDEServer::enabled=%s for "%s"' % (fEnable, self.sName));
1426	fRc = False;
1427
1428	if uPort is not None and fRc:
1429	try:
1430	if self.fpApiVer >= 4.0:
1431	self.o.machine.VRDEServer.setVRDEProperty("TCP/Ports", str(uPort));
1432	else:
1433	self.o.machine.VRDPServer.ports = str(uPort);
1434	except:
1435	reporter.errorXcpt('failed to set VRDEServer::ports=%s for "%s"' % (uPort, self.sName));
1436	fRc = False;
1437	if fRc:
1438	reporter.log('set VRDEServer.enabled/ports=%s/%s for "%s"' % (fEnable, uPort, self.sName));
1439	self.oTstDrv.processPendingEvents();
1440	return fRc;
1441
1442	def getNicDriverNameFromType(self, eNicType):
1443	"""
1444	Helper that translate the adapter type into a driver name.
1445	"""
1446	if eNicType in (vboxcon.NetworkAdapterType_Am79C970A, vboxcon.NetworkAdapterType_Am79C973):
1447	sName = 'pcnet';
1448	elif eNicType in (vboxcon.NetworkAdapterType_I82540EM,
1449	vboxcon.NetworkAdapterType_I82543GC,
1450	vboxcon.NetworkAdapterType_I82545EM):
1451	sName = 'e1000';
1452	elif eNicType == vboxcon.NetworkAdapterType_Virtio:
1453	sName = 'virtio-net';
1454	else:
1455	reporter.error('Unknown adapter type "%s" (VM: "%s")' % (eNicType, self.sName));
1456	sName = 'pcnet';
1457	return sName;
1458
1459	def setupNatForwardingForTxs(self, iNic = 0, iHostPort = 5042):
1460	"""
1461	Sets up NAT forwarding for port 5042 if applicable, cleans up if not.
1462	"""
1463	try:
1464	oNic = self.o.machine.getNetworkAdapter(iNic);
1465	except:
1466	reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName));
1467	return False;
1468
1469	# Nuke the old setup for all possible adapter types (in case we're
1470	# called after it changed).
1471	for sName in ('pcnet', 'e1000', 'virtio-net'):
1472	for sConfig in ('VBoxInternal/Devices/%s/%u/LUN#0/AttachedDriver/Config' % (sName, iNic), \
1473	'VBoxInternal/Devices/%s/%u/LUN#0/Config' % (sName, iNic)):
1474	try:
1475	self.o.machine.setExtraData('%s/txs/Protocol' % (sConfig), '');
1476	self.o.machine.setExtraData('%s/txs/HostPort' % (sConfig), '');
1477	self.o.machine.setExtraData('%s/txs/GuestPort' % (sConfig), '');
1478	except:
1479	reporter.errorXcpt();
1480
1481	# Set up port forwarding if NAT attachment.
1482	try:
1483	eAttType = oNic.attachmentType;
1484	except:
1485	reporter.errorXcpt('attachmentType on %s failed for "%s"' % (iNic, self.sName));
1486	return False;
1487	if eAttType != vboxcon.NetworkAttachmentType_NAT:
1488	return True;
1489
1490	try:
1491	eNicType = oNic.adapterType;
1492	fTraceEnabled = oNic.traceEnabled;
1493	except:
1494	reporter.errorXcpt('attachmentType/traceEnabled on %s failed for "%s"' % (iNic, self.sName));
1495	return False;
1496
1497	if self.fpApiVer >= 4.1:
1498	try:
1499	if self.fpApiVer >= 4.2:
1500	oNatEngine = oNic.NATEngine;
1501	else:
1502	oNatEngine = oNic.natDriver;
1503	except:
1504	reporter.errorXcpt('Failed to get INATEngine data on "%s"' % (self.sName));
1505	return False;
1506	try: oNatEngine.removeRedirect('txs');
1507	except: pass;
1508	try:
1509	oNatEngine.addRedirect('txs', vboxcon.NATProtocol_TCP, '127.0.0.1', '%s' % (iHostPort), '', '5042');
1510	except:
1511	reporter.errorXcpt('Failed to add a addRedirect redirect on "%s"' % (self.sName));
1512	return False;
1513
1514	else:
1515	sName = self.getNicDriverNameFromType(eNicType);
1516	if fTraceEnabled:
1517	sConfig = 'VBoxInternal/Devices/%s/%u/LUN#0/AttachedDriver/Config' % (sName, iNic)
1518	else:
1519	sConfig = 'VBoxInternal/Devices/%s/%u/LUN#0/Config' % (sName, iNic)
1520
1521	try:
1522	self.o.machine.setExtraData('%s/txs/Protocol' % (sConfig), 'TCP');
1523	self.o.machine.setExtraData('%s/txs/HostPort' % (sConfig), '%s' % (iHostPort));
1524	self.o.machine.setExtraData('%s/txs/GuestPort' % (sConfig), '5042');
1525	except:
1526	reporter.errorXcpt('Failed to set NAT extra data on "%s"' % (self.sName));
1527	return False;
1528	return True;
1529
1530	def setNicType(self, eType, iNic = 0):
1531	"""
1532	Sets the NIC type of the specified NIC.
1533	Returns True on success and False on failure. Error information is logged.
1534	"""
1535	try:
1536	try:
1537	oNic = self.o.machine.getNetworkAdapter(iNic);
1538	except:
1539	reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName));
1540	return False;
1541	try:
1542	oNic.adapterType = eType;
1543	except:
1544	reporter.errorXcpt('failed to set NIC type on slot %s to %s for VM "%s"' % (iNic, eType, self.sName));
1545	return False;
1546	finally:
1547	self.oTstDrv.processPendingEvents();
1548
1549	if not self.setupNatForwardingForTxs(iNic):
1550	return False;
1551	reporter.log('set NIC type on slot %s to %s for VM "%s"' % (iNic, eType, self.sName));
1552	return True;
1553
1554	def setNicTraceEnabled(self, fTraceEnabled, sTraceFile, iNic = 0):
1555	"""
1556	Sets the NIC trace enabled flag and file path.
1557	Returns True on success and False on failure. Error information is logged.
1558	"""
1559	try:
1560	try:
1561	oNic = self.o.machine.getNetworkAdapter(iNic);
1562	except:
1563	reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName));
1564	return False;
1565	try:
1566	oNic.traceEnabled = fTraceEnabled;
1567	oNic.traceFile = sTraceFile;
1568	except:
1569	reporter.errorXcpt('failed to set NIC trace flag on slot %s to %s for VM "%s"' \
1570	% (iNic, fTraceEnabled, self.sName));
1571	return False;
1572	finally:
1573	self.oTstDrv.processPendingEvents();
1574
1575	if not self.setupNatForwardingForTxs(iNic):
1576	return False;
1577	reporter.log('set NIC trace on slot %s to "%s" (path "%s") for VM "%s"' %
1578	(iNic, fTraceEnabled, sTraceFile, self.sName));
1579	return True;
1580
1581	def getDefaultNicName(self, eAttachmentType):
1582	"""
1583	Return the default network / interface name for the NIC attachment type.
1584	"""
1585	sRetName = '';
1586	if eAttachmentType == vboxcon.NetworkAttachmentType_Bridged:
1587	if self.oTstDrv.sDefBridgedNic is not None:
1588	sRetName = self.oTstDrv.sDefBridgedNic;
1589	else:
1590	sRetName = 'eth0';
1591	try:
1592	aoHostNics = self.oVBoxMgr.getArray(self.oVBox.host, 'networkInterfaces');
1593	for oHostNic in aoHostNics:
1594	if oHostNic.interfaceType == vboxcon.HostNetworkInterfaceType_Bridged \
1595	and oHostNic.status == vboxcon.HostNetworkInterfaceStatus_Up:
1596	sRetName = oHostNic.name;
1597	break;
1598	except:
1599	reporter.errorXcpt();
1600
1601	elif eAttachmentType == vboxcon.NetworkAttachmentType_HostOnly:
1602	try:
1603	aoHostNics = self.oVBoxMgr.getArray(self.oVBox.host, 'networkInterfaces');
1604	for oHostNic in aoHostNics:
1605	if oHostNic.interfaceType == vboxcon.HostNetworkInterfaceType_HostOnly:
1606	if oHostNic.status == vboxcon.HostNetworkInterfaceStatus_Up:
1607	sRetName = oHostNic.name;
1608	break;
1609	if sRetName == '':
1610	sRetName = oHostNic.name;
1611	except:
1612	reporter.errorXcpt();
1613	if sRetName == '':
1614	# Create a new host-only interface.
1615	reporter.log("Creating host only NIC ...");
1616	try:
1617	(oIProgress, oIHostOnly) = self.oVBox.host.createHostOnlyNetworkInterface();
1618	oProgress = ProgressWrapper(oIProgress, self.oVBoxMgr, self.oTstDrv, 'Create host only NIC');
1619	oProgress.wait();
1620	if oProgress.logResult() is False:
1621	return '';
1622	sRetName = oIHostOnly.name;
1623	except:
1624	reporter.errorXcpt();
1625	return '';
1626	reporter.log("Created host only NIC: '%s'" % (sRetName,));
1627
1628	elif self.fpApiVer >= 7.0 and eAttachmentType == vboxcon.NetworkAttachmentType_HostOnlyNetwork:
1629	aoHostNetworks = self.oVBoxMgr.getArray(self.oVBox, 'hostOnlyNetworks');
1630	if aoHostNetworks:
1631	sRetName = aoHostNetworks[0].networkName;
1632	else:
1633	try:
1634	oHostOnlyNet = self.oVBox.createHostOnlyNetwork('Host-only Test Network');
1635	oHostOnlyNet.lowerIP = '192.168.56.1';
1636	oHostOnlyNet.upperIP = '192.168.56.199';
1637	oHostOnlyNet.networkMask = '255.255.255.0';
1638	sRetName = oHostOnlyNet.networkName;
1639	except:
1640	reporter.errorXcpt();
1641	return '';
1642
1643	elif eAttachmentType == vboxcon.NetworkAttachmentType_Internal:
1644	sRetName = 'VBoxTest';
1645
1646	elif eAttachmentType == vboxcon.NetworkAttachmentType_NAT:
1647	sRetName = '';
1648
1649	else: ## @todo Support NetworkAttachmentType_NATNetwork
1650	reporter.error('eAttachmentType=%s is not known' % (eAttachmentType));
1651	return sRetName;
1652
1653	def setNicAttachment(self, eAttachmentType, sName = None, iNic = 0):
1654	"""
1655	Sets the attachment type of the specified NIC.
1656	Returns True on success and False on failure. Error information is logged.
1657	"""
1658	try:
1659	oNic = self.o.machine.getNetworkAdapter(iNic);
1660	except:
1661	reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName));
1662	return False;
1663
1664	try:
1665	if eAttachmentType is not None:
1666	try:
1667	if self.fpApiVer >= 4.1:
1668	oNic.attachmentType = eAttachmentType;
1669	else:
1670	if eAttachmentType == vboxcon.NetworkAttachmentType_NAT:
1671	oNic.attachToNAT();
1672	elif eAttachmentType == vboxcon.NetworkAttachmentType_Bridged:
1673	oNic.attachToBridgedInterface();
1674	elif eAttachmentType == vboxcon.NetworkAttachmentType_Internal:
1675	oNic.attachToInternalNetwork();
1676	elif eAttachmentType == vboxcon.NetworkAttachmentType_HostOnly:
1677	oNic.attachToHostOnlyInterface();
1678	else:
1679	raise base.GenError("eAttachmentType=%s is invalid" % (eAttachmentType));
1680	except:
1681	reporter.errorXcpt('failed to set the attachment type on slot %s to %s for VM "%s"' \
1682	% (iNic, eAttachmentType, self.sName));
1683	return False;
1684	else:
1685	try:
1686	eAttachmentType = oNic.attachmentType;
1687	except:
1688	reporter.errorXcpt('failed to get the attachment type on slot %s for VM "%s"' % (iNic, self.sName));
1689	return False;
1690	finally:
1691	self.oTstDrv.processPendingEvents();
1692
1693	if sName is not None:
1694	# Resolve the special 'default' name.
1695	if sName == 'default':
1696	sName = self.getDefaultNicName(eAttachmentType);
1697
1698	# The name translate to different attributes depending on the
1699	# attachment type.
1700	try:
1701	if eAttachmentType == vboxcon.NetworkAttachmentType_Bridged:
1702	## @todo check this out on windows, may have to do a
1703	# translation of the name there or smth IIRC.
1704	try:
1705	if self.fpApiVer >= 4.1:
1706	oNic.bridgedInterface = sName;
1707	else:
1708	oNic.hostInterface = sName;
1709	except:
1710	reporter.errorXcpt('failed to set the hostInterface property on slot %s to "%s" for VM "%s"'
1711	% (iNic, sName, self.sName,));
1712	return False;
1713	elif eAttachmentType == vboxcon.NetworkAttachmentType_HostOnly:
1714	try:
1715	if self.fpApiVer >= 4.1:
1716	oNic.hostOnlyInterface = sName;
1717	else:
1718	oNic.hostInterface = sName;
1719	except:
1720	reporter.errorXcpt('failed to set the internalNetwork property on slot %s to "%s" for VM "%s"'
1721	% (iNic, sName, self.sName,));
1722	return False;
1723	elif self.fpApiVer >= 7.0 and eAttachmentType == vboxcon.NetworkAttachmentType_HostOnlyNetwork:
1724	try:
1725	oNic.hostOnlyNetwork = sName;
1726	except:
1727	reporter.errorXcpt('failed to set the hostOnlyNetwork property on slot %s to "%s" for VM "%s"'
1728	% (iNic, sName, self.sName,));
1729	return False;
1730	elif eAttachmentType == vboxcon.NetworkAttachmentType_Internal:
1731	try:
1732	oNic.internalNetwork = sName;
1733	except:
1734	reporter.errorXcpt('failed to set the internalNetwork property on slot %s to "%s" for VM "%s"'
1735	% (iNic, sName, self.sName,));
1736	return False;
1737	elif eAttachmentType == vboxcon.NetworkAttachmentType_NAT:
1738	try:
1739	oNic.NATNetwork = sName;
1740	except:
1741	reporter.errorXcpt('failed to set the NATNetwork property on slot %s to "%s" for VM "%s"'
1742	% (iNic, sName, self.sName,));
1743	return False;
1744	finally:
1745	self.oTstDrv.processPendingEvents();
1746
1747	if not self.setupNatForwardingForTxs(iNic):
1748	return False;
1749	reporter.log('set NIC attachment type on slot %s to %s for VM "%s"' % (iNic, eAttachmentType, self.sName));
1750	return True;
1751
1752	def setNicLocalhostReachable(self, fReachable, iNic = 0):
1753	"""
1754	Sets whether the specified NIC can reach the host or not.
1755	Only affects (enabled) NICs configured to NAT at the moment.
1756
1757	Returns True on success and False on failure. Error information is logged.
1758	"""
1759	try:
1760	oNic = self.o.machine.getNetworkAdapter(iNic);
1761	except:
1762	return reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName,));
1763
1764	try:
1765	if not oNic.enabled: # NIC not enabled? Nothing to do here.
1766	return True;
1767	except:
1768	return reporter.errorXcpt('NIC enabled status (%s) failed for "%s"' % (iNic, self.sName,));
1769
1770	reporter.log('Setting "LocalhostReachable" for network adapter in slot %d to %s' % (iNic, fReachable));
1771
1772	try:
1773	oNatEngine = oNic.NATEngine;
1774	except:
1775	return reporter.errorXcpt('Getting NIC NAT engine (%s) failed for "%s"' % (iNic, self.sName,));
1776
1777	try:
1778	if hasattr(oNatEngine, "localhostReachable"):
1779	oNatEngine.localhostReachable = fReachable;
1780	else:
1781	oNatEngine.LocalhostReachable = fReachable;
1782	except:
1783	return reporter.errorXcpt('LocalhostReachable (%s) failed for "%s"' % (iNic, self.sName,));
1784
1785	return True;
1786
1787	def setNicMacAddress(self, sMacAddr, iNic = 0):
1788	"""
1789	Sets the MAC address of the specified NIC.
1790
1791	The sMacAddr parameter is a string supplying the tail end of the MAC
1792	address, missing quads are supplied from a constant byte (2), the IPv4
1793	address of the host, and the NIC number.
1794
1795	Returns True on success and False on failure. Error information is logged.
1796	"""
1797
1798	# Resolve missing MAC address prefix by feeding in the host IP address bytes.
1799	cchMacAddr = len(sMacAddr);
1800	if 0 < cchMacAddr < 12:
1801	sHostIP = netutils.getPrimaryHostIp();
1802	abHostIP = socket.inet_aton(sHostIP);
1803	if sys.version_info[0] < 3:
1804	abHostIP = (ord(abHostIP[0]), ord(abHostIP[1]), ord(abHostIP[2]), ord(abHostIP[3]));
1805
1806	if abHostIP[0] == 127 \
1807	or (abHostIP[0] == 169 and abHostIP[1] == 254) \
1808	or (abHostIP[0] == 192 and abHostIP[1] == 168 and abHostIP[2] == 56):
1809	return reporter.error('host IP for "%s" is %s, most likely not unique.' % (netutils.getHostnameFqdn(), sHostIP,));
1810
1811	sDefaultMac = '%02X%02X%02X%02X%02X%02X' % (0x02, abHostIP[0], abHostIP[1], abHostIP[2], abHostIP[3], iNic);
1812	sMacAddr = sDefaultMac[0:(12 - cchMacAddr)] + sMacAddr;
1813
1814	# Get the NIC object and try set it address.
1815	try:
1816	oNic = self.o.machine.getNetworkAdapter(iNic);
1817	except:
1818	return reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName,));
1819
1820	try:
1821	oNic.MACAddress = sMacAddr;
1822	except:
1823	return reporter.errorXcpt('failed to set the MAC address on slot %s to "%s" for VM "%s"'
1824	% (iNic, sMacAddr, self.sName));
1825
1826	reporter.log('set MAC address on slot %s to %s for VM "%s"' % (iNic, sMacAddr, self.sName,));
1827	return True;
1828
1829	def setRamSize(self, cMB):
1830	"""
1831	Set the RAM size of the VM.
1832	Returns True on success and False on failure. Error information is logged.
1833	"""
1834	fRc = True;
1835	try:
1836	self.o.machine.memorySize = cMB;
1837	except:
1838	reporter.errorXcpt('failed to set the RAM size of "%s" to %s' % (self.sName, cMB));
1839	fRc = False;
1840	else:
1841	reporter.log('set the RAM size of "%s" to %s' % (self.sName, cMB));
1842	self.oTstDrv.processPendingEvents();
1843	return fRc;
1844
1845	def setLargePagesX86(self, fUseLargePages):
1846	"""
1847	Configures whether the VM should use large pages or not. x86 only.
1848	Returns True on success and False on failure. Error information is logged.
1849
1850	Ignored on non-x86 platform architectures.
1851	"""
1852	if not self.isPlatformX86(): return True;
1853	fRc = True;
1854	try:
1855	if self.fpApiVer >= 7.1:
1856	self.o.machine.platform.x86.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_LargePages, fUseLargePages);
1857	else:
1858	self.o.machine.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_LargePages, fUseLargePages);
1859	except:
1860	reporter.errorXcpt('failed to set large pages of "%s" to %s' % (self.sName, fUseLargePages));
1861	fRc = False;
1862	else:
1863	reporter.log('set the large pages of "%s" to %s' % (self.sName, fUseLargePages));
1864	self.oTstDrv.processPendingEvents();
1865	return fRc;
1866
1867	def setVRamSize(self, cMB):
1868	"""
1869	Set the RAM size of the VM.
1870	Returns True on success and False on failure. Error information is logged.
1871	"""
1872	fRc = True;
1873	try:
1874	if self.fpApiVer >= 6.1 and hasattr(self.o.machine, 'graphicsAdapter'):
1875	self.o.machine.graphicsAdapter.VRAMSize = cMB;
1876	else:
1877	self.o.machine.VRAMSize = cMB;
1878	except:
1879	reporter.errorXcpt('failed to set the VRAM size of "%s" to %s' % (self.sName, cMB));
1880	fRc = False;
1881	else:
1882	reporter.log('set the VRAM size of "%s" to %s' % (self.sName, cMB));
1883	self.oTstDrv.processPendingEvents();
1884	return fRc;
1885
1886	def setVideoControllerType(self, eControllerType):
1887	"""
1888	Set the video controller type of the VM.
1889	Returns True on success and False on failure. Error information is logged.
1890	"""
1891	fRc = True;
1892	try:
1893	if self.fpApiVer >= 6.1 and hasattr(self.o.machine, 'graphicsAdapter'):
1894	self.o.machine.graphicsAdapter.graphicsControllerType = eControllerType;
1895	else:
1896	self.o.machine.graphicsControllerType = eControllerType;
1897	except:
1898	reporter.errorXcpt('failed to set the video controller type of "%s" to %s' % (self.sName, eControllerType));
1899	fRc = False;
1900	else:
1901	reporter.log('set the video controller type of "%s" to %s' % (self.sName, eControllerType));
1902	self.oTstDrv.processPendingEvents();
1903	return fRc;
1904
1905	def setAccelerate3DEnabled(self, fEnabled):
1906	"""
1907	Set the video controller type of the VM.
1908	Returns True on success and False on failure. Error information is logged.
1909	"""
1910	fRc = True;
1911	try:
1912	if self.fpApiVer >= 6.1 and hasattr(self.o.machine, 'graphicsAdapter'):
1913	self.o.machine.graphicsAdapter.accelerate3DEnabled = fEnabled;
1914	else:
1915	self.o.machine.accelerate3DEnabled = fEnabled;
1916	except:
1917	reporter.errorXcpt('failed to set the accelerate3DEnabled of "%s" to %s' % (self.sName, fEnabled));
1918	fRc = False;
1919	else:
1920	reporter.log('set the accelerate3DEnabled of "%s" to %s' % (self.sName, fEnabled));
1921	self.oTstDrv.processPendingEvents();
1922	return fRc;
1923
1924	def setCpuCount(self, cCpus):
1925	"""
1926	Set the number of CPUs.
1927	Returns True on success and False on failure. Error information is logged.
1928	"""
1929	fRc = True;
1930	try:
1931	self.o.machine.CPUCount = cCpus;
1932	except:
1933	reporter.errorXcpt('failed to set the CPU count of "%s" to %s' % (self.sName, cCpus));
1934	fRc = False;
1935	else:
1936	reporter.log('set the CPU count of "%s" to %s' % (self.sName, cCpus));
1937	self.oTstDrv.processPendingEvents();
1938	return fRc;
1939
1940	def getCpuCount(self):
1941	"""
1942	Returns the number of CPUs.
1943	Returns the number of CPUs on success and 0 on failure. Error information is logged.
1944	"""
1945	cCpus = 0;
1946	try:
1947	cCpus = self.o.machine.CPUCount;
1948	except:
1949	reporter.errorXcpt('failed to get the CPU count of "%s"' % (self.sName,));
1950
1951	self.oTstDrv.processPendingEvents();
1952	return cCpus;
1953
1954	def ensureControllerAttached(self, sController):
1955	"""
1956	Makes sure the specified controller is attached to the VM, attaching it
1957	if necessary.
1958	"""
1959	try:
1960	try:
1961	self.o.machine.getStorageControllerByName(sController);
1962	except:
1963	(eBus, eType) = _ControllerNameToBusAndType(sController);
1964	try:
1965	oCtl = self.o.machine.addStorageController(sController, eBus);
1966	except:
1967	reporter.errorXcpt('addStorageController("%s",%s) failed on "%s"' % (sController, eBus, self.sName) );
1968	return False;
1969	try:
1970	oCtl.controllerType = eType;
1971	reporter.log('added storage controller "%s" (bus %s, type %s) to %s'
1972	% (sController, eBus, eType, self.sName));
1973	except:
1974	reporter.errorXcpt('controllerType = %s on ("%s" / %s) failed on "%s"'
1975	% (eType, sController, eBus, self.sName) );
1976	return False;
1977	finally:
1978	self.oTstDrv.processPendingEvents();
1979	return True;
1980
1981	def setStorageControllerPortCount(self, sController, iPortCount):
1982	"""
1983	Set maximum ports count for storage controller
1984	"""
1985	try:
1986	oCtl = self.o.machine.getStorageControllerByName(sController)
1987	oCtl.portCount = iPortCount
1988	self.oTstDrv.processPendingEvents()
1989	reporter.log('set controller "%s" port count to value %d' % (sController, iPortCount))
1990	return True
1991	except:
1992	reporter.log('unable to set storage controller "%s" ports count to %d' % (sController, iPortCount))
1993
1994	return False
1995
1996	def setStorageControllerHostIoCache(self, sController, fUseHostIoCache):
1997	"""
1998	Set maximum ports count for storage controller
1999	"""
2000	try:
2001	oCtl = self.o.machine.getStorageControllerByName(sController);
2002	oCtl.useHostIOCache = fUseHostIoCache;
2003	self.oTstDrv.processPendingEvents();
2004	reporter.log('set controller "%s" host I/O cache setting to %r' % (sController, fUseHostIoCache));
2005	return True;
2006	except:
2007	reporter.log('unable to set storage controller "%s" host I/O cache setting to %r' % (sController, fUseHostIoCache));
2008
2009	return False;
2010
2011	def setBootOrder(self, iPosition, eType):
2012	"""
2013	Set guest boot order type
2014	@param iPosition boot order position
2015	@param eType device type (vboxcon.DeviceType_HardDisk,
2016	vboxcon.DeviceType_DVD, vboxcon.DeviceType_Floppy)
2017	"""
2018	try:
2019	self.o.machine.setBootOrder(iPosition, eType)
2020	except:
2021	return reporter.errorXcpt('Unable to set boot order.')
2022
2023	reporter.log('Set boot order [%d] for device %s' % (iPosition, str(eType)))
2024	self.oTstDrv.processPendingEvents();
2025
2026	return True
2027
2028	def setStorageControllerType(self, eType, sController = "IDE Controller"):
2029	"""
2030	Similar to ensureControllerAttached, except it will change the type.
2031	"""
2032	try:
2033	oCtl = self.o.machine.getStorageControllerByName(sController);
2034	except:
2035	(eBus, _) = _ControllerNameToBusAndType(sController);
2036	try:
2037	oCtl = self.o.machine.addStorageController(sController, eBus);
2038	reporter.log('added storage controller "%s" (bus %s) to %s' % (sController, eBus, self.sName));
2039	except:
2040	reporter.errorXcpt('addStorageController("%s",%s) failed on "%s"' % (sController, eBus, self.sName) );
2041	return False;
2042	try:
2043	oCtl.controllerType = eType;
2044	except:
2045	reporter.errorXcpt('failed to set controller type of "%s" on "%s" to %s' % (sController, self.sName, eType) );
2046	return False;
2047	reporter.log('set controller type of "%s" on "%s" to %s' % (sController, self.sName, eType) );
2048	self.oTstDrv.processPendingEvents();
2049	return True;
2050
2051	def attachDvd(self, sImage = None, sController = "IDE Controller", iPort = 1, iDevice = 0):
2052	"""
2053	Attaches a DVD drive to a VM, optionally with an ISO inserted.
2054	Returns True on success and False on failure. Error information is logged.
2055	"""
2056	# Input validation.
2057	if sImage is not None and not self.oTstDrv.isResourceFile(sImage)\
2058	and not os.path.isabs(sImage): ## fixme - testsuite unzip ++
2059	reporter.fatal('"%s" is not in the resource set' % (sImage));
2060	return None;
2061
2062	if not self.ensureControllerAttached(sController):
2063	return False;
2064
2065	# Find/register the image if specified.
2066	oImage = None;
2067	sImageUuid = "";
2068	if sImage is not None:
2069	sFullName = self.oTstDrv.getFullResourceName(sImage)
2070	try:
2071	oImage = self.oVBox.findDVDImage(sFullName);
2072	except:
2073	try:
2074	if self.fpApiVer >= 4.1:
2075	oImage = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_DVD, vboxcon.AccessMode_ReadOnly, False);
2076	elif self.fpApiVer >= 4.0:
2077	oImage = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_DVD, vboxcon.AccessMode_ReadOnly);
2078	else:
2079	oImage = self.oVBox.openDVDImage(sFullName, "");
2080	except vbox.ComException as oXcpt:
2081	if oXcpt.errno != -1:
2082	reporter.errorXcpt('failed to open DVD image "%s" xxx' % (sFullName));
2083	else:
2084	reporter.errorXcpt('failed to open DVD image "%s" yyy' % (sFullName));
2085	return False;
2086	except:
2087	reporter.errorXcpt('failed to open DVD image "%s"' % (sFullName));
2088	return False;
2089	try:
2090	sImageUuid = oImage.id;
2091	except:
2092	reporter.errorXcpt('failed to get the UUID of "%s"' % (sFullName));
2093	return False;
2094
2095	# Attach the DVD.
2096	fRc = True;
2097	try:
2098	if self.fpApiVer >= 4.0:
2099	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_DVD, oImage);
2100	else:
2101	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_DVD, sImageUuid);
2102	except:
2103	reporter.errorXcpt('attachDevice("%s",%s,%s,HardDisk,"%s") failed on "%s"' \
2104	% (sController, iPort, iDevice, sImageUuid, self.sName) );
2105	fRc = False;
2106	else:
2107	reporter.log('attached DVD to %s, image="%s"' % (self.sName, sImage));
2108	self.oTstDrv.processPendingEvents();
2109	return fRc;
2110
2111	def attachHd(self, sHd, sController = "IDE Controller", iPort = 0, iDevice = 0, fImmutable = True, fForceResource = True):
2112	"""
2113	Attaches a HD to a VM.
2114	Returns True on success and False on failure. Error information is logged.
2115	"""
2116	# Input validation.
2117	if fForceResource and not self.oTstDrv.isResourceFile(sHd):
2118	reporter.fatal('"%s" is not in the resource set' % (sHd,));
2119	return None;
2120
2121	if not self.ensureControllerAttached(sController):
2122	return False;
2123
2124	# Find the HD, registering it if necessary (as immutable).
2125	if fForceResource:
2126	sFullName = self.oTstDrv.getFullResourceName(sHd);
2127	else:
2128	sFullName = sHd;
2129	try:
2130	oHd = self.oVBox.findHardDisk(sFullName);
2131	except:
2132	try:
2133	if self.fpApiVer >= 4.1:
2134	oHd = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_HardDisk, vboxcon.AccessMode_ReadOnly, False);
2135	elif self.fpApiVer >= 4.0:
2136	oHd = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_HardDisk, vboxcon.AccessMode_ReadOnly);
2137	else:
2138	oHd = self.oVBox.openHardDisk(sFullName, vboxcon.AccessMode_ReadOnly, False, "", False, "");
2139	except:
2140	reporter.errorXcpt('failed to open hd "%s"' % (sFullName));
2141	return False;
2142	try:
2143	if fImmutable:
2144	oHd.type = vboxcon.MediumType_Immutable;
2145	else:
2146	oHd.type = vboxcon.MediumType_Normal;
2147	except:
2148	if fImmutable:
2149	reporter.errorXcpt('failed to set hd "%s" immutable' % (sHd));
2150	else:
2151	reporter.errorXcpt('failed to set hd "%s" normal' % (sHd));
2152	return False;
2153
2154	# Attach it.
2155	fRc = True;
2156	try:
2157	if self.fpApiVer >= 4.0:
2158	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_HardDisk, oHd);
2159	else:
2160	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_HardDisk, oHd.id);
2161	except:
2162	reporter.errorXcpt('attachDevice("%s",%s,%s,HardDisk,"%s") failed on "%s"' \
2163	% (sController, iPort, iDevice, oHd.id, self.sName) );
2164	fRc = False;
2165	else:
2166	reporter.log('attached "%s" to %s' % (sHd, self.sName));
2167	self.oTstDrv.processPendingEvents();
2168	return fRc;
2169
2170	def createBaseHd(self, sHd, sFmt = "VDI", cb = 1010241024*1024, cMsTimeout = 60000, tMediumVariant = None):
2171	"""
2172	Creates a base HD.
2173	Returns Medium object on success and None on failure. Error information is logged.
2174	"""
2175	if tMediumVariant is None:
2176	tMediumVariant = (vboxcon.MediumVariant_Standard, );
2177
2178	try:
2179	if self.fpApiVer >= 5.0:
2180	oHd = self.oVBox.createMedium(sFmt, sHd, vboxcon.AccessMode_ReadWrite, vboxcon.DeviceType_HardDisk);
2181	else:
2182	oHd = self.oVBox.createHardDisk(sFmt, sHd);
2183	oProgressXpcom = oHd.createBaseStorage(cb, tMediumVariant);
2184	oProgress = ProgressWrapper(oProgressXpcom, self.oVBoxMgr, self.oTstDrv, 'create base disk %s' % (sHd));
2185	oProgress.wait(cMsTimeout);
2186	oProgress.logResult();
2187	except:
2188	reporter.errorXcpt('failed to create base hd "%s"' % (sHd));
2189	oHd = None
2190
2191	return oHd;
2192
2193	def createDiffHd(self, oParentHd, sHd, sFmt = "VDI"):
2194	"""
2195	Creates a differencing HD.
2196	Returns Medium object on success and None on failure. Error information is logged.
2197	"""
2198	# Detect the proper format if requested
2199	if sFmt is None:
2200	try:
2201	oHdFmt = oParentHd.mediumFormat;
2202	lstCaps = self.oVBoxMgr.getArray(oHdFmt, 'capabilities');
2203	if vboxcon.MediumFormatCapabilities_Differencing in lstCaps:
2204	sFmt = oHdFmt.id;
2205	else:
2206	sFmt = 'VDI';
2207	except:
2208	reporter.errorXcpt('failed to get preferred diff format for "%s"' % (sHd));
2209	return None;
2210	try:
2211	if self.fpApiVer >= 5.0:
2212	oHd = self.oVBox.createMedium(sFmt, sHd, vboxcon.AccessMode_ReadWrite, vboxcon.DeviceType_HardDisk);
2213	else:
2214	oHd = self.oVBox.createHardDisk(sFmt, sHd);
2215	oProgressXpcom = oParentHd.createDiffStorage(oHd, (vboxcon.MediumVariant_Standard, ))
2216	oProgress = ProgressWrapper(oProgressXpcom, self.oVBoxMgr, self.oTstDrv, 'create diff disk %s' % (sHd));
2217	oProgress.wait();
2218	oProgress.logResult();
2219	except:
2220	reporter.errorXcpt('failed to create diff hd "%s"' % (sHd));
2221	oHd = None
2222
2223	return oHd;
2224
2225	def createAndAttachHd(self, sHd, sFmt = "VDI", sController = "IDE Controller", cb = 1010241024*1024, # pylint: disable=too-many-arguments
2226	iPort = 0, iDevice = 0, fImmutable = True, cMsTimeout = 60000, tMediumVariant = None):
2227	"""
2228	Creates and attaches a HD to a VM.
2229	Returns True on success and False on failure. Error information is logged.
2230	"""
2231	if not self.ensureControllerAttached(sController):
2232	return False;
2233
2234	oHd = self.createBaseHd(sHd, sFmt, cb, cMsTimeout, tMediumVariant);
2235	if oHd is None:
2236	return False;
2237
2238	fRc = True;
2239	try:
2240	if fImmutable:
2241	oHd.type = vboxcon.MediumType_Immutable;
2242	else:
2243	oHd.type = vboxcon.MediumType_Normal;
2244	except:
2245	if fImmutable:
2246	reporter.errorXcpt('failed to set hd "%s" immutable' % (sHd));
2247	else:
2248	reporter.errorXcpt('failed to set hd "%s" normal' % (sHd));
2249	fRc = False;
2250
2251	# Attach it.
2252	if fRc is True:
2253	try:
2254	if self.fpApiVer >= 4.0:
2255	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_HardDisk, oHd);
2256	else:
2257	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_HardDisk, oHd.id);
2258	except:
2259	reporter.errorXcpt('attachDevice("%s",%s,%s,HardDisk,"%s") failed on "%s"' \
2260	% (sController, iPort, iDevice, oHd.id, self.sName) );
2261	fRc = False;
2262	else:
2263	reporter.log('attached "%s" to %s' % (sHd, self.sName));
2264
2265	# Delete disk in case of an error
2266	if fRc is False:
2267	try:
2268	oProgressCom = oHd.deleteStorage();
2269	except:
2270	reporter.errorXcpt('deleteStorage() for disk %s failed' % (sHd,));
2271	else:
2272	oProgress = ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oTstDrv, 'delete disk %s' % (sHd));
2273	oProgress.wait();
2274	oProgress.logResult();
2275
2276	self.oTstDrv.processPendingEvents();
2277	return fRc;
2278
2279	def detachHd(self, sController = "IDE Controller", iPort = 0, iDevice = 0):
2280	"""
2281	Detaches a HD, if attached, and returns a reference to it (IMedium).
2282
2283	In order to delete the detached medium, the caller must first save
2284	the changes made in this session.
2285
2286	Returns (fRc, oHd), where oHd is None unless fRc is True, and fRc is
2287	your standard success indicator. Error information is logged.
2288	"""
2289
2290	# What's attached?
2291	try:
2292	oHd = self.o.machine.getMedium(sController, iPort, iDevice);
2293	except:
2294	if self.oVBoxMgr.xcptIsOurXcptKind() \
2295	and self.oVBoxMgr.xcptIsEqual(None, self.oVBoxMgr.constants.VBOX_E_OBJECT_NOT_FOUND):
2296	reporter.log('No HD attached (to %s %s:%s)' % (sController, iPort, iDevice));
2297	return (True, None);
2298	return (reporter.errorXcpt('Error getting media at port %s, device %s, on %s.'
2299	% (iPort, iDevice, sController)), None);
2300	# Detach it.
2301	try:
2302	self.o.machine.detachDevice(sController, iPort, iDevice);
2303	except:
2304	return (reporter.errorXcpt('detachDevice("%s",%s,%s) failed on "%s"' \
2305	% (sController, iPort, iDevice, self.sName) ), None);
2306	reporter.log('detached HD ("%s",%s,%s) from %s' % (sController, iPort, iDevice, self.sName));
2307	return (True, oHd);
2308
2309	def attachFloppy(self, sFloppy, sController = "Floppy Controller", iPort = 0, iDevice = 0):
2310	"""
2311	Attaches a floppy image to a VM.
2312	Returns True on success and False on failure. Error information is logged.
2313	"""
2314	# Input validation.
2315	## @todo Fix this wrt to bootsector-xxx.img from the validationkit.zip.
2316	##if not self.oTstDrv.isResourceFile(sFloppy):
2317	## reporter.fatal('"%s" is not in the resource set' % (sFloppy));
2318	## return None;
2319
2320	if not self.ensureControllerAttached(sController):
2321	return False;
2322
2323	# Find the floppy image, registering it if necessary (as immutable).
2324	sFullName = self.oTstDrv.getFullResourceName(sFloppy);
2325	try:
2326	oFloppy = self.oVBox.findFloppyImage(sFullName);
2327	except:
2328	try:
2329	if self.fpApiVer >= 4.1:
2330	oFloppy = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_Floppy, vboxcon.AccessMode_ReadOnly, False);
2331	elif self.fpApiVer >= 4.0:
2332	oFloppy = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_Floppy, vboxcon.AccessMode_ReadOnly);
2333	else:
2334	oFloppy = self.oVBox.openFloppyImage(sFullName, "");
2335	except:
2336	reporter.errorXcpt('failed to open floppy "%s"' % (sFullName));
2337	return False;
2338	## @todo the following works but causes trouble below (asserts in main).
2339	#try:
2340	# oFloppy.type = vboxcon.MediumType_Immutable;
2341	#except:
2342	# reporter.errorXcpt('failed to make floppy "%s" immutable' % (sFullName));
2343	# return False;
2344
2345	# Attach it.
2346	fRc = True;
2347	try:
2348	if self.fpApiVer >= 4.0:
2349	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_Floppy, oFloppy);
2350	else:
2351	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_Floppy, oFloppy.id);
2352	except:
2353	reporter.errorXcpt('attachDevice("%s",%s,%s,Floppy,"%s") failed on "%s"' \
2354	% (sController, iPort, iDevice, oFloppy.id, self.sName) );
2355	fRc = False;
2356	else:
2357	reporter.log('attached "%s" to %s' % (sFloppy, self.sName));
2358	self.oTstDrv.processPendingEvents();
2359	return fRc;
2360
2361	def setupNic(self, sType, sXXX):
2362	"""
2363	Sets up a NIC to a VM.
2364	Returns True on success and False on failure. Error information is logged.
2365	"""
2366	if sType == "PCNet": enmType = vboxcon.NetworkAdapterType_Am79C973;
2367	elif sType == "PCNetOld": enmType = vboxcon.NetworkAdapterType_Am79C970A;
2368	elif sType == "E1000": enmType = vboxcon.NetworkAdapterType_I82545EM; # MT Server
2369	elif sType == "E1000Desk": enmType = vboxcon.NetworkAdapterType_I82540EM; # MT Desktop
2370	elif sType == "E1000Srv2": enmType = vboxcon.NetworkAdapterType_I82543GC; # T Server
2371	elif sType == "Virtio": enmType = vboxcon.NetworkAdapterType_Virtio;
2372	else:
2373	reporter.error('Invalid NIC type: "%s" (sXXX=%s)' % (sType, sXXX));
2374	return False;
2375	## @todo Implement me!
2376	if enmType is not None: pass
2377	return True;
2378
2379	def setupAudio(self, eAudioControllerType, fEnable = True, fEnableIn = False, fEnableOut = True, eAudioDriverType = None):
2380	"""
2381	Sets up audio.
2382
2383	:param eAudioControllerType: The audio controller type (vboxcon.AudioControllerType_XXX).
2384	:param fEnable: Whether to enable or disable the audio controller (default enable).
2385	:param fEnableIn: Whether to enable or disable audio input (default disable).
2386	:param fEnableOut: Whether to enable or disable audio output (default enable).
2387	:param eAudioDriverType: The audio driver type (vboxcon.AudioDriverType_XXX), picks something suitable
2388	if None is passed (default).
2389	"""
2390	try:
2391	if self.fpApiVer >= 7.0:
2392	oAdapter = self.o.machine.audioSettings.adapter;
2393	else:
2394	oAdapter = self.o.machine.audioAdapter;
2395	except: return reporter.errorXcpt('Failed to get the audio adapter.');
2396
2397	try: oAdapter.audioController = eAudioControllerType;
2398	except: return reporter.errorXcpt('Failed to set the audio controller to %s.' % (eAudioControllerType,));
2399
2400	if eAudioDriverType is None:
2401	sHost = utils.getHostOs()
2402	if sHost == 'darwin': eAudioDriverType = vboxcon.AudioDriverType_CoreAudio;
2403	elif sHost == 'win': eAudioDriverType = vboxcon.AudioDriverType_DirectSound;
2404	elif sHost == 'linux': eAudioDriverType = vboxcon.AudioDriverType_Pulse;
2405	elif sHost == 'solaris': eAudioDriverType = vboxcon.AudioDriverType_OSS;
2406	else:
2407	reporter.error('PORTME: Do not know which audio driver to pick for: %s!' % (sHost,));
2408	eAudioDriverType = vboxcon.AudioDriverType_Null;
2409
2410	try: oAdapter.audioDriver = eAudioDriverType;
2411	except: return reporter.errorXcpt('Failed to set the audio driver to %s.' % (eAudioDriverType,))
2412
2413	try: oAdapter.enabled = fEnable;
2414	except: return reporter.errorXcpt('Failed to set the "enabled" property to %s.' % (fEnable,));
2415
2416	try: oAdapter.enabledIn = fEnableIn;
2417	except: return reporter.errorXcpt('Failed to set the "enabledIn" property to %s.' % (fEnable,));
2418
2419	try: oAdapter.enabledOut = fEnableOut;
2420	except: return reporter.errorXcpt('Failed to set the "enabledOut" property to %s.' % (fEnable,));
2421
2422	reporter.log('set audio adapter type to %d, driver to %d, and enabled to %s (input is %s, output is %s)'
2423	% (eAudioControllerType, eAudioDriverType, fEnable, fEnableIn, fEnableOut,));
2424	self.oTstDrv.processPendingEvents();
2425	return True;
2426
2427	def setupPreferredConfig(self): # pylint: disable=too-many-locals
2428	"""
2429	Configures the VM according to the preferences of the guest type.
2430	"""
2431	try:
2432	sOsTypeId = self.o.machine.OSTypeId;
2433	except:
2434	reporter.errorXcpt('failed to obtain the OSTypeId for "%s"' % (self.sName));
2435	return False;
2436
2437	try:
2438	oOsType = self.oVBox.getGuestOSType(sOsTypeId);
2439	except:
2440	reporter.errorXcpt('getGuestOSType("%s") failed for "%s"' % (sOsTypeId, self.sName));
2441	return False;
2442
2443	# get the attributes.
2444	try:
2445	#sFamilyId = oOsType.familyId;
2446	#f64Bit = oOsType.is64Bit;
2447	fIoApic = oOsType.recommendedIOAPIC;
2448	fVirtEx = oOsType.recommendedVirtEx;
2449	cMBRam = oOsType.recommendedRAM;
2450	cMBVRam = oOsType.recommendedVRAM;
2451	#cMBHdd = oOsType.recommendedHDD;
2452	eNicType = oOsType.adapterType;
2453	if self.fpApiVer >= 3.2:
2454	if self.fpApiVer >= 4.2:
2455	fPae = oOsType.recommendedPAE;
2456	fUsbHid = oOsType.recommendedUSBHID;
2457	fHpet = oOsType.recommendedHPET;
2458	eStorCtlType = oOsType.recommendedHDStorageController;
2459	else:
2460	fPae = oOsType.recommendedPae;
2461	fUsbHid = oOsType.recommendedUsbHid;
2462	fHpet = oOsType.recommendedHpet;
2463	eStorCtlType = oOsType.recommendedHdStorageController;
2464	eFirmwareType = oOsType.recommendedFirmware;
2465	else:
2466	fPae = False;
2467	fUsbHid = False;
2468	fHpet = False;
2469	eFirmwareType = -1;
2470	eStorCtlType = vboxcon.StorageControllerType_PIIX4;
2471	if self.fpApiVer >= 4.0:
2472	eAudioCtlType = oOsType.recommendedAudioController;
2473	except:
2474	reporter.errorXcpt('exception reading IGuestOSType(%s) attribute' % (sOsTypeId));
2475	self.oTstDrv.processPendingEvents();
2476	return False;
2477	self.oTstDrv.processPendingEvents();
2478
2479	# Do the setting. Continue applying settings on error in case the
2480	# caller ignores the return code
2481	fRc = True;
2482	if not self.enableIoApic(fIoApic): fRc = False;
2483	if not self.enableVirtExX86(fVirtEx): fRc = False;
2484	if not self.enablePaeX86(fPae): fRc = False;
2485	if not self.setRamSize(cMBRam): fRc = False;
2486	if not self.setVRamSize(cMBVRam): fRc = False;
2487	if not self.setNicType(eNicType, 0): fRc = False;
2488	if self.fpApiVer >= 3.2:
2489	if not self.setFirmwareType(eFirmwareType): fRc = False;
2490	if not self.enableUsbHid(fUsbHid): fRc = False;
2491	if not self.enableHpetX86(fHpet): fRc = False;
2492	if eStorCtlType in (vboxcon.StorageControllerType_PIIX3,
2493	vboxcon.StorageControllerType_PIIX4,
2494	vboxcon.StorageControllerType_ICH6,):
2495	if not self.setStorageControllerType(eStorCtlType, "IDE Controller"):
2496	fRc = False;
2497	if self.fpApiVer >= 4.0:
2498	if not self.setupAudio(eAudioCtlType): fRc = False;
2499
2500	return fRc;
2501
2502	def addUsbDeviceFilter(self, sName, sVendorId = None, sProductId = None, sRevision = None, # pylint: disable=too-many-arguments
2503	sManufacturer = None, sProduct = None, sSerialNumber = None,
2504	sPort = None, sRemote = None):
2505	"""
2506	Creates a USB device filter and inserts it into the VM.
2507	Returns True on success.
2508	Returns False on failure (logged).
2509	"""
2510	fRc = True;
2511
2512	try:
2513	oUsbDevFilter = self.o.machine.USBDeviceFilters.createDeviceFilter(sName);
2514	oUsbDevFilter.active = True;
2515	if sVendorId is not None:
2516	oUsbDevFilter.vendorId = sVendorId;
2517	if sProductId is not None:
2518	oUsbDevFilter.productId = sProductId;
2519	if sRevision is not None:
2520	oUsbDevFilter.revision = sRevision;
2521	if sManufacturer is not None:
2522	oUsbDevFilter.manufacturer = sManufacturer;
2523	if sProduct is not None:
2524	oUsbDevFilter.product = sProduct;
2525	if sSerialNumber is not None:
2526	oUsbDevFilter.serialnumber = sSerialNumber;
2527	if sPort is not None:
2528	oUsbDevFilter.port = sPort;
2529	if sRemote is not None:
2530	oUsbDevFilter.remote = sRemote;
2531	try:
2532	self.o.machine.USBDeviceFilters.insertDeviceFilter(0, oUsbDevFilter);
2533	except:
2534	reporter.errorXcpt('insertDeviceFilter(%s) failed on "%s"' \
2535	% (0, self.sName) );
2536	fRc = False;
2537	else:
2538	reporter.log('inserted USB device filter "%s" to %s' % (sName, self.sName));
2539	except:
2540	reporter.errorXcpt('createDeviceFilter("%s") failed on "%s"' \
2541	% (sName, self.sName) );
2542	fRc = False;
2543	return fRc;
2544
2545	def getGuestPropertyValue(self, sName):
2546	"""
2547	Gets a guest property value.
2548	Returns the value on success, None on failure (logged).
2549	"""
2550	try:
2551	sValue = self.o.machine.getGuestPropertyValue(sName);
2552	except:
2553	reporter.errorXcpt('IMachine::getGuestPropertyValue("%s") failed' % (sName));
2554	return None;
2555	return sValue;
2556
2557	def setGuestPropertyValue(self, sName, sValue):
2558	"""
2559	Sets a guest property value.
2560	Returns the True on success, False on failure (logged).
2561	"""
2562	try:
2563	self.o.machine.setGuestPropertyValue(sName, sValue);
2564	except:
2565	reporter.errorXcpt('IMachine::setGuestPropertyValue("%s","%s") failed' % (sName, sValue));
2566	return False;
2567	return True;
2568
2569	def delGuestPropertyValue(self, sName):
2570	"""
2571	Deletes a guest property value.
2572	Returns the True on success, False on failure (logged).
2573	"""
2574	try:
2575	oMachine = self.o.machine;
2576	if self.fpApiVer >= 4.2:
2577	oMachine.deleteGuestProperty(sName);
2578	else:
2579	oMachine.setGuestPropertyValue(sName, '');
2580	except:
2581	reporter.errorXcpt('Unable to delete guest property "%s"' % (sName,));
2582	return False;
2583	return True;
2584
2585	def setExtraData(self, sKey, sValue):
2586	"""
2587	Sets extra data.
2588	Returns the True on success, False on failure (logged).
2589	"""
2590	try:
2591	self.o.machine.setExtraData(sKey, sValue);
2592	except:
2593	reporter.errorXcpt('IMachine::setExtraData("%s","%s") failed' % (sKey, sValue));
2594	return False;
2595	return True;
2596
2597	def getExtraData(self, sKey):
2598	"""
2599	Gets extra data.
2600	Returns value on success, None on failure.
2601	"""
2602	try:
2603	sValue = self.o.machine.getExtraData(sKey)
2604	except:
2605	reporter.errorXcpt('IMachine::getExtraData("%s") failed' % (sKey,))
2606	return None
2607	return sValue
2608
2609	def setupTeleporter(self, fEnabled=True, uPort = 6500, sAddress = '', sPassword = ''):
2610	"""
2611	Sets up the teleporter for the VM.
2612	Returns True on success, False on failure (logged).
2613	"""
2614	try:
2615	self.o.machine.teleporterAddress = sAddress;
2616	self.o.machine.teleporterPort = uPort;
2617	self.o.machine.teleporterPassword = sPassword;
2618	self.o.machine.teleporterEnabled = fEnabled;
2619	except:
2620	reporter.errorXcpt('setupTeleporter(%s, %s, %s, %s)' % (fEnabled, sPassword, uPort, sAddress));
2621	return False;
2622	return True;
2623
2624	def enableTeleporter(self, fEnable=True):
2625	"""
2626	Enables or disables the teleporter of the VM.
2627	Returns True on success, False on failure (logged).
2628	"""
2629	try:
2630	self.o.machine.teleporterEnabled = fEnable;
2631	except:
2632	reporter.errorXcpt('IMachine::teleporterEnabled=%s failed' % (fEnable));
2633	return False;
2634	return True;
2635
2636	def teleport(self, sHostname = 'localhost', uPort = 6500, sPassword = 'password', cMsMaxDowntime = 250):
2637	"""
2638	Wrapper around the IConsole::teleport() method.
2639	Returns a progress object on success, None on failure (logged).
2640	"""
2641	reporter.log2('"%s"::teleport(%s,%s,%s,%s)...' % (self.sName, sHostname, uPort, sPassword, cMsMaxDowntime));
2642	try:
2643	oProgress = self.o.console.teleport(sHostname, uPort, sPassword, cMsMaxDowntime)
2644	except:
2645	reporter.errorXcpt('IConsole::teleport(%s,%s,%s,%s) failed' % (sHostname, uPort, sPassword, cMsMaxDowntime));
2646	return None;
2647	return ProgressWrapper(oProgress, self.oVBoxMgr, self.oTstDrv, 'teleport %s' % (self.sName,));
2648
2649	def getOsType(self):
2650	"""
2651	Gets the IGuestOSType interface for the machine.
2652
2653	return IGuestOSType interface on success, None + errorXcpt on failure.
2654	No exceptions raised.
2655	"""
2656	try:
2657	sOsTypeId = self.o.machine.OSTypeId;
2658	except:
2659	reporter.errorXcpt('failed to obtain the OSTypeId for "%s"' % (self.sName));
2660	return None;
2661
2662	try:
2663	oOsType = self.oVBox.getGuestOSType(sOsTypeId);
2664	except:
2665	reporter.errorXcpt('getGuestOSType("%s") failed for "%s"' % (sOsTypeId, self.sName));
2666	return None;
2667
2668	return oOsType;
2669
2670	def setOsType(self, sNewTypeId):
2671	"""
2672	Changes the OS type.
2673
2674	returns True on success, False + errorXcpt on failure.
2675	No exceptions raised.
2676	"""
2677	try:
2678	self.o.machine.OSTypeId = sNewTypeId;
2679	except:
2680	reporter.errorXcpt('failed to set the OSTypeId for "%s" to "%s"' % (self.sName, sNewTypeId));
2681	return False;
2682	return True;
2683
2684
2685	def setParavirtProvider(self, iProvider):
2686	"""
2687	Sets a paravirtualisation provider.
2688	Returns the True on success, False on failure (logged).
2689	"""
2690	try:
2691	self.o.machine.paravirtProvider = iProvider
2692	except:
2693	reporter.errorXcpt('Unable to set paravirtualisation provider "%s"' % (iProvider,))
2694	return False;
2695	return True;
2696
2697
2698	def setupSerialToRawFile(self, iSerialPort, sRawFile):
2699	"""
2700	Enables the given serial port (zero based) and redirects it to sRawFile.
2701	Returns the True on success, False on failure (logged).
2702	"""
2703	try:
2704	oPort = self.o.machine.getSerialPort(iSerialPort);
2705	except:
2706	fRc = reporter.errorXcpt('failed to get serial port #%u' % (iSerialPort,));
2707	else:
2708	try:
2709	oPort.path = sRawFile;
2710	except:
2711	fRc = reporter.errorXcpt('failed to set the "path" property on serial port #%u to "%s"'
2712	% (iSerialPort, sRawFile));
2713	else:
2714	try:
2715	oPort.hostMode = vboxcon.PortMode_RawFile;
2716	except:
2717	fRc = reporter.errorXcpt('failed to set the "hostMode" property on serial port #%u to PortMode_RawFile'
2718	% (iSerialPort,));
2719	else:
2720	try:
2721	oPort.enabled = True;
2722	except:
2723	fRc = reporter.errorXcpt('failed to set the "enable" property on serial port #%u to True'
2724	% (iSerialPort,));
2725	else:
2726	reporter.log('set SerialPort[%s].enabled/hostMode/path=True/RawFile/%s' % (iSerialPort, sRawFile,));
2727	fRc = True;
2728	self.oTstDrv.processPendingEvents();
2729	return fRc;
2730
2731
2732	def enableSerialPort(self, iSerialPort):
2733	"""
2734	Enables the given serial port setting the initial port mode to disconnected.
2735	"""
2736	try:
2737	oPort = self.o.machine.getSerialPort(iSerialPort);
2738	except:
2739	fRc = reporter.errorXcpt('failed to get serial port #%u' % (iSerialPort,));
2740	else:
2741	try:
2742	oPort.hostMode = vboxcon.PortMode_Disconnected;
2743	except:
2744	fRc = reporter.errorXcpt('failed to set the "hostMode" property on serial port #%u to PortMode_Disconnected'
2745	% (iSerialPort,));
2746	else:
2747	try:
2748	oPort.enabled = True;
2749	except:
2750	fRc = reporter.errorXcpt('failed to set the "enable" property on serial port #%u to True'
2751	% (iSerialPort,));
2752	else:
2753	reporter.log('set SerialPort[%s].enabled/hostMode/=True/Disconnected' % (iSerialPort,));
2754	fRc = True;
2755	self.oTstDrv.processPendingEvents();
2756	return fRc;
2757
2758
2759	def changeSerialPortAttachment(self, iSerialPort, ePortMode, sPath, fServer):
2760	"""
2761	Changes the attachment of the given serial port to the attachment config given.
2762	"""
2763	try:
2764	oPort = self.o.machine.getSerialPort(iSerialPort);
2765	except:
2766	fRc = reporter.errorXcpt('failed to get serial port #%u' % (iSerialPort,));
2767	else:
2768	try:
2769	# Change port mode to disconnected first so changes get picked up by a potentially running VM.
2770	oPort.hostMode = vboxcon.PortMode_Disconnected;
2771	except:
2772	fRc = reporter.errorXcpt('failed to set the "hostMode" property on serial port #%u to PortMode_Disconnected'
2773	% (iSerialPort,));
2774	else:
2775	try:
2776	oPort.path = sPath;
2777	oPort.server = fServer;
2778	oPort.hostMode = ePortMode;
2779	except:
2780	fRc = reporter.errorXcpt('failed to configure the serial port');
2781	else:
2782	reporter.log('set SerialPort[%s].hostMode/path/server=%s/%s/%s'
2783	% (iSerialPort, ePortMode, sPath, fServer));
2784	fRc = True;
2785	self.oTstDrv.processPendingEvents();
2786	return fRc;
2787
2788	#
2789	# IConsole wrappers.
2790	#
2791
2792	def powerOff(self, fFudgeOnFailure = True):
2793	"""
2794	Powers off the VM.
2795
2796	Returns True on success.
2797	Returns False on IConsole::powerDown() failure.
2798	Returns None if the progress object returns failure.
2799	"""
2800	#
2801	# Deregister event handler before we power off the VM, otherwise we're
2802	# racing for VM process termination and cause misleading spurious
2803	# error messages in the event handling code, because the event objects
2804	# disappear.
2805	#
2806	# Note! Doing this before powerDown to try prevent numerous smoketest
2807	# timeouts on XPCOM hosts.
2808	#
2809	self.deregisterEventHandlerForTask();
2810
2811
2812	# Try power if off.
2813	try:
2814	oProgress = self.o.console.powerDown();
2815	except:
2816	reporter.logXcpt('IConsole::powerDown failed on %s' % (self.sName));
2817	if fFudgeOnFailure:
2818	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2819	self.waitForTask(1000); # fudge
2820	return False;
2821
2822	# Wait on power off operation to complete.
2823	rc = self.oTstDrv.waitOnProgress(oProgress);
2824	if rc < 0:
2825	self.close();
2826	if fFudgeOnFailure:
2827	vbox.reportError(oProgress, 'powerDown for "%s" failed' % (self.sName));
2828	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2829	return None;
2830
2831	# Wait for the VM to really power off or we'll fail to open a new session to it.
2832	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2833	return self.waitForTask(30 * 1000); # fudge
2834
2835	def saveState(self, fPause = True):
2836	"""
2837	Saves state of the VM.
2838
2839	Returns True on success.
2840	Returns False on IConsole::saveState() failure.
2841	Returns None if the progress object returns Failure.
2842	"""
2843
2844	if fPause is True \
2845	and self.oVM.state is vboxcon.MachineState_Running:
2846	self.o.console.pause();
2847	if self.oVM.state is not vboxcon.MachineState_Paused:
2848	reporter.error('pause for "%s" failed' % (self.sName));
2849	# Try saving state.
2850	try:
2851	if self.fpApiVer >= 5.0:
2852	oProgress = self.o.machine.saveState()
2853	else:
2854	oProgress = self.o.console.saveState()
2855	except:
2856	reporter.logXcpt('IMachine::saveState failed on %s' % (self.sName));
2857	return False;
2858
2859	# Wait for saving state operation to complete.
2860	rc = self.oTstDrv.waitOnProgress(oProgress);
2861	if rc < 0:
2862	self.close();
2863	return None;
2864
2865	# Wait for the VM to really terminate or we'll fail to open a new session to it.
2866	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2867	return self.waitForTask(30 * 1000); # fudge
2868
2869	def discardSavedState(self, fRemove = True):
2870	"""
2871	Discards saved state of the VM.
2872
2873	Returns True on success.
2874	Returns False on IConsole::discardSaveState() failure.
2875	"""
2876
2877	try:
2878	if self.fpApiVer >= 5.0:
2879	self.o.machine.discardSavedState(fRemove)
2880	else:
2881	self.o.console.discardSavedState(fRemove)
2882	except:
2883	reporter.logXcpt('IMachine::discardSavedState failed on %s' % (self.sName))
2884	return False
2885	return True
2886
2887	def restoreSnapshot(self, oSnapshot, fFudgeOnFailure = True):
2888	"""
2889	Restores the given snapshot.
2890
2891	Returns True on success.
2892	Returns False on IMachine::restoreSnapshot() failure.
2893	Returns None if the progress object returns failure.
2894	"""
2895	try:
2896	if self.fpApiVer >= 5.0:
2897	oProgress = self.o.machine.restoreSnapshot(oSnapshot);
2898	else:
2899	oProgress = self.o.console.restoreSnapshot(oSnapshot);
2900	except:
2901	reporter.logXcpt('IMachine::restoreSnapshot failed on %s' % (self.sName));
2902	if fFudgeOnFailure:
2903	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2904	self.waitForTask(1000); # fudge
2905	return False;
2906
2907	rc = self.oTstDrv.waitOnProgress(oProgress);
2908	if rc < 0:
2909	self.close();
2910	if fFudgeOnFailure:
2911	vbox.reportError(oProgress, 'restoreSnapshot for "%s" failed' % (self.sName));
2912	return None;
2913
2914	return self.waitForTask(30 * 1000);
2915
2916	def deleteSnapshot(self, oSnapshot, fFudgeOnFailure = True, cMsTimeout = 30 * 1000):
2917	"""
2918	Deletes the given snapshot merging the diff image into the base.
2919
2920	Returns True on success.
2921	Returns False on IMachine::deleteSnapshot() failure.
2922	"""
2923	try:
2924	if self.fpApiVer >= 5.0:
2925	oProgressCom = self.o.machine.deleteSnapshot(oSnapshot);
2926	else:
2927	oProgressCom = self.o.console.deleteSnapshot(oSnapshot);
2928	oProgress = ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oTstDrv, 'Delete Snapshot %s' % (oSnapshot));
2929	oProgress.wait(cMsTimeout);
2930	oProgress.logResult();
2931	except:
2932	reporter.logXcpt('IMachine::deleteSnapshot failed on %s' % (self.sName));
2933	if fFudgeOnFailure:
2934	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2935	self.waitForTask(1000); # fudge
2936	return False;
2937
2938	return True;
2939
2940	def takeSnapshot(self, sName, sDescription = '', fPause = True, fFudgeOnFailure = True, cMsTimeout = 30 * 1000):
2941	"""
2942	Takes a snapshot with the given name
2943
2944	Returns True on success.
2945	Returns False on IMachine::takeSnapshot() or VM state change failure.
2946	"""
2947	try:
2948	if fPause is True \
2949	and self.oVM.state is vboxcon.MachineState_Running:
2950	self.o.console.pause();
2951	if self.fpApiVer >= 5.0:
2952	(oProgressCom, _) = self.o.machine.takeSnapshot(sName, sDescription, True);
2953	else:
2954	oProgressCom = self.o.console.takeSnapshot(sName, sDescription);
2955	oProgress = ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oTstDrv, 'Take Snapshot %s' % (sName));
2956	oProgress.wait(cMsTimeout);
2957	oProgress.logResult();
2958	except:
2959	reporter.logXcpt('IMachine::takeSnapshot failed on %s' % (self.sName));
2960	if fFudgeOnFailure:
2961	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2962	self.waitForTask(1000); # fudge
2963	return False;
2964
2965	if fPause is True \
2966	and self.oVM.state is vboxcon.MachineState_Paused:
2967	self.o.console.resume();
2968
2969	return True;
2970
2971	def findSnapshot(self, sName):
2972	"""
2973	Returns the snapshot object with the given name
2974
2975	Returns snapshot object on success.
2976	Returns None if there is no snapshot with the given name.
2977	"""
2978	return self.oVM.findSnapshot(sName);
2979
2980	def takeScreenshot(self, sFilename, iScreenId=0):
2981	"""
2982	Take screenshot from the given display and save it to specified file.
2983
2984	Returns True on success
2985	Returns False on failure.
2986	"""
2987	try:
2988	if self.fpApiVer >= 5.0:
2989	iWidth, iHeight, _, _, _, _ = self.o.console.display.getScreenResolution(iScreenId)
2990	aPngData = self.o.console.display.takeScreenShotToArray(iScreenId, iWidth, iHeight,
2991	vboxcon.BitmapFormat_PNG)
2992	else:
2993	iWidth, iHeight, _, _, _ = self.o.console.display.getScreenResolution(iScreenId)
2994	aPngData = self.o.console.display.takeScreenShotPNGToArray(iScreenId, iWidth, iHeight)
2995	except:
2996	reporter.logXcpt("Unable to take screenshot")
2997	return False
2998
2999	with open(sFilename, 'wb') as oFile: # pylint: disable=unspecified-encoding
3000	oFile.write(aPngData)
3001
3002	return True
3003
3004	def attachUsbDevice(self, sUuid, sCaptureFilename = None):
3005	"""
3006	Attach given USB device UUID to the VM.
3007
3008	Returns True on success
3009	Returns False on failure.
3010	"""
3011	fRc = True;
3012	try:
3013	if sCaptureFilename is None:
3014	self.o.console.attachUSBDevice(sUuid, '');
3015	else:
3016	self.o.console.attachUSBDevice(sUuid, sCaptureFilename);
3017	except:
3018	reporter.logXcpt('Unable to attach USB device %s' % (sUuid,));
3019	fRc = False;
3020
3021	return fRc;
3022
3023	def detachUsbDevice(self, sUuid):
3024	"""
3025	Detach given USB device UUID from the VM.
3026
3027	Returns True on success
3028	Returns False on failure.
3029	"""
3030	fRc = True;
3031	try:
3032	_ = self.o.console.detachUSBDevice(sUuid);
3033	except:
3034	reporter.logXcpt('Unable to detach USB device %s' % (sUuid,));
3035	fRc = False;
3036
3037	return fRc;
3038
3039
3040	#
3041	# IMachineDebugger wrappers.
3042	#
3043
3044	def queryOsKernelLog(self):
3045	"""
3046	Tries to get the OS kernel log using the VM debugger interface.
3047
3048	Returns string containing the kernel log on success.
3049	Returns None on failure.
3050	"""
3051	sOsKernelLog = None;
3052	try:
3053	self.o.console.debugger.loadPlugIn('all');
3054	except:
3055	reporter.logXcpt('Unable to load debugger plugins');
3056	else:
3057	try:
3058	sOsDetected = self.o.console.debugger.detectOS();
3059	except:
3060	reporter.logXcpt('Failed to detect the guest OS');
3061	else:
3062	try:
3063	sOsKernelLog = self.o.console.debugger.queryOSKernelLog(0);
3064	except:
3065	reporter.logXcpt('Unable to get the guest OS (%s) kernel log' % (sOsDetected,));
3066	return sOsKernelLog;
3067
3068	def queryDbgInfo(self, sItem, sArg = '', sDefault = None):
3069	"""
3070	Simple wrapper around IMachineDebugger::info.
3071
3072	Returns string on success, sDefault on failure (logged).
3073	"""
3074	try:
3075	return self.o.console.debugger.info(sItem, sArg);
3076	except:
3077	reporter.logXcpt('Unable to query "%s" with arg "%s"' % (sItem, sArg,));
3078	return sDefault;
3079
3080	def queryDbgInfoVgaText(self, sArg = 'all'):
3081	"""
3082	Tries to get the 'info vgatext' output, provided we're in next mode.
3083
3084	Returns string containing text on success.
3085	Returns None on failure or not text mode.
3086	"""
3087	sVgaText = None;
3088	try:
3089	sVgaText = self.o.console.debugger.info('vgatext', sArg);
3090	if sVgaText.startswith('Not in text mode!'):
3091	sVgaText = None;
3092	except:
3093	reporter.logXcpt('Unable to query vgatext with arg "%s"' % (sArg,));
3094	return sVgaText;
3095
3096	def queryDbgGuestStack(self, iCpu = 0):
3097	"""
3098	Returns the guest stack for the given VCPU.
3099
3100	Returns string containing the guest stack for the selected VCPU on success.
3101	Returns None on failure.
3102	"""
3103
3104	#
3105	# Load all plugins first and try to detect the OS so we can
3106	# get nicer stack traces.
3107	#
3108	try:
3109	self.o.console.debugger.loadPlugIn('all');
3110	except:
3111	reporter.logXcpt('Unable to load debugger plugins');
3112	else:
3113	try:
3114	sOsDetected = self.o.console.debugger.detectOS();
3115	_ = sOsDetected;
3116	except:
3117	reporter.logXcpt('Failed to detect the guest OS');
3118
3119	sGuestStack = None;
3120	try:
3121	sGuestStack = self.o.console.debugger.dumpGuestStack(iCpu);
3122	except:
3123	reporter.logXcpt('Unable to query guest stack for CPU %s' % (iCpu, ));
3124
3125	return sGuestStack;
3126
3127
3128	#
3129	# Other methods.
3130	#
3131
3132	def getPrimaryIp(self):
3133	"""
3134	Tries to obtain the primary IP address of the guest via the guest
3135	properties.
3136
3137	Returns IP address on success.
3138	Returns empty string on failure.
3139	"""
3140	sIpAddr = self.getGuestPropertyValue('/VirtualBox/GuestInfo/Net/0/V4/IP');
3141	if vbox.isIpAddrValid(sIpAddr):
3142	return sIpAddr;
3143	return '';
3144
3145	def getPid(self):
3146	"""
3147	Gets the process ID for the direct session unless it's ourselves.
3148	"""
3149	if self.uPid is None and self.o is not None and self.fRemoteSession:
3150	try:
3151	if self.fpApiVer >= 4.2:
3152	uPid = self.o.machine.sessionPID;
3153	else:
3154	uPid = self.o.machine.sessionPid;
3155	if uPid != os.getpid() and uPid != 0xffffffff:
3156	self.uPid = uPid;
3157	except Exception as oXcpt:
3158	if vbox.ComError.equal(oXcpt, vbox.ComError.E_UNEXPECTED):
3159	try:
3160	if self.fpApiVer >= 4.2:
3161	uPid = self.oVM.sessionPID;
3162	else:
3163	uPid = self.oVM.sessionPid;
3164	if uPid != os.getpid() and uPid != 0xffffffff:
3165	self.uPid = uPid;
3166	except:
3167	reporter.log2Xcpt();
3168	else:
3169	reporter.log2Xcpt();
3170	if self.uPid is not None:
3171	reporter.log2('getPid: %u' % (self.uPid,));
3172	self.fPidFile = self.oTstDrv.pidFileAdd(self.uPid, 'vm_%s' % (self.sName,), # Set-uid-to-root is similar to SUDO.
3173	fSudo = True);
3174	return self.uPid;
3175
3176	def addLogsToReport(self, cReleaseLogs = 1):
3177	"""
3178	Retrieves and adds the release and debug logs to the test report.
3179	"""
3180	fRc = True;
3181
3182	# Add each of the requested release logs to the report.
3183	for iLog in range(0, cReleaseLogs):
3184	try:
3185	if self.fpApiVer >= 3.2:
3186	sLogFile = self.oVM.queryLogFilename(iLog);
3187	elif iLog > 0:
3188	sLogFile = '%s/VBox.log' % (self.oVM.logFolder,);
3189	else:
3190	sLogFile = '%s/VBox.log.%u' % (self.oVM.logFolder, iLog);
3191	except:
3192	reporter.logXcpt('iLog=%s' % (iLog,));
3193	fRc = False;
3194	else:
3195	if sLogFile is not None and sLogFile != '': # the None bit is for a 3.2.0 bug.
3196	reporter.addLogFile(sLogFile, 'log/release/vm', '%s #%u' % (self.sName, iLog),
3197	sAltName = '%s-%s' % (self.sName, os.path.basename(sLogFile),));
3198
3199	# Now for the hardened windows startup log.
3200	try:
3201	sLogFile = os.path.join(self.oVM.logFolder, 'VBoxHardening.log');
3202	except:
3203	reporter.logXcpt();
3204	fRc = False;
3205	else:
3206	if os.path.isfile(sLogFile):
3207	reporter.addLogFile(sLogFile, 'log/release/vm', '%s hardening log' % (self.sName, ),
3208	sAltName = '%s-%s' % (self.sName, os.path.basename(sLogFile),));
3209
3210	# Now for the debug log.
3211	if self.sLogFile is not None and os.path.isfile(self.sLogFile):
3212	reporter.addLogFile(self.sLogFile, 'log/debug/vm', '%s debug' % (self.sName, ),
3213	sAltName = '%s-%s' % (self.sName, os.path.basename(self.sLogFile),));
3214
3215	return fRc;
3216
3217	def registerDerivedEventHandler(self, oSubClass, dArgs = None, fMustSucceed = True):
3218	"""
3219	Create an instance of the given ConsoleEventHandlerBase sub-class and
3220	register it.
3221
3222	The new instance is returned on success. None is returned on error.
3223	"""
3224
3225	# We need a console object.
3226	try:
3227	oConsole = self.o.console;
3228	except Exception as oXcpt:
3229	if fMustSucceed or vbox.ComError.notEqual(oXcpt, vbox.ComError.E_UNEXPECTED):
3230	reporter.errorXcpt('Failed to get ISession::console for "%s"' % (self.sName, ));
3231	return None;
3232
3233	# Add the base class arguments.
3234	dArgsCopy = dArgs.copy() if dArgs is not None else {};
3235	dArgsCopy['oSession'] = self;
3236	dArgsCopy['oConsole'] = oConsole;
3237	sLogSuffix = 'on %s' % (self.sName,)
3238	return oSubClass.registerDerivedEventHandler(self.oVBoxMgr, self.fpApiVer, oSubClass, dArgsCopy,
3239	oConsole, 'IConsole', 'IConsoleCallback',
3240	fMustSucceed = fMustSucceed, sLogSuffix = sLogSuffix);
3241
3242	def enableVmmDevTestingPart(self, fEnabled, fEnableMMIO = False):
3243	"""
3244	Enables the testing part of the VMMDev.
3245
3246	Returns True on success and False on failure. Error information is logged.
3247	"""
3248	fRc = True;
3249	try:
3250	self.o.machine.setExtraData('VBoxInternal/Devices/VMMDev/0/Config/TestingEnabled',
3251	'1' if fEnabled else '');
3252	self.o.machine.setExtraData('VBoxInternal/Devices/VMMDev/0/Config/TestingMMIO',
3253	'1' if fEnableMMIO and fEnabled else '');
3254	except:
3255	reporter.errorXcpt('VM name "%s", fEnabled=%s' % (self.sName, fEnabled));
3256	fRc = False;
3257	else:
3258	reporter.log('set VMMDevTesting=%s for "%s"' % (fEnabled, self.sName));
3259	self.oTstDrv.processPendingEvents();
3260	return fRc;
3261
3262	#
3263	# Test eXecution Service methods.
3264	#
3265
3266	def txsConnectViaTcp(self, cMsTimeout = 10*60000, sIpAddr = None, fNatForwardingForTxs = False):
3267	"""
3268	Connects to the TXS using TCP/IP as transport. If no IP or MAC is
3269	addresses are specified, we'll get the IP from the guest additions.
3270
3271	Returns a TxsConnectTask object on success, None + log on failure.
3272	"""
3273	# If the VM is configured with a NAT interface, connect to local host.
3274	fReversedSetup = False;
3275	fUseNatForTxs = False;
3276	sMacAddr = None;
3277	oIDhcpServer = None;
3278	if sIpAddr is None:
3279	try:
3280	oNic = self.oVM.getNetworkAdapter(0);
3281	enmAttachmentType = oNic.attachmentType;
3282	if enmAttachmentType == vboxcon.NetworkAttachmentType_NAT:
3283	fUseNatForTxs = True;
3284	elif enmAttachmentType == vboxcon.NetworkAttachmentType_HostOnly and not sIpAddr:
3285	# Get the MAC address and find the DHCP server.
3286	sMacAddr = oNic.MACAddress;
3287	sHostOnlyNIC = oNic.hostOnlyInterface;
3288	oIHostOnlyIf = self.oVBox.host.findHostNetworkInterfaceByName(sHostOnlyNIC);
3289	sHostOnlyNet = oIHostOnlyIf.networkName;
3290	oIDhcpServer = self.oVBox.findDHCPServerByNetworkName(sHostOnlyNet);
3291	except:
3292	reporter.errorXcpt();
3293	return None;
3294
3295	if fUseNatForTxs:
3296	fReversedSetup = not fNatForwardingForTxs;
3297	sIpAddr = '127.0.0.1';
3298
3299	# Kick off the task.
3300	try:
3301	oTask = TxsConnectTask(self, cMsTimeout, sIpAddr, sMacAddr, oIDhcpServer, fReversedSetup,
3302	fnProcessEvents = self.oTstDrv.processPendingEvents);
3303	except:
3304	reporter.errorXcpt();
3305	oTask = None;
3306	return oTask;
3307
3308	def txsTryConnectViaTcp(self, cMsTimeout, sHostname, fReversed = False):
3309	"""
3310	Attempts to connect to a TXS instance.
3311
3312	Returns True if a connection was established, False if not (only grave
3313	failures are logged as errors).
3314
3315	Note! The timeout is more of a guideline...
3316	"""
3317
3318	if sHostname is None or sHostname.strip() == '':
3319	raise base.GenError('Empty sHostname is not implemented yet');
3320
3321	oTxsSession = txsclient.tryOpenTcpSession(cMsTimeout, sHostname, fReversedSetup = fReversed,
3322	cMsIdleFudge = cMsTimeout // 2,
3323	fnProcessEvents = self.oTstDrv.processPendingEvents);
3324	if oTxsSession is None:
3325	return False;
3326
3327	# Wait for the connect task to time out.
3328	self.oTstDrv.addTask(oTxsSession);
3329	self.oTstDrv.processPendingEvents();
3330	oRc = self.oTstDrv.waitForTasks(cMsTimeout);
3331	self.oTstDrv.removeTask(oTxsSession);
3332	if oRc != oTxsSession:
3333	if oRc is not None:
3334	reporter.log('oRc=%s, expected %s' % (oRc, oTxsSession));
3335	self.oTstDrv.processPendingEvents();
3336	oTxsSession.cancelTask(); # this is synchronous
3337	return False;
3338
3339	# Check the status.
3340	reporter.log2('TxsSession is ready, isSuccess() -> %s.' % (oTxsSession.isSuccess(),));
3341	if not oTxsSession.isSuccess():
3342	return False;
3343
3344	reporter.log2('Disconnecting from TXS...');
3345	return oTxsSession.syncDisconnect();
3346
3347
3348
3349	class TxsConnectTask(TdTaskBase):
3350	"""
3351	Class that takes care of connecting to a VM.
3352	"""
3353
3354	class TxsConnectTaskVBoxCallback(vbox.VirtualBoxEventHandlerBase):
3355	""" Class for looking for IPv4 address changes on interface 0."""
3356	def __init__(self, dArgs):
3357	vbox.VirtualBoxEventHandlerBase.__init__(self, dArgs);
3358	self.oParentTask = dArgs['oParentTask'];
3359	self.sMachineId = dArgs['sMachineId'];
3360
3361	def onGuestPropertyChange(self, sMachineId, sName, sValue, sFlags, fWasDeleted):
3362	"""Look for IP address."""
3363	reporter.log2('onGuestPropertyChange(,%s,%s,%s,%s,%s)' % (sMachineId, sName, sValue, sFlags, fWasDeleted));
3364	if sMachineId == self.sMachineId \
3365	and sName == '/VirtualBox/GuestInfo/Net/0/V4/IP':
3366	oParentTask = self.oParentTask;
3367	if oParentTask:
3368	oParentTask._setIp(sValue); # pylint: disable=protected-access
3369
3370
3371	def __init__(self, oSession, cMsTimeout, sIpAddr, sMacAddr, oIDhcpServer, fReversedSetup, fnProcessEvents = None):
3372	TdTaskBase.__init__(self, utils.getCallerName(), fnProcessEvents = fnProcessEvents);
3373	self.cMsTimeout = cMsTimeout;
3374	self.fnProcessEvents = fnProcessEvents;
3375	self.sIpAddr = None;
3376	self.sNextIpAddr = None;
3377	self.sMacAddr = sMacAddr;
3378	self.oIDhcpServer = oIDhcpServer;
3379	self.fReversedSetup = fReversedSetup;
3380	self.oVBoxEventHandler = None;
3381	self.oTxsSession = None;
3382
3383	# Check that the input makes sense:
3384	if (sMacAddr is None) != (oIDhcpServer is None) \
3385	or (sMacAddr and fReversedSetup) \
3386	or (sMacAddr and sIpAddr):
3387	reporter.error('TxsConnectTask sMacAddr=%s oIDhcpServer=%s sIpAddr=%s fReversedSetup=%s'
3388	% (sMacAddr, oIDhcpServer, sIpAddr, fReversedSetup,));
3389	raise base.GenError();
3390
3391	reporter.log2('TxsConnectTask: sIpAddr=%s fReversedSetup=%s' % (sIpAddr, fReversedSetup))
3392	if fReversedSetup is True:
3393	self._openTcpSession(sIpAddr, fReversedSetup = True);
3394	elif sIpAddr is not None and sIpAddr.strip() != '':
3395	self._openTcpSession(sIpAddr, cMsIdleFudge = 5000);
3396	else:
3397	#
3398	# If we've got no IP address, register callbacks that listens for
3399	# the primary network adaptor of the VM to set a IPv4 guest prop.
3400	# Note! The order in which things are done here is kind of important.
3401	#
3402
3403	# 0. The caller zaps the property before starting the VM.
3404	#try:
3405	# oSession.delGuestPropertyValue('/VirtualBox/GuestInfo/Net/0/V4/IP');
3406	#except:
3407	# reporter.logXcpt();
3408
3409	# 1. Register the callback / event listener object.
3410	dArgs = {'oParentTask':self, 'sMachineId':oSession.o.machine.id};
3411	self.oVBoxEventHandler = oSession.oVBox.registerDerivedEventHandler(self.TxsConnectTaskVBoxCallback, dArgs);
3412
3413	# 2. Query the guest properties.
3414	try:
3415	sIpAddr = oSession.getGuestPropertyValue('/VirtualBox/GuestInfo/Net/0/V4/IP');
3416	except:
3417	reporter.errorXcpt('IMachine::getGuestPropertyValue("/VirtualBox/GuestInfo/Net/0/V4/IP") failed');
3418	self._deregisterEventHandler();
3419	raise;
3420	if sIpAddr is not None:
3421	self._setIp(sIpAddr);
3422
3423	#
3424	# If the network adapter of the VM is host-only we can talk poll IDHCPServer
3425	# for the guest IP, allowing us to detect it for VMs without guest additions.
3426	# This will when we're polled.
3427	#
3428	if sMacAddr is not None:
3429	assert self.oIDhcpServer is not None;
3430
3431
3432	# end __init__
3433
3434	def __del__(self):
3435	""" Make sure we deregister the callback. """
3436	self._deregisterEventHandler();
3437	return TdTaskBase.__del__(self);
3438
3439	def toString(self):
3440	return '<%s cMsTimeout=%s, sIpAddr=%s, sNextIpAddr=%s, sMacAddr=%s, fReversedSetup=%s,' \
3441	' oTxsSession=%s oVBoxEventHandler=%s>' \
3442	% (TdTaskBase.toString(self), self.cMsTimeout, self.sIpAddr, self.sNextIpAddr, self.sMacAddr, self.fReversedSetup,
3443	self.oTxsSession, self.oVBoxEventHandler);
3444
3445	def _deregisterEventHandler(self):
3446	"""Deregisters the event handler."""
3447	fRc = True;
3448	oVBoxEventHandler = self.oVBoxEventHandler;
3449	if oVBoxEventHandler is not None:
3450	self.oVBoxEventHandler = None;
3451	fRc = oVBoxEventHandler.unregister();
3452	oVBoxEventHandler.oParentTask = None; # Try avoid cylic deps.
3453	return fRc;
3454
3455	def _setIp(self, sIpAddr, fInitCall = False):
3456	"""Called when we get an IP. Will create a TXS session and signal the task."""
3457	sIpAddr = sIpAddr.strip();
3458
3459	if sIpAddr is not None \
3460	and sIpAddr != '':
3461	if vbox.isIpAddrValid(sIpAddr) or fInitCall:
3462	try:
3463	for s in sIpAddr.split('.'):
3464	i = int(s);
3465	if str(i) != s:
3466	raise Exception();
3467	except:
3468	reporter.fatalXcpt();
3469	else:
3470	reporter.log('TxsConnectTask: opening session to ip "%s"' % (sIpAddr));
3471	self._openTcpSession(sIpAddr, cMsIdleFudge = 5000);
3472	return None;
3473
3474	reporter.log('TxsConnectTask: Ignoring Bad ip "%s"' % (sIpAddr));
3475	else:
3476	reporter.log2('TxsConnectTask: Ignoring empty ip "%s"' % (sIpAddr));
3477	return None;
3478
3479	def _openTcpSession(self, sIpAddr, uPort = None, fReversedSetup = False, cMsIdleFudge = 0):
3480	"""
3481	Calls txsclient.openTcpSession and switches our task to reflect the
3482	state of the subtask.
3483	"""
3484	self.oCv.acquire();
3485	if self.oTxsSession is None:
3486	reporter.log2('_openTcpSession: sIpAddr=%s, uPort=%d, fReversedSetup=%s' %
3487	(sIpAddr, uPort if uPort is not None else 0, fReversedSetup));
3488	self.sIpAddr = sIpAddr;
3489	self.oTxsSession = txsclient.openTcpSession(self.cMsTimeout, sIpAddr, uPort, fReversedSetup,
3490	cMsIdleFudge, fnProcessEvents = self.fnProcessEvents);
3491	self.oTxsSession.setTaskOwner(self);
3492	else:
3493	self.sNextIpAddr = sIpAddr;
3494	reporter.log2('_openTcpSession: sNextIpAddr=%s' % (sIpAddr,));
3495	self.oCv.release();
3496	return None;
3497
3498	def notifyAboutReadyTask(self, oTxsSession):
3499	"""
3500	Called by the TXS session task when it's done.
3501
3502	We'll signal the task completed or retry depending on the result.
3503	"""
3504
3505	self.oCv.acquire();
3506
3507	# Disassociate ourselves with the session (avoid cyclic ref)
3508	oTxsSession.setTaskOwner(None);
3509	fSuccess = oTxsSession.isSuccess();
3510	if self.oTxsSession is not None:
3511	if not fSuccess:
3512	self.oTxsSession = None;
3513	if fSuccess and self.fReversedSetup:
3514	self.sIpAddr = oTxsSession.oTransport.sHostname;
3515	else:
3516	fSuccess = False;
3517
3518	# Signal done, or retry?
3519	fDeregister = False;
3520	if fSuccess \
3521	or self.fReversedSetup \
3522	or self.getAgeAsMs() >= self.cMsTimeout:
3523	self.signalTaskLocked();
3524	fDeregister = True;
3525	else:
3526	sIpAddr = self.sNextIpAddr if self.sNextIpAddr is not None else self.sIpAddr;
3527	self._openTcpSession(sIpAddr, cMsIdleFudge = 5000);
3528
3529	self.oCv.release();
3530
3531	# If we're done, deregister the callback (w/o owning lock). It will
3532	if fDeregister:
3533	self._deregisterEventHandler();
3534	return True;
3535
3536	def _pollDhcpServer(self):
3537	"""
3538	Polls the DHCP server by MAC address in host-only setups.
3539	"""
3540
3541	if self.sIpAddr:
3542	return False;
3543
3544	if self.oIDhcpServer is None or not self.sMacAddr:
3545	return False;
3546
3547	try:
3548	(sIpAddr, sState, secIssued, secExpire) = self.oIDhcpServer.findLeaseByMAC(self.sMacAddr, 0);
3549	except:
3550	reporter.log4Xcpt('sMacAddr=%s' % (self.sMacAddr,));
3551	return False;
3552
3553	secNow = utils.secondsSinceUnixEpoch();
3554	reporter.log2('dhcp poll: secNow=%s secExpire=%s secIssued=%s sState=%s sIpAddr=%s'
3555	% (secNow, secExpire, secIssued, sState, sIpAddr,));
3556	if secNow > secExpire or sState != 'acked' or not sIpAddr:
3557	return False;
3558
3559	reporter.log('dhcp poll: sIpAddr=%s secExpire=%s (%s TTL) secIssued=%s (%s ago)'
3560	% (sIpAddr, secExpire, secExpire - secNow, secIssued, secNow - secIssued,));
3561	self._setIp(sIpAddr);
3562	return True;
3563
3564	#
3565	# Task methods
3566	#
3567
3568	def pollTask(self, fLocked = False):
3569	"""
3570	Overridden pollTask method.
3571	"""
3572	self._pollDhcpServer();
3573	return TdTaskBase.pollTask(self, fLocked);
3574
3575	#
3576	# Public methods
3577	#
3578
3579	def getResult(self):
3580	"""
3581	Returns the connected TXS session object on success.
3582	Returns None on failure or if the task has not yet completed.
3583	"""
3584	self.oCv.acquire();
3585	oTxsSession = self.oTxsSession;
3586	self.oCv.release();
3587
3588	if oTxsSession is not None and not oTxsSession.isSuccess():
3589	oTxsSession = None;
3590	return oTxsSession;
3591
3592	def cancelTask(self):
3593	""" Cancels the task. """
3594	self._deregisterEventHandler(); # (make sure to avoid cyclic fun)
3595	self.oCv.acquire();
3596	if not self.fSignalled:
3597	oTxsSession = self.oTxsSession;
3598	if oTxsSession is not None:
3599	self.oCv.release();
3600	oTxsSession.setTaskOwner(None);
3601	oTxsSession.cancelTask();
3602	oTxsSession.waitForTask(1000);
3603	self.oCv.acquire();
3604	self.signalTaskLocked();
3605	self.oCv.release();
3606	return True;
3607
3608
3609
3610	class AdditionsStatusTask(TdTaskBase):
3611	"""
3612	Class that takes care of waiting till the guest additions are in a given state.
3613	"""
3614
3615	class AdditionsStatusTaskCallback(vbox.EventHandlerBase):
3616	""" Class for looking for IPv4 address changes on interface 0."""
3617	def __init__(self, dArgs):
3618	self.oParentTask = dArgs['oParentTask'];
3619	vbox.EventHandlerBase.__init__(self, dArgs, self.oParentTask.oSession.fpApiVer,
3620	'AdditionsStatusTaskCallback/%s' % (self.oParentTask.oSession.sName,));
3621
3622	def handleEvent(self, oEvt):
3623	try:
3624	enmType = oEvt.type;
3625	except:
3626	reporter.errorXcpt();
3627	else:
3628	reporter.log2('AdditionsStatusTaskCallback:handleEvent: enmType=%s' % (enmType,));
3629	if enmType == vboxcon.VBoxEventType_OnGuestAdditionsStatusChanged:
3630	oParentTask = self.oParentTask;
3631	if oParentTask:
3632	oParentTask.pollTask();
3633
3634	# end
3635
3636
3637	def __init__(self, oSession, oIGuest, cMsTimeout = 120000, aenmWaitForRunLevels = None, aenmWaitForActive = None,
3638	aenmWaitForInactive = None):
3639	"""
3640	aenmWaitForRunLevels - List of run level values to wait for (success if one matches).
3641	aenmWaitForActive - List facilities (type values) that must be active.
3642	aenmWaitForInactive - List facilities (type values) that must be inactive.
3643
3644	The default is to wait for AdditionsRunLevelType_Userland if all three lists
3645	are unspecified or empty.
3646	"""
3647	TdTaskBase.__init__(self, utils.getCallerName());
3648	self.oSession = oSession # type: vboxwrappers.SessionWrapper
3649	self.oIGuest = oIGuest;
3650	self.cMsTimeout = cMsTimeout;
3651	self.fSucceeded = False;
3652	self.oVBoxEventHandler = None;
3653	self.aenmWaitForRunLevels = aenmWaitForRunLevels if aenmWaitForRunLevels else [];
3654	self.aenmWaitForActive = aenmWaitForActive if aenmWaitForActive else [];
3655	self.aenmWaitForInactive = aenmWaitForInactive if aenmWaitForInactive else [];
3656
3657	# Provide a sensible default if nothing is given.
3658	if not self.aenmWaitForRunLevels and not self.aenmWaitForActive and not self.aenmWaitForInactive:
3659	self.aenmWaitForRunLevels = [vboxcon.AdditionsRunLevelType_Userland,];
3660
3661	# Register the event handler on hosts which has it:
3662	if oSession.fpApiVer >= 6.1 or hasattr(vboxcon, 'VBoxEventType_OnGuestAdditionsStatusChanged'):
3663	aenmEvents = (vboxcon.VBoxEventType_OnGuestAdditionsStatusChanged,);
3664	dArgs = {
3665	'oParentTask': self,
3666	};
3667	self.oVBoxEventHandler = vbox.EventHandlerBase.registerDerivedEventHandler(oSession.oVBoxMgr,
3668	oSession.fpApiVer,
3669	self.AdditionsStatusTaskCallback,
3670	dArgs,
3671	oIGuest,
3672	'IGuest',
3673	'AdditionsStatusTaskCallback',
3674	aenmEvents = aenmEvents);
3675	reporter.log2('AdditionsStatusTask: %s' % (self.toString(), ));
3676
3677	def __del__(self):
3678	""" Make sure we deregister the callback. """
3679	self._deregisterEventHandler();
3680	self.oIGuest = None;
3681	return TdTaskBase.__del__(self);
3682
3683	def toString(self):
3684	return '<%s cMsTimeout=%s, fSucceeded=%s, aenmWaitForRunLevels=%s, aenmWaitForActive=%s, aenmWaitForInactive=%s, ' \
3685	'oVBoxEventHandler=%s>' \
3686	% (TdTaskBase.toString(self), self.cMsTimeout, self.fSucceeded, self.aenmWaitForRunLevels, self.aenmWaitForActive,
3687	self.aenmWaitForInactive, self.oVBoxEventHandler,);
3688
3689	def _deregisterEventHandler(self):
3690	"""Deregisters the event handler."""
3691	fRc = True;
3692	oVBoxEventHandler = self.oVBoxEventHandler;
3693	if oVBoxEventHandler is not None:
3694	self.oVBoxEventHandler = None;
3695	fRc = oVBoxEventHandler.unregister();
3696	oVBoxEventHandler.oParentTask = None; # Try avoid cylic deps.
3697	return fRc;
3698
3699	def _poll(self):
3700	"""
3701	Internal worker for pollTask() that returns the new signalled state.
3702	"""
3703
3704	#
3705	# Check if any of the runlevels we wait for have been reached:
3706	#
3707	if self.aenmWaitForRunLevels:
3708	try:
3709	enmRunLevel = self.oIGuest.additionsRunLevel;
3710	except:
3711	reporter.errorXcpt();
3712	return True;
3713	if enmRunLevel not in self.aenmWaitForRunLevels:
3714	reporter.log6('AdditionsStatusTask/poll: enmRunLevel=%s not in %s' % (enmRunLevel, self.aenmWaitForRunLevels,));
3715	return False;
3716	reporter.log2('AdditionsStatusTask/poll: enmRunLevel=%s matched %s!' % (enmRunLevel, self.aenmWaitForRunLevels,));
3717
3718
3719	#
3720	# Check for the facilities that must all be active.
3721	#
3722	for enmFacility in self.aenmWaitForActive:
3723	try:
3724	(enmStatus, _) = self.oIGuest.getFacilityStatus(enmFacility);
3725	except:
3726	reporter.errorXcpt('enmFacility=%s' % (enmFacility,));
3727	return True;
3728	if enmStatus != vboxcon.AdditionsFacilityStatus_Active:
3729	reporter.log2('AdditionsStatusTask/poll: enmFacility=%s not active: %s' % (enmFacility, enmStatus,));
3730	return False;
3731
3732	#
3733	# Check for the facilities that must all be inactive or terminated.
3734	#
3735	for enmFacility in self.aenmWaitForInactive:
3736	try:
3737	(enmStatus, _) = self.oIGuest.getFacilityStatus(enmFacility);
3738	except:
3739	reporter.errorXcpt('enmFacility=%s' % (enmFacility,));
3740	return True;
3741	if enmStatus not in (vboxcon.AdditionsFacilityStatus_Inactive,
3742	vboxcon.AdditionsFacilityStatus_Terminated):
3743	reporter.log2('AdditionsStatusTask/poll: enmFacility=%s not inactive: %s' % (enmFacility, enmStatus,));
3744	return False;
3745
3746
3747	reporter.log('AdditionsStatusTask: Poll succeeded, signalling...');
3748	self.fSucceeded = True;
3749	return True;
3750
3751
3752	#
3753	# Task methods
3754	#
3755
3756	def pollTask(self, fLocked = False):
3757	"""
3758	Overridden pollTask method.
3759	"""
3760	if not fLocked:
3761	self.lockTask();
3762
3763	fDeregister = False;
3764	fRc = self.fSignalled;
3765	if not fRc:
3766	fRc = self._poll();
3767	if fRc or self.getAgeAsMs() >= self.cMsTimeout:
3768	self.signalTaskLocked();
3769	fDeregister = True;
3770
3771	if not fLocked:
3772	self.unlockTask();
3773
3774	# If we're done, deregister the event callback (w/o owning lock).
3775	if fDeregister:
3776	self._deregisterEventHandler();
3777	return fRc;
3778
3779	def getResult(self):
3780	"""
3781	Returns true if the we succeeded.
3782	Returns false if not. If the task is signalled already, then we
3783	encountered a problem while polling.
3784	"""
3785	return self.fSucceeded;
3786
3787	def cancelTask(self):
3788	"""
3789	Cancels the task.
3790	Just to actively disengage the event handler.
3791	"""
3792	self._deregisterEventHandler();
3793	return True;

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

source: vbox/trunk/src/VBox/ValidationKit/testdriver/vboxwrappers.py@ 103025

Download in other formats: