vboxapi.py@ 95353

Last change on this file since 95353 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 43.0 KB

Line
1	# -- coding: utf-8 --
2	# $Id: vboxapi.py 93115 2022-01-01 11:31:46Z vboxsync $
3	"""
4	VirtualBox Python API Glue.
5	"""
6
7	__copyright__ = \
8	"""
9	Copyright (C) 2009-2022 Oracle Corporation
10
11	This file is part of VirtualBox Open Source Edition (OSE), as
12	available from http://www.virtualbox.org. This file is free software;
13	you can redistribute it and/or modify it under the terms of the GNU
14	General Public License (GPL) as published by the Free Software
15	Foundation, in version 2 as it comes in the "COPYING" file of the
16	VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17	hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18
19	The contents of this file may alternatively be used under the terms
20	of the Common Development and Distribution License Version 1.0
21	(CDDL) only, as it comes in the "COPYING.CDDL" file of the
22	VirtualBox OSE distribution, in which case the provisions of the
23	CDDL are applicable instead of those of the GPL.
24
25	You may elect to license modified versions of this file under the
26	terms and conditions of either the GPL or the CDDL or both.
27	"""
28	__version__ = "$Revision: 93115 $"
29
30
31	# Note! To set Python bitness on OSX use 'export VERSIONER_PYTHON_PREFER_32_BIT=yes'
32
33
34	# Standard Python imports.
35	import os
36	import sys
37	import traceback
38
39
40	if sys.version_info >= (3, 0):
41	xrange = range
42	long = int
43
44	#
45	# Globals, environment and sys.path changes.
46	#
47	import platform
48	VBoxBinDir = os.environ.get("VBOX_PROGRAM_PATH", None)
49	VBoxSdkDir = os.environ.get("VBOX_SDK_PATH", None)
50
51	if VBoxBinDir is None:
52	if platform.system() == 'Darwin':
53	VBoxBinDir = '/Applications/VirtualBox.app/Contents/MacOS'
54	else: # Will be set by the installer
55	VBoxBinDir = "%VBOX_INSTALL_PATH%"
56	else:
57	VBoxBinDir = os.path.abspath(VBoxBinDir)
58
59	if VBoxSdkDir is None:
60	if platform.system() == 'Darwin':
61	VBoxSdkDir = '/Applications/VirtualBox.app/Contents/MacOS/sdk'
62	else: # Will be set by the installer
63	VBoxSdkDir = "%VBOX_SDK_PATH%"
64	else:
65	VBoxSdkDir = os.path.abspath(VBoxSdkDir)
66
67	os.environ["VBOX_PROGRAM_PATH"] = VBoxBinDir
68	os.environ["VBOX_SDK_PATH"] = VBoxSdkDir
69	sys.path.append(VBoxBinDir)
70
71
72	#
73	# Import the generated VirtualBox constants.
74	#
75	from .VirtualBox_constants import VirtualBoxReflectionInfo
76
77
78	class PerfCollector(object):
79	""" This class provides a wrapper over IPerformanceCollector in order to
80	get more 'pythonic' interface.
81
82	To begin collection of metrics use setup() method.
83
84	To get collected data use query() method.
85
86	It is possible to disable metric collection without changing collection
87	parameters with disable() method. The enable() method resumes metric
88	collection.
89	"""
90
91	def __init__(self, mgr, vbox):
92	""" Initializes the instance.
93
94	"""
95	self.mgr = mgr
96	self.isMscom = (mgr.type == 'MSCOM')
97	self.collector = vbox.performanceCollector
98
99	def setup(self, names, objects, period, nsamples):
100	""" Discards all previously collected values for the specified
101	metrics, sets the period of collection and the number of retained
102	samples, enables collection.
103	"""
104	self.collector.setupMetrics(names, objects, period, nsamples)
105
106	def enable(self, names, objects):
107	""" Resumes metric collection for the specified metrics.
108	"""
109	self.collector.enableMetrics(names, objects)
110
111	def disable(self, names, objects):
112	""" Suspends metric collection for the specified metrics.
113	"""
114	self.collector.disableMetrics(names, objects)
115
116	def query(self, names, objects):
117	""" Retrieves collected metric values as well as some auxiliary
118	information. Returns an array of dictionaries, one dictionary per
119	metric. Each dictionary contains the following entries:
120	'name': metric name
121	'object': managed object this metric associated with
122	'unit': unit of measurement
123	'scale': divide 'values' by this number to get float numbers
124	'values': collected data
125	'values_as_string': pre-processed values ready for 'print' statement
126	"""
127	# Get around the problem with input arrays returned in output
128	# parameters (see #3953) for MSCOM.
129	if self.isMscom:
130	(values, names, objects, names_out, objects_out, units, scales, sequence_numbers,
131	indices, lengths) = self.collector.queryMetricsData(names, objects)
132	else:
133	(values, names_out, objects_out, units, scales, sequence_numbers,
134	indices, lengths) = self.collector.queryMetricsData(names, objects)
135	out = []
136	for i in xrange(0, len(names_out)):
137	scale = int(scales[i])
138	if scale != 1:
139	fmt = '%.2f%s'
140	else:
141	fmt = '%d %s'
142	out.append({
143	'name': str(names_out[i]),
144	'object': str(objects_out[i]),
145	'unit': str(units[i]),
146	'scale': scale,
147	'values': [int(values[j]) for j in xrange(int(indices[i]), int(indices[i]) + int(lengths[i]))],
148	'values_as_string': '[' + ', '.join([fmt % (int(values[j]) / scale, units[i]) for j in
149	xrange(int(indices[i]), int(indices[i]) + int(lengths[i]))]) + ']'
150	})
151	return out
152
153
154	#
155	# Attribute hacks.
156	#
157	def ComifyName(name):
158	return name[0].capitalize() + name[1:]
159
160
161	## This is for saving the original DispatchBaseClass __getattr__ and __setattr__
162	# method references.
163	_g_dCOMForward = {
164	'getattr': None,
165	'setattr': None,
166	}
167
168
169	def _CustomGetAttr(self, sAttr):
170	""" Our getattr replacement for DispatchBaseClass. """
171	# Fastpath.
172	oRet = self.__class__.__dict__.get(sAttr)
173	if oRet is not None:
174	return oRet
175
176	# Try case-insensitivity workaround for class attributes (COM methods).
177	sAttrLower = sAttr.lower()
178	for k in list(self.__class__.__dict__.keys()):
179	if k.lower() == sAttrLower:
180	setattr(self.__class__, sAttr, self.__class__.__dict__[k])
181	return getattr(self, k)
182
183	# Slow path.
184	try:
185	return _g_dCOMForward['getattr'](self, ComifyName(sAttr))
186	except AttributeError:
187	return _g_dCOMForward['getattr'](self, sAttr)
188
189
190	def _CustomSetAttr(self, sAttr, oValue):
191	""" Our setattr replacement for DispatchBaseClass. """
192	try:
193	return _g_dCOMForward['setattr'](self, ComifyName(sAttr), oValue)
194	except AttributeError:
195	return _g_dCOMForward['setattr'](self, sAttr, oValue)
196
197
198	class PlatformBase(object):
199	"""
200	Base class for the platform specific code.
201	"""
202
203	def __init__(self, aoParams):
204	_ = aoParams
205
206	def getVirtualBox(self):
207	"""
208	Gets a the IVirtualBox singleton.
209	"""
210	return None
211
212	def getSessionObject(self):
213	"""
214	Get a session object that can be used for opening machine sessions.
215
216	The oIVBox parameter is an getVirtualBox() return value, i.e. an
217	IVirtualBox reference.
218
219	See also openMachineSession.
220	"""
221	return None
222
223	def getType(self):
224	""" Returns the platform type (class name sans 'Platform'). """
225	return None
226
227	def isRemote(self):
228	"""
229	Returns True if remote (web services) and False if local (COM/XPCOM).
230	"""
231	return False
232
233	def getArray(self, oInterface, sAttrib):
234	"""
235	Retrives the value of the array attribute 'sAttrib' from
236	interface 'oInterface'.
237
238	This is for hiding platform specific differences in attributes
239	returning arrays.
240	"""
241	_ = oInterface
242	_ = sAttrib
243	return None
244
245	def setArray(self, oInterface, sAttrib, aoArray):
246	"""
247	Sets the value (aoArray) of the array attribute 'sAttrib' in
248	interface 'oInterface'.
249
250	This is for hiding platform specific differences in attributes
251	setting arrays.
252	"""
253	_ = oInterface
254	_ = sAttrib
255	_ = aoArray
256	return None
257
258	def initPerThread(self):
259	"""
260	Does backend specific initialization for the calling thread.
261	"""
262	return True
263
264	def deinitPerThread(self):
265	"""
266	Does backend specific uninitialization for the calling thread.
267	"""
268	return True
269
270	def createListener(self, oImplClass, dArgs):
271	"""
272	Instantiates and wraps an active event listener class so it can be
273	passed to an event source for registration.
274
275	oImplClass is a class (type, not instance) which implements
276	IEventListener.
277
278	dArgs is a dictionary with string indexed variables. This may be
279	modified by the method to pass platform specific parameters. Can
280	be None.
281
282	This currently only works on XPCOM. COM support is not possible due to
283	shortcuts taken in the COM bridge code, which is not under our control.
284	Use passive listeners for COM and web services.
285	"""
286	_ = oImplClass
287	_ = dArgs
288	raise Exception("No active listeners for this platform")
289
290	def waitForEvents(self, cMsTimeout):
291	"""
292	Wait for events to arrive and process them.
293
294	The timeout (cMsTimeout) is in milliseconds for how long to wait for
295	events to arrive. A negative value means waiting for ever, while 0
296	does not wait at all.
297
298	Returns 0 if events was processed.
299	Returns 1 if timed out or interrupted in some way.
300	Returns 2 on error (like not supported for web services).
301
302	Raises an exception if the calling thread is not the main thread (the one
303	that initialized VirtualBoxManager) or if the time isn't an integer.
304	"""
305	_ = cMsTimeout
306	return 2
307
308	def interruptWaitEvents(self):
309	"""
310	Interrupt a waitForEvents call.
311	This is normally called from a worker thread to wake up the main thread.
312
313	Returns True on success, False on failure.
314	"""
315	return False
316
317	def deinit(self):
318	"""
319	Unitializes the platform specific backend.
320	"""
321	return None
322
323	def queryInterface(self, oIUnknown, sClassName):
324	"""
325	IUnknown::QueryInterface wrapper.
326
327	oIUnknown is who to ask.
328	sClassName is the name of the interface we're asking for.
329	"""
330	return None
331
332	#
333	# Error (exception) access methods.
334	#
335
336	def xcptGetStatus(self, oXcpt):
337	"""
338	Returns the COM status code from the VBox API given exception.
339	"""
340	return None
341
342	def xcptIsDeadInterface(self, oXcpt):
343	"""
344	Returns True if the exception indicates that the interface is dead, False if not.
345	"""
346	return False
347
348	def xcptIsEqual(self, oXcpt, hrStatus):
349	"""
350	Checks if the exception oXcpt is equal to the COM/XPCOM status code
351	hrStatus.
352
353	The oXcpt parameter can be any kind of object, we'll just return True
354	if it doesn't behave like a our exception class.
355
356	Will not raise any exception as long as hrStatus and self are not bad.
357	"""
358	try:
359	hrXcpt = self.xcptGetStatus(oXcpt)
360	except AttributeError:
361	return False
362	if hrXcpt == hrStatus:
363	return True
364
365	# Fudge for 32-bit signed int conversion.
366	if 0x7fffffff < hrStatus <= 0xffffffff and hrXcpt < 0:
367	if (hrStatus - 0x100000000) == hrXcpt:
368	return True
369	return False
370
371	def xcptGetMessage(self, oXcpt):
372	"""
373	Returns the best error message found in the COM-like exception.
374	Returns None to fall back on xcptToString.
375	Raises exception if oXcpt isn't our kind of exception object.
376	"""
377	return None
378
379	def xcptGetBaseXcpt(self):
380	"""
381	Returns the base exception class.
382	"""
383	return None
384
385	def xcptSetupConstants(self, oDst):
386	"""
387	Copy/whatever all error constants onto oDst.
388	"""
389	return oDst
390
391	@staticmethod
392	def xcptCopyErrorConstants(oDst, oSrc):
393	"""
394	Copy everything that looks like error constants from oDst to oSrc.
395	"""
396	for sAttr in dir(oSrc):
397	if sAttr[0].isupper() and (sAttr[1].isupper() or sAttr[1] == '_'):
398	oAttr = getattr(oSrc, sAttr)
399	if type(oAttr) is int:
400	setattr(oDst, sAttr, oAttr)
401	return oDst
402
403
404	class PlatformMSCOM(PlatformBase):
405	"""
406	Platform specific code for MS COM.
407	"""
408
409	## @name VirtualBox COM Typelib definitions (should be generate)
410	#
411	# @remarks Must be updated when the corresponding VirtualBox.xidl bits
412	# are changed. Fortunately this isn't very often.
413	# @{
414	VBOX_TLB_GUID = '{D7569351-1750-46F0-936E-BD127D5BC264}'
415	VBOX_TLB_LCID = 0
416	VBOX_TLB_MAJOR = 1
417	VBOX_TLB_MINOR = 3
418	## @}
419
420	def __init__(self, dParams):
421	PlatformBase.__init__(self, dParams)
422
423	#
424	# Since the code runs on all platforms, we have to do a lot of
425	# importing here instead of at the top of the file where it's normally located.
426	#
427	from win32com import universal
428	from win32com.client import gencache, DispatchBaseClass
429	from win32com.client import constants, getevents
430	import win32com
431	import pythoncom
432	import win32api
433	import winerror
434	from win32con import DUPLICATE_SAME_ACCESS
435	from win32api import GetCurrentThread, GetCurrentThreadId, DuplicateHandle, GetCurrentProcess
436	import threading
437
438	self.winerror = winerror
439
440	# Setup client impersonation in COM calls.
441	try:
442	pythoncom.CoInitializeSecurity(None,
443	None,
444	None,
445	pythoncom.RPC_C_AUTHN_LEVEL_DEFAULT,
446	pythoncom.RPC_C_IMP_LEVEL_IMPERSONATE,
447	None,
448	pythoncom.EOAC_NONE,
449	None)
450	except:
451	_, oXcpt, _ = sys.exc_info();
452	if isinstance(oXcpt, pythoncom.com_error) and self.xcptGetStatus(oXcpt) == -2147417831: # RPC_E_TOO_LATE
453	print("Warning: CoInitializeSecurity was already called");
454	else:
455	print("Warning: CoInitializeSecurity failed: ", oXcpt);
456
457	# Remember this thread ID and get its handle so we can wait on it in waitForEvents().
458	self.tid = GetCurrentThreadId()
459	pid = GetCurrentProcess()
460	self.aoHandles = [DuplicateHandle(pid, GetCurrentThread(), pid, 0, 0, DUPLICATE_SAME_ACCESS),] # type: list[PyHANDLE]
461
462	# Hack the COM dispatcher base class so we can modify method and
463	# attribute names to match those in xpcom.
464	if _g_dCOMForward['setattr'] is None:
465	_g_dCOMForward['getattr'] = DispatchBaseClass.__dict__['__getattr__']
466	_g_dCOMForward['setattr'] = DispatchBaseClass.__dict__['__setattr__']
467	setattr(DispatchBaseClass, '__getattr__', _CustomGetAttr)
468	setattr(DispatchBaseClass, '__setattr__', _CustomSetAttr)
469
470	# Hack the exception base class so the users doesn't need to check for
471	# XPCOM or COM and do different things.
472	## @todo
473
474	#
475	# Make sure the gencache is correct (we don't quite follow the COM
476	# versioning rules).
477	#
478	self.flushGenPyCache(win32com.client.gencache)
479	win32com.client.gencache.EnsureDispatch('VirtualBox.Session')
480	win32com.client.gencache.EnsureDispatch('VirtualBox.VirtualBox')
481	win32com.client.gencache.EnsureDispatch('VirtualBox.VirtualBoxClient')
482
483	self.oClient = None ##< instance of client used to support lifetime of VBoxSDS
484	self.oIntCv = threading.Condition()
485	self.fInterrupted = False
486
487	_ = dParams
488
489	def flushGenPyCache(self, oGenCache):
490	"""
491	Flushes VBox related files in the win32com gen_py cache.
492
493	This is necessary since we don't follow the typelib versioning rules
494	that everyeone else seems to subscribe to.
495	"""
496	#
497	# The EnsureModule method have broken validation code, it doesn't take
498	# typelib module directories into account. So we brute force them here.
499	# (It's possible the directory approach is from some older pywin
500	# version or the result of runnig makepy or gencache manually, but we
501	# need to cover it as well.)
502	#
503	sName = oGenCache.GetGeneratedFileName(self.VBOX_TLB_GUID, self.VBOX_TLB_LCID,
504	self.VBOX_TLB_MAJOR, self.VBOX_TLB_MINOR)
505	sGenPath = oGenCache.GetGeneratePath()
506	if len(sName) > 36 and len(sGenPath) > 5:
507	sTypelibPath = os.path.join(sGenPath, sName)
508	if os.path.isdir(sTypelibPath):
509	import shutil
510	shutil.rmtree(sTypelibPath, ignore_errors=True)
511
512	#
513	# Ensure that our typelib is valid.
514	#
515	return oGenCache.EnsureModule(self.VBOX_TLB_GUID, self.VBOX_TLB_LCID, self.VBOX_TLB_MAJOR, self.VBOX_TLB_MINOR)
516
517	def getSessionObject(self):
518	import win32com
519	from win32com.client import Dispatch
520	return win32com.client.Dispatch("VirtualBox.Session")
521
522	def getVirtualBox(self):
523	# Caching self.oClient is the trick for SDS. It allows to keep the
524	# VBoxSDS in the memory until the end of PlatformMSCOM lifetme.
525	if self.oClient is None:
526	import win32com
527	from win32com.client import Dispatch
528	self.oClient = win32com.client.Dispatch("VirtualBox.VirtualBoxClient")
529	return self.oClient.virtualBox
530
531	def getType(self):
532	return 'MSCOM'
533
534	def getArray(self, oInterface, sAttrib):
535	return oInterface.__getattr__(sAttrib)
536
537	def setArray(self, oInterface, sAttrib, aoArray):
538	#
539	# HACK ALERT!
540	#
541	# With pywin32 build 218, we're seeing type mismatch errors here for
542	# IGuestSession::environmentChanges (safearray of BSTRs). The Dispatch
543	# object (_oleobj_) seems to get some type conversion wrong and COM
544	# gets upset. So, we redo some of the dispatcher work here, picking
545	# the missing type information from the getter.
546	#
547	oOleObj = getattr(oInterface, '_oleobj_')
548	aPropMapGet = getattr(oInterface, '_prop_map_get_')
549	aPropMapPut = getattr(oInterface, '_prop_map_put_')
550	sComAttrib = sAttrib if sAttrib in aPropMapGet else ComifyName(sAttrib)
551	try:
552	aArgs, aDefaultArgs = aPropMapPut[sComAttrib]
553	aGetArgs = aPropMapGet[sComAttrib]
554	except KeyError: # fallback.
555	return oInterface.__setattr__(sAttrib, aoArray)
556
557	import pythoncom
558	oOleObj.InvokeTypes(aArgs[0], # dispid
559	aArgs[1], # LCID
560	aArgs[2], # DISPATCH_PROPERTYPUT
561	(pythoncom.VT_HRESULT, 0), # retType - or void?
562	(aGetArgs[2],), # argTypes - trick: we get the type from the getter.
563	aoArray,) # The array
564
565	def initPerThread(self):
566	import pythoncom
567	pythoncom.CoInitializeEx(0)
568
569	def deinitPerThread(self):
570	import pythoncom
571	pythoncom.CoUninitialize()
572
573	def createListener(self, oImplClass, dArgs):
574	if True:
575	raise Exception('no active listeners on Windows as PyGatewayBase::QueryInterface() '
576	'returns new gateway objects all the time, thus breaking EventQueue '
577	'assumptions about the listener interface pointer being constants between calls ')
578	# Did this code ever really work?
579	d = {}
580	d['BaseClass'] = oImplClass
581	d['dArgs'] = dArgs
582	d['tlb_guid'] = PlatformMSCOM.VBOX_TLB_GUID
583	d['tlb_major'] = PlatformMSCOM.VBOX_TLB_MAJOR
584	d['tlb_minor'] = PlatformMSCOM.VBOX_TLB_MINOR
585	str_ = ""
586	str_ += "import win32com.server.util\n"
587	str_ += "import pythoncom\n"
588
589	str_ += "class ListenerImpl(BaseClass):\n"
590	str_ += " _com_interfaces_ = ['IEventListener']\n"
591	str_ += " _typelib_guid_ = tlb_guid\n"
592	str_ += " _typelib_version_ = tlb_major, tlb_minor\n"
593	str_ += " _reg_clsctx_ = pythoncom.CLSCTX_INPROC_SERVER\n"
594	# Maybe we'd better implement Dynamic invoke policy, to be more flexible here
595	str_ += " _reg_policy_spec_ = 'win32com.server.policy.EventHandlerPolicy'\n"
596
597	# capitalized version of listener method
598	str_ += " HandleEvent=BaseClass.handleEvent\n"
599	str_ += " def __init__(self): BaseClass.__init__(self, dArgs)\n"
600	str_ += "result = win32com.server.util.wrap(ListenerImpl())\n"
601	exec(str_, d, d)
602	return d['result']
603
604	def waitForEvents(self, timeout):
605	from win32api import GetCurrentThreadId
606	from win32event import INFINITE
607	from win32event import MsgWaitForMultipleObjects, QS_ALLINPUT, WAIT_TIMEOUT, WAIT_OBJECT_0
608	from pythoncom import PumpWaitingMessages
609	import types
610
611	if not isinstance(timeout, int):
612	raise TypeError("The timeout argument is not an integer")
613	if self.tid != GetCurrentThreadId():
614	raise Exception("wait for events from the same thread you inited!")
615
616	if timeout < 0:
617	cMsTimeout = INFINITE
618	else:
619	cMsTimeout = timeout
620	rc = MsgWaitForMultipleObjects(self.aoHandles, 0, cMsTimeout, QS_ALLINPUT)
621	if WAIT_OBJECT_0 <= rc < WAIT_OBJECT_0 + len(self.aoHandles):
622	# is it possible?
623	rc = 2
624	elif rc == WAIT_OBJECT_0 + len(self.aoHandles):
625	# Waiting messages
626	PumpWaitingMessages()
627	rc = 0
628	else:
629	# Timeout
630	rc = 1
631
632	# check for interruption
633	self.oIntCv.acquire()
634	if self.fInterrupted:
635	self.fInterrupted = False
636	rc = 1
637	self.oIntCv.release()
638
639	return rc
640
641	def interruptWaitEvents(self):
642	"""
643	Basically a python implementation of NativeEventQueue::postEvent().
644
645	The magic value must be in sync with the C++ implementation or this
646	won't work.
647
648	Note that because of this method we cannot easily make use of a
649	non-visible Window to handle the message like we would like to do.
650	"""
651	from win32api import PostThreadMessage
652	from win32con import WM_USER
653
654	self.oIntCv.acquire()
655	self.fInterrupted = True
656	self.oIntCv.release()
657	try:
658	PostThreadMessage(self.tid, WM_USER, None, 0xf241b819)
659	except:
660	return False
661	return True
662
663	def deinit(self):
664	for oHandle in self.aoHandles:
665	if oHandle is not None:
666	oHandle.Close();
667	self.oHandle = None;
668
669	del self.oClient;
670	self.oClient = None;
671
672	# This non-sense doesn't pair up with any pythoncom.CoInitialize[Ex].
673	# See @bugref{9037}.
674	#import pythoncom
675	#pythoncom.CoUninitialize()
676
677	def queryInterface(self, oIUnknown, sClassName):
678	from win32com.client import CastTo
679	return CastTo(oIUnknown, sClassName)
680
681	def xcptGetStatus(self, oXcpt):
682	# The DISP_E_EXCEPTION + excptinfo fun needs checking up, only
683	# empirical info on it so far.
684	hrXcpt = oXcpt.hresult
685	if hrXcpt == self.winerror.DISP_E_EXCEPTION:
686	try:
687	hrXcpt = oXcpt.excepinfo[5]
688	except:
689	pass
690	return hrXcpt
691
692	def xcptIsDeadInterface(self, oXcpt):
693	return self.xcptGetStatus(oXcpt) in [
694	0x800706ba, -2147023174, # RPC_S_SERVER_UNAVAILABLE.
695	0x800706be, -2147023170, # RPC_S_CALL_FAILED.
696	0x800706bf, -2147023169, # RPC_S_CALL_FAILED_DNE.
697	0x80010108, -2147417848, # RPC_E_DISCONNECTED.
698	0x800706b5, -2147023179, # RPC_S_UNKNOWN_IF
699	]
700
701	def xcptGetMessage(self, oXcpt):
702	if hasattr(oXcpt, 'excepinfo'):
703	try:
704	if len(oXcpt.excepinfo) >= 3:
705	sRet = oXcpt.excepinfo[2]
706	if len(sRet) > 0:
707	return sRet[0:]
708	except:
709	pass
710	if hasattr(oXcpt, 'strerror'):
711	try:
712	sRet = oXcpt.strerror
713	if len(sRet) > 0:
714	return sRet
715	except:
716	pass
717	return None
718
719	def xcptGetBaseXcpt(self):
720	import pythoncom
721
722	return pythoncom.com_error
723
724	def xcptSetupConstants(self, oDst):
725	import winerror
726
727	oDst = self.xcptCopyErrorConstants(oDst, winerror)
728
729	# XPCOM compatability constants.
730	oDst.NS_OK = oDst.S_OK
731	oDst.NS_ERROR_FAILURE = oDst.E_FAIL
732	oDst.NS_ERROR_ABORT = oDst.E_ABORT
733	oDst.NS_ERROR_NULL_POINTER = oDst.E_POINTER
734	oDst.NS_ERROR_NO_INTERFACE = oDst.E_NOINTERFACE
735	oDst.NS_ERROR_INVALID_ARG = oDst.E_INVALIDARG
736	oDst.NS_ERROR_OUT_OF_MEMORY = oDst.E_OUTOFMEMORY
737	oDst.NS_ERROR_NOT_IMPLEMENTED = oDst.E_NOTIMPL
738	oDst.NS_ERROR_UNEXPECTED = oDst.E_UNEXPECTED
739	return oDst
740
741
742	class PlatformXPCOM(PlatformBase):
743	"""
744	Platform specific code for XPCOM.
745	"""
746
747	def __init__(self, dParams):
748	PlatformBase.__init__(self, dParams)
749	sys.path.append(VBoxSdkDir + '/bindings/xpcom/python/')
750	import xpcom.vboxxpcom
751	import xpcom
752	import xpcom.components
753	_ = dParams
754
755	def getSessionObject(self):
756	import xpcom.components
757	return xpcom.components.classes["@virtualbox.org/Session;1"].createInstance()
758
759	def getVirtualBox(self):
760	import xpcom.components
761	client = xpcom.components.classes["@virtualbox.org/VirtualBoxClient;1"].createInstance()
762	return client.virtualBox
763
764	def getType(self):
765	return 'XPCOM'
766
767	def getArray(self, oInterface, sAttrib):
768	return oInterface.__getattr__('get' + ComifyName(sAttrib))()
769
770	def setArray(self, oInterface, sAttrib, aoArray):
771	return oInterface.__getattr__('set' + ComifyName(sAttrib))(aoArray)
772
773	def initPerThread(self):
774	import xpcom
775	xpcom._xpcom.AttachThread()
776
777	def deinitPerThread(self):
778	import xpcom
779	xpcom._xpcom.DetachThread()
780
781	def createListener(self, oImplClass, dArgs):
782	d = {}
783	d['BaseClass'] = oImplClass
784	d['dArgs'] = dArgs
785	str = ""
786	str += "import xpcom.components\n"
787	str += "class ListenerImpl(BaseClass):\n"
788	str += " _com_interfaces_ = xpcom.components.interfaces.IEventListener\n"
789	str += " def __init__(self): BaseClass.__init__(self, dArgs)\n"
790	str += "result = ListenerImpl()\n"
791	exec(str, d, d)
792	return d['result']
793
794	def waitForEvents(self, timeout):
795	import xpcom
796	return xpcom._xpcom.WaitForEvents(timeout)
797
798	def interruptWaitEvents(self):
799	import xpcom
800	return xpcom._xpcom.InterruptWait()
801
802	def deinit(self):
803	import xpcom
804	xpcom._xpcom.DeinitCOM()
805
806	def queryInterface(self, oIUnknown, sClassName):
807	import xpcom.components
808	return oIUnknown.queryInterface(getattr(xpcom.components.interfaces, sClassName))
809
810	def xcptGetStatus(self, oXcpt):
811	return oXcpt.errno
812
813	def xcptIsDeadInterface(self, oXcpt):
814	return self.xcptGetStatus(oXcpt) in [
815	0x80004004, -2147467260, # NS_ERROR_ABORT
816	0x800706be, -2147023170, # NS_ERROR_CALL_FAILED (RPC_S_CALL_FAILED)
817	]
818
819	def xcptGetMessage(self, oXcpt):
820	if hasattr(oXcpt, 'msg'):
821	try:
822	sRet = oXcpt.msg
823	if len(sRet) > 0:
824	return sRet
825	except:
826	pass
827	return None
828
829	def xcptGetBaseXcpt(self):
830	import xpcom
831	return xpcom.Exception
832
833	def xcptSetupConstants(self, oDst):
834	import xpcom
835	oDst = self.xcptCopyErrorConstants(oDst, xpcom.nsError)
836
837	# COM compatability constants.
838	oDst.E_ACCESSDENIED = -2147024891 # see VBox/com/defs.h
839	oDst.S_OK = oDst.NS_OK
840	oDst.E_FAIL = oDst.NS_ERROR_FAILURE
841	oDst.E_ABORT = oDst.NS_ERROR_ABORT
842	oDst.E_POINTER = oDst.NS_ERROR_NULL_POINTER
843	oDst.E_NOINTERFACE = oDst.NS_ERROR_NO_INTERFACE
844	oDst.E_INVALIDARG = oDst.NS_ERROR_INVALID_ARG
845	oDst.E_OUTOFMEMORY = oDst.NS_ERROR_OUT_OF_MEMORY
846	oDst.E_NOTIMPL = oDst.NS_ERROR_NOT_IMPLEMENTED
847	oDst.E_UNEXPECTED = oDst.NS_ERROR_UNEXPECTED
848	oDst.DISP_E_EXCEPTION = -2147352567 # For COM compatability only.
849	return oDst
850
851
852	class PlatformWEBSERVICE(PlatformBase):
853	"""
854	VirtualBox Web Services API specific code.
855	"""
856
857	def __init__(self, dParams):
858	PlatformBase.__init__(self, dParams)
859	# Import web services stuff. Fix the sys.path the first time.
860	sWebServLib = os.path.join(VBoxSdkDir, 'bindings', 'webservice', 'python', 'lib')
861	if sWebServLib not in sys.path:
862	sys.path.append(sWebServLib)
863	import VirtualBox_wrappers
864	from VirtualBox_wrappers import IWebsessionManager2
865
866	# Initialize instance variables from parameters.
867	if dParams is not None:
868	self.user = dParams.get("user", "")
869	self.password = dParams.get("password", "")
870	self.url = dParams.get("url", "")
871	else:
872	self.user = ""
873	self.password = ""
874	self.url = None
875	self.vbox = None
876	self.wsmgr = None
877
878	#
879	# Base class overrides.
880	#
881
882	def getSessionObject(self):
883	return self.wsmgr.getSessionObject(self.vbox)
884
885	def getVirtualBox(self):
886	return self.connect(self.url, self.user, self.password)
887
888	def getType(self):
889	return 'WEBSERVICE'
890
891	def isRemote(self):
892	""" Returns True if remote VBox host, False if local. """
893	return True
894
895	def getArray(self, oInterface, sAttrib):
896	return oInterface.__getattr__(sAttrib)
897
898	def setArray(self, oInterface, sAttrib, aoArray):
899	return oInterface.__setattr__(sAttrib, aoArray)
900
901	def waitForEvents(self, timeout):
902	# Webservices cannot do that yet
903	return 2
904
905	def interruptWaitEvents(self, timeout):
906	# Webservices cannot do that yet
907	return False
908
909	def deinit(self):
910	try:
911	self.disconnect()
912	except:
913	pass
914
915	def queryInterface(self, oIUnknown, sClassName):
916	d = {}
917	d['oIUnknown'] = oIUnknown
918	str = ""
919	str += "from VirtualBox_wrappers import " + sClassName + "\n"
920	str += "result = " + sClassName + "(oIUnknown.mgr, oIUnknown.handle)\n"
921	# wrong, need to test if class indeed implements this interface
922	exec(str, d, d)
923	return d['result']
924
925	#
926	# Web service specific methods.
927	#
928
929	def connect(self, url, user, passwd):
930	if self.vbox is not None:
931	self.disconnect()
932	from VirtualBox_wrappers import IWebsessionManager2
933
934	if url is None:
935	url = ""
936	self.url = url
937	if user is None:
938	user = ""
939	self.user = user
940	if passwd is None:
941	passwd = ""
942	self.password = passwd
943	self.wsmgr = IWebsessionManager2(self.url)
944	self.vbox = self.wsmgr.logon(self.user, self.password)
945	if not self.vbox.handle:
946	raise Exception("cannot connect to '" + self.url + "' as '" + self.user + "'")
947	return self.vbox
948
949	def disconnect(self):
950	if self.vbox is not None and self.wsmgr is not None:
951	self.wsmgr.logoff(self.vbox)
952	self.vbox = None
953	self.wsmgr = None
954
955
956	## The current (last) exception class.
957	# This is reinitalized whenever VirtualBoxManager is called, so it will hold
958	# the reference to the error exception class for the last platform/style that
959	# was used. Most clients does talk to multiple VBox instance on different
960	# platforms at the same time, so this should be sufficent for most uses and
961	# be way simpler to use than VirtualBoxManager::oXcptClass.
962	CurXcptClass = None
963
964
965	class VirtualBoxManager(object):
966	"""
967	VirtualBox API manager class.
968
969	The API users will have to instantiate this. If no parameters are given,
970	it will default to interface with the VirtualBox running on the local
971	machine. sStyle can be None (default), MSCOM, XPCOM or WEBSERVICES. Most
972	users will either be specifying None or WEBSERVICES.
973
974	The dPlatformParams is an optional dictionary for passing parameters to the
975	WEBSERVICE backend.
976	"""
977
978	class Statuses(object):
979	def __init__(self):
980	pass
981
982	def __init__(self, sStyle=None, dPlatformParams=None):
983	if sStyle is None:
984	if sys.platform == 'win32':
985	sStyle = "MSCOM"
986	else:
987	sStyle = "XPCOM"
988	if sStyle == 'XPCOM':
989	self.platform = PlatformXPCOM(dPlatformParams)
990	elif sStyle == 'MSCOM':
991	self.platform = PlatformMSCOM(dPlatformParams)
992	elif sStyle == 'WEBSERVICE':
993	self.platform = PlatformWEBSERVICE(dPlatformParams)
994	else:
995	raise Exception('Unknown sStyle=%s' % (sStyle,))
996	self.style = sStyle
997	self.type = self.platform.getType()
998	self.remote = self.platform.isRemote()
999	## VirtualBox API constants (for webservices, enums are symbolic).
1000	self.constants = VirtualBoxReflectionInfo(sStyle == "WEBSERVICE")
1001
1002	## Status constants.
1003	self.statuses = self.platform.xcptSetupConstants(VirtualBoxManager.Statuses())
1004	## @todo Add VBOX_E_XXX to statuses? They're already in constants...
1005	## Dictionary for errToString, built on demand.
1006	self._dErrorValToName = None
1007
1008	## Dictionary for resolving enum values to names, two levels of dictionaries.
1009	## First level is indexed by enum name, the next by value.
1010	self._ddEnumValueToName = {};
1011
1012	## The exception class for the selected platform.
1013	self.oXcptClass = self.platform.xcptGetBaseXcpt()
1014	global CurXcptClass
1015	CurXcptClass = self.oXcptClass
1016
1017	# Get the virtualbox singleton.
1018	try:
1019	vbox = self.platform.getVirtualBox()
1020	except NameError:
1021	print("Installation problem: check that appropriate libs in place")
1022	traceback.print_exc()
1023	raise
1024	except Exception:
1025	_, e, _ = sys.exc_info()
1026	print("init exception: ", e)
1027	traceback.print_exc()
1028
1029	def __del__(self):
1030	self.deinit()
1031
1032	def getPythonApiRevision(self):
1033	"""
1034	Returns a Python API revision number.
1035	This will be incremented when features are added to this file.
1036	"""
1037	return 3
1038
1039	@property
1040	def mgr(self):
1041	"""
1042	This used to be an attribute referring to a session manager class with
1043	only one method called getSessionObject. It moved into this class.
1044	"""
1045	return self
1046
1047	#
1048	# Wrappers for self.platform methods.
1049	#
1050	def getVirtualBox(self):
1051	""" See PlatformBase::getVirtualBox(). """
1052	return self.platform.getVirtualBox()
1053
1054	def getSessionObject(self, oIVBox = None):
1055	""" See PlatformBase::getSessionObject(). """
1056	# ignore parameter which was never needed
1057	_ = oIVBox
1058	return self.platform.getSessionObject()
1059
1060	def getArray(self, oInterface, sAttrib):
1061	""" See PlatformBase::getArray(). """
1062	return self.platform.getArray(oInterface, sAttrib)
1063
1064	def setArray(self, oInterface, sAttrib, aoArray):
1065	""" See PlatformBase::setArray(). """
1066	return self.platform.setArray(oInterface, sAttrib, aoArray)
1067
1068	def createListener(self, oImplClass, dArgs=None):
1069	""" See PlatformBase::createListener(). """
1070	return self.platform.createListener(oImplClass, dArgs)
1071
1072	def waitForEvents(self, cMsTimeout):
1073	""" See PlatformBase::waitForEvents(). """
1074	return self.platform.waitForEvents(cMsTimeout)
1075
1076	def interruptWaitEvents(self):
1077	""" See PlatformBase::interruptWaitEvents(). """
1078	return self.platform.interruptWaitEvents()
1079
1080	def queryInterface(self, oIUnknown, sClassName):
1081	""" See PlatformBase::queryInterface(). """
1082	return self.platform.queryInterface(oIUnknown, sClassName)
1083
1084	#
1085	# Init and uninit.
1086	#
1087	def initPerThread(self):
1088	""" See PlatformBase::deinitPerThread(). """
1089	self.platform.initPerThread()
1090
1091	def deinitPerThread(self):
1092	""" See PlatformBase::deinitPerThread(). """
1093	return self.platform.deinitPerThread()
1094
1095	def deinit(self):
1096	"""
1097	For unitializing the manager.
1098	Do not access it after calling this method.
1099	"""
1100	if hasattr(self, "platform") and self.platform is not None:
1101	self.platform.deinit()
1102	self.platform = None
1103	return True
1104
1105	#
1106	# Utility methods.
1107	#
1108	def openMachineSession(self, oIMachine, fPermitSharing=True):
1109	"""
1110	Attempts to open the a session to the machine.
1111	Returns a session object on success.
1112	Raises exception on failure.
1113	"""
1114	oSession = self.getSessionObject()
1115	if fPermitSharing:
1116	eType = self.constants.LockType_Shared
1117	else:
1118	eType = self.constants.LockType_Write
1119	oIMachine.lockMachine(oSession, eType)
1120	return oSession
1121
1122	def closeMachineSession(self, oSession):
1123	"""
1124	Closes a session opened by openMachineSession.
1125	Ignores None parameters.
1126	"""
1127	if oSession is not None:
1128	oSession.unlockMachine()
1129	return True
1130
1131	def getPerfCollector(self, oIVBox):
1132	"""
1133	Returns a helper class (PerfCollector) for accessing performance
1134	collector goodies. See PerfCollector for details.
1135	"""
1136	return PerfCollector(self, oIVBox)
1137
1138	def getBinDir(self):
1139	"""
1140	Returns the VirtualBox binary directory.
1141	"""
1142	global VBoxBinDir
1143	return VBoxBinDir
1144
1145	def getSdkDir(self):
1146	"""
1147	Returns the VirtualBox SDK directory.
1148	"""
1149	global VBoxSdkDir
1150	return VBoxSdkDir
1151
1152	def getEnumValueName(self, sEnumTypeNm, oEnumValue, fTypePrefix = False):
1153	"""
1154	Returns the name (string) for the corresponding enum value.
1155	"""
1156	# Cache lookup:
1157	dValueNames = self._ddEnumValueToName.get(sEnumTypeNm);
1158	if dValueNames is not None:
1159	sValueName = dValueNames.get(oEnumValue);
1160	if sValueName:
1161	return sValueName if not fTypePrefix else '%s_%s' % (sEnumTypeNm, sValueName);
1162	else:
1163	# Cache miss. Build the reverse lookup dictionary and add it to the cache:
1164	dNamedValues = self.constants.all_values(sEnumTypeNm);
1165	if len(dNamedValues) > 0:
1166
1167	dValueNames = dict();
1168	for sName in dNamedValues:
1169	dValueNames[dNamedValues[sName]] = sName;
1170	self._ddEnumValueToName[sEnumTypeNm] = dValueNames;
1171
1172	# Lookup the value:
1173	sValueName = dValueNames.get(oEnumValue);
1174	if sValueName:
1175	return sValueName if not fTypePrefix else '%s_%s' % (sEnumTypeNm, sValueName);
1176
1177	# Fallback:
1178	return '%s_Unknown_%s' % (sEnumTypeNm, oEnumValue);
1179
1180	#
1181	# Error code utilities.
1182	#
1183	## @todo port to webservices!
1184	def xcptGetStatus(self, oXcpt=None):
1185	"""
1186	Gets the status code from an exception. If the exception parameter
1187	isn't specified, the current exception is examined.
1188	"""
1189	if oXcpt is None:
1190	oXcpt = sys.exc_info()[1]
1191	return self.platform.xcptGetStatus(oXcpt)
1192
1193	def xcptIsDeadInterface(self, oXcpt=None):
1194	"""
1195	Returns True if the exception indicates that the interface is dead,
1196	False if not. If the exception parameter isn't specified, the current
1197	exception is examined.
1198	"""
1199	if oXcpt is None:
1200	oXcpt = sys.exc_info()[1]
1201	return self.platform.xcptIsDeadInterface(oXcpt)
1202
1203	def xcptIsOurXcptKind(self, oXcpt=None):
1204	"""
1205	Checks if the exception is one that could come from the VBox API. If
1206	the exception parameter isn't specified, the current exception is
1207	examined.
1208	"""
1209	if self.oXcptClass is None: # @todo find the exception class for web services!
1210	return False
1211	if oXcpt is None:
1212	oXcpt = sys.exc_info()[1]
1213	return isinstance(oXcpt, self.oXcptClass)
1214
1215	def xcptIsEqual(self, oXcpt, hrStatus):
1216	"""
1217	Checks if the exception oXcpt is equal to the COM/XPCOM status code
1218	hrStatus.
1219
1220	The oXcpt parameter can be any kind of object, we'll just return True
1221	if it doesn't behave like a our exception class. If it's None, we'll
1222	query the current exception and examine that.
1223
1224	Will not raise any exception as long as hrStatus and self are not bad.
1225	"""
1226	if oXcpt is None:
1227	oXcpt = sys.exc_info()[1]
1228	return self.platform.xcptIsEqual(oXcpt, hrStatus)
1229
1230	def xcptIsNotEqual(self, oXcpt, hrStatus):
1231	"""
1232	Negated xcptIsEqual.
1233	"""
1234	return not self.xcptIsEqual(oXcpt, hrStatus)
1235
1236	def xcptToString(self, hrStatusOrXcpt=None):
1237	"""
1238	Converts the specified COM status code, or the status code of the
1239	specified exception, to a C constant string. If the parameter isn't
1240	specified (is None), the current exception is examined.
1241	"""
1242
1243	# Deal with exceptions.
1244	if hrStatusOrXcpt is None or self.xcptIsOurXcptKind(hrStatusOrXcpt):
1245	hrStatus = self.xcptGetStatus(hrStatusOrXcpt)
1246	else:
1247	hrStatus = hrStatusOrXcpt
1248
1249	# Build the dictionary on demand.
1250	if self._dErrorValToName is None:
1251	dErrorValToName = dict()
1252	for sKey in dir(self.statuses):
1253	if sKey[0].isupper():
1254	oValue = getattr(self.statuses, sKey)
1255	if isinstance(oValue, (int, long)):
1256	dErrorValToName[int(oValue)] = sKey
1257	# Always prefer the COM names (see aliasing in platform specific code):
1258	for sKey in ('S_OK', 'E_FAIL', 'E_ABORT', 'E_POINTER', 'E_NOINTERFACE', 'E_INVALIDARG',
1259	'E_OUTOFMEMORY', 'E_NOTIMPL', 'E_UNEXPECTED',):
1260	oValue = getattr(self.statuses, sKey, None)
1261	if oValue is not None:
1262	dErrorValToName[oValue] = sKey
1263	self._dErrorValToName = dErrorValToName
1264
1265	# Do the lookup, falling back on formatting the status number.
1266	try:
1267	sStr = self._dErrorValToName[int(hrStatus)]
1268	except KeyError:
1269	hrLong = long(hrStatus)
1270	sStr = '%#x (%d)' % (hrLong & 0xffffffff, hrLong)
1271	return sStr
1272
1273	def xcptGetMessage(self, oXcpt=None):
1274	"""
1275	Returns the best error message found in the COM-like exception. If the
1276	exception parameter isn't specified, the current exception is examined.
1277	"""
1278	if oXcpt is None:
1279	oXcpt = sys.exc_info()[1]
1280	sRet = self.platform.xcptGetMessage(oXcpt)
1281	if sRet is None:
1282	sRet = self.xcptToString(oXcpt)
1283	return sRet
1284

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

source: vbox/trunk/src/VBox/Main/glue/vboxapi.py@ 95353

Download in other formats: