Index: /trunk/doc/manual/en_US/SDKRef.xml =================================================================== --- /trunk/doc/manual/en_US/SDKRef.xml (revision 35294) +++ /trunk/doc/manual/en_US/SDKRef.xml (revision 35295) @@ -423,9 +423,10 @@ This way you can specify any shared object/dynamic link module - that conforms with the specifications for VirtualBox external authentication - modules as laid out in section VRDE authentication - of the VirtualBox User Manual; the web service uses the same kind of modules as the - VirtualBox VRDE server. For technical details on VirtualBox external authentication - modules see + that conforms with the specifications for VirtualBox external + authentication modules as laid out in section VRDE authentication of the VirtualBox User + Manual; the web service uses the same kind of modules as the + VirtualBox VRDE server. For technical details on VirtualBox external + authentication modules see By default, after installation, the web service uses the @@ -3178,17 +3179,18 @@ VirtualBox external authentication modules - VirtualBox supports arbitrary external modules to perform authentication. - The module is used when the authentication method is set to "external" for a - particular VM VRDE access and the library was specified with - VBoxManage setproperty vrdeauthlibrary. - Web service also use the authentication module which was specified with - VBoxManage setproperty websrvauthlibrary. - - This library will be loaded by the VM or web service process on demand, i.e. - when the first remote desktop connection is made by a client or when - a client that wants to use the web service logs on. - - External authentication is the most flexible as the external - handler can both choose to grant access to everyone (like the "null" + VirtualBox supports arbitrary external modules to perform + authentication. The module is used when the authentication method is set + to "external" for a particular VM VRDE access and the library was + specified with VBoxManage setproperty + vrdeauthlibrary. Web service also use the authentication + module which was specified with VBoxManage setproperty + websrvauthlibrary. + + This library will be loaded by the VM or web service process on + demand, i.e. when the first remote desktop connection is made by a client + or when a client that wants to use the web service logs on. + + External authentication is the most flexible as the external handler + can both choose to grant access to everyone (like the "null" authentication method would) and delegate the request to the guest authentication component. When delegating the request to the guest @@ -3196,6 +3198,6 @@ override the result. - An authentication library is required to implement exactly one - entry point: + An authentication library is required to implement exactly one entry + point: #include "VBoxAuth.h" @@ -3247,12 +3249,11 @@ A note regarding the UUID implementation of the - pUuid argument: - VirtualBox uses a consistent binary representation of UUIDs on all - platforms. For this reason the integer fields comprising the UUID are - stored as little endian values. If you want to pass such UUIDs to code - which assumes that the integer fields are big endian (often also called - network byte order), you need to adjust the contents of the UUID to e.g. - achieve the same string representation. The required changes - are: + pUuid argument: VirtualBox uses a + consistent binary representation of UUIDs on all platforms. For this + reason the integer fields comprising the UUID are stored as little endian + values. If you want to pass such UUIDs to code which assumes that the + integer fields are big endian (often also called network byte order), you + need to adjust the contents of the UUID to e.g. achieve the same string + representation. The required changes are: reverse the order of byte 0, 1, 2 and 3 @@ -3266,19 +3267,20 @@ reverse the order of byte 6 and 7. - Using this conversion you will get identical results - when converting the binary UUID to the string representation. - - The guestJudgement argument contains - information about the guest authentication status. For the first call, it is - always set to AuthGuestNotAsked. In case the + Using this conversion you will get identical results when + converting the binary UUID to the string representation. + + The guestJudgement argument + contains information about the guest authentication status. For the first + call, it is always set to + AuthGuestNotAsked. In case the AuthEntry function returns - AuthResultDelegateToGuest, a - guest authentication will be attempted and another call to the - AuthEntry is made with its result. - This can be either granted / denied or no judgement (the guest component - chose for whatever reason to not make a decision). In case there is a problem - with the guest authentication module (e.g. the Additions are not installed or - not running or the guest did not respond within a timeout), the "not reacted" - status will be returned. + AuthResultDelegateToGuest, a guest + authentication will be attempted and another call to the + AuthEntry is made with its result. This + can be either granted / denied or no judgement (the guest component chose + for whatever reason to not make a decision). In case there is a problem + with the guest authentication module (e.g. the Additions are not installed + or not running or the guest did not respond within a timeout), the "not + reacted" status will be returned. @@ -3448,4 +3450,14 @@ + A new Java glue layer replacing the previous OOWS JAX-WS + bindings was introduced. The new library allows for uniform code + targeting both local (COM/XPCOM) and remote (SOAP) transports. Now, + instead of IWebsessionManager, the + new class VirtualBoxManager must be + used. See + for details. + + + The confusingly named and impractical session APIs were changed. In existing client code, the following changes need to be @@ -3541,39 +3553,67 @@ The rare use case of changing the UUID and parent UUID - of a medium previously handled by openHardDisk() is now in a + of a medium previously handled by + openHardDisk() is now in a separate method. + + + ISystemProperties::get/setDefaultHardDiskFolder() + have been removed since disk images are now by default placed + in each machine's folder. + + + + ISystemProperties::getMaxVDISize() + has been replaced by the attribute; this + now uses bytes instead of megabytes. + - To reduce code duplication and for consistency with the - aforementioned changes, IVirtualBox::getMachine() has been merged - with , and - IMachine::getSnapshot() has been merged with . - - - - IVirtualBox::unregisterMachine() was replaced with - with additional functionality. - - - - is no longer restricted - to creating machines in the default "Machines" folder, but can now - create machines at arbitrary locations. For this to work, the - parameter list had to be changed. - - - - IConsole::forgetSavedState has been renamed to . + Machine management APIs were enhanced as follows: + + is no longer + restricted to creating machines in the default "Machines" + folder, but can now create machines at arbitrary locations. + For this to work, the parameter list had to be changed. + + + + The long-deprecated + IVirtualBox::createLegacyMachine() + API has been removed. + + + + To reduce code duplication and for consistency with the + aforementioned media API changes, + IVirtualBox::getMachine() has + been merged with , and + IMachine::getSnapshot() has + been merged with . + + + + IVirtualBox::unregisterMachine() + was replaced with with additional + functionality for cleaning up machine files. + + + + IConsole::forgetSavedState + has been renamed to . + + @@ -3588,5 +3628,11 @@ - additionsActive() was + replaced with and in order to support a more + detailed status of the current Guest Additions loading/readiness + state. no longer returns the Guest Additions interface version but the installed Guest Additions @@ -3596,14 +3642,4 @@ - additionsActive() was replaced with and in order to support a more - detailed status of the current Guest Additions loading/readiness - state. - - - To address shared folders auto-mounting support, the following APIs were extended to require an additional @@ -3630,80 +3666,64 @@ - received an extra parameter - location, which is used to decide - for the disk naming. - - - - received an extra parameter - manifest, which can suppress - creating the manifest file on export. - - - - received two extra - parameters sizes and - modes, which contains the sizes (in - bytes) and the file access modes (in octal form) of the returned - files. - - - - The long-deprecated IVirtualBox::createLegacyMachine() API has - been removed. - - - - ISystemProperties::get/setDefaultHardDiskFolder() have been - removed. - - - - ISystemProperties::getMaxVDISize() is now and the returned - unit has changed from megabytes to bytes. - - - - A new Java glue layer replacing the previous OOWS JAX-WS - bindings was introduced. The new library allows for uniform code - targeting both local (COM/XPCOM) and remote (SOAP) transports. Now, - instead of IWebsessionManager, the - new class VirtualBoxManager must be - used. See - for details. - - - - Support for remote desktop access to virtual machines - has been cleaned up to allow third party implementations of - the remote desktop server. This is called VirtualBox Remote Desktop Extension - and can be added to VirtualBox by installing the corresponding - extension package. - The following API changes were made to support the VRDE interface: - - - IVRDPServer interface has been - renamed to . - - - - IRemoteDisplayInfo interface has been - renamed to . - - - - IMachine::VRDPServer attribute has - been renamed to The appliance (OVF) APIs were enhanced as + follows: + + received an extra parameter + location, which is used to + decide for the disk naming. + + + + received an extra parameter + manifest, which can suppress + creating the manifest file on export. + + + + received two extra + parameters sizes and + modes, which contains the + sizes (in bytes) and the file access modes (in octal form) of + the returned files. + + + + + + Support for remote desktop access to virtual machines has been + cleaned up to allow third party implementations of the remote + desktop server. This is called the VirtualBox Remote Desktop + Extension (VRDE) and can be added to VirtualBox by installing the + corresponding extension package; see the VirtualBox User Manual for + details. + + The following API changes were made to support the VRDE + interface: + + IVRDPServer interface + has been renamed to . + + + + IRemoteDisplayInfo + interface has been renamed to . + + + + IMachine::VRDPServer + attribute has been renamed to . - IConsole::RemoteDisplayInfo attribute - has been renamed to IConsole::RemoteDisplayInfo + attribute has been renamed to . @@ -3711,69 +3731,79 @@ ISystemProperties::RemoteDisplayAuthLibrary - attribute has been renamed to . - Following methods has been implemented in IVRDEServer - to support generic VRDE properties: - + Following methods has been implemented in + IVRDEServer to support + generic VRDE properties: - - + + - - + + - - + - - - A few implementation specific attributes of the old IVRDPServer - interface have been removed and replaced with properties: - + + + A few implementation specific attributes of the old + IVRDPServer interface have + been removed and replaced with properties: - IVRDPServer::Ports -- replaced with - "TCP/Ports" property. The property value is - a string, which contains a comma-separated list of ports or ranges of ports. - Use a dash between two port numbers to specify a range. Example: - "5000,5010-5012" - + IVRDPServer::Ports + -- replaced with + "TCP/Ports" property. + The property value is a string, which contains a + comma-separated list of ports or ranges of ports. Use a + dash between two port numbers to specify a range. + Example: + "5000,5010-5012" + - IVRDPServer::NetAddress -- replaced with - "TCP/Address" property. The property value is - an IP address string. Example: "127.0.0.1" - + IVRDPServer::NetAddress + -- replaced with + "TCP/Address" property. + The property value is an IP address string. Example: + "127.0.0.1" + - IVRDPServer::VideoChannel -- replaced with - "VideoChannel/Enabled" property. The property value - is either "true" or "false" - + IVRDPServer::VideoChannel + -- replaced with + "VideoChannel/Enabled" + property. The property value is either + "true" or + "false" + - IVRDPServer::VideoChannelQuality -- replaced with - "VideoChannel/Quality" property. The property value is a - string which contain a decimal number in range 10..100. Invalid values are ignored and - the quality is set to the default value 75. Example: "50" - + IVRDPServer::VideoChannelQuality + -- replaced with + "VideoChannel/Quality" + property. The property value is a string which contain a + decimal number in range 10..100. Invalid values are + ignored and the quality is set to the default value 75. + Example: "50" - - - - - - - - - VirtualBox external authentication module interface - has been updated and made more general. - Because of that, VRDPAuthType enumeration has been - renamed to . - + + + + + + + The VirtualBox external authentication module interface has + been updated and made more generic. Because of that, + VRDPAuthType enumeration has been + renamed to .