[vbox-dev] Updated Automated-guest-installs for VirtualBox ! (beta5)

[Klaus Espenlaub]

Alexey,

On 08.06.2015 16:04, Alexey Eromenko wrote:
>>> 2. Compatibility with Oracle VirtualBox is unstable: I defined new VM
>>> types for Red Hat guests, like RHEL7_64, which Oracle VirtualBox fails
>>> to understand and renders RHEL VMs inaccessible.
>>
>> It also changes the API (and forgets to change the UUID of IMachine,
>> which means that compiled API clients using the "native" interface would
>> crash or call the wrong method). If the UUID of IMachine would be
>> updated then existing 3rd party API clients using the "native" interface
>> would refuse to work. In other words: there is no solution which truly
>> solves the incompatibility.
>>
>> With the API groundwork of VirtualBox 5.0 it will be possible in the
>> future to support multiple interface versions once several generators
>> and tools are extended further (no idea when we have time for this).
>> Then such API incompatibilities can be handled cleanly. The API wrapper
>> generator is designed to be far more than yet another quirky abstraction :)
>>
>
> I don't understand this COM issue at all.

OK... let me explain a little (I might need it again in the future, 
which means doing it publicly increases the chance I can find it and 
save time :) ).

With COM (and XPCOM borrowed the exact same idea) every interface is 
associated with a UUID (in the IMachine case as of VirtualBox 5.0 that's 
6bf820b3-a08f-49a7-ac08-b88efbd3a313). A specific interface UUID has a 
defined set of API attributes and methods, in a defined order.

One COM object can implement multiple interfaces, and there's a 
mandatory method for querying the interface with a specific UUID for 
some other object reference.

>   Assume IMachine has UUID: 0x1111
> IMachine::Foo() has 0xF00 (assume it is part of Oracle's VirtualBox)

Interfaces (corresponding to specific C++ vtables) as a whole have a 
UUID. Each method is represented by a pointer in the vtable at a 
specific index. So what you wanted to say is that IMachine has e.g. 
vtable indexes 0..99 used (made up numbers, the point here is 
independent of the exact value).

> Now I have added a new main API function in my patch:
> IMachine::Boo() and decided it has 0xB00 (UUID 0xB00 was never used in Oracle)

You wanted to say that you added a method to the end, with index 100.

> What is the problem with this ?
>
> I don't see how adding Boo() with a new UUID can it possibly break
> IMachine class or IMachine::Foo() method.
>
> Anyway I did test VBoxPython code, and it seems to work.

Sure it works, because you built all the code consistently with the 
additional entry in the vtable, so nothing bad will happen. The 
incompatible change (relative to official vbox) is of course compatible 
with itself.

Say that a 3rd party developer hacked up an API client in C++ (which 
directly uses the vtable entries). If he built the code against the _TE 
variant of the API (using the new method) and then someone runs it 
against official vbox it would reach the place with the new method call 
(because it would query the interface with the UUID for IMachine it 
knows), and call the not existing method at index 100. Crash.

That's why one needs to change the interface UUID whenever any method is 
added/removed/reordered or its parameters change significantly. Which 
then makes another 3rd party developer's API client (not using any new 
methods but still built against _TE) totally incompatible against 
official vbox, as that one would simply say "no one home" when the API 
client asks for the interface with the new UUID.

For this reason there's a need to support multiple IMachine interfaces. 
COM can handle this, but VirtualBox currently doesn't as there's no 
viable way to specify that class Machine (which implements the IMachine 
interface) supports both the official IMachine interface (with the 
original, unmodified UUID) and say IMachinePlusUnattended (with a new 
UUID and the additional methods). Then a well-written API client could 
use IMachine for pretty much everything. It would be perfectly 
compatible with official vbox and _TE. An API client which wants to use 
the unattended functionality would use IMachinePlusUnattended (if not 
present it would get a NULL object reference, so it could detect the 
problem and give a descriptive error message) to do the new method call.

Klaus

>>> 3. License is simple BSD.
>>
>> Previously it was MIT, but that's just a reminder. It's your change, and
>> therefore you're free to use whichever license you like (including
>> several of them).
>
> Sorry it is MIT (X11). This one seems shorter than BSD.