From fb123f93f9f5ce42c8e5785d2f8e0edaf951740e Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Wed, 26 Mar 2014 19:21:20 +0000 Subject: Imported from /home/lorry/working-area/delta_VirtualBox/VirtualBox-4.3.10.tar.bz2. --- doc/manual/en_US/SDKRef.xml | 776 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 599 insertions(+), 177 deletions(-) (limited to 'doc/manual/en_US/SDKRef.xml') diff --git a/doc/manual/en_US/SDKRef.xml b/doc/manual/en_US/SDKRef.xml index 40e1559f..e8c63cc3 100644 --- a/doc/manual/en_US/SDKRef.xml +++ b/doc/manual/en_US/SDKRef.xml @@ -308,7 +308,7 @@ user1, it will see and manipulate the virtual machines and other data represented by the VirtualBox data of that user (for example, on a Linux machine, under - /home/user1/.VirtualBox; see the + /home/user1/.config/VirtualBox; see the VirtualBox User Manual for details on where this data is stored). @@ -1542,7 +1542,7 @@ for m in mgr.getArray(vbox, 'machines'): print "Machine '%s' logs in '%s'" %(m.name, m.logFolder) - Code above demonstartes cross-platform access to array properties + Code above demonstrates cross-platform access to array properties (certain limitations prevent one from using vbox.machines to access a list of available virtual machines in case of XPCOM), and a mechanism of @@ -1718,157 +1718,210 @@ print "Machine '%s' logs in '%s'" %(m.name, m.logFolder) - C binding to XPCOM API + C binding to VirtualBox API - - This section currently applies to Linux hosts only. - + The VirtualBox API originally is designed as object oriented, + using XPCOM or COM as the middleware, which translates natively to C++. + This means that in order to use it from C there needs to be some + helper code to bridge the language differences and reduce the + differences between platforms. - Starting with version 2.2, VirtualBox offers a C binding for the - XPCOM API. + + Cross-platform C binding to VirtualBox API - The C binding provides a layer enabling object creation, method - invocation and attribute access from C. + Starting with version 4.3, VirtualBox offers a C binding + which allows using the same C client sources for all platforms, + covering Windows, Linux, Mac OS X and Solaris. It is the + preferred way to write API clients, even though the old style + is still available. + + Getting started - The following sections describe how to use the C binding in a - C program. - - For Linux, a sample program is provided which demonstrates use - of the C binding to initialize XPCOM, get handles for VirtualBox and - Session objects, make calls to list and start virtual machines, and - uninitialize resources when done. The program uses the VBoxGlue - library to open the C binding layer during runtime. - - The sample program - tstXPCOMCGlue is located in the bin - directory and can be run without arguments. It lists registered - machines on the host along with some additional information and ask - for a machine to start. The source for this program is available in - sdk/bindings/xpcom/cbinding/samples/ - directory. The source for the VBoxGlue library is available in the - sdk/bindings/xpcom/cbinding/ - directory. + The following sections describe how to use the VirtualBox API + in a C program. The necessary files are included in the SDK, in the + directories sdk/bindings/c/include + and sdk/bindings/c/glue. + + As part of the SDK, a sample program + tstCAPIGlue.c is provided in the + directory sdk/bindings/c/samples + which demonstrates + using the C binding to initialize the API, get handles for + VirtualBox and Session objects, make calls to list and start virtual + machines, monitor events, and uninitialize resources when done. The + sample program is trying to illustrate all relevant concepts, so it + is a great source of detail information. Among many other generally + useful code sequences it contains a function which shows how to + retrieve error details in C code if they are available from the API + call. + + The sample program tstCAPIGlue + can be built using the provided Makefile + and can be run without arguments. + + It uses the VBoxCAPIGlue library (source code is in directory + sdk/bindings/c/glue, to be used in + your API client code) to open the C binding layer during runtime, + which is preferred to other means as it isolates the code which + locates the necessary dynamic library, using a known working way + which works on all platforms. If you encounter problems with this + glue code in VBoxCAPIGlue.c, let the + VirtualBox developers know, rather than inventing incompatible + solutions. + + The following sections document the important concepts needed + to correctly use the C binding, as it is vital for developing API + client code which manages memory correctly, updates the reference + counters correctly, avoiding crashes and memory leaks. Often API + clients need to handle events, so the C API specifics are also + described below. - XPCOM initialization - - Just like in C++, XPCOM needs to be initialized before it can - be used. The VBoxCAPI_v2_5.h header - provides the interface to the C binding. Here's how to initialize - XPCOM: - - #include "VBoxCAPI_v2_5.h" + VirtualBox C API initialization + + Just like in C++, the API and the underlying middleware needs + to be initialized before it can be used. The + VBoxCAPI_v4_3.h header provides the + interface to the C binding, but you can alternatively and more + 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 + pointer to the structure which contains the helper function pointers. + Here's how to initialize the C API:#include "VBoxCAPIGlue.h" ... -PCVBOXXPCOM g_pVBoxFuncs = NULL; -IVirtualBox *vbox = NULL; -ISession *session = NULL; +IVirtualBoxClient *vboxclient = NULL; +IVirtualBox *vbox = NULL; +ISession *session = NULL; +HRESULT rc; +ULONG revision; /* - * VBoxGetXPCOMCFunctions() is the only function exported by - * VBoxXPCOMC.so and the only one needed to make virtualbox - * work with C. This functions gives you the pointer to the - * function table (g_pVBoxFuncs). + * VBoxCGlueInit() loads the necessary dynamic library, handles errors + * (producing an error message hinting what went wrong) and gives you + * the pointer to the function table (g_pVBoxFuncs). * * Once you get the function table, then how and which functions * to use is explained below. * - * g_pVBoxFuncs->pfnComInitialize does all the necessary startup - * action and provides us with pointers to vbox and session handles. - * It should be matched by a call to g_pVBoxFuncs->pfnComUninitialize() + * g_pVBoxFuncs->pfnClientInitialize does all the necessary startup + * action and provides us with pointers to an IVirtualBoxClient instance. + * It should be matched by a call to g_pVBoxFuncs->pfnClientUninitialize() * when done. */ -g_pVBoxFuncs = VBoxGetXPCOMCFunctions(VBOX_XPCOMC_VERSION); -g_pVBoxFuncs->pfnComInitialize(&vbox, &session); - - If either vbox or - session is still - NULL, initialization failed and the - XPCOM API cannot be used. +if (VBoxCGlueInit()) +{ + fprintf(stderr, "s: FATAL: VBoxCGlueInit failed: %s\n", + argv[0], g_szVBoxErrMsg); + return EXIT_FAILURE; +} + +g_pVBoxFuncs->pfnClientInitialize(NULL, &vboxclient); +if (!vboxclient) +{ + fprintf(stderr, "%s: FATAL: could not get VirtualBoxClient reference\n", + argv[0]); + return EXIT_FAILURE; +} + + If vboxclient is still + NULL this means the initializationi + failed and the VirtualBox C API cannot be used. + + It is possible to write C applications using multiple threads + which all use the VirtualBox API, as long as you're initializing + the C API in each thread which your application creates. This is done + with g_pVBoxFuncs->pfnClientThreadInitialize() and + likewise before the thread is terminated the API must be + uninitialized with + g_pVBoxFuncs->pfnClientThreadUninitialize(). You don't + have to use these functions in worker threads created by COM/XPCOM + (which you might observe if your code uses active event handling), + everything is initialized correctly already. On Windows the C + bindings create a marshaller which supports a wide range of COM + threading models, from STA to MTA, so you don't have to worry about + these details unless you plan to use active event handlers. See + the sample code how to get this to work reliably (in other words + think twice if passive event handling isn't the better solution after + you looked at the sample code). - XPCOM method invocation + C API attribute and method invocation Method invocation is straightforward. It looks pretty much - like the C++ way, augmented with an extra indirection due to - accessing the vtable and passing a pointer to the object as the - first argument to serve as the this - pointer. + like the C++ way, by using a macro which internally accesses the + vtable, and additionally needs to be passed a pointer to the objecti + as the first argument to serve as the + this pointer. Using the C binding, all method invocations return a numeric - result code. + result code of type HRESULT (with a few exceptions + which normally are not relevant). If an interface is specified as returning an object, a pointer to a pointer to the appropriate object must be passed as the last argument. The method will then store an object pointer in that location. - In other words, to call an object's method what you need - is + Likewise, attributes (properties) can be queried or set using + method invocations, using specially named methods. For each + attribute there exists a getter method, the name of which is composed + of get_ followed by the capitalized + attribute name. Unless the attribute is read-only, an analogous + set_ method exists. Let's apply + these rules to get the IVirtualBox + reference, an ISession instance + reference and read the attribute:rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &vbox); +if (FAILED(rc) || !vbox) +{ + PrintErrorInfo(argv[0], "FATAL: could not get VirtualBox reference", rc); + return EXIT_FAILURE; +} +rc = IVirtualBoxClient_get_Session(vboxclient, &session); +if (FAILED(rc) || !session) +{ + PrintErrorInfo(argv[0], "FATAL: could not get Session reference", rc); + return EXIT_FAILURE; +} - IObject *object; -nsresult rc; -... -/* - * Calling void IObject::method(arg, ...) - */ -rc = object->vtbl->Method(object, arg, ...); +rc = IVirtualBox_get_Revision(vbox, &revision); +if (SUCCEEDED(rc)) +{ + printf("Revision: %u\n", revision); +} + The convenience macros for calling a method are named by + prepending the method name with the interface name (using + _as the separator). + + So far only attribute getters were illustrated, but generic + method calls are straightforward, too:IMachine *machine = NULL; +BSTR vmname = ...; ... -IFoo *foo; /* - * Calling IFoo IObject::method(arg, ...) + * Calling IMachine::findMachine(...) */ -rc = object->vtbl->Method(object, args, ..., &foo); +rc = IVirtualBox_FindMachine(vbox, vmname, &machine); - As a real-world example of a method invocation, let's call - 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; + capitalized:IProgress *progress; ... -rc = vbox->vtbl->LaunchVMProcess( +rc = IMachine_LaunchVMProcess( machine, /* this */ session, /* arg 1 */ sessionType, /* arg 2 */ env, /* arg 3 */ &progress /* Out */ -); - - - - - XPCOM attribute access - - A construct similar to calling non-void methods is used to - access object attributes. For each attribute there exists a getter - method, the name of which is composed of - Get followed by the capitalized - attribute name. Unless the attribute is read-only, an analogous - Set method exists. Let's apply - these rules to read the attribute. - - Using the IVirtualBox handle - vbox obtained above, calling its - GetRevision method looks like - this: - - PRUint32 rev; - -rc = vbox->vtbl->GetRevision(vbox, &rev); -if (NS_SUCCEEDED(rc)) -{ - printf("Revision: %u\n", (unsigned)rev); -} - +); All objects with their methods and attributes are documented in . @@ -1880,65 +1933,173 @@ if (NS_SUCCEEDED(rc)) When dealing with strings you have to be aware of a string's encoding and ownership. - Internally, XPCOM uses UTF-16 encoded strings. A set of + Internally, the API uses UTF-16 encoded strings. A set of conversion functions is provided to convert other encodings to and from UTF-16. The type of a UTF-16 character is - PRUnichar. Strings of UTF-16 - characters are arrays of that type. Most string handling functions - take pointers to that type. Prototypes for the following conversion - functions are declared in - VBoxCAPI_v2_5.h. - - - Conversion of UTF-16 to and from UTF-8 - - int (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString); -int (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString); - - + BSTR (or its constant counterpart + CBSTR), which is an array type, + 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); +int (*pfnUtf8ToUtf16)(const char *pszString, BSTR *ppwszString); + + The ownership of a string determines who is responsible for + releasing resources associated with the string. Whenever the API + creates a string (essentially for output parameters), ownership is + transferred to the caller. To avoid resource leaks, the caller + should release resources once the string is no longer needed. + There are plenty of examples in the sample code. + + + + Array handling + + Arrays are handled somewhat similarly to strings, with the + additional information of the number of elements in the array. The + exact details of string passing depends on the platform middleware + (COM/XPCOM), and therefore the C binding offers helper functions to + gloss over these differences. + + 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 }; +ULONG cElements = sizeof(aElements) / sizeof(aElements[0]); +SAFEARRAY *psa = NULL; +psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_I4, 0, cElements); +g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, aElements, sizeof(aElements)); +IArrayDemo_PassArray(pThis, ComSafeArrayAsInParam(psa)); +g_pVBoxFuncs->pfnSafeArrayDestroy(psa); + + 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(); +ULONG *pData; +ULONG cElements; +IArrayDemo_ReturnArray(pThis, ComSafeArrayAsOutParam(psa)); +g_pVBoxFuncs->pfnSafeArrayCopyOutParamHelper((void **)&pData, &cElements, VT_I4, psa); +g_pVBoxFuncs->pfnSafeArrayDestroy(psa); + + This covers the necessary functionality for all array element + types except interface references. These need special helpers to + manage the reference counting correctly. The following code snippet + 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(); +IMachine **machines = NULL; +ULONG machineCnt = 0; +ULONG i; +IVirtualBox_get_Machines(virtualBox, ComSafeArrayAsOutIfaceParam(machinesSA, IMachine *)); +g_pVBoxFuncs->pfnSafeArrayCopyOutIfaceParamHelper((IUnknown ***)&machines, &machineCnt, machinesSA); +g_pVBoxFuncs->pfnSafeArrayDestroy(machinesSA); +/* Now "machines" contains the IMachine references, and machineCnt the + * number of elements in the array. */ +... +SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_IUNKNOWN, 0, 1); +g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, (void *)&machines[0], sizeof(machines[0])); +IVirtualBox_GetMachineStates(ComSafeArrayAsInParam(psa), ...); +... +g_pVBoxFuncs->pfnSafeArrayDestroy(psa); +for (i = 0; i < machineCnt; ++i) +{ + IMachine *machine = machines[i]; + IMachine_Release(machine); +} +free(machines); - - Ownership + Handling output parameters needs more special effort than + input parameters, thus only for the former there are special helpers, + and the latter is handled through the generic array support. + - The ownership of a string determines who is responsible for - releasing resources associated with the string. Whenever XPCOM - creates a string, ownership is transferred to the caller. To avoid - resource leaks, the caller should release resources once the - string is no longer needed. - + + Event handling + + The VirtualBox API offers two types of event handling, active + and passive, and consequently there is support for both with the + C API binding. Active event handling (based on asynchronous + callback invocation for event delivery) is more difficult, as it + requires the construction of valid C++ objects in C, which is + inherently platform and compiler dependent. Passive event handling + is much simpler, it relies on an event loop, fetching events and + triggering the necessary handlers explicitly in the API client code. + Both approaches depend on an event loop to make sure that events + get delivered in a timely manner, with differences what exactly needs + to be done. + + The C API sample contains code for both event handling styles, + and one has to modify the appropriate #define to select + which style is actually used by the compiled program. It allows a + good comparison between the two variants, and the code sequences are + probably worth reusing without much change in other API clients + with only minor adaptions. + + Active event handling needs to ensure that the following helper + function is called frequently enough in the primary thread: + g_pVBoxFuncs->pfnProcessEventQueue(cTimeoutMS); + + 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. + + Passive event handling uses a similar event loop structure, + which requires calling the following function in a loop, and + processing the returned event appropriately: + rc = IEventSource_GetEvent(pEventSource, pListener, cTimeoutMS, &pEvent); + + After processing the event it needs to be marked as processed + with the following method call: + rc = IEventSource_EventProcessed(pEventSource, pListener, pEvent); + + This is vital for vetoable events, as they would be stuck + otherwise, waiting whether the veto comes or not. It does not do any + harm for other event types, and in the end is cheaper than checking + if the event at hand is vetoable or not. + + The general event handling concepts are described in the API + 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. - XPCOM uninitialization + C API uninitialization Uninitialization is performed by - g_pVBoxFuncs->pfnComUninitialize(). + g_pVBoxFuncs->pfnClientUninitialize(). If your program can exit from more than one place, it is a good idea to install this function as an exit handler with Standard C's atexit() just after calling - g_pVBoxFuncs->pfnComInitialize() + g_pVBoxFuncs->pfnClientInitialize() , e.g. #include <stdlib.h> #include <stdio.h> ... /* - * Make sure g_pVBoxFuncs->pfnComUninitialize() is called at exit, no + * Make sure g_pVBoxFuncs->pfnClientUninitialize() is called at exit, no * matter if we return from the initial call to main or call exit() * somewhere else. Note that atexit registered functions are not * called upon abnormal termination, i.e. when calling abort() or - * signal(). Separate provisions must be taken for these cases. + * signal(). */ -if (atexit(g_pVBoxFuncs->pfnComUninitialize()) != 0) { - fprintf(stderr, "failed to register g_pVBoxFuncs->pfnComUninitialize()\n"); +if (atexit(g_pVBoxFuncs->pfnClientUninitialize()) != 0) { + fprintf(stderr, "failed to register g_pVBoxFuncs->pfnClientUninitialize()\n"); exit(EXIT_FAILURE); -} - +} Another idea would be to write your own void myexit(int status) function, calling - g_pVBoxFuncs->pfnComUninitialize() + g_pVBoxFuncs->pfnClientUninitialize() followed by the real exit(), and use it instead of exit() throughout your program and at the end of @@ -1948,15 +2109,14 @@ if (atexit(g_pVBoxFuncs->pfnComUninitialize()) != 0) { user types CTRL-C sending SIGINT) you might want to install a signal handler setting a flag noting that a signal was sent and then calling - g_pVBoxFuncs->pfnComUninitialize() - later on (usually not from the handler itself - .) + g_pVBoxFuncs->pfnClientUninitialize() + later on, not from the handler itself. That said, if a client program forgets to call - g_pVBoxFuncs->pfnComUninitialize() + g_pVBoxFuncs->pfnClientUninitialize() before it terminates, there is a mechanism in place which will - eventually release references held by the client. You should not - rely on this, however. + eventually release references held by the client. On Windows it can + take quite a while, in the order of 6-7 minutes. @@ -1964,27 +2124,101 @@ if (atexit(g_pVBoxFuncs->pfnComUninitialize()) != 0) { A program using the C binding has to open the library during runtime using the help of glue code provided and as shown in the - example tstXPCOMCGlue.c. - Compilation and linking can be achieved, e.g., with a makefile - fragment similar to - - # Where is the XPCOM include directory? -INCS_XPCOM = -I../../include -# Where is the glue code directory? -GLUE_DIR = .. -GLUE_INC = -I.. - -#Compile Glue Library -VBoxXPCOMCGlue.o: $(GLUE_DIR)/VBoxXPCOMCGlue.c - $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $< - -# Compile. -program.o: program.c VBoxCAPI_v2_5.h - $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $< - -# Link. -program: program.o VBoxXPCOMCGlue.o - $(CC) -o $@ $^ -ldl + example tstCAPIGlue.c. + Compilation and linking can be achieved with a makefile fragment + similar to:# Where is the SDK directory? +PATH_SDK = ../../.. +CAPI_INC = -I$(PATH_SDK)/bindings/c/include +ifeq ($(BUILD_PLATFORM),win) +PLATFORM_INC = -I$(PATH_SDK)/bindings/mscom/include +PLATFORM_LIB = $(PATH_SDK)/bindings/mscom/lib +else +PLATFORM_INC = -I$(PATH_SDK)/bindings/xpcom/include +PLATFORM_LIB = $(PATH_SDK)/bindings/xpcom/lib +endif +GLUE_DIR = $(PATH_SDK)/bindings/c/glue +GLUE_INC = -I$(GLUE_DIR) + +# Compile Glue Library +VBoxCAPIGlue.o: $(GLUE_DIR)/VBoxCAPIGlue.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Compile interface ID list +VirtualBox_i.o: $(PLATFORM_LIB)/VirtualBox_i.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Compile program code +program.o: program.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Link program. +program: program.o VBoxCAPICGlue.o VirtualBox_i.o + $(CC) -o $@ $^ -ldl -lpthread + + + + Conversion of code using legacy C binding + + This section aims to make the task of converting code using + the legacy C binding to the new style a breeze, by pointing out some + key steps. + + One necessary change is adjusting your Makefile to reflect the + different include paths. See above. There are now 3 relevant include + directories, and most of it is pointing to the C binding directory. + The XPCOM include directory is still relevant for platforms where + the XPCOM middleware is used, but most of the include files live + elsewhere now, so it's good to have it last. Additionally the + VirtualBox_i.c file needs to be + compiled and linked to the program, it contains the IIDs relevant + for the VirtualBox API, making sure they are not replicated endlessly + if the code refers to them frequently. + + 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. + + All API method calls (anything mentioning vtbl) + should be rewritten using the convenience macros for calling methods, + as these hide the internal details, are generally easier to use and + shorter to type. You should remove as many as possible + (nsISupports **) or similar typecasts, as the new style + should use the correct type in most places, increasing the type + safety in case of an error in the source code. + + To gloss over the platform differences, API client code should + no longer rely on XPCOM specific interface names such as + nsISupports, nsIException and + nsIEventQueue, and replace them by the platform + independent interface names IUnknown and + IErrorInfo for the first two respectively. Event queue + handling should be replaced by using the platform independent way + described in . + + Finally adjust the string and array handling to use the new + helpers, as these make sure the code works without changes with + both COM and XPCOM, which are significantly different in this area. + The code should be double checked if it uses the correct way to + manage memory, and is freeing it only after the last use. + + + + Legacy C binding to VirtualBox API for XPCOM + + + This section applies to Linux, Mac OS X and Solaris + hosts only and describes deprecated use of the API from C. + + + Starting with version 2.2, VirtualBox offers a C binding for + its API which works only on platforms using XPCOM. Refer to the + old SDK documentation (included in the SDK packages for version 4.3.6 + or earlier), it still applies unchanged. The fundamental concepts are + similar (but the syntactical details are quite different) to the + newer cross-platform C binding which should be used for all new code, + as the support for the old C binding will go away in a major release + after version 4.3. @@ -2133,7 +2367,7 @@ if (prog.getResultCode() != 0) // check success stopped, snapshotted or other things. - + VirtualBox events In VirtualBox, "events" provide a uniform mechanism to register @@ -2216,8 +2450,8 @@ es.unregisterListener(listener); three COM/XPCOM/WS styles of the API. You can easily extend this shell with your own commands. Create a - subdirectory named .VirtualBox/shexts - below your home directory and put a Python file implementing your shell + 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: @@ -2245,7 +2479,7 @@ es.unregisterListener(listener); # Call VirtualBox API, using context's fields hdd = ctx['vb'].createHardDisk(format, loc) # Access constants using ctx['global'].constants - progress = hdd.createBaseStorage(size, ctx['global'].constants.HardDiskVariant_Standard) + progress = hdd.createBaseStorage(size, (ctx['global'].constants.MediumVariant_Standard, )) # use standard progress bar mechanism ctx['progressBar'](progress) @@ -2266,7 +2500,7 @@ es.unregisterListener(listener); } Just store the above text in the file createHdd (or any other meaningful name) - in .VirtualBox/shexts/. Start the + in .config/VirtualBox/shexts/. Start the VirtualBox shell, or just issue the reloadExts command, if the shell is already running. Your new command will now be available. @@ -3447,7 +3681,7 @@ AuthResult AUTHCALL AuthEntry( setup phase (see ws variable). In the SOAP case it's possible to create several VirtualBoxManager instances to communicate with multiple VirtualBox hosts. - import org.virtualbox_3_3.*; + import org.virtualbox_4_3.*; .... VirtualBoxManager mgr = VirtualBoxManager.createInstance(null); boolean ws = false; // or true, if we need the SOAP version @@ -3472,7 +3706,8 @@ AuthResult AUTHCALL AuthEntry( mgr.cleanup(); For more a complete example, see TestVBox.java, shipped with the - SDK. + SDK. It contains exception handling and error printing code, which + is important for reliable larger scale projects. @@ -3524,6 +3759,194 @@ AuthResult AUTHCALL AuthEntry( interfaces, methods or attributes or other changes that do not affect existing client code. + + Incompatible API changes with version 4.3 + + + + The explicit medium locking methods + + and + 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. + + + + IMachine::delete + has been renamed to , 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. + + + + Medium management APIs were changed as follows: + + + The type of attribute + + 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. + + + + + 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 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. + + + + + 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 + to query the current guest session status. + + + + The + APIs are now implemented to provide native guest file access from + the host. + + + + 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 + enum are 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. + + + + IDisplay::getScreenResolution + has been extended to return the display position in the guest. + + + + + 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 . + + + + + Incompatible API changes with version 4.2 @@ -3785,7 +4208,7 @@ AuthResult AUTHCALL AuthEntry( IUSBController::enabledEhci - + IUSBController::enabledEHCI" INATEngine::tftpPrefix @@ -3837,7 +4260,6 @@ AuthResult AUTHCALL AuthEntry( - Incompatible API changes with version 4.1 @@ -4156,8 +4578,8 @@ AuthResult AUTHCALL AuthEntry( The appliance (OVF) APIs were enhanced as follows: - received an extra parameter + IMachine::export + received an extra parameter location, which is used to decide for the disk naming. @@ -4466,7 +4888,7 @@ AuthResult AUTHCALL AuthEntry( Reading the attribute no longer + xreflabel="IMedium::state" /> attribute no longer automatically performs an accessibility check; a new method does this. The attribute only -- cgit v1.2.1