<html><head><base href="x-msg://1763/"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>Joe,</div><div><br></div><div>the policy is that when we do a major update (first and/or second digit change, 3.2 is one), we may change APIs in incompatible ways. This is is a burden on the API consumer but it allows us to keep a clean design and not accumulate legacy. Within one major version (e.g. 3.1.x), we guarantee API stability.</div><div><br></div><div>Regarding versioning, the first call you make should be to query the VirtualBox version number. Then you know which API is in place and in your code, you should differentiate between versions and make the appropriate calls.</div><div><br></div><div>Ideally, we document all API changes in the SDK manual but unfortunately that didn't happen for the 3.2.0 release. Some of the changes are explained (section 7.5) but it's not complete. We will address this for the upcoming 3.2.2 service release.</div><div><br></div><div>The IGuest::getStatistics stuff is gone in 3.2 as it was a Windows guest only temporary solution that got finally folded into the more generic metrics API.</div><div><br></div><div>A good way to see what has changed is to diff VirtualBox.xidl which is the abstract definition of our API. You can find the trunk version here: <a href="http://www.virtualbox.org/browser/trunk/src/VBox/Main/idl/VirtualBox.xidl">http://www.virtualbox.org/browser/trunk/src/VBox/Main/idl/VirtualBox.xidl</a></div><div>Just diff the one from the 3.2.0 tarball and the one from 3.1.8 to get an idea.</div><div><br></div><div>Achim</div><div><br></div><br><div><div>On May 20, 2010, at 10:27 , Joseph Smith wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font-family: 'times new roman', 'new york', times, serif; font-size: 12pt; "><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Hi,</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">I am currently using VBox 3.1.6 webservice APIs (PHP version) and decided to make the jump to version 3.2 (skipping 3.1.8) as I thought it was time to 'get caught up'.</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">In doing so, I got caught by a few surprises. I have only begun initial testing ... here is what I've found thus far:</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">1) IMachine::getCPUProperty throws the following exception:</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Method 'ns1:IMachine_getCpuProperty' not implemented: method name or namespace not recognized). The method is described in the WSDL and so is the CPUPropertyType. PHP API wrappers also appears to be correct. Was this method deprecated?</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">2) IGuest::getStatistic (required a parm of 'GuestStatisticType') does not seem to be a valid method any more. Appears to have been replaced with IGuest::internalGetStatistics. From the 3.2 API docs ... seems this method is intended to only be called internally? What does 'internal' mean here? I am assuming the getStatistic method was deprecated?</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">3) IDisplay::getWidth, IDisplay::getHeight and IDisplay::getBitsPerPixel do not seem to be valid any more. Appears to have been replaced with IDisplay::getScreenResolution. I'm guessing here the width, height and bpp elements were depricated?</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Thinking I missed something ... I went back and looked at the 3.1.8 docs to find where deprecated functions were listed ... and found the usual IVirtualBox::createLegacyMachine and IVirtualBox::openMachine listed ... but nothing else.</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Some questions:</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">1) Where are deprecated and 'planned to be deprecated' APIs and fields/elements listed? Is it somewhere else I should have checked?</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">2) What is the deprecation policy? How far in advance will APIs be advised of deprecation?</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">3) Generally ... when APIs are deprecated ... they are supported for N past versions ... what is the past-version-support and 'roll-off' duration for deprecated APIs?</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">I am trying to identify a proactive way in detecting changes to APIs that my solution uses so that I don't have to suddenly react for a new release. Is there some other documentation that details all this and I'm just not aware of it? This is not the first time ... a similar situation happened when the more robust and better IMedium and IStorageController approach was added.</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">May I make a suggestion:</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">WSDL files and the vboxServiceWrappers.php file do not appear have any 'version' related information that could allow an application to be "smarter" about what APIs are available. Can versioning be added to the WSDL files that correlate somehow to the API version? Maybe an enumerated list of releases of the VirtualBox application that the WSDL supports ... or even a simple comma separated list of versions? That way, the generated vboxServiceWrappers.php module (and other generated modules) would also include that information. It could go a long way in allowing applications to use the version information to make 'smart' decisions about which APIs or features are available or not.</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Thanks,</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Joe</div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><br></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; position: fixed; "></div></div><br>_______________________________________________<br>vbox-dev mailing list<br><a href="mailto:vbox-dev@virtualbox.org">vbox-dev@virtualbox.org</a><br><a href="http://vbox.innotek.de/mailman/listinfo/vbox-dev">http://vbox.innotek.de/mailman/listinfo/vbox-dev</a><br></div></blockquote></div><br><div>
<span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div><span class="Apple-style-span" style="font-size: 12px; "><p align=""><br></p></span></div></div></span></span>
</div>
<br></body></html>