Index: /trunk/doc/manual/docbook2latex.xsl =================================================================== --- /trunk/doc/manual/docbook2latex.xsl (revision 56531) +++ /trunk/doc/manual/docbook2latex.xsl (revision 56532) @@ -621,10 +621,21 @@ - - - - + + + + + + + + + + + + + + + - + Index: /trunk/doc/manual/en_US/SDKRef.xml =================================================================== --- /trunk/doc/manual/en_US/SDKRef.xml (revision 56531) +++ /trunk/doc/manual/en_US/SDKRef.xml (revision 56532) @@ -38,5 +38,5 @@ + width="12cm"/> @@ -62,5 +62,5 @@ exposes the entire feature set of the virtualization engine below. It is completely documented in this SDK Reference -- see and -- and + linkend="sdkref_classes"/> and -- and available to anyone who wishes to control VirtualBox programmatically. We chose the name "Main API" to differentiate it from other programming @@ -114,6 +114,6 @@ The OO bindings for Java are described in , those for Python in . + linkend="javaapi"/>, those for Python in . @@ -133,5 +133,5 @@ We describe this further in , with samples for Java and + linkend="raw-webservice"/>, with samples for Java and Perl. @@ -155,5 +155,5 @@ necessary files and documentation to build fully functional COM applications. For an introduction, please see below. + linkend="api_com"/> below. The VirtualBox front-ends (the graphical user interfaces as @@ -346,5 +346,6 @@ --ssl (or - -s): This enables SSL support. + -s): This enables SSL + support. @@ -434,5 +435,6 @@ -k): This specifies the maximum number of requests which can be sent in one web service connection, - and defaults to 100. This normally does not need to be changed. + and defaults to 100. This normally does not need to be + changed. @@ -503,6 +505,6 @@ As opposed to the COM/XPCOM variant of the Main API, a client that wants to use the web service must first log on by calling the - IWebsessionManager::logon() API (see - ) that is specific to the + IWebsessionManager::logon() + API that is specific to the web service. Logon is necessary for the web service to be stateful; internally, it maintains a session for each client that connects to @@ -515,5 +517,6 @@ For testing purposes, it is recommended that you first disable - authentication with this command:VBoxManage setproperty websrvauthlibrary null + authentication with this command: + VBoxManage setproperty websrvauthlibrary null @@ -533,5 +536,5 @@ Manual; the web service uses the same kind of modules as the VirtualBox VRDE server. For technical details on VirtualBox external - authentication modules see + authentication modules see By default, after installation, the web service uses the @@ -557,9 +560,9 @@ Environment-specific notes - The Main API described in and - is mostly identical in all the supported + The Main API described in and + is mostly identical in all the supported programming environments which have been briefly mentioned in the introduction of this book. As a result, the Main API's general concepts - described in are the same whether you use the + described in are the same whether you use the object-oriented web service (OOWS) for JAX-WS or a raw web service connection via, say, Perl, or whether you use C++ COM bindings. @@ -571,5 +574,5 @@ Using the object-oriented web service (OOWS) - As explained in , VirtualBox + As explained in , VirtualBox ships with client-side libraries for Java, Python and PHP that allow you to use the VirtualBox web service in an intuitive, object-oriented way. @@ -577,5 +580,5 @@ object references and other implementation details that come with the VirtualBox web service. (If you are interested in these complications, - have a look at ). + have a look at ). We recommend that you start your experiments with the VirtualBox @@ -585,6 +588,6 @@ As "interfaces", "attributes" and "methods" are COM concepts, - please read the documentation in and - with the following notes in mind. + please read the documentation in and + with the following notes in mind. The OOWS bindings attempt to map the Main API as closely as @@ -597,5 +600,5 @@ capitalized first letter. So when the Main API Reference says that IMachine has a "name" attribute (see - ), call + IMachine::name), call getName() on an IMachine object to obtain a machine's name. Unless the attribute is marked as read-only in @@ -650,10 +653,11 @@ To start the VirtualBox web service, open a second terminal and change to the directory where the VirtualBox - executables are located. Then type:./vboxwebsrv -v + executables are located. Then type: + ./vboxwebsrv -v The web service now waits for connections and will run until you press Ctrl+C in this second terminal. The -v argument causes it to log all connections to the terminal. - (See for details on how + (See for details on how to run the web service.) @@ -661,5 +665,6 @@ Back in the first terminal and still in the samples - directory, to start a simple client example just type:make run16 + directory, to start a simple client example just type: + make run16 if you're on a Java 6 system; on a Java 5 system, run @@ -715,9 +720,10 @@ clienttest constructor: - An instance of , which is an interface - provided by the web service to manage "web sessions" -- that - is, stateful connections to the web service with persistent - objects upon which methods can be invoked. + An instance of + IWebsessionManager, + which is an interface provided by the web service to manage + "web sessions" -- that is, stateful connections to the web + service with persistent objects upon which methods can be + invoked. In the OOWS for JAX-WS, the IWebsessionManager class @@ -731,20 +737,19 @@ number given to the vboxwebsrv command line; see - . - - - - After that, the code calls , which is the first - call that actually communicates with the server. This - authenticates the client with the web service and returns an - instance of , the most fundamental interface of - the VirtualBox web service, from which all other functionality - can be derived. + . + + + + After that, the code calls + IWebsessionManager::logon(), + which is the first call that actually communicates with the + server. This authenticates the client with the web service and + returns an instance of + IVirtualBox, + the most fundamental interface of the VirtualBox web service, + from which all other functionality can be derived. If logon doesn't work, please take another look at . + linkend="websrv_authenticate"/>. @@ -756,8 +761,8 @@ The current OOWS for JAX-WS has certain memory management related limitations. When you no longer need an object, call its - method explicitly, which + IManagedObjectRef::release() + method explicitly, which frees appropriate managed reference, as is required by the raw - web service; see for + web service; see for details. This limitation may be reconsidered in a future version of the VirtualBox SDK. @@ -770,11 +775,11 @@ VirtualBox comes with two flavors of a Python API: one for web service, discussed here, and one for the COM/XPCOM API discussed in - . The client code is mostly similar, except + . The client code is mostly similar, except for the initialization part, so it is up to the application developer to choose the appropriate technology. Moreover, a common Python glue layer exists, abstracting out concrete platform access details, see - . - - As indicated in , the + . + + As indicated in , the COM/XPCOM API gives better performance without the SOAP overhead, and does not require a web server to be running. On the other hand, the @@ -785,12 +790,14 @@ are officially supported. This means Python 2.3 for 10.4, Python 2.5 for 10.5 and Python 2.5 and 2.6 for 10.6. - ). On Windows, you can use the Main API from Python if the Win32 extensions - package for Python + ). On Windows, you can use the Main API from Python if the + Win32 extensions package for Python See http://sourceforge.net/project/showfiles.php?group_id=78018. - is installed. Version of Python Win32 extensions earlier than 2.16 are known to have bugs, - leading to issues with VirtualBox Python bindings, and also some early builds of Python 2.5 for Windows have issues with - reporting platform name on some Windows versions, so please make sure to use latest available Python - and Win32 extensions. + is installed. Version of Python Win32 extensions earlier + than 2.16 are known to have bugs, leading to issues with VirtualBox + Python bindings, and also some early builds of Python 2.5 for Windows + have issues with reporting platform name on some Windows versions, so + please make sure to use latest available Python and Win32 + extensions. The VirtualBox OOWS for Python relies on the Python ZSI SOAP @@ -813,5 +820,6 @@ and web services). - To start the shell, perform the following commands: /opt/VirtualBox/vboxwebsrv -t 0 + To start the shell, perform the following commands: + /opt/VirtualBox/vboxwebsrv -t 0 # start web service with object autocollection disabled export VBOX_PROGRAM_PATH=/opt/VirtualBox @@ -819,5 +827,6 @@ export VBOX_SDK_PATH=/home/youruser/vbox-sdk # where you've extracted the SDK -./vboxshell.py -w See for more +./vboxshell.py -w + See for more details on the shell's functionality. For you, as a VirtualBox application developer, the vboxshell sample could be interesting as an @@ -851,7 +860,7 @@ Generally, when reading the documentation in and , due to + linkend="sdkref_classes"/> and , due to the limitations of SOAP and WSDL lined out in , please have the following notes in + linkend="rawws-conventions"/>, please have the following notes in mind: @@ -864,7 +873,7 @@ the IVirtualBox interface supports the createMachine() - method (see ), the web service - operation is + method (see + IVirtualBox::createMachine()), + the web service operation is IVirtualBox_createMachine(...), and a managed object reference to an @@ -924,5 +933,6 @@ Open a terminal in your working directory. Execute the - following command: java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl + following command: + java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl The vboxwebService.wsdl @@ -933,5 +943,6 @@ If this fails, your Apache Axis may not be located on your system classpath, and you may have to adjust the CLASSPATH - environment variable. Something like this:export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH + environment variable. Something like this: + export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH Use the directory where the Axis JAR files are located. @@ -956,5 +967,6 @@ Next, compile the - clienttest.java source:javac clienttest.java + clienttest.java + source:javac clienttest.java This should yield a "clienttest.class" file. @@ -964,10 +976,11 @@ To start the VirtualBox web service, open a second terminal and change to the directory where the VirtualBox - executables are located. Then type:./vboxwebsrv -v + executables are located. Then type: + ./vboxwebsrv -v The web service now waits for connections and will run until you press Ctrl+C in this second terminal. The -v argument causes it to log all connections to the terminal. (See for details on how to run the + linkend="runvboxwebsrv"/> for details on how to run the web service.) @@ -1021,10 +1034,11 @@ To start the VirtualBox web service, open a second terminal and change to the directory where the VirtualBox - executables are located. Then type:./vboxwebsrv -v + executables are located. Then type: + ./vboxwebsrv -v The web service now waits for connections and will run until you press Ctrl+C in this second terminal. The -v argument causes it to log all connections to the terminal. (See for details on how to run the + linkend="runvboxwebsrv"/> for details on how to run the web service.) @@ -1032,5 +1046,6 @@ In the first terminal with the Perl sample, run the - clienttest.pl script:perl -I ../lib clienttest.pl + clienttest.pl script: + perl -I ../lib clienttest.pl @@ -1043,5 +1058,5 @@ things in mind, or you will sooner or later run into issues that are not immediately obvious. By contrast, the object-oriented client-side - libraries described in take care of these + libraries described in take care of these things automatically and thus greatly simplify using the web service. @@ -1089,5 +1104,5 @@ method is invoked. (Managed object references are explained in detail below; see .) + linkend="managed-object-references"/>.) So, when one would normally code, in the pseudo-code of @@ -1104,11 +1119,11 @@ To make the web service stateful, and objects persistent between method calls, the VirtualBox web service introduces a - session manager (by way of - the interface), which manages - object references. Any client wishing to interact with the web - service must first log on to the session manager and in turn - receives a managed object reference to an object that supports - the + session manager (by way of the + IWebsessionManager + interface), which manages object references. Any client wishing + to interact with the web service must first log on to the + session manager and in turn receives a managed object reference + to an object that supports the + IVirtualBox interface (the basic interface in the Main API). @@ -1127,8 +1142,8 @@ Main API version number) looks like this: - A client logs on to the web service by calling with a valid user - name and password. See + A client logs on to the web service by calling + IWebsessionManager::logon() + with a valid user name and password. See + for details about how authentication works. @@ -1137,12 +1152,11 @@ On the server side, vboxwebsrv creates a session, - which persists until the client calls or the session - times out after a configurable period of inactivity (see ). + which persists until the client calls + IWebsessionManager::logoff() + or the session times out after a configurable period of + inactivity (see ). For the new session, the web service creates an instance - of . + of IVirtualBox. This interface is the most central one in the Main API and allows access to all other interfaces, either through @@ -1163,8 +1177,7 @@ string consisting of digits and dashes. However, it is a string with a meaning and will be checked by the web service. - For details, see below. As hinted above, is the - only operation provided by the web + For details, see below. As hinted above, + IWebsessionManager::logon() + is the only operation provided by the web service which does not take a managed object reference as the first argument!) @@ -1174,10 +1187,11 @@ The VirtualBox Main API documentation says that the IVirtualBox interface has a - + version attribute, which is a string. For each attribute, there is a "get" and a "set" method in COM, which maps to according operations in the web service. So, to retrieve the "version" attribute of this IVirtualBox - object, the web service client does this:string version; + object, the web service client does this: + string version; version = webservice.IVirtualBox_getVersion(oVirtualBox); @@ -1189,9 +1203,8 @@ - The web service client calls with the - VirtualBox managed object reference. This will clean up all - allocated resources. + The web service client calls + IWebsessionManager::logoff() + with the VirtualBox managed object reference. This will clean + up all allocated resources. @@ -1212,19 +1225,17 @@ situations: - When a client logs on, by calling . + When a client logs on, by calling + IWebsessionManager::logon(). Upon logon, the websession manager creates one instance - of , + of IVirtualBox, which can be used for directly performing calls to its methods, or used as a parameter for calling some methods of - . - Creating Main API session objects is performed using . - - (Technically, there is always only one object, which + IWebsessionManager. + Creating Main API session objects is performed using + IWebsessionManager::getSessionObject(). + + (Technically, there is always only one + IVirtualBox object, which is shared between all websessions and clients, as it is a COM singleton. However, each session receives its own managed @@ -1236,7 +1247,8 @@ whose COM implementation creates COM objects. - For example, creates a new - instance of ; + For example, + IVirtualBox::createMachine() + creates a new instance of + IMachine; the COM object returned by the COM method call is then wrapped into a managed object reference by the web server, and this @@ -1255,7 +1267,7 @@ Managed object references are not destroyed automatically and - must be released by explicitly calling . This is important, as + must be released by explicitly calling + IManagedObjectRef::release(). + This is important, as otherwise hundreds or thousands of managed object references (and corresponding COM objects, which can consume much more memory!) can @@ -1269,11 +1281,10 @@ them. - When a web service client calls , all managed object - references created during the session are automatically freed. For - short-lived sessions that do not create a lot of objects, logging - off may therefore be sufficient, although it is certainly not "best - practice". + When a web service client calls + IWebsessionManager::logoff(), + all managed object references created during the session are + automatically freed. For short-lived sessions that do not create a + lot of objects, logging off may therefore be sufficient, although it + is certainly not "best practice". @@ -1321,6 +1332,6 @@ webServiceClass service("localhost", 18083); // server and port -string result = service.SayHello("Peter"); // invoke remote procedureand - would, for these two pseudo-lines, automatically perform these +string result = service.SayHello("Peter"); // invoke remote procedure + and would, for these two pseudo-lines, automatically perform these steps: @@ -1384,5 +1395,5 @@ procedure calls into the native language syntax -- for example, like in the Java sample shown in . + linkend="webservice-java-sample"/>. For details about how programming languages support web @@ -1401,6 +1412,6 @@ For Java, there are several implementations already described in this document - (see and ). + (see and ). @@ -1412,8 +1423,10 @@ (You can also import any WSDL file "live" by having it parsed every time the script runs, but that can take a while.) You - can then code (again, assuming the above example):my $result = servicename->sayHello("Peter"); + can then code (again, assuming the above example): + my $result = servicename->sayHello("Peter"); + A sample that uses SOAP::Lite was described in . + linkend="raw-webservice-perl"/>. @@ -1533,5 +1546,6 @@ - Following code will print all registered machines and their log folders + Following code will print all registered machines and their log + folders from vboxapi import VirtualBoxManager @@ -1760,6 +1774,7 @@ The sample program tstCAPIGlue - can be built using the provided Makefile - and can be run without arguments. + can be built using the provided + Makefile and can be run without + arguments. It uses the VBoxCAPIGlue library (source code is in directory @@ -1788,5 +1803,6 @@ VBoxCAPI_v4_3.h header provides the interface to the C binding, but you can alternatively and more - conveniently also include VBoxCAPIGlue.h, + conveniently also include + VBoxCAPIGlue.h, as this avoids the VirtualBox version dependent header file name and makes sure the global variable g_pVBoxFuncs contains a @@ -1877,6 +1893,8 @@ these rules to get the IVirtualBox reference, an ISession instance - reference and read the attribute:rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &vbox); + reference and read the + IVirtualBox::revision + attribute: + rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &vbox); if (FAILED(rc) || !vbox) { @@ -1902,5 +1920,6 @@ So far only attribute getters were illustrated, but generic - method calls are straightforward, too:IMachine *machine = NULL; + method calls are straightforward, too: + IMachine *machine = NULL; BSTR vmname = ...; ... @@ -1911,8 +1930,9 @@ As a more complicated example of a method invocation, let's - call which returns an - IProgress object. Note again that the method name is - capitalized:IProgress *progress; + call + IMachine::launchVMProcess + which returns an IProgress object. Note again that the method name is + capitalized: + IProgress *progress; ... rc = IMachine_LaunchVMProcess( @@ -1925,5 +1945,5 @@ All objects with their methods and attributes are documented - in . + in . @@ -1941,5 +1961,6 @@ represented by a pointer to the start of the zero-terminated string. There are functions for converting between UTF-8 and UTF-16 strings - available through g_pVBoxFuncs:int (*pfnUtf16ToUtf8)(CBSTR pwszString, char **ppszString); + available through g_pVBoxFuncs: + int (*pfnUtf16ToUtf8)(CBSTR pwszString, char **ppszString); int (*pfnUtf8ToUtf16)(const char *pszString, BSTR *ppwszString); @@ -1963,5 +1984,6 @@ Passing arrays as input parameters to API methods is usually done by the following sequence, calling a hypothetical - IArrayDemo_PassArray API method:static const ULONG aElements[] = { 1, 2, 3, 4 }; + IArrayDemo_PassArray API method: + static const ULONG aElements[] = { 1, 2, 3, 4 }; ULONG cElements = sizeof(aElements) / sizeof(aElements[0]); SAFEARRAY *psa = NULL; @@ -1973,5 +1995,6 @@ Likewise, getting arrays results from output parameters is done using helper functions which manage memory allocations as part of - their other functionality:SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc(); + their other functionality: + SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc(); ULONG *pData; ULONG cElements; @@ -1985,5 +2008,6 @@ gets the list of VMs, and passes the first IMachine reference to another API function (assuming that there is at least one element - in the array, to simplify the example):SAFEARRAY psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc(); + in the array, to simplify the example): + SAFEARRAY psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc(); IMachine **machines = NULL; ULONG machineCnt = 0; @@ -2040,8 +2064,9 @@ The actual event handler implementation is quite tedious, as it has to implement a complete API interface. Especially on Windows - it is a lot of work to implement the complicated IDispatch - interface, requiring to load COM type information and using it - in the IDispatch method implementation. Overall this is - quite tedious compared to passive event handling. + it is a lot of work to implement the complicated + IDispatch interface, requiring to load COM type + information and using it in the IDispatch method + implementation. Overall this is quite tedious compared to passive + event handling. Passive event handling uses a similar event loop structure, @@ -2060,13 +2085,14 @@ The general event handling concepts are described in the API - specification (see ), including how to + specification (see ), including how to aggregate multiple event sources for processing in one event loop. As mentioned, the sample illustrates the practical aspects of how to use both types of event handling, active and passive, from a C application. Additional hints are in the comments documenting - the helper methods in VBoxCAPI_v4_3.h. - The code complexity of active event handling (and its inherenly - platform/compiler specific aspects) should be motivation to use - passive event handling whereever possible. + the helper methods in + VBoxCAPI_v4_3.h. The code complexity + of active event handling (and its inherenly platform/compiler + specific aspects) should be motivation to use passive event handling + whereever possible. @@ -2175,6 +2201,7 @@ if the code refers to them frequently. - The C API client code should include VBoxCAPIGlue.h - instead of VBoxXPCOMCGlue.h or + The C API client code should include + VBoxCAPIGlue.h instead of + VBoxXPCOMCGlue.h or VBoxCAPI_v4_3.h, as this makes sure the correct macros and internal translations are selected. @@ -2195,5 +2222,5 @@ IErrorInfo for the first two respectively. Event queue handling should be replaced by using the platform independent way - described in . + described in . Finally adjust the string and array handling to use the new @@ -2239,29 +2266,34 @@ Any program using the Main API will first need access to the - global VirtualBox object (see ), from which all other functionality of the - API is derived. With the OOWS for JAX-WS, this is returned from the - call. + global VirtualBox object (see + IVirtualBox), from which all other + functionality of the API is derived. With the OOWS for JAX-WS, this is + returned from the + IWebsessionManager::logon() + call. To enumerate virtual machines, one would look at the "machines" - array attribute in the VirtualBox object (see ). + array attribute in the VirtualBox object (see + IVirtualBox::machines). This array contains all virtual machines currently registered with the - host, each of them being an instance of . From each such instance, one can query - additional information, such as the UUID, the name, memory, operating - system and more by looking at the attributes; see the attributes list in - . + host, each of them being an instance of + IMachine. + From each such instance, one can query additional information, such as + the UUID, the name, memory, operating system and more by looking at the + attributes; see the attributes list in + IMachine documentation. As mentioned in the preceding chapters, depending on your programming environment, attributes are mapped to corresponding "get" and (if the attribute is not read-only) "set" methods. So when the - documentation says that IMachine has a "" attribute, this means you need to code something - like the following to get the machine's name:IMachine machine = ...; -String name = machine.getName();Boolean attribute getters can - sometimes be called isAttribute() due - to JAX-WS naming conventions. + documentation says that IMachine has a + "name" attribute, this means you + need to code something + like the following to get the machine's name: + IMachine machine = ...; +String name = machine.getName(); + Boolean attribute getters can sometimes be called + isAttribute() due to JAX-WS naming + conventions. @@ -2288,37 +2320,35 @@ These requirements are implemented in the Main API by way of - "sessions", in particular, the interface. Each process which talks to + "sessions", in particular, the ISession + interface. Each process which talks to VirtualBox needs its own instance of ISession. In the web service, you - can request the creation of such an object by calling . More complex - management tasks might need multiple instances of ISession, and each call - returns a new one. + can request the creation of such an object by calling + IWebsessionManager::getSessionObject(). + More complex management tasks might need multiple instances of ISession, + and each call returns a new one. This session object must then be used like a mutex semaphore in common programming environments. Before you can change machine settings, - you must write-lock the machine by calling + you must write-lock the machine by calling + IMachine::lockMachine() with your process's session object. - After the machine has been locked, the attribute + After the machine has been locked, the + ISession::machine attribute contains a copy of the original IMachine object upon which the session was opened, but this copy is "mutable": you can invoke "set" methods on it. - When done making the changes to the machine, you must call , which will copy the changes you - have made from your "mutable" machine back to the real machine and write - them out to the machine settings XML file. This will make your changes - permanent. + When done making the changes to the machine, you must call + IMachine::saveSettings(), + which will copy the changes you have made from your "mutable" machine + back to the real machine and write them out to the machine settings XML + file. This will make your changes permanent. Finally, it is important to always unlock the machine again, by - calling . Otherwise, when the calling - process end, the machine will receive the "aborted" state, which can - lead to loss of data. + calling + ISession::unlockMachine(). + Otherwise, when the calling process end, the machine will receive the + "aborted" state, which can lead to loss of data. So, as an example, the sequence to change a machine's memory to @@ -2338,16 +2368,16 @@ Launching virtual machines - To launch a virtual machine, you call . In doing so, the caller - instructs the VirtualBox engine to start a new process with the virtual - machine in it, since to the host, each virtual machine looks like a - single process, even if it has hundreds of its own processes inside. - (This new VM process in turn obtains a write lock on the machine, as - described above, to prevent conflicting changes from other processes; - this is why opening another session will fail while the VM is - running.) - - Starting a machine looks something like this:IWebsessionManager mgr ...; + To launch a virtual machine, you call + IMachine::launchVMProcess(). + In doing so, the caller instructs the VirtualBox engine to start a new + process with the virtual machine in it, since to the host, each virtual + machine looks like single process, even if it has hundreds of its own + processes inside. (This new VM process in turn obtains a write lock on + the machine, as described above, to prevent conflicting changes from + other processes; this is why opening another session will fail while the + VM is running.) + + Starting a machine looks something like this: + IWebsessionManager mgr ...; IVirtualBox vbox = mgr.logon(user, pass); ... @@ -2363,6 +2393,6 @@ The caller's session object can then be used as a sort of remote control to the VM process that was launched. It contains a "console" - object (see ) with which the VM can be paused, + object (see ISession::console) + with which the VM can be paused, stopped, snapshotted or other things. @@ -2373,15 +2403,15 @@ In VirtualBox, "events" provide a uniform mechanism to register for and consume specific events. A VirtualBox client can register an - "event listener" (represented by the interface), which will then get notified - by the server when an event (represented by the interface) happens. + "event listener" (represented by the + IEventListener interface), which + will then get notified by the server when an event (represented by the + IEvent interface) happens. The IEvent interface is an abstract parent interface for all events that can occur in VirtualBox. The actual events that the server - sends out are then of one of the specific subclasses, for example or . + sends out are then of one of the specific subclasses, for example + IMachineStateChangedEvent + or + IMediumChangedEvent. As an example, the VirtualBox GUI waits for machine events and can @@ -2451,8 +2481,12 @@ You can easily extend this shell with your own commands. Create a - subdirectory named .config/VirtualBox/shexts - below your home directory (respectively .VirtualBox/shexts on a Windows system and Library/VirtualBox/shexts on OS X) and put a Python file implementing your shell - extension commands in this directory. This file must contain an array - named commands containing your command + subdirectory named + .config/VirtualBox/shexts below your home + directory (respectively .VirtualBox/shexts + on a Windows system and + Library/VirtualBox/shexts on OS X) and put + a Python file implementing your shell extension commands in this directory. + This file must contain an array named + commands containing your command definitions: commands = { @@ -3496,5 +3530,6 @@ Since VirtualBox 4.2 it's possible to transfer files from host to the Linux guests by dragging files, directories or text from the host into the - guest's screen. This is called drag'n drop (DnD). + guest's screen. This is called drag'n drop + (DnD). In version 5.0 support for Windows guests has been added, as well as @@ -3517,20 +3552,21 @@ source and a target: - The source is the side which provides the data, - e.g. is the origin of data. This data can be stored within the source directly - or can be retrieved on-demand by the source itself. Other interfaces don't - care where the data from this source actually came from. + The source is the side which provides the + data, e.g. is the origin of data. This data can be stored within the + source directly or can be retrieved on-demand by the source itself. Other + interfaces don't care where the data from this source actually came + from. The target on the other hand is the side which provides the source a visual representation where the user can drop the - data the source offers. This representation can be a window (or just a certain - part of it), for example. + data the source offers. This representation can be a window (or just a + certain part of it), for example. The source and the target have abstract interfaces called - and - . VirtualBox also + IDnDSource and + IDnDTarget. VirtualBox also provides implementations of both interfaces, called - and - . Both + IGuestDnDSource and + IGuestDnDTarget. Both implementations are also used in the VirtualBox Manager frontend. @@ -3539,40 +3575,43 @@ Supported formats - As the target needs to perform specific actions depending on the data - the source provided, the target first needs to know what type of data it - actually is going to retrieve. It might be that the source offers data the - target cannot (or intentionally does not want to) support. + As the target needs to perform specific actions depending on the + data the source provided, the target first needs to know what type of + data it actually is going to retrieve. It might be that the source offers + data the target cannot (or intentionally does not want to) + support. VirtualBox handles those data types by providing so-called - MIME types -- these MIME types were originally defined - in RFC 2046 and + MIME types -- these MIME types were originally + defined in + RFC 2046 and are also called Content-types. - and - support + IGuestDnDSource and + IGuestDnDTarget support the following MIME types by default: - text/uri-list - A list of URIs - (Uniform Resource Identifier, see + text/uri-list - A list of + URIs (Uniform Resource Identifier, see RFC 3986) - pointing to the file and/or directory paths already transferred from - the source to the target. + pointing to the file and/or directory paths already transferred + from the source to the target. text/plain;charset=utf-8 and - UTF8_STRING - text in UTF8 format. + UTF8_STRING - text in UTF-8 + format. text/plain, TEXT - and STRING - plain ASCII text, depending - on the source's active ANSI page (if any). + and STRING - plain ASCII text, + depending on the source's active ANSI page (if any). - If, for whatever reason, a certain default format should not be supported - or a new format should be registered, - and - have methods derived from - which provide adding, + If, for whatever reason, a certain default format should not be + supported or a new format should be registered, + IDnDSource and + IDnDTarget have methods derived from + IDnDBase which provide adding, removing and enumerating specific formats. Registering new or removing default formats on the guest side @@ -3738,7 +3777,6 @@ class path. - Start your application like this: - java -cp vboxjmscom.jar;c:\jacob\jacob.jar -Djava.library.path=c:\jacob MyProgram - + Start your application like this: + java -cp vboxjmscom.jar;c:\jacob\jacob.jar -Djava.library.path=c:\jacob MyProgram @@ -3866,42 +3904,42 @@ those operations in the case where no VM is running. - replaces - IConsole::saveState() - - - replaces - IConsole::adoptSavedState() - - - replaces - IConsole::discardSavedState() - - - replaces - IConsole::takeSnapshot() - - - replaces - IConsole::deleteSnapshot() - - - replaces - IConsole::deleteSnapshotAndAllChildren() - - - replaces - IConsole::deleteSnapshotRange() + IMachine::saveState() + replaces + IConsole::saveState() + + + IMachine::adoptSavedState() + replaces + IConsole::adoptSavedState() + + + IMachine::discardSavedState() + replaces + IConsole::discardSavedState() + + + IMachine::takeSnapshot() + replaces + IConsole::takeSnapshot() + + + IMachine::deleteSnapshot() + replaces + IConsole::deleteSnapshot() + + + IMachine::deleteSnapshotAndAllChildren() + replaces + IConsole::deleteSnapshotAndAllChildren() + + + IMachine::deleteSnapshotRange() + replaces + IConsole::deleteSnapshotRange() - replaces - IConsole::restoreSnapshot() + IMachine::restoreSnapshot() + replaces + IConsole::restoreSnapshot() @@ -3916,26 +3954,28 @@ Two new machine states have been introduced to allow proper distinction between saving state and taking a snapshot. - + MachineState::Saving now is used exclusively while the VM's state is being saved, without any overlaps with snapshot functionality. The new state - + MachineState::Snapshotting is used when an offline snapshot is taken and likewise the new state - + MachineState::OnlineSnapshotting is used when an online snapshot is taken. - A new event has been introduced, which signals when a snapshot has been - restored: - . + A new event has been introduced, which signals when a snapshot + has been restored: + ISnapshotRestoredEvent. Previously the event - was - signalled, which isn't logical (but could be distinguished from actual deletion - by the fact that the snapshot was still there). - - - - The method replaces + ISnapshotDeletedEvent + was signalled, which isn't logical (but could be distinguished from + actual deletion by the fact that the snapshot was still + there). + + + + The method + IVirtualBox::createMedium() + replaces VirtualBox::createHardDisk(). Adjusting existing code needs adding two parameters with @@ -3948,21 +3988,24 @@ - The method now has an - additional parameter (first parameter), for specifying the storage - bus which the storage controller must be using. The method was not - useful before, as the instance numbers are only unique for a specfic - storage bus. - - - - The attribute IMachine::sessionType - has been renamed to . This cleans up the confusing - terminology (as the session type is something different). - - - - The attribute IMachine::guestPropertyNotificationPatterns + The method + IMachine::getStorageControllerByInstance() + now has an additional parameter (first parameter), for specifying the + storage bus which the storage controller must be using. The method + was not useful before, as the instance numbers are only unique for a + specfic storage bus. + + + + The attribute + IMachine::sessionType has been + renamed to + IMachine::sessionName(). + This cleans up the confusing terminology (as the session type is + something different). + + + + The attribute + IMachine::guestPropertyNotificationPatterns has been removed. In practice it was not usable because it is too global and didn't distinguish between API clients. @@ -3972,6 +4015,7 @@ - Methods for providing host to guest drag'n drop functionality, - such as IGuest::dragHGEnter, + Methods for providing host to guest drag'n drop + functionality, such as + IGuest::dragHGEnter, IGuest::dragHGMove(), IGuest::dragHGLeave(), @@ -3979,62 +4023,70 @@ IGuest::dragHGPutData(), have been moved to an abstract base class called - . VirtualBox implements - this base class in the + IDnDTarget. + VirtualBox implements this base class in the + IGuestDnDTarget interface. The implementation can be used by using the - method. - Methods for providing guest to host drag'n drop functionality, - such as IGuest::dragGHPending(), + IGuest::dnDTarget() + method. + Methods for providing guest to host drag'n drop + functionality, such as + IGuest::dragGHPending(), IGuest::dragGHDropped() and IGuest::dragGHGetData(), have been moved to an abstract base class called - . VirtualBox implements - this base class in the + IDnDSource. + VirtualBox implements this base class in the + IGuestDnDSource interface. The implementation can be used by using the - method. + IGuest::dnDSource() + method. - The DragAndDropAction enumeration has been - renamed to . + The DragAndDropAction + enumeration has been renamed to + DnDAction. - The DragAndDropMode enumeration has been - renamed to . + The DragAndDropMode + enumeration has been renamed to + DnDMode. - The attribute IMachine::dragAndDropMode - has been renamed to . + The attribute + IMachine::dragAndDropMode + has been renamed to + IMachine::dnDMode(). - The event IDragAndDropModeChangedEvent - has been renamed to . + The event + IDragAndDropModeChangedEvent + has been renamed to + IDnDModeChangedEvent. - - The callback method IInternalSessionControl::onDragAndDropModeChange - has been renamed to . - - - IDisplay and IFramebuffer interfaces were changed to allow IFramebuffer - object to reside in a separate frontend process: + IDisplay and IFramebuffer interfaces were changed to + allow IFramebuffer object to reside in a separate frontend + process: - IDisplay::ResizeCompleted() has been removed, because the IFramebuffer object - does not provide the screen memory anymore. + IDisplay::ResizeCompleted() has been removed, because the + IFramebuffer object does not provide the screen memory anymore. - IDisplay::SetFramebuffer() has been replaced with IDisplay::AttachFramebuffer() - and IDisplay::DetachFramebuffer(). + IDisplay::SetFramebuffer() has been replaced with + IDisplay::AttachFramebuffer() and IDisplay::DetachFramebuffer(). - IDisplay::GetFramebuffer() has been replaced with IDisplay::QueryFramebuffer(). + IDisplay::GetFramebuffer() has been replaced with + IDisplay::QueryFramebuffer(). @@ -4046,20 +4098,25 @@ - IDisplay::TakeScreenShot() and IDisplay::TakeScreenShotToArray() have a new parameter - bitmapFormat. As a consequence of this, - IDisplay::TakeScreenShotPNGToArray() has been removed. + IDisplay::TakeScreenShot() and IDisplay::TakeScreenShotToArray() + have a new parameter + bitmapFormat. As a consequence of + this, IDisplay::TakeScreenShotPNGToArray() has been removed. - IFramebuffer::RequestResize() has been replaced with IFramebuffer::NotifyChange(). + IFramebuffer::RequestResize() has been replaced with + IFramebuffer::NotifyChange(). - IFramebuffer::NotifyUpdateImage() added to support IFramebuffer objects in a different process. + IFramebuffer::NotifyUpdateImage() added to support IFramebuffer + objects in a different process. - IFramebuffer::Lock(), IFramebuffer::Unlock(), IFramebuffer::Address(), IFramebuffer::UsesGuestVRAM() - have been removed because the IFramebuffer object does not provide the screen memory anymore. + IFramebuffer::Lock(), IFramebuffer::Unlock(), + IFramebuffer::Address(), IFramebuffer::UsesGuestVRAM() have been + removed because the IFramebuffer object does not provide the screen + memory anymore. @@ -4067,135 +4124,180 @@ - IGuestSession, IGuestFile and IGuestProcess interfaces were changed as follows: + IGuestSession, IGuestFile and IGuestProcess interfaces + were changed as follows: - Replaced IGuestSession::directoryQueryInfo and IGuestSession::fileQueryInfo with a new - method - that works on any type of file system object. - - - Replaced IGuestSession::fileRemove, IGuestSession::symlinkRemoveDirectory and + Replaced IGuestSession::directoryQueryInfo and + IGuestSession::fileQueryInfo with a new + IGuestSession::fsObjQueryInfo + method that works on any type of file system object. + + + Replaced IGuestSession::fileRemove, + IGuestSession::symlinkRemoveDirectory and IGuestSession::symlinkRemoveFile with a new - method that works - on any type of file system object except directories. (fileRemove also worked on any type of object too, + IGuestSession::fsObjRemove + method that works on any type of file system object except + directories. (fileRemove also worked on any type of object + too, though that was not the intent of the method.) + + + Replaced IGuestSession::directoryRename and + IGuestSession::directoryRename with a new + IGuestSession::fsObjRename + method that works on any type of file system object. + (directoryRename and fileRename may already have worked for + any kind of object, but that was never the intent of the + methods.) + + + Replaced the unimplemented IGuestSession::directorySetACL + and IGuestSession::fileSetACL with a new + IGuestSession::fsObjSetACL + method that works on all type of file system object. Also + added a UNIX-style mode parameter as an alternative to the + ACL. + + + Replaced IGuestSession::fileRemove, + IGuestSession::symlinkRemoveDirectory and + IGuestSession::symlinkRemoveFile with a new + IGuestSession::fsObjRemove + method that works on any type of file system object except + directories (fileRemove also worked on any type of object, though that was not the intent of the method.) - Replaced IGuestSession::directoryRename and IGuestSession::directoryRename with a new - method that works - on any type of file system object. (directoryRename and fileRename may already have worked for any kind - of object, but that was never the intent of the methods.) - - - Replaced the unimplemented IGuestSession::directorySetACL and IGuestSession::fileSetACL with a new - method that works - on all type of file system object. Also added a UNIX-style mode parameter as an alternative to the ACL. - - - Replaced IGuestSession::fileRemove, IGuestSession::symlinkRemoveDirectory and - IGuestSession::symlinkRemoveFile with a new - method that works - on any type of file system object except directories (fileRemove also worked on any type of object, - though that was not the intent of the method.) - - - Renamed IGuestSession::copyTo to . - - - Renamed IGuestSession::copyFrom to . - - - Renamed the CopyFileFlag enum to . - - - Renamed the IGuestSession::environment attribute to to better reflect what it does. - - - Changed the to - a stub returning E_NOTIMPL since it wasn't doing what was advertised (returned changes, not the - actual environment). - - - Renamed IGuestSession::environmentSet to to better reflect what it does. - - - Renamed IGuestSession::environmentUnset to to better reflect what it does. - - - Removed IGuestSession::environmentGet it was only getting changes while giving the impression it was - actual environment variables, and it did not represent scheduled unset operations. - - - Removed IGuestSession::environmentClear as it duplicates assigning an empty array to the - (formerly - known as IGuestSession::environment). - - - Changed the and - methods to accept - arguments starting with argument zero (argv[0]) instead of argument one (argv[1]). (Not yet implemented on the - guest additions side, so argv[0] will probably be ignored for a short while.) - - - - Added a followSymlink parameter to the following methods: - - - + Renamed IGuestSession::copyTo to + IGuestSession::fileCopyToGuest. + + + Renamed IGuestSession::copyFrom to + IGuestSession::fileCopyFromGuest. + + + Renamed the CopyFileFlag enum to + FileCopyFlag. + + + Renamed the IGuestSession::environment attribute to + IGuestSession::environmentChanges + to better reflect what it does. + + + Changed the + IGuestProcess::environment + to a stub returning E_NOTIMPL since it wasn't doing what was + advertised (returned changes, not the actual environment). + + + Renamed IGuestSession::environmentSet to + IGuestSession::environmentScheduleSet + to better reflect what it does. + + + Renamed IGuestSession::environmentUnset to + IGuestSession::environmentScheduleUnset + to better reflect what it does. + + + Removed IGuestSession::environmentGet it was only getting + changes while giving the impression it was actual environment + variables, and it did not represent scheduled unset + operations. + + + Removed IGuestSession::environmentClear as it duplicates + assigning an empty array to the + IGuestSession::environmentChanges + (formerly known as IGuestSession::environment). + + + Changed the + IGuestSession::processCreate + and + IGuestSession::processCreateEx + methods to accept arguments starting with argument zero (argv[0]) + instead of argument one (argv[1]). (Not yet implemented on the + guest additions side, so argv[0] will probably be ignored for a + short while.) + + + + Added a followSymlink parameter to the following methods: + + IGuestSession::directoryExists + IGuestSession::fileExists + IGuestSession::fileQuerySize - The parameters to the - and methods were - altered: - The openMode string parameter was replaced by the enum - and renamed to accessMode. - The disposition string parameter was replaced by the enum - and renamed to openAction. - The unimplemented sharingMode string parameter was replaced by the enum - (fileOpenEx only). - Added a flags parameter taking a list of values (fileOpenEx only). - Removed the offset parameter (fileOpenEx only). + The parameters to the + IGuestSession::fileOpen + and + IGuestSession::fileOpenEx + methods were altered: + The openMode string parameter was replaced by + the enum + FileAccessMode + and renamed to accessMode. + The disposition string parameter was replaced + by the enum + FileOpenAction + and renamed to openAction. + The unimplemented sharingMode string parameter + was replaced by the enum + FileSharingMode + (fileOpenEx only). + Added a flags parameter taking a list of + FileOpenExFlags values + (fileOpenEx only). + Removed the offset parameter (fileOpenEx + only). - now returns the new offset. - - - Renamed the FileSeekType enum used by - to and added the missing End value - and renaming the Set to Begin. - - - Extended the unimplemented - method with a UNIX-style mode parameter as an alternative to the ACL. - - - Renamed the IFile::openMode attribute to - and change the type from string to to reflect + IGuestFile::seek now + returns the new offset. + + + Renamed the FileSeekType enum used by + IGuestFile::seek + to FileSeekOrigin and + added the missing End value and renaming the Set to + Begin. + + + Extended the unimplemented + IGuestFile::setACL + method with a UNIX-style mode parameter as an alternative to + the ACL. + + + Renamed the IFile::openMode attribute to + IFile::accessMode + and change the type from string to + FileAccessMode to reflect the changes to the fileOpen methods. - Renamed the IGuestFile::disposition attribute to and change the type from string to to reflect the changes to the fileOpen methods. + Renamed the IGuestFile::disposition attribute to + IFile::openAction and + change the type from string to + FileOpenAction to reflect + the changes to the fileOpen methods. - Added attribute. - - - Added attribute. + Added + IGuestSession::pathStyle + attribute. + + + Added + IGuestSession::fsObjExists + attribute. @@ -4205,11 +4307,12 @@ - IConsole::GetDeviceActivity() returns information about multiple devices. + IConsole::GetDeviceActivity() returns information about multiple + devices. IMachine::ReadSavedThumbnailToArray() has a new parameter - bitmapFormat. As a consequence of this, - IMachine::ReadSavedThumbnailPNGToArray() has been removed. + bitmapFormat. As a consequence of + this, IMachine::ReadSavedThumbnailPNGToArray() has been removed. @@ -4231,10 +4334,11 @@ - The method now returns - a new instance for - every invocation. This puts the behavior in line with other binding - styles, which never forced the equivalent of establishing another - connection and logging in again to get another instance. + The method + IWebsessionManager::getSessionObject() + now returns a new ISession instance + for every invocation. This puts the behavior in line with other + binding styles, which never forced the equivalent of establishing + another connection and logging in again to get another + instance. @@ -4247,43 +4351,44 @@ The explicit medium locking methods - - and + IMedium::lockRead() + and IMedium::lockWrite() have been redesigned. They return a lock token object reference - now, and calling the method (or letting the reference - count to this object drop to 0) will unlock it. This eliminates - the rather common problem that an API client crash left behind - locks, and also improves the safety (API clients can't release - locks they didn't obtain). - - - - The parameter list of has been changed slightly, to - allow multiple flags to be passed. + now, and calling the + IToken::abandon() method (or + letting the reference count to this object drop to 0) will unlock + it. This eliminates the rather common problem that an API client + crash left behind locks, and also improves the safety (API clients + can't release locks they didn't obtain). + + + + The parameter list of + IAppliance::write() + has been changed slightly, to allow multiple flags to be + passed. IMachine::delete - has been renamed to , to improve API client - binding compatibility. + has been renamed to + IMachine::deleteConfig(), + to improve API client binding compatibility. IMachine::export - has been renamed to , to improve API client binding - compatibility. - - - - For the meaning of the - type parameter has changed slightly. - Empty string now means that the per-VM or global default frontend - is launched. Most callers of this method should use the empty string - now, unless they really want to override the default and launch a - particular frontend. + has been renamed to + IMachine::exportTo(), + to improve API client binding compatibility. + + + + For + IMachine::launchVMProcess() + the meaning of the type parameter + has changed slightly. Empty string now means that the per-VM or + global default frontend is launched. Most callers of this method + should use the empty string now, unless they really want to override + the default and launch a particular frontend. @@ -4293,37 +4398,42 @@ The type of attribute - + IMedium::variant() changed from unsigned long to safe-array MediumVariant. - It is an array of flags instead of a set of flags which were stored inside one variable. + It is an array of flags instead of a set of flags which were + stored inside one variable. - The parameter list for was modified. - The type of parameter variant was changed from unsigned long to safe-array MediumVariant. - - - - The parameter list for was modified. - The type of parameter variant was changed from unsigned long to safe-array MediumVariant. - - - - The parameter list for was modified. - The type of parameter variant was changed from unsigned long to safe-array MediumVariant. - - - - The parameter list for was modified. - The type of parameter variant was changed from unsigned long to safe-array MediumVariant. + The parameter list for + IMedium::cloneTo() + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + + + + + The parameter list for + IMedium::createBaseStorage() + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + + + + + The parameter list for + IMedium::createDiffStorage() + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + + + + + The parameter list for + IMedium::cloneToBase() + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + @@ -4332,50 +4442,52 @@ The type of attribute - - changed from unsigned long - to safe-array MediumFormatCapabilities. - It is an array of flags instead of a set of flags which were stored inside one variable. + IMediumFormat::capabilities() + changed from unsigned long to + safe-array MediumFormatCapabilities. + It is an array of flags instead of a set of flags which were stored + inside one variable. - The attribute now returns the logical - size of exactly this medium object (whether it is a base or diff - image). The old behavior was no longer acceptable, as each image - can have a different capacity. - - - - Guest control APIs - such as , , and so on - now emit own events to provide - clients much finer control and the ability to write own frontends for - guest operations. The event acts as an abstract base class - for all guest control events. Certain guest events contain a - member - to provide more information in case of an error happened on the - guest side. - - - - Guest control sessions on the guest started by - now are dedicated guest processes to provide more safety and performance - for certain operations. Also, the call does not wait for the - guest session being created anymore due to the dedicated guest session - processes just mentioned. This also will enable webservice clients to - handle guest session creation more gracefully. To wait for a guest - session being started, use the newly added attribute + The attribute + IMedium::logicalSize() + now returns the logical size of exactly this medium object (whether + it is a base or diff image). The old behavior was no longer + acceptable, as each image can have a different capacity. + + + + Guest control APIs - such as + IGuest, + IGuestSession, + IGuestProcess and so on - now + emit own events to provide clients much finer control and the ability + to write own frontends for guest operations. The event + IGuestSessionEvent acts as + an abstract base class for all guest control events. Certain guest + events contain a + IVirtualBoxErrorInfo + member to provide more information in case of an error happened on + the guest side. + + + + Guest control sessions on the guest started by + IGuest::createSession() + now are dedicated guest processes to provide more safety and + performance for certain operations. Also, the + IGuest::createSession() + call does not wait for the guest session being created anymore due + to the dedicated guest session processes just mentioned. This also + will enable webservice clients to handle guest session creation + more gracefully. To wait for a guest session being started, use the + newly added attribute + IGuestSession::status() to query the current guest session status. - The + The IGuestFile APIs are now implemented to provide native guest file access from the host. @@ -4383,31 +4495,33 @@ - The parameter list for was modified. - It now supports specifying optional command line arguments for the - Guest Additions installer performing the actual update on the guest. - - - - A new event was introduced to provide - guest user status updates to the host via event listeners. To use this - event there needs to be at least the 4.3 Guest Additions installed on - the guest. At the moment only the states "Idle" and "InUse" of the - enumeration are supported on - Windows guests, starting at Windows 2000 SP2. + The parameter list for + IMedium::updateGuestAdditions() + was modified. It now supports specifying optional command line + arguments for the Guest Additions installer performing the actual + update on the guest. + + + + + A new event + IGuestUserStateChangedEvent + was introduced to provide guest user status updates to the host via + event listeners. To use this event there needs to be at least the 4.3 + Guest Additions installed on the guest. At the moment only the states + "Idle" and "InUse" of the + GuestUserState enumeration arei + supported on Windows guests, starting at Windows 2000 SP2. - The attribute was added to provide a - convenient way to lookup the guest session's protocol version it - uses to communicate with the installed Guest Additions on the guest. - Older Guest Additions will set the protocol version to 1, whereas - Guest Additions 4.3 will set the protocol version to 2. This might - change in the future as new features arise. + The attribute + IGuestSession::protocolVersion + was added to provide a convenient way to lookup the guest session's + protocol version it uses to communicate with the installed Guest + Additions on the guest. Older Guest Additions will set the protocol + version to 1, whereas Guest Additions 4.3 will set the protocol + version to 2. This might change in the future as new features + arise. @@ -4419,9 +4533,11 @@ - The - class is not a singleton of - anymore but contains - a list of USB controllers present in the VM. The USB device filter - handling was moved to . + The IUSBController + class is not a singleton of + IMachine anymore but + IMachine contains a list of USB + controllers present in the VM. The USB device filter handling was + moved to + IUSBDeviceFilters. @@ -4436,7 +4552,7 @@ Guest control APIs for executing guest processes, working with guest files or directories have been moved to the newly introduced - interface which - can be created by calling . + IGuestSession interface which + can be created by calling + IGuest::createSession(). A guest session will act as a @@ -4448,9 +4564,9 @@ Instead of working with process or directory handles before version 4.2, there now are the dedicated interfaces - , - and - . To retrieve more + IGuestProcess, + IGuestDirectory and + IGuestFile. To retrieve more information of a file system object the new interface - has been + IGuestFsObjInfo has been introduced. @@ -4458,19 +4574,16 @@ compatible so that it can be used with older installed Guest Additions. However, to use upcoming features like process termination - or waiting for input / output new Guest Additions must be installed when - these features got implemented. + or waiting for input / output new Guest Additions must be installed + when these features got implemented. The following limitations apply: - The + The IGuestFile interface is not fully implemented yet. The symbolic link APIs - , - , - , + IGuestSession::symlinkCreate(), + IGuestSession::symlinkExists(), + IGuestSession::symlinkRead(), IGuestSession::symlinkRemoveDirectory() and IGuestSession::symlinkRemoveFile() are not @@ -4478,8 +4591,6 @@ The directory APIs - , - , + IGuestSession::directoryRemove(), + IGuestSession::directoryRemoveRecursive(), IGuestSession::directoryRename() and IGuestSession::directorySetACL() are not @@ -4487,27 +4598,31 @@ The temporary file creation API - is not + IGuestSession::fileCreateTemp() + is not implemented yet. + + Guest process termination via + IProcess::terminate() + is not implemented yet. + + Waiting for guest process output via + ProcessWaitForFlag::StdOut + and + ProcessWaitForFlag::StdErr + is not implemented yet. + To wait for process output, + IProcess::read() with + appropriate flags still can be used to periodically check for + new output data to arrive. Note that + ProcessCreateFlag::WaitForStdOut + and / or + ProcessCreateFlag::WaitForStdErr + need to be specified when creating a guest process via + IGuestSession::processCreate() + or + IGuestSession::processCreateEx(). + + + ACL (Access Control List) handling in general is not implemented yet. - - Guest process termination via - is not - implemented yet. - - Waiting for guest process output via - - and - is not implemented yet.To wait for process output, with appropriate flags still can be used to periodically - check for new output data to arrive. Note that and / or - - need to be specified when creating a guest process via or . - - - ACL (Access Control List) handling in general is not implemented yet. @@ -4516,13 +4631,13 @@ - The - enumeration now has an additional value VM - which tells to create a full-blown - object structure for running a VM. This was the previous behavior - with Write, which now only creates - the minimal object structure to save time and resources (at the - moment the Console object is still created, but all sub-objects - such as Display, Keyboard, Mouse, Guest are not. + The LockType + enumeration now has an additional value + VM which tells + IMachine::lockMachine() + to create a full-blown object structure for running a VM. This was + the previous behavior with Write, + which now only creates the minimal object structure to save time and + resources (at the moment the Console object is still created, but all + sub-objects such as Display, Keyboard, Mouse, Guest are not. @@ -4530,18 +4645,18 @@ Machines can be put in groups (actually an array of groups). The primary group affects the default placement of files belonging - to a VM. and - have been - adjusted accordingly, the former taking an array of groups as an - additional parameter and the latter taking a group as an additional - parameter. The create option handling has been changed for those two - methods, too. + to a VM. + IVirtualBox::createMachine() + and + IVirtualBox::composeMachineFilename() + have been adjusted accordingly, the former taking an array of groups + as an additional parameter and the latter taking a group as an + additional parameter. The create option handling has been changed for + those two methods, too. The method IVirtualBox::findMedium() has been removed, since - it provides a subset of the functionality of . + it provides a subset of the functionality of + IVirtualBox::openMedium(). @@ -4562,125 +4677,125 @@ PointingHidType - + PointingHIDType KeyboardHidType - + KeyboardHIDType IPciAddress - + IPCIAddress IPciDeviceAttachment - + IPCIDeviceAttachment IMachine::pointingHidType - + IMachine::pointingHIDType IMachine::keyboardHidType - + IMachine::keyboardHIDType IMachine::hpetEnabled - + IMachine::HPETEnabled IMachine::sessionPid - + IMachine::sessionPID IMachine::ioCacheEnabled - + IMachine::IOCacheEnabled IMachine::ioCacheSize - + IMachine::IOCacheSize IMachine::pciDeviceAssignments - + IMachine::PCIDeviceAssignments IMachine::attachHostPciDevice() - + IMachine::attachHostPCIDevice IMachine::detachHostPciDevice() - + IMachine::detachHostPCIDevice() IConsole::attachedPciDevices - + IConsole::attachedPCIDevices IHostNetworkInterface::dhcpEnabled - + IHostNetworkInterface::DHCPEnabled IHostNetworkInterface::enableStaticIpConfig() - + IHostNetworkInterface::enableStaticIPConfig() IHostNetworkInterface::enableStaticIpConfigV6() - + IHostNetworkInterface::enableStaticIPConfigV6() IHostNetworkInterface::enableDynamicIpConfig() - + IHostNetworkInterface::enableDynamicIPConfig() IHostNetworkInterface::dhcpRediscover() - + IHostNetworkInterface::DHCPRediscover() IHost::Acceleration3DAvailable - + IHost::acceleration3DAvailable IGuestOSType::recommendedPae - + IGuestOSType::recommendedPAE IGuestOSType::recommendedDvdStorageController - + IGuestOSType::recommendedDVDStorageController IGuestOSType::recommendedDvdStorageBus - + IGuestOSType::recommendedDVDStorageBus IGuestOSType::recommendedHdStorageController - + IGuestOSType::recommendedHDStorageController IGuestOSType::recommendedHdStorageBus - + IGuestOSType::recommendedHDStorageBus IGuestOSType::recommendedUsbHid - + IGuestOSType::recommendedUSBHID IGuestOSType::recommendedHpet - + IGuestOSType::recommendedHPET IGuestOSType::recommendedUsbTablet - + IGuestOSType::recommendedUSBTablet IGuestOSType::recommendedRtcUseUtc - + IGuestOSType::recommendedRTCUseUTC IGuestOSType::recommendedUsb - + IGuestOSType::recommendedUSB INetworkAdapter::natDriver - + INetworkAdapter::NATEngine @@ -4690,45 +4805,45 @@ INATEngine::tftpPrefix - + INATEngine::TFTPPrefix INATEngine::tftpBootFile - + INATEngine::TFTPBootFile INATEngine::tftpNextServer - + INATEngine::TFTPNextServer INATEngine::dnsPassDomain - + INATEngine::DNSPassDomain INATEngine::dnsProxy - + INATEngine::DNSProxy INATEngine::dnsUseHostResolver - + INATEngine::DNSUseHostResolver VBoxEventType::OnHostPciDevicePlug - + VBoxEventType::OnHostPCIDevicePlug ICPUChangedEvent::cpu - + ICPUChangedEvent::CPU INATRedirectEvent::hostIp - + INATRedirectEvent::hostIP INATRedirectEvent::guestIp - + INATRedirectEvent::guestIP IHostPciDevicePlugEvent - + IHostPCIDevicePlugEvent @@ -4743,22 +4858,24 @@ - The method has one more parameter - now, which allows to configure the import process in more detail. + The method + IAppliance::importMachines() + has one more parameter now, which allows to configure the import + process in more detail. - The method has one more parameter - now, which allows resolving duplicate medium UUIDs without the need - for external tools. - - - - The + The method + IVirtualBox::openMedium() + has one more parameter now, which allows resolving duplicate medium + UUIDs without the need for external tools. + + + + The INetworkAdapter interface has been cleaned up. The various methods to activate an attachment type have been replaced by the - setter. + INetworkAdapter::attachmentType + setter. Additionally each attachment mode now has its own attribute, which means that host only networks no longer share the settings with @@ -4772,22 +4889,28 @@ This version introduces the guest facilities concept. A guest - facility either represents a module or feature the guest is running or - offering, which is defined by . Each facility is member of a - - and has a current status indicated by , together with a timestamp (in ms) of - the last status update. + facility either represents a module or feature the guest is running + or offering, which is defined by + AdditionsFacilityType. + Each facility is member of a + AdditionsFacilityClass + and has a current status indicated by + AdditionsFacilityStatus, + together with a timestamp (in ms) of the last status update. To address the above concept, the following changes were made: - In the interface, the following were removed: + In the IGuest interface, the + following were removed: - the supportsSeamless attribute; + the + supportsSeamless + attribute; - the supportsGraphics attribute; + the + supportsGraphics + attribute; @@ -4796,27 +4919,32 @@ - The function - was added. It quickly provides a facility's status without the need to get the facility - collection with . + The function + IGuest::getFacilityStatus() + was added. It quickly provides a facility's status without + the need to get the facility collection with + IGuest::facilities. - The attribute - was added to provide an easy to access collection of all currently known guest - facilities, that is, it contains all facilies where at least one status update was - made since the guest was started. + The attribute + IGuest::facilities + was added to provide an easy to access collection of all + currently known guest facilities, that is, it contains all + facilies where at least one status update was made since the + guest was started. - The interface + The interface + IAdditionsFacility was added to represent a single facility returned by - . + IGuest::facilities. - + AdditionsFacilityStatus was added to represent a facility's overall status. @@ -4824,6 +4952,6 @@ - and - were + AdditionsFacilityType and + AdditionsFacilityClass were added to represent the facility's type and class. @@ -4845,6 +4973,5 @@ instead of IWebsessionManager, the new class VirtualBoxManager must be - used. See - for details. + used. See for details. @@ -4856,7 +4983,7 @@ Replace any IVirtualBox::openSession(uuidMachine, - ...) API call with the machine's call and a + ...) API call with the machine's + IMachine::lockMachine() + call and a LockType.Write argument. The functionality is unchanged, but instead of "opening a direct @@ -4869,12 +4996,11 @@ Similarly, replace any IVirtualBox::openExistingSession(uuidMachine, - ...) call with the machine's call and a - LockType.Shared argument. - Whereas it was previously impossible to connect a client - session to a running VM process in a race-free manner, the new - API will atomically either write-lock the machine for the - current session or establish a remote link to an existing + ...) call with the machine's + IMachine::lockMachine() + call and a LockType.Shared + argument. Whereas it was previously impossible to connect a + client session to a running VM process in a race-free manner, + the new API will atomically either write-lock the machine for + the current session or establish a remote link to an existing session. Existing client code which tried calling both openSession() and @@ -4886,15 +5012,13 @@ Third, replace any IVirtualBox::openRemoteSession(uuidMachine, - ...) call with the machine's call. The - functionality is unchanged. - - - - The enum was adjusted accordingly: - "Open" is now "Locked", "Closed" is now "Unlocked", "Closing" - is now "Unlocking". + ...) call with the machine's + IMachine::launchVMProcess() + call. The functionality is unchanged. + + + + The SessionState enum + was adjusted accordingly: "Open" is now "Locked", "Closed" is + now "Unlocked", "Closing" is now "Unlocking". @@ -4911,20 +5035,19 @@ Neither IVirtualBox::createHardDisk() - nor register media - automatically any more. - - - - and now take an IMedium - object instead of a UUID as an argument. It is these two calls - which add media to a registry now (either a machine registry - for machines created with VirtualBox 4.0 or later or the - global registry otherwise). As a consequence, if a medium is - opened but never attached to a machine, it is no longer added - to any registry any more. + nor + IVirtualBox::openMedium() + register media automatically any more. + + + + IMachine::attachDevice() + and + IMachine::mountMedium() + now take an IMedium object instead of a UUID as an argument. It + is these two calls which add media to a registry now (either a + machine registry for machines created with VirtualBox 4.0 or + later or the global registry otherwise). As a consequence, if a + medium is opened but never attached to a machine, it is no + longer added to any registry any more. @@ -4935,7 +5058,6 @@ been merged into IVirtualBox::findMedium(), and IVirtualBox::openHardDisk(), openDVDImage() and - openFloppyImage() have all been merged into . + openFloppyImage() have all been merged into + IVirtualBox::openMedium(). @@ -4954,7 +5076,8 @@ - The attribute - replaces the getMaxVDISize() + The + ISystemProperties::infoVDSize + attribute replaces the + getMaxVDISize() API call; this now uses bytes instead of megabytes. @@ -4965,9 +5088,9 @@ 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. + IVirtualBox::createMachine() + 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. @@ -4982,16 +5105,18 @@ aforementioned media APIs, IVirtualBox::getMachine() has - been merged with , and + been merged with + IVirtualBox::findMachine(), + and IMachine::getSnapshot() has - been merged with . + been merged with + IMachine::findSnapshot(). IVirtualBox::unregisterMachine() - was replaced with with additional - functionality for cleaning up machine files. + was replaced with + IMachine::unregister() + with additional functionality for cleaning up machine + files. @@ -5008,5 +5133,6 @@ IConsole::forgetSavedState - has been renamed to IConsole::discardSavedState(). + has been renamed to + IConsole::discardSavedState(). @@ -5017,20 +5143,20 @@ event mechanism that can be used both locally (COM, XPCOM) and remotely (web services). Also, the new mechanism is usable from - scripting languages and a local Java. See for details. The new concept will require - changes to all clients that used event callbacks. - - - - 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 - version and revision in form of + scripting languages and a local Java. See + events for details. The new concept + will require changes to all clients that used event callbacks. + + + + additionsActive() was replaced + with + additionsRunLevel() + and + getAdditionsStatus() + in order to support a more detailed status of the current Guest + Additions loading/readiness state. + IGuest::additionsVersion() + no longer returns the Guest Additions interface version but the + installed Guest Additions version and revision in form of 3.3.0r12345. @@ -5041,20 +5167,17 @@ automount parameter: - - - - - - - - - + IVirtualBox::createSharedFolder() + + + + IMachine::createSharedFolder() + + + + IConsole::createSharedFolder() Also, a new property named - autoMount was added to the + autoMount was added to the + ISharedFolder interface. @@ -5071,6 +5194,6 @@ - received an extra parameter + IAppliance::write() + received an extra parameter manifest, which can suppress creating the manifest file on export. @@ -5078,7 +5201,7 @@ - received two extra - parameters sizes and + IVFSExplorer::entryList() + received two extra parameters + sizes and modes, which contains the sizes (in bytes) and the file access modes (in octal form) of @@ -5100,29 +5223,29 @@ IVRDPServer has been - renamed to . + renamed to + IVRDEServer. IRemoteDisplayInfo has - been renamed to . - - - - replaces + been renamed to + IVRDEServerInfo. + + + + IMachine::VRDEServer + replaces VRDPServer. - replaces + IConsole::VRDEServerInfo + replaces RemoteDisplayInfo. - replaces + ISystemProperties::VRDEAuthLibrary + replaces RemoteDisplayAuthLibrary. @@ -5133,16 +5256,13 @@ generic VRDE properties: - + IVRDEServer::setVRDEProperty - + IVRDEServer::getVRDEProperty - + IVRDEServer::VRDEProperties @@ -5197,5 +5317,5 @@ been updated and made more generic. Because of that, VRDPAuthType enumeration has been - renamed to . + renamed to AuthType. @@ -5210,43 +5330,36 @@ - IMachine::getCpuProperty() is now ; - - - - IMachine::setCpuProperty() is now ; - - - - IMachine::getCpuIdLeaf() is now ; - - - - IMachine::setCpuIdLeaf() is now ; - - - - IMachine::removeCpuIdLeaf() is now ; - - - - IMachine::removeAllCpuIdLeafs() is now ; - - - - the CpuPropertyType enum is now . + IMachine::getCpuProperty() is now + IMachine::getCPUProperty(); + + + + IMachine::setCpuProperty() is now + IMachine::setCPUProperty(); + + + + IMachine::getCpuIdLeaf() is now + IMachine::getCPUIDLeaf(); + + + + IMachine::setCpuIdLeaf() is now + IMachine::setCPUIDLeaf(); + + + + IMachine::removeCpuIdLeaf() is now + IMachine::removeCPUIDLeaf(); + + + + IMachine::removeAllCpuIdLeafs() is now + IMachine::removeAllCPUIDLeaves(); + + + + the CpuPropertyType enum is now + CPUPropertyType. @@ -5259,11 +5372,9 @@ - When creating a VM configuration with it is now possible to - ignore existing configuration files which would previously have - caused a failure. For this the - override parameter was - added. + When creating a VM configuration with + IVirtualBox::createMachine() + it is now possible to ignore existing configuration files which would + previously have caused a failure. For this the + override parameter was added. @@ -5279,6 +5390,6 @@ The IoBackendType enumeration was replaced with a boolean flag - (see ). + (see + IStorageController::useHostIOCache). @@ -5292,16 +5403,13 @@ - - - - - - - - - + IMachine::readSavedThumbnailToArray() + + + + IMachine::querySavedScreenshotPNGSize() + + + + IMachine::readSavedScreenshotPNGToArray() @@ -5326,15 +5434,15 @@ attaching CD/DVD drives to arbitrary controllers), we seized the opportunity to rework all interfaces dealing with storage media to - make the API more flexible as well as logical. The , - , and, - interfaces were + make the API more flexible as well as logical. The + IStorageController, + IMedium, + IMediumAttachment and + IMachine interfaces were affected the most. Existing code using them to configure storage and media needs to be carefully checked. All media (hard disks, floppies and CDs/DVDs) are now - uniformly handled through the interface. The device-specific interfaces + uniformly handled through the IMedium + interface. The device-specific interfaces (IHardDisk, IDVDImage, IHostDVDDrive, IFloppyImage and @@ -5347,12 +5455,12 @@ IMachine::attachHardDisk and similar methods have been renamed and generalized to deal with any type of drive and - medium. is the API method for adding - any drive to a storage controller. The floppy and DVD/CD drives are - no longer handled specially, and that means you can have more than - one of them. As before, drives can only be changed while the VM is - powered off. Mounting (or unmounting) removable media at runtime is - possible with . + medium. + IMachine::attachDevice() + is the API method for adding any drive to a storage controller. The + floppy and DVD/CD drives are no longer handled specially, and that + means you can have more than one of them. As before, drives can only + be changed while the VM is powered off. Mounting (or unmounting) + removable media at runtime is possible with + IMachine::mountMedium(). Newly created virtual machines have no storage controllers @@ -5372,10 +5480,9 @@ - Reading the attribute no longer - automatically performs an accessibility check; a new method does this. The attribute only - returns the state any more. + Reading the + IMedium::state attribute no + longer automatically performs an accessibility check; a new method + IMedium::refreshState() + does this. The attribute only returns the state now. @@ -5387,5 +5494,6 @@ IConsole::discardCurrentState and IConsole::discardCurrentSnapshotAndState were removed; corresponding - new functionality is in IConsole::restoreSnapshot(). + new functionality is in + IConsole::restoreSnapshot(). Also, when IConsole::takeSnapshot() is called on a running virtual machine, a live snapshot will be @@ -5418,11 +5526,9 @@ modified: - - - - - + IHost::removeHostOnlyNetworkInterface() + + + + IHost::removeUSBDeviceFilter() @@ -5448,5 +5554,5 @@ casting is no longer needed to call methods from a parent class. In particular, IHardDisk and other classes now properly derive from - . + IMedium. @@ -5478,6 +5584,7 @@ - The type of changed from + The type of + IVirtualBoxErrorInfo::resultCode + changed from result to long. @@ -5495,6 +5602,6 @@ - The method IConsole::powerDownAsync was renamed to , + The method IConsole::powerDownAsync was renamed to + IConsole::powerDown, and the previous method with that name was deleted. So effectively a parameter was added. @@ -5502,7 +5609,7 @@ - In the interface, the following were - removed: + In the + IFramebuffer interface, the + following were removed: the operationSupported @@ -5527,5 +5634,5 @@ - In the + In the IDisplay interface, the following were removed: @@ -5640,12 +5747,11 @@ The HostNetworkInterfaceType enum has been renamed to - + HostNetworkInterfaceMediumType The IHostNetworkInterface::type attribute has been renamed - to + to + IHostNetworkInterface::mediumType @@ -5657,13 +5763,12 @@ In the IHost interface, createHostNetworkInterface() has - been renamed to + been renamed to + createHostOnlyNetworkInterface() Similarly, removeHostNetworkInterface() has been renamed - to + to + removeHostOnlyNetworkInterface() @@ -5707,17 +5812,16 @@ the back-end that is in use for a particular hard disk image. ISystemProperties::hardDiskFormats[] contains a list of all - back-ends supported by the system. contains - the default system format. - - - - In addition, the new interface is a generic interface for hard - disk, DVD and floppy images that contains the attributes and - methods shared between them. It can be considered a parent class - of the more specific interfaces for those images, which are now - IHardDisk2, IDVDImage2 and IFloppyImage2. + back-ends supported by the system. + ISystemProperties::defaultHardDiskFormat + contains the default system format. + + + + In addition, the new + IMedium interface is a generic + interface for hard disk, DVD and floppy images that contains the + attributes and methods shared between them. It can be considered + a parent class of the more specific interfaces for those images, + which are now IHardDisk2, IDVDImage2 and IFloppyImage2. In each case, the "2" versions of these interfaces replace @@ -5743,5 +5847,5 @@ - was + IGuestOSType was extended to group operating systems into families and for 64-bit support. @@ -5749,8 +5853,9 @@ - The interface was completely - rewritten to account for the changes in how Host Interface - Networking is now implemented in VirtualBox 2.1. + The + IHostNetworkInterface + interface was completely rewritten to account for the changes in how + Host Interface Networking is now implemented in VirtualBox + 2.1. @@ -5761,14 +5866,14 @@ - Added and + Added + IHost::getProcessorFeature() + and ProcessorFeature enumeration. - The parameter list for was modified. + The parameter list for + IVirtualBox::createMachine() + was modified. @@ -5778,16 +5883,16 @@ - New attributes in IMachine: , HWVirtExVPIDEnabled, - IMachine::guestPropertyNotificationPatterns, . - - - - Added and . + New attributes in IMachine: + accelerate3DEnabled, + HWVirtExVPIDEnabled, + IMachine::guestPropertyNotificationPatterns, + CPUCount. + + + + Added + IConsole::powerUpPaused() + and + IConsole::getGuestEnteredACPIMode(). Index: /trunk/doc/manual/xidl2docbook.xsl =================================================================== --- /trunk/doc/manual/xidl2docbook.xsl (revision 56531) +++ /trunk/doc/manual/xidl2docbook.xsl (revision 56532) @@ -6,5 +6,5 @@ VirtualBox.xidl. - Copyright (C) 2006-2012 Oracle Corporation + Copyright (C) 2006-2015 Oracle Corporation This file is part of VirtualBox Open Source Edition (OSE), as @@ -54,20 +54,18 @@ - - yes + - + - - yes + - + @@ -122,27 +120,26 @@ - + This interface is not supported in the web service. - + - With the web service, this interface is mapped to a structure. Attributes that return this interface will not return an object, but a complete structure - containing the attributes listed below as structure members. + With the web service, this interface is mapped to a structure. Attributes that return this interface will not return an object, but a complete structure + containing the attributes listed below as structure members. - This interface is supported in the web service only, not in COM/XPCOM. + This interface is supported in the web service only, not in COM/XPCOM. - + This interface extends - - yes + - + and therefore supports all its methods and attributes as well. - + @@ -181,7 +178,7 @@ - + This attribute is not supported in the web service. - + @@ -209,7 +206,7 @@ - + This method is not supported in the web service. - + @@ -256,7 +253,8 @@ - - - + + + + @@ -320,4 +318,7 @@ + + + @@ -398,5 +399,9 @@ + + + @@ -411,6 +416,5 @@ - - yes + @@ -493,5 +497,5 @@ - + @@ -502,7 +506,7 @@ - + - + @@ -545,5 +549,7 @@ - + + +