Changeset 35295 in vbox
- Timestamp:
- Dec 22, 2010 12:21:43 PM (14 years ago)
- File:
-
- 1 edited
-
trunk/doc/manual/en_US/SDKRef.xml (modified) (11 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/manual/en_US/SDKRef.xml
r35293 r35295 423 423 424 424 <para>This way you can specify any shared object/dynamic link module 425 that conforms with the specifications for VirtualBox external authentication 426 modules as laid out in section <emphasis role="bold">VRDE authentication</emphasis> 427 of the VirtualBox User Manual; the web service uses the same kind of modules as the 428 VirtualBox VRDE server. For technical details on VirtualBox external authentication 429 modules see <xref linkend="vbox-auth" /></para> 425 that conforms with the specifications for VirtualBox external 426 authentication modules as laid out in section <emphasis 427 role="bold">VRDE authentication</emphasis> of the VirtualBox User 428 Manual; the web service uses the same kind of modules as the 429 VirtualBox VRDE server. For technical details on VirtualBox external 430 authentication modules see <xref linkend="vbox-auth" /></para> 430 431 431 432 <para>By default, after installation, the web service uses the … … 3178 3179 <title>VirtualBox external authentication modules</title> 3179 3180 3180 <para>VirtualBox supports arbitrary external modules to perform authentication. 3181 The module is used when the authentication method is set to "external" for a 3182 particular VM VRDE access and the library was specified with 3183 <computeroutput>VBoxManage setproperty vrdeauthlibrary</computeroutput>. 3184 Web service also use the authentication module which was specified with 3185 <computeroutput>VBoxManage setproperty websrvauthlibrary</computeroutput>.</para> 3186 3187 <para>This library will be loaded by the VM or web service process on demand, i.e. 3188 when the first remote desktop connection is made by a client or when 3189 a client that wants to use the web service logs on.</para> 3190 3191 <para>External authentication is the most flexible as the external 3192 handler can both choose to grant access to everyone (like the "null" 3181 <para>VirtualBox supports arbitrary external modules to perform 3182 authentication. The module is used when the authentication method is set 3183 to "external" for a particular VM VRDE access and the library was 3184 specified with <computeroutput>VBoxManage setproperty 3185 vrdeauthlibrary</computeroutput>. Web service also use the authentication 3186 module which was specified with <computeroutput>VBoxManage setproperty 3187 websrvauthlibrary</computeroutput>.</para> 3188 3189 <para>This library will be loaded by the VM or web service process on 3190 demand, i.e. when the first remote desktop connection is made by a client 3191 or when a client that wants to use the web service logs on.</para> 3192 3193 <para>External authentication is the most flexible as the external handler 3194 can both choose to grant access to everyone (like the "null" 3193 3195 authentication method would) and delegate the request to the guest 3194 3196 authentication component. When delegating the request to the guest … … 3196 3198 override the result.</para> 3197 3199 3198 <para>An authentication library is required to implement exactly one 3199 entrypoint:</para>3200 <para>An authentication library is required to implement exactly one entry 3201 point:</para> 3200 3202 3201 3203 <screen>#include "VBoxAuth.h" … … 3247 3249 3248 3250 <para>A note regarding the UUID implementation of the 3249 <computeroutput>pUuid</computeroutput> argument: 3250 VirtualBox uses a consistent binary representation of UUIDs on all 3251 platforms. For this reason the integer fields comprising the UUID are 3252 stored as little endian values. If you want to pass such UUIDs to code 3253 which assumes that the integer fields are big endian (often also called 3254 network byte order), you need to adjust the contents of the UUID to e.g. 3255 achieve the same string representation. The required changes 3256 are:<itemizedlist> 3251 <computeroutput>pUuid</computeroutput> argument: VirtualBox uses a 3252 consistent binary representation of UUIDs on all platforms. For this 3253 reason the integer fields comprising the UUID are stored as little endian 3254 values. If you want to pass such UUIDs to code which assumes that the 3255 integer fields are big endian (often also called network byte order), you 3256 need to adjust the contents of the UUID to e.g. achieve the same string 3257 representation. The required changes are:<itemizedlist> 3257 3258 <listitem> 3258 3259 <para>reverse the order of byte 0, 1, 2 and 3</para> … … 3266 3267 <para>reverse the order of byte 6 and 7.</para> 3267 3268 </listitem> 3268 </itemizedlist>Using this conversion you will get identical results 3269 when converting the binary UUID to the string representation.</para> 3270 3271 <para>The <computeroutput>guestJudgement</computeroutput> argument contains 3272 information about the guest authentication status. For the first call, it is 3273 always set to <computeroutput>AuthGuestNotAsked</computeroutput>. In case the 3269 </itemizedlist>Using this conversion you will get identical results when 3270 converting the binary UUID to the string representation.</para> 3271 3272 <para>The <computeroutput>guestJudgement</computeroutput> argument 3273 contains information about the guest authentication status. For the first 3274 call, it is always set to 3275 <computeroutput>AuthGuestNotAsked</computeroutput>. In case the 3274 3276 <computeroutput>AuthEntry</computeroutput> function returns 3275 <computeroutput>AuthResultDelegateToGuest</computeroutput>, a 3276 guestauthentication will be attempted and another call to the3277 <computeroutput>AuthEntry</computeroutput> is made with its result. 3278 This can be either granted / denied or no judgement (the guest component3279 chosefor whatever reason to not make a decision). In case there is a problem3280 with the guest authentication module (e.g. the Additions are not installed or3281 not running or the guest did not respond within a timeout), the "not reacted"3282 status will be returned.</para>3277 <computeroutput>AuthResultDelegateToGuest</computeroutput>, a guest 3278 authentication will be attempted and another call to the 3279 <computeroutput>AuthEntry</computeroutput> is made with its result. This 3280 can be either granted / denied or no judgement (the guest component chose 3281 for whatever reason to not make a decision). In case there is a problem 3282 with the guest authentication module (e.g. the Additions are not installed 3283 or not running or the guest did not respond within a timeout), the "not 3284 reacted" status will be returned.</para> 3283 3285 </chapter> 3284 3286 … … 3448 3450 <itemizedlist> 3449 3451 <listitem> 3452 <para>A new Java glue layer replacing the previous OOWS JAX-WS 3453 bindings was introduced. The new library allows for uniform code 3454 targeting both local (COM/XPCOM) and remote (SOAP) transports. Now, 3455 instead of <computeroutput>IWebsessionManager</computeroutput>, the 3456 new class <computeroutput>VirtualBoxManager</computeroutput> must be 3457 used. See <xref linkend="javaapi" xreflabel="Java API chapter" /> 3458 for details.</para> 3459 </listitem> 3460 3461 <listitem> 3450 3462 <para>The confusingly named and impractical session APIs were 3451 3463 changed. In existing client code, the following changes need to be … … 3541 3553 <listitem> 3542 3554 <para>The rare use case of changing the UUID and parent UUID 3543 of a medium previously handled by openHardDisk() is now in a 3555 of a medium previously handled by 3556 <computeroutput>openHardDisk()</computeroutput> is now in a 3544 3557 separate <xref linkend="IMedium__setIDs" 3545 3558 xreflabel="IMedium::setIDs" /> method.</para> 3546 3559 </listitem> 3560 3561 <listitem> 3562 <para><computeroutput>ISystemProperties::get/setDefaultHardDiskFolder()</computeroutput> 3563 have been removed since disk images are now by default placed 3564 in each machine's folder.</para> 3565 </listitem> 3566 3567 <listitem> 3568 <para><computeroutput>ISystemProperties::getMaxVDISize()</computeroutput> 3569 has been replaced by the <xref 3570 linkend="ISystemProperties__infoVDSize" 3571 xreflabel="ISystemProperties::infoVDSize" /> attribute; this 3572 now uses bytes instead of megabytes.</para> 3573 </listitem> 3547 3574 </itemizedlist></para> 3548 3575 </listitem> 3549 3576 3550 3577 <listitem> 3551 <para>To reduce code duplication and for consistency with the 3552 aforementioned changes, IVirtualBox::getMachine() has been merged 3553 with <xref linkend="IVirtualBox__findMachine" 3554 xreflabel="IVirtualBox::findMachine()" />, and 3555 IMachine::getSnapshot() has been merged with <xref 3556 linkend="IMachine__findSnapshot" 3557 xreflabel="IMachine::findSnapshot()" />.</para> 3558 </listitem> 3559 3560 <listitem> 3561 <para>IVirtualBox::unregisterMachine() was replaced with <xref 3562 linkend="IMachine__unregister" xreflabel="IMachine::unregister()" /> 3563 with additional functionality.</para> 3564 </listitem> 3565 3566 <listitem> 3567 <para><xref linkend="IVirtualBox__createMachine" 3568 xreflabel="IVirtualBox::createMachine()" /> is no longer restricted 3569 to creating machines in the default "Machines" folder, but can now 3570 create machines at arbitrary locations. For this to work, the 3571 parameter list had to be changed.</para> 3572 </listitem> 3573 3574 <listitem> 3575 <para>IConsole::forgetSavedState has been renamed to <xref 3576 linkend="IConsole__discardSavedState" 3577 xreflabel="IConsole::discardSavedState()" />.</para> 3578 <para>Machine management APIs were enhanced as follows:<itemizedlist> 3579 <listitem> 3580 <para><xref linkend="IVirtualBox__createMachine" 3581 xreflabel="IVirtualBox::createMachine()" /> is no longer 3582 restricted to creating machines in the default "Machines" 3583 folder, but can now create machines at arbitrary locations. 3584 For this to work, the parameter list had to be changed.</para> 3585 </listitem> 3586 3587 <listitem> 3588 <para>The long-deprecated 3589 <computeroutput>IVirtualBox::createLegacyMachine()</computeroutput> 3590 API has been removed.</para> 3591 </listitem> 3592 3593 <listitem> 3594 <para>To reduce code duplication and for consistency with the 3595 aforementioned media API changes, 3596 <computeroutput>IVirtualBox::getMachine()</computeroutput> has 3597 been merged with <xref linkend="IVirtualBox__findMachine" 3598 xreflabel="IVirtualBox::findMachine()" />, and 3599 <computeroutput>IMachine::getSnapshot()</computeroutput> has 3600 been merged with <xref linkend="IMachine__findSnapshot" 3601 xreflabel="IMachine::findSnapshot()" />.</para> 3602 </listitem> 3603 3604 <listitem> 3605 <para><computeroutput>IVirtualBox::unregisterMachine()</computeroutput> 3606 was replaced with <xref linkend="IMachine__unregister" 3607 xreflabel="IMachine::unregister()" /> with additional 3608 functionality for cleaning up machine files.</para> 3609 </listitem> 3610 3611 <listitem> 3612 <para><computeroutput>IConsole::forgetSavedState</computeroutput> 3613 has been renamed to <xref 3614 linkend="IConsole__discardSavedState" 3615 xreflabel="IConsole::discardSavedState()" />.</para> 3616 </listitem> 3617 </itemizedlist></para> 3578 3618 </listitem> 3579 3619 … … 3588 3628 3589 3629 <listitem> 3590 <para><xref linkend="IGuest__additionsVersion" 3630 <para><computeroutput>additionsActive()</computeroutput> was 3631 replaced with <xref linkend="IGuest__additionsRunLevel" 3632 xreflabel="additionsRunLevel()" /> and <xref 3633 linkend="IGuest__getAdditionsStatus" 3634 xreflabel="getAdditionsStatus()" /> in order to support a more 3635 detailed status of the current Guest Additions loading/readiness 3636 state. <xref linkend="IGuest__additionsVersion" 3591 3637 xreflabel="IGuest::additionsVersion()" /> no longer returns the 3592 3638 Guest Additions interface version but the installed Guest Additions … … 3596 3642 3597 3643 <listitem> 3598 <para>additionsActive() was replaced with <xref3599 linkend="IGuest__additionsRunLevel"3600 xreflabel="additionsRunLevel()" /> and <xref3601 linkend="IGuest__getAdditionsStatus"3602 xreflabel="getAdditionsStatus()" /> in order to support a more3603 detailed status of the current Guest Additions loading/readiness3604 state.</para>3605 </listitem>3606 3607 <listitem>3608 3644 <para>To address shared folders auto-mounting support, the following 3609 3645 APIs were extended to require an additional … … 3630 3666 3631 3667 <listitem> 3632 <para><xref linkend="IMachine__export" 3633 xreflabel="IMachine::export()" /> received an extra parameter 3634 <computeroutput>location</computeroutput>, which is used to decide 3635 for the disk naming.</para> 3636 </listitem> 3637 3638 <listitem> 3639 <para><xref linkend="IAppliance__write" 3640 xreflabel="IAppliance::write()" /> received an extra parameter 3641 <computeroutput>manifest</computeroutput>, which can suppress 3642 creating the manifest file on export.</para> 3643 </listitem> 3644 3645 <listitem> 3646 <para><xref linkend="IVFSExplorer__entryList" 3647 xreflabel="IVFSExplorer::entryList()" /> received two extra 3648 parameters <computeroutput>sizes</computeroutput> and 3649 <computeroutput>modes</computeroutput>, which contains the sizes (in 3650 bytes) and the file access modes (in octal form) of the returned 3651 files.</para> 3652 </listitem> 3653 3654 <listitem> 3655 <para>The long-deprecated IVirtualBox::createLegacyMachine() API has 3656 been removed.</para> 3657 </listitem> 3658 3659 <listitem> 3660 <para>ISystemProperties::get/setDefaultHardDiskFolder() have been 3661 removed.</para> 3662 </listitem> 3663 3664 <listitem> 3665 <para>ISystemProperties::getMaxVDISize() is now <xref 3666 linkend="ISystemProperties__getInfoVDSize" 3667 xreflabel="ISystemProperties::getInfoVDSize()" /> and the returned 3668 unit has changed from megabytes to bytes.</para> 3669 </listitem> 3670 3671 <listitem> 3672 <para>A new Java glue layer replacing the previous OOWS JAX-WS 3673 bindings was introduced. The new library allows for uniform code 3674 targeting both local (COM/XPCOM) and remote (SOAP) transports. Now, 3675 instead of <computeroutput>IWebsessionManager</computeroutput>, the 3676 new class <computeroutput>VirtualBoxManager</computeroutput> must be 3677 used. See <xref linkend="javaapi" xreflabel="Java API chapter" /> 3678 for details.</para> 3679 </listitem> 3680 3681 <listitem> 3682 <para>Support for remote desktop access to virtual machines 3683 has been cleaned up to allow third party implementations of 3684 the remote desktop server. This is called VirtualBox Remote Desktop Extension 3685 and can be added to VirtualBox by installing the corresponding 3686 extension package.</para> 3687 <para>The following API changes were made to support the VRDE interface: 3688 <itemizedlist> 3689 <listitem> 3690 <para><computeroutput>IVRDPServer</computeroutput> interface has been 3691 renamed to <xref linkend="IVRDEServer" xreflabel="IVRDEServer" />.</para> 3692 </listitem> 3693 3694 <listitem> 3695 <para><computeroutput>IRemoteDisplayInfo</computeroutput> interface has been 3696 renamed to <xref linkend="IVRDEServerInfo" xreflabel="IVRDEServerInfo" />.</para> 3697 </listitem> 3698 3699 <listitem> 3700 <para><computeroutput>IMachine::VRDPServer</computeroutput> attribute has 3701 been renamed to <xref linkend="IMachine__VRDEServer" 3668 <para>The appliance (OVF) APIs were enhanced as 3669 follows:<itemizedlist> 3670 <listitem> 3671 <para><xref linkend="IMachine__export" 3672 xreflabel="IMachine::export()" /> received an extra parameter 3673 <computeroutput>location</computeroutput>, which is used to 3674 decide for the disk naming.</para> 3675 </listitem> 3676 3677 <listitem> 3678 <para><xref linkend="IAppliance__write" 3679 xreflabel="IAppliance::write()" /> received an extra parameter 3680 <computeroutput>manifest</computeroutput>, which can suppress 3681 creating the manifest file on export.</para> 3682 </listitem> 3683 3684 <listitem> 3685 <para><xref linkend="IVFSExplorer__entryList" 3686 xreflabel="IVFSExplorer::entryList()" /> received two extra 3687 parameters <computeroutput>sizes</computeroutput> and 3688 <computeroutput>modes</computeroutput>, which contains the 3689 sizes (in bytes) and the file access modes (in octal form) of 3690 the returned files.</para> 3691 </listitem> 3692 </itemizedlist></para> 3693 </listitem> 3694 3695 <listitem> 3696 <para>Support for remote desktop access to virtual machines has been 3697 cleaned up to allow third party implementations of the remote 3698 desktop server. This is called the VirtualBox Remote Desktop 3699 Extension (VRDE) and can be added to VirtualBox by installing the 3700 corresponding extension package; see the VirtualBox User Manual for 3701 details.</para> 3702 3703 <para>The following API changes were made to support the VRDE 3704 interface: <itemizedlist> 3705 <listitem> 3706 <para><computeroutput>IVRDPServer</computeroutput> interface 3707 has been renamed to <xref linkend="IVRDEServer" 3708 xreflabel="IVRDEServer" />.</para> 3709 </listitem> 3710 3711 <listitem> 3712 <para><computeroutput>IRemoteDisplayInfo</computeroutput> 3713 interface has been renamed to <xref linkend="IVRDEServerInfo" 3714 xreflabel="IVRDEServerInfo" />.</para> 3715 </listitem> 3716 3717 <listitem> 3718 <para><computeroutput>IMachine::VRDPServer</computeroutput> 3719 attribute has been renamed to <xref 3720 linkend="IMachine__VRDEServer" 3702 3721 xreflabel="IMachine::VRDEServer" />.</para> 3703 3722 </listitem> 3704 3723 3705 3724 <listitem> 3706 <para><computeroutput>IConsole::RemoteDisplayInfo</computeroutput> attribute 3707 has been renamed to <xref linkend="IConsole__VRDEServerInfo" 3725 <para><computeroutput>IConsole::RemoteDisplayInfo</computeroutput> 3726 attribute has been renamed to <xref 3727 linkend="IConsole__VRDEServerInfo" 3708 3728 xreflabel="IConsole::VRDEServerInfo" />.</para> 3709 3729 </listitem> … … 3711 3731 <listitem> 3712 3732 <para><computeroutput>ISystemProperties::RemoteDisplayAuthLibrary</computeroutput> 3713 attribute has been renamed to <xref linkend="ISystemProperties__VRDEAuthLibrary" 3733 attribute has been renamed to <xref 3734 linkend="ISystemProperties__VRDEAuthLibrary" 3714 3735 xreflabel="ISystemProperties::VRDEAuthLibrary" />.</para> 3715 3736 </listitem> 3716 3737 3717 3738 <listitem> 3718 <para>Following methods has been implemented in <computeroutput>IVRDEServer</computeroutput>3719 to support generic VRDE properties:3720 <itemizedlist>3739 <para>Following methods has been implemented in 3740 <computeroutput>IVRDEServer</computeroutput> to support 3741 generic VRDE properties: <itemizedlist> 3721 3742 <listitem> 3722 <para><xref linkend="IVRDEServer__setVRDEProperty" xreflabel="IVRDEServer::SetVRDEProperty" />3723 </para>3743 <para><xref linkend="IVRDEServer__setVRDEProperty" 3744 xreflabel="IVRDEServer::SetVRDEProperty" /></para> 3724 3745 </listitem> 3746 3725 3747 <listitem> 3726 <para><xref linkend="IVRDEServer__getVRDEProperty" xreflabel="IVRDEServer::GetVRDEProperty"/>3727 </para>3748 <para><xref linkend="IVRDEServer__getVRDEProperty" 3749 xreflabel="IVRDEServer::GetVRDEProperty" /></para> 3728 3750 </listitem> 3751 3729 3752 <listitem> 3730 <para><xref linkend="IVRDEServer__VRDEProperties" xreflabel="IVRDEServer::VRDEProperties" />3731 </para>3753 <para><xref linkend="IVRDEServer__VRDEProperties" 3754 xreflabel="IVRDEServer::VRDEProperties" /></para> 3732 3755 </listitem> 3733 </itemizedlist> 3734 </para> 3735 <para>A few implementation specific attributes of the old <computeroutput>IVRDPServer</computeroutput>3736 interface have been removed and replaced with properties:3737 <itemizedlist>3756 </itemizedlist></para> 3757 3758 <para>A few implementation specific attributes of the old 3759 <computeroutput>IVRDPServer</computeroutput> interface have 3760 been removed and replaced with properties: <itemizedlist> 3738 3761 <listitem> 3739 <para><computeroutput>IVRDPServer::Ports</computeroutput> -- replaced with 3740 <computeroutput>"TCP/Ports"</computeroutput> property. The property value is 3741 a string, which contains a comma-separated list of ports or ranges of ports. 3742 Use a dash between two port numbers to specify a range. Example: 3743 <computeroutput>"5000,5010-5012"</computeroutput> 3744 </para> 3762 <para><computeroutput>IVRDPServer::Ports</computeroutput> 3763 -- replaced with 3764 <computeroutput>"TCP/Ports"</computeroutput> property. 3765 The property value is a string, which contains a 3766 comma-separated list of ports or ranges of ports. Use a 3767 dash between two port numbers to specify a range. 3768 Example: 3769 <computeroutput>"5000,5010-5012"</computeroutput></para> 3745 3770 </listitem> 3771 3746 3772 <listitem> 3747 <para><computeroutput>IVRDPServer::NetAddress</computeroutput> -- replaced with 3748 <computeroutput>"TCP/Address"</computeroutput> property. The property value is 3749 an IP address string. Example: <computeroutput>"127.0.0.1"</computeroutput> 3750 </para> 3773 <para><computeroutput>IVRDPServer::NetAddress</computeroutput> 3774 -- replaced with 3775 <computeroutput>"TCP/Address"</computeroutput> property. 3776 The property value is an IP address string. Example: 3777 <computeroutput>"127.0.0.1"</computeroutput></para> 3751 3778 </listitem> 3779 3752 3780 <listitem> 3753 <para><computeroutput>IVRDPServer::VideoChannel</computeroutput> -- replaced with 3754 <computeroutput>"VideoChannel/Enabled"</computeroutput> property. The property value 3755 is either <computeroutput>"true"</computeroutput> or <computeroutput>"false"</computeroutput> 3756 </para> 3781 <para><computeroutput>IVRDPServer::VideoChannel</computeroutput> 3782 -- replaced with 3783 <computeroutput>"VideoChannel/Enabled"</computeroutput> 3784 property. The property value is either 3785 <computeroutput>"true"</computeroutput> or 3786 <computeroutput>"false"</computeroutput></para> 3757 3787 </listitem> 3788 3758 3789 <listitem> 3759 <para><computeroutput>IVRDPServer::VideoChannelQuality</computeroutput> -- replaced with 3760 <computeroutput>"VideoChannel/Quality"</computeroutput> property. The property value is a 3761 string which contain a decimal number in range 10..100. Invalid values are ignored and 3762 the quality is set to the default value 75. Example: <computeroutput>"50"</computeroutput> 3763 </para> 3790 <para><computeroutput>IVRDPServer::VideoChannelQuality</computeroutput> 3791 -- replaced with 3792 <computeroutput>"VideoChannel/Quality"</computeroutput> 3793 property. The property value is a string which contain a 3794 decimal number in range 10..100. Invalid values are 3795 ignored and the quality is set to the default value 75. 3796 Example: <computeroutput>"50"</computeroutput></para> 3764 3797 </listitem> 3765 </itemizedlist> 3766 </para> 3767 </listitem> 3768 </itemizedlist> 3769 </para> 3770 </listitem> 3771 3772 <listitem> 3773 <para>VirtualBox external authentication module interface 3774 has been updated and made more general.</para> 3775 <para>Because of that, <computeroutput>VRDPAuthType</computeroutput> enumeration has been 3776 renamed to <xref linkend="AuthType" xreflabel="AuthType" />. 3777 </para> 3798 </itemizedlist></para> 3799 </listitem> 3800 </itemizedlist></para> 3801 </listitem> 3802 3803 <listitem> 3804 <para>The VirtualBox external authentication module interface has 3805 been updated and made more generic. Because of that, 3806 <computeroutput>VRDPAuthType</computeroutput> enumeration has been 3807 renamed to <xref linkend="AuthType" xreflabel="AuthType" />.</para> 3778 3808 </listitem> 3779 3809 </itemizedlist>
Note:
See TracChangeset
for help on using the changeset viewer.

