Changeset 49539 in vbox

Timestamp:

Nov 18, 2013 4:52:10 PM (11 years ago)

Author:

vboxsync

Message:

Main/cbinding: lots of love and care for this long forgotten part of the code, make it easier to use and more functional (error handling, initialization), and clean up and extend the sample code. It now includes the event sample, no need to keep so much redundant code.

Location:

trunk/src/VBox/Main/cbinding

Files:

• Makefile.kmk (modified) (2 diffs)
• VBoxXPCOMC.cpp (modified) (13 diffs)
• VBoxXPCOMCGlue.c (modified) (3 diffs)
• makefile.tstXPCOMCGlue (modified) (2 diffs)
• tstXPCOMCEvent.c (deleted)
• tstXPCOMCGlue.c (modified) (21 diffs)
• xpcidl.xsl (modified) (3 diffs)

trunk/src/VBox/Main/cbinding/Makefile.kmk

@@ -30 +30 @@
 XpComCSamples_SOURCES = \
         tstXPCOMCGlue.c \
-        tstXPCOMCEvent.c \
         makefile.tstXPCOMCGlue=>Makefile
 
@@ -119 +118 @@
   tstXPCOMCGlue_LIBS = \
         $(VBoxXPCOMCGlue_1_TARGET)
-
-  #
-  # The event listener testcase.
-  #
-  PROGRAMS += tstXPCOMCEvent
-  tstXPCOMCEvent_TEMPLATE = VBOXR3TSTEXE
-  tstXPCOMCEvent_INCS = \
-        $(VBOX_PATH_SDK)/bindings/xpcom/include \
-        $(VBOX_PATH_SDK)/bindings/xpcom/cbinding
-  tstXPCOMCEvent_INTERMEDIATES = \
-        $(VBOX_PATH_SDK)/bindings/xpcom/cbinding/VBoxXPCOMCGlue.h \
-        $(VBOX_PATH_SDK)/bindings/xpcom/include/VBoxCAPI_v$(VBOX_API_VERSION).h
-  tstXPCOMCEvent_SOURCES = \
-        tstXPCOMCEvent.c
-  tstXPCOMCEvent_LIBS = \
-        $(VBoxXPCOMCGlue_1_TARGET)
  endif
 

trunk/src/VBox/Main/cbinding/VBoxXPCOMC.cpp

@@ -5 +5 @@
 
 /*
- * Copyright (C) 2009-2012 Oracle Corporation
+ * Copyright (C) 2009-2013 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -20 +20 @@
 #include <nsIServiceManager.h>
 #include <nsEventQueueUtils.h>
+#include <nsIExceptionService.h>
 
 #include <iprt/string.h>
@@ -31 +32 @@
 using namespace std;
 
-static ISession            *Session        = NULL;
-static IVirtualBox         *Ivirtualbox    = NULL;
-static nsIComponentManager *manager        = NULL;
-static nsIEventQueue       *eventQ         = NULL;
+/* The following 3 object references should be eliminated once the legacy
+ * way to initialize the XPCOM C bindings is removed. */
+static ISession            *g_Session           = NULL;
+static IVirtualBox         *g_VirtualBox        = NULL;
+static nsIComponentManager *g_Manager           = NULL;
+
+static nsIEventQueue       *g_EventQueue        = NULL;
 
 static void VBoxComUninitialize(void);
+static void VBoxClientUninitialize(void);
 
 static int
@@ -66 +71 @@
 {
     if (ptr)
-    {
         nsMemory::Free(ptr);
-    }
 }
 
@@ -94 +97 @@
     }
 
-    rc = NS_GetComponentManager (&manager);
+    rc = NS_GetComponentManager(&g_Manager);
     if (NS_FAILED(rc))
     {
@@ -102 +105 @@
     }
 
-    rc = NS_GetMainEventQ (&eventQ);
+    rc = NS_GetMainEventQ(&g_EventQueue);
     if (NS_FAILED(rc))
     {
@@ -110 +113 @@
     }
 
-    rc = manager->CreateInstanceByContractID(NS_VIRTUALBOX_CONTRACTID,
-                                             nsnull,
-                                             virtualBoxIID,
-                                             (void **)ppVirtualBox);
+    rc = g_Manager->CreateInstanceByContractID(NS_VIRTUALBOX_CONTRACTID,
+                                               nsnull,
+                                               virtualBoxIID,
+                                               (void **)&g_VirtualBox);
     if (NS_FAILED(rc))
     {
@@ -123 +126 @@
     Log(("Cbinding: IVirtualBox object created.\n"));
 
-    rc = manager->CreateInstanceByContractID (NS_SESSION_CONTRACTID,
-                                              nsnull,
-                                              sessionIID,
-                                              (void **)ppSession);
+    rc = g_Manager->CreateInstanceByContractID(NS_SESSION_CONTRACTID,
+                                               nsnull,
+                                               sessionIID,
+                                               (void **)&g_Session);
     if (NS_FAILED(rc))
     {
@@ -136 +139 @@
     Log(("Cbinding: ISession object created.\n"));
 
-    /* Store ppSession & ppVirtualBox so that VBoxComUninitialize
-     * can later take care of them while cleanup
-     */
-    Session     = *ppSession;
-    Ivirtualbox = *ppVirtualBox;
-
+    *ppSession = g_Session;
+    *ppVirtualBox = g_VirtualBox;
 }
 
@@ -147 +146 @@
 VBoxComInitializeV1(IVirtualBox **ppVirtualBox, ISession **ppSession)
 {
-    /* stub that always fails. */
-    *ppVirtualBox = NULL;
-    *ppSession = NULL;
+    VBoxComInitialize(IVIRTUALBOX_IID_STR, ppVirtualBox,
+                      ISESSION_IID_STR, ppSession);
 }
 
@@ -155 +153 @@
 VBoxComUninitialize(void)
 {
-    if (Session)
-        NS_RELEASE(Session);        // decrement refcount
-    if (Ivirtualbox)
-        NS_RELEASE(Ivirtualbox);    // decrement refcount
-    if (eventQ)
-        NS_RELEASE(eventQ);         // decrement refcount
-    if (manager)
-        NS_RELEASE(manager);        // decrement refcount
+    if (g_Session)
+    {
+        NS_RELEASE(g_Session);
+        g_Session = NULL;
+    }
+    if (g_VirtualBox)
+    {
+        NS_RELEASE(g_VirtualBox);
+        g_VirtualBox = NULL;
+    }
+    if (g_EventQueue)
+    {
+        NS_RELEASE(g_EventQueue);
+        g_EventQueue = NULL;
+    }
+    if (g_Manager)
+    {
+        NS_RELEASE(g_Manager);
+        g_Manager = NULL;
+    }
     com::Shutdown();
-    Log(("Cbinding: Cleaned up the created IVirtualBox and ISession Objects.\n"));
-}
-
-static void
-VBoxGetEventQueue(nsIEventQueue **eventQueue)
-{
-    *eventQueue = eventQ;
-}
-
-static uint32_t
+    Log(("Cbinding: Cleaned up the created objects.\n"));
+}
+
+static void
+VBoxGetEventQueue(nsIEventQueue **ppEventQueue)
+{
+    *ppEventQueue = g_EventQueue;
+}
+
+static nsresult
+VBoxGetException(nsIException **ppException)
+{
+    nsresult rc;
+
+    *ppException = NULL;
+    nsIServiceManager *mgr = NULL;
+    rc = NS_GetServiceManager(&mgr);
+    if (NS_FAILED(rc) || !mgr)
+        return rc;
+
+    nsIID esid = NS_IEXCEPTIONSERVICE_IID;
+    nsIExceptionService *es = NULL;
+    rc = mgr->GetServiceByContractID(NS_EXCEPTIONSERVICE_CONTRACTID, esid, (void **)&es);
+    if (NS_FAILED(rc) || !es)
+    {
+        NS_RELEASE(mgr);
+        return rc;
+    }
+
+    nsIExceptionManager *em;
+    rc = es->GetCurrentExceptionManager(&em);
+    if (NS_FAILED(rc) || !em)
+    {
+        NS_RELEASE(es);
+        NS_RELEASE(mgr);
+        return rc;
+    }
+
+    nsIException *ex;
+    rc = em->GetCurrentException(&ex);
+    if (NS_FAILED(rc))
+    {
+        NS_RELEASE(em);
+        NS_RELEASE(es);
+        NS_RELEASE(mgr);
+        return rc;
+    }
+
+    *ppException = ex;
+    NS_RELEASE(em);
+    NS_RELEASE(es);
+    NS_RELEASE(mgr);
+    return rc;
+}
+
+static nsresult
+VBoxClearException(void)
+{
+    nsresult rc;
+
+    nsIServiceManager *mgr = NULL;
+    rc = NS_GetServiceManager(&mgr);
+    if (NS_FAILED(rc) || !mgr)
+        return rc;
+
+    nsIID esid = NS_IEXCEPTIONSERVICE_IID;
+    nsIExceptionService *es = NULL;
+    rc = mgr->GetServiceByContractID(NS_EXCEPTIONSERVICE_CONTRACTID, esid, (void **)&es);
+    if (NS_FAILED(rc) || !es)
+    {
+        NS_RELEASE(mgr);
+        return rc;
+    }
+
+    nsIExceptionManager *em;
+    rc = es->GetCurrentExceptionManager(&em);
+    if (NS_FAILED(rc) || !em)
+    {
+        NS_RELEASE(es);
+        NS_RELEASE(mgr);
+        return rc;
+    }
+
+    rc = em->SetCurrentException(NULL);
+    NS_RELEASE(em);
+    NS_RELEASE(es);
+    NS_RELEASE(mgr);
+    return rc;
+}
+
+static nsresult
+VBoxClientInitialize(const char *pszVirtualBoxClientIID, IVirtualBoxClient **ppVirtualBoxClient)
+{
+    nsresult rc;
+    nsID virtualBoxClientIID;
+    nsID sessionIID;
+
+    *ppVirtualBoxClient = NULL;
+
+    /* convert the string representation of UUID to nsIID type */
+    if (!virtualBoxClientIID.Parse(pszVirtualBoxClientIID))
+        return NS_ERROR_INVALID_ARG;
+
+    rc = com::Initialize();
+    if (NS_FAILED(rc))
+    {
+        Log(("Cbinding: XPCOM could not be initialized! rc=%Rhrc\n", rc));
+        VBoxClientUninitialize();
+        return rc;
+    }
+
+    nsIComponentManager *pManager;
+    rc = NS_GetComponentManager(&pManager);
+    if (NS_FAILED(rc))
+    {
+        Log(("Cbinding: Could not get component manager! rc=%Rhrc\n", rc));
+        VBoxClientUninitialize();
+        return rc;
+    }
+
+    rc = NS_GetMainEventQ(&g_EventQueue);
+    if (NS_FAILED(rc))
+    {
+        Log(("Cbinding: Could not get xpcom event queue! rc=%Rhrc\n", rc));
+        VBoxClientUninitialize();
+        return rc;
+    }
+
+    rc = pManager->CreateInstanceByContractID(NS_VIRTUALBOXCLIENT_CONTRACTID,
+                                              nsnull,
+                                              virtualBoxClientIID,
+                                              (void **)ppVirtualBoxClient);
+    if (NS_FAILED(rc))
+    {
+        Log(("Cbinding: Could not instantiate VirtualBoxClient object! rc=%Rhrc\n",rc));
+        VBoxClientUninitialize();
+        return rc;
+    }
+
+    NS_RELEASE(pManager);
+    pManager = NULL;
+
+    Log(("Cbinding: IVirtualBoxClient object created.\n"));
+
+    return NS_OK;
+}
+
+static void
+VBoxClientUninitialize(void)
+{
+    if (g_EventQueue)
+    {
+        NS_RELEASE(g_EventQueue);
+        g_EventQueue = NULL;
+    }
+    com::Shutdown();
+    Log(("Cbinding: Cleaned up the created objects.\n"));
+}
+
+static unsigned int
 VBoxVersion(void)
 {
-    uint32_t version = 0;
-
-    version = (VBOX_VERSION_MAJOR * 1000 * 1000) + (VBOX_VERSION_MINOR * 1000) + (VBOX_VERSION_BUILD);
-
-    return version;
+    return VBOX_VERSION_MAJOR * 1000 * 1000 + VBOX_VERSION_MINOR * 1000 + VBOX_VERSION_BUILD;
+}
+
+static unsigned int
+VBoxAPIVersion(void)
+{
+    return VBOX_VERSION_MAJOR * 1000 + VBOX_VERSION_MINOR + (VBOX_VERSION_BUILD > 50 ? 1 : 0);
 }
 
@@ -195 +357 @@
 
         VBoxVersion,
+        VBoxAPIVersion,
+
+        VBoxClientInitialize,
+        VBoxClientUninitialize,
+
+        VBoxComInitialize,
+        VBoxComUninitialize,
+
+        VBoxComUnallocMem,
+
+        VBoxUtf16ToUtf8,
+        VBoxUtf8ToUtf16,
+        VBoxUtf8Free,
+        VBoxUtf16Free,
+
+        VBoxGetEventQueue,
+        VBoxGetException,
+        VBoxClearException,
+
+        VBOX_XPCOMC_VERSION
+    };
+
+    if ((uVersion & 0xffff0000U) == (VBOX_XPCOMC_VERSION & 0xffff0000U))
+        return &s_Functions;
+
+    /*
+     * Legacy interface version 2.0.
+     */
+    static const struct VBOXXPCOMCV2
+    {
+        /** The size of the structure. */
+        unsigned cb;
+        /** The structure version. */
+        unsigned uVersion;
+
+        unsigned int (*pfnGetVersion)(void);
+
+        void  (*pfnComInitialize)(const char *pszVirtualBoxIID,
+                                  IVirtualBox **ppVirtualBox,
+                                  const char *pszSessionIID,
+                                  ISession **ppSession);
+
+        void  (*pfnComUninitialize)(void);
+
+        void  (*pfnComUnallocMem)(void *pv);
+        void  (*pfnUtf16Free)(PRUnichar *pwszString);
+        void  (*pfnUtf8Free)(char *pszString);
+
+        int   (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString);
+        int   (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString);
+
+        void  (*pfnGetEventQueue)(nsIEventQueue **ppEventQueue);
+
+        /** Tail version, same as uVersion. */
+        unsigned uEndVersion;
+    } s_Functions_v2_0 =
+    {
+        sizeof(s_Functions_v2_0),
+        0x00020000U,
+
+        VBoxVersion,
 
         VBoxComInitialize,
@@ -208 +431 @@
         VBoxGetEventQueue,
 
-        VBOX_XPCOMC_VERSION
+        0x00020000U
     };
 
-    if ((uVersion & 0xffff0000U) == (VBOX_XPCOMC_VERSION & 0xffff0000U))
-        return &s_Functions;
+    if ((uVersion & 0xffff0000U) == 0x00020000U)
+        return (PCVBOXXPCOM)&s_Functions_v2_0;
 
     /*

trunk/src/VBox/Main/cbinding/VBoxXPCOMCGlue.c

@@ -5 +5 @@
 
 /*
- * Copyright (C) 2008-2010 Oracle Corporation
+ * Copyright (C) 2008-2013 Oracle Corporation
  *
  * Permission is hereby granted, free of charge, to any person
@@ -38 +38 @@
 #include <stdint.h>
 #include <dlfcn.h>
+#include <pthread.h>
 
 #include "VBoxXPCOMCGlue.h"
@@ -68 +69 @@
 PFNVBOXGETXPCOMCFUNCTIONS g_pfnGetFunctions = NULL;
 
+typedef void FNDUMMY(void);
+typedef FNDUMMY *PFNDUMMY;
+/** Just a dummy global structure containing a bunch of
+ * function pointers to code which is wanted in the link.
+ * In this case this is for helping gdb as it gets hideously
+ * confused if the application doesn't drag in pthreads.
+ */
+PFNDUMMY g_apfnVBoxXPCOMCGlue[] =
+{
+    (PFNDUMMY)pthread_create
+};
+
 
 /**

trunk/src/VBox/Main/cbinding/makefile.tstXPCOMCGlue

@@ -1 +1 @@
 # $Revision$
-## @file makefile.tstLinuxC
+## @file makefile.tstXPCOMCGlue
 # Makefile for sample program illustrating use of C binding for XPCOM.
 #
@@ -24 +24 @@
 
 .PHONY: all
-all: tstXPCOMCGlue tstXPCOMCEvent
+all: tstXPCOMCGlue
 
 .PHONY: clean
 clean:
-        rm -f tstXPCOMCGlue.o tstXPCOMCGlue VBoxXPCOMCGlue.o tstXPCOMCEvent.o tstXPCOMCEvent
+        rm -f tstXPCOMCGlue.o tstXPCOMCGlue VBoxXPCOMCGlue.o
 
 tstXPCOMCGlue: tstXPCOMCGlue.o VBoxXPCOMCGlue.o
-        $(CC) -o $@ $^ -ldl
+        $(CC) -o $@ $^ -ldl -lpthread
 
 tstXPCOMCGlue.o: tstXPCOMCGlue.c
         $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<
 
-tstXPCOMCEvent: tstXPCOMCEvent.o VBoxXPCOMCGlue.o
-        $(CC) -o $@ $^ -ldl -lpthread
-
-tstXPCOMCEvent.o: tstXPCOMCEvent.c
-        $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<
-
 VBoxXPCOMCGlue.o: $(GLUE_DIR)/VBoxXPCOMCGlue.c
         $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<

trunk/src/VBox/Main/cbinding/tstXPCOMCGlue.c

@@ -1 +1 @@
 /* $Revision$ */
 /** @file tstXPCOMCGlue.c
- * Demonstrator program to illustrate use of C bindings of Main API.
+ * Demonstrator program to illustrate use of C bindings of Main API, including
+ * how to retrieve all available error information.
+ *
+ * This includes code which shows how to handle active event listeners
+ * (event delivery through callbacks), which is not so frequently seen in
+ * other samples which mostly use passive event listeners.
  *
  * Linux only at the moment due to shared library magic in the Makefile.
@@ -25 +30 @@
 #include <string.h>
 #include <stdlib.h>
+#include <unistd.h>
+#include <signal.h>
+#include <sys/poll.h>
+
+/*******************************************************************************
+*   Global Variables                                                           *
+*******************************************************************************/
+/** Set by signal handler. */
+static volatile int g_fStop = 0;
+
+static const char *GetStateName(PRUint32 machineState)
+{
+    switch (machineState)
+    {
+        case MachineState_Null:                return "<null>";
+        case MachineState_PoweredOff:          return "PoweredOff";
+        case MachineState_Saved:               return "Saved";
+        case MachineState_Teleported:          return "Teleported";
+        case MachineState_Aborted:             return "Aborted";
+        case MachineState_Running:             return "Running";
+        case MachineState_Paused:              return "Paused";
+        case MachineState_Stuck:               return "Stuck";
+        case MachineState_Teleporting:         return "Teleporting";
+        case MachineState_LiveSnapshotting:    return "LiveSnapshotting";
+        case MachineState_Starting:            return "Starting";
+        case MachineState_Stopping:            return "Stopping";
+        case MachineState_Saving:              return "Saving";
+        case MachineState_Restoring:           return "Restoring";
+        case MachineState_TeleportingPausedVM: return "TeleportingPausedVM";
+        case MachineState_TeleportingIn:       return "TeleportingIn";
+        case MachineState_FaultTolerantSyncing: return "FaultTolerantSyncing";
+        case MachineState_DeletingSnapshotOnline: return "DeletingSnapshotOnline";
+        case MachineState_DeletingSnapshotPaused: return "DeletingSnapshotPaused";
+        case MachineState_RestoringSnapshot:   return "RestoringSnapshot";
+        case MachineState_DeletingSnapshot:    return "DeletingSnapshot";
+        case MachineState_SettingUp:           return "SettingUp";
+        default:                               return "no idea";
+    }
+}
+
+struct IEventListenerDemo_vtbl
+{
+    struct IEventListener_vtbl ieventlistener;
+};
+
+typedef struct IEventListenerDemo
+{
+    struct IEventListenerDemo_vtbl *vtbl;
+
+    int refcount;
+} IEventListenerDemo;
 
 /**
- * Start a VM.
+ * Event handler function
+ */
+static nsresult IEventListenerDemo_HandleEvent(IEventListener *pThis, IEvent *event)
+{
+    enum VBoxEventType evType;
+    nsresult rc;
+
+    if (!event)
+    {
+        printf("event null\n");
+        return NS_OK;
+    }
+
+    evType = VBoxEventType_Invalid;
+    rc = event->vtbl->GetType(event, &evType);
+    if (NS_FAILED(rc))
+    {
+        printf("cannot get event type, rc=%#x\n", rc);
+        return NS_OK;
+    }
+
+    switch (evType)
+    {
+        case VBoxEventType_OnMousePointerShapeChanged:
+            printf("OnMousePointerShapeChanged\n");
+            break;
+
+        case VBoxEventType_OnMouseCapabilityChanged:
+            printf("OnMouseCapabilityChanged\n");
+            break;
+
+        case VBoxEventType_OnKeyboardLedsChanged:
+            printf("OnMouseCapabilityChanged\n");
+            break;
+
+        case VBoxEventType_OnStateChanged:
+        {
+            static const nsID istateChangedEventUUID = ISTATECHANGEDEVENT_IID;
+            IStateChangedEvent *ev = NULL;
+            enum MachineState state;
+            rc = event->vtbl->nsisupports.QueryInterface((nsISupports *)event, &istateChangedEventUUID, (void **)&ev);
+            if (NS_FAILED(rc))
+            {
+                printf("cannot get StateChangedEvent interface, rc=%#x\n", rc);
+                return NS_OK;
+            }
+            if (!ev)
+            {
+                printf("StateChangedEvent reference null\n");
+                return NS_OK;
+            }
+            rc = ev->vtbl->GetState(ev, &state);
+            if (NS_FAILED(rc))
+                printf("warning: cannot get state, rc=%#x\n", rc);
+            ev->vtbl->ievent.nsisupports.Release((nsISupports *)ev);
+            printf("OnStateChanged: %s\n", GetStateName(state));
+
+            fflush(stdout);
+            if (   state == MachineState_PoweredOff
+                || state == MachineState_Saved
+                || state == MachineState_Teleported
+                || state == MachineState_Aborted
+               )
+                g_fStop = 1;
+            break;
+        }
+
+        case VBoxEventType_OnAdditionsStateChanged:
+            printf("OnAdditionsStateChanged\n");
+            break;
+
+        case VBoxEventType_OnNetworkAdapterChanged:
+            printf("OnNetworkAdapterChanged\n");
+            break;
+
+        case VBoxEventType_OnSerialPortChanged:
+            printf("OnSerialPortChanged\n");
+            break;
+
+        case VBoxEventType_OnParallelPortChanged:
+            printf("OnParallelPortChanged\n");
+            break;
+
+        case VBoxEventType_OnStorageControllerChanged:
+            printf("OnStorageControllerChanged\n");
+            break;
+
+        case VBoxEventType_OnMediumChanged:
+            printf("OnMediumChanged\n");
+            break;
+
+        case VBoxEventType_OnVRDEServerChanged:
+            printf("OnVRDEServerChanged\n");
+            break;
+
+        case VBoxEventType_OnUSBControllerChanged:
+            printf("OnUSBControllerChanged\n");
+            break;
+
+        case VBoxEventType_OnUSBDeviceStateChanged:
+            printf("OnUSBDeviceStateChanged\n");
+            break;
+
+        case VBoxEventType_OnSharedFolderChanged:
+            printf("OnSharedFolderChanged\n");
+            break;
+
+        case VBoxEventType_OnRuntimeError:
+            printf("OnRuntimeError\n");
+            break;
+
+        case VBoxEventType_OnCanShowWindow:
+            printf("OnCanShowWindow\n");
+            break;
+        case VBoxEventType_OnShowWindow:
+            printf("OnShowWindow\n");
+            break;
+
+        default:
+            printf("unknown event: %d\n", evType);
+    }
+
+    return NS_OK;
+}
+
+static nsresult IEventListenerDemo_QueryInterface(nsISupports *pThis, const nsID *iid, void **resultp)
+{
+    static const nsID ieventListenerUUID = IEVENTLISTENER_IID;
+    static const nsID isupportIID = NS_ISUPPORTS_IID;
+
+    /* match iid */
+    if (    memcmp(iid, &ieventListenerUUID, sizeof(nsID)) == 0
+        ||  memcmp(iid, &isupportIID, sizeof(nsID)) == 0)
+    {
+        pThis->vtbl->AddRef(pThis);
+        *resultp = pThis;
+        return NS_OK;
+    }
+
+    return NS_NOINTERFACE;
+}
+
+static nsresult IEventListenerDemo_AddRef(nsISupports *pThis)
+{
+    return ++(((IEventListenerDemo *)pThis)->refcount);
+}
+
+static nsresult IEventListenerDemo_Release(nsISupports *pThis)
+{
+    nsresult c;
+
+    c = --(((IEventListenerDemo *)pThis)->refcount);
+    if (c == 0)
+        free(pThis);
+    return c;
+}
+
+struct IEventListenerDemo_vtbl_int_gcc
+{
+    ptrdiff_t offset_to_top;
+    void *typeinfo;
+    struct IEventListenerDemo_vtbl vtbl;
+};
+
+static struct IEventListenerDemo_vtbl_int_gcc g_IEventListenerDemo_vtbl_int_gcc =
+{
+    0,      /* offset_to_top */
+    NULL,   /* typeinfo, not vital */
+    {
+        {
+            {
+                IEventListenerDemo_QueryInterface,
+                IEventListenerDemo_AddRef,
+                IEventListenerDemo_Release
+            },
+            IEventListenerDemo_HandleEvent
+        }
+    }
+};
+
+/**
+ * Signal handler, terminate event listener.
+ *
+ * @param  iSig     The signal number (ignored).
+ */
+static void sigIntHandler(int iSig)
+{
+    (void)iSig;
+    g_fStop = 1;
+}
+
+/**
+ * Register event listener for the selected VM.
  *
  * @param   virtualBox ptr to IVirtualBox object
  * @param   session    ptr to ISession object
  * @param   id         identifies the machine to start
+ * @param   queue      handle to the event queue
  */
-static void startVM(IVirtualBox *virtualBox, ISession *session, PRUnichar *id)
+static void registerEventListener(IVirtualBox *virtualBox, ISession *session, PRUnichar *machineId, nsIEventQueue *queue)
+{
+    IConsole *console = NULL;
+    nsresult rc;
+
+    rc = session->vtbl->GetConsole(session, &console);
+    if ((NS_SUCCEEDED(rc)) && console)
+    {
+        IEventSource *es = NULL;
+        rc = console->vtbl->GetEventSource(console, &es);
+        if (NS_SUCCEEDED(rc) && es)
+        {
+            PRUint32 interestingEvents[] =
+                {
+                    VBoxEventType_OnMousePointerShapeChanged,
+                    VBoxEventType_OnMouseCapabilityChanged,
+                    VBoxEventType_OnKeyboardLedsChanged,
+                    VBoxEventType_OnStateChanged,
+                    VBoxEventType_OnAdditionsStateChanged,
+                    VBoxEventType_OnNetworkAdapterChanged,
+                    VBoxEventType_OnSerialPortChanged,
+                    VBoxEventType_OnParallelPortChanged,
+                    VBoxEventType_OnStorageControllerChanged,
+                    VBoxEventType_OnMediumChanged,
+                    VBoxEventType_OnVRDEServerChanged,
+                    VBoxEventType_OnUSBControllerChanged,
+                    VBoxEventType_OnUSBDeviceStateChanged,
+                    VBoxEventType_OnSharedFolderChanged,
+                    VBoxEventType_OnRuntimeError,
+                    VBoxEventType_OnCanShowWindow,
+                    VBoxEventType_OnShowWindow
+                };
+            IEventListenerDemo *consoleListener = NULL;
+            consoleListener = calloc(1, sizeof(IEventListenerDemo));
+            if (consoleListener)
+            {
+                consoleListener->vtbl = &(g_IEventListenerDemo_vtbl_int_gcc.vtbl);
+                consoleListener->vtbl->ieventlistener.nsisupports.AddRef((nsISupports *)consoleListener);
+
+                rc = es->vtbl->RegisterListener(es, (IEventListener *)consoleListener,
+                                                sizeof(interestingEvents) / sizeof(interestingEvents[0]),
+                                                interestingEvents, 1 /* active */);
+                if (NS_SUCCEEDED(rc))
+                {
+                    /* Just wait here for events, no easy way to do this better
+                     * as there's not much to do after this completes. */
+                    PRInt32 fd;
+                    int ret;
+                    printf("Entering event loop, PowerOff the machine to exit or press Ctrl-C to terminate\n");
+                    fflush(stdout);
+                    signal(SIGINT, sigIntHandler);
+
+                    fd = queue->vtbl->GetEventQueueSelectFD(queue);
+                    if (fd >= 0)
+                    {
+                        while (!g_fStop)
+                        {
+                            struct pollfd pfd;
+
+                            pfd.fd = fd;
+                            pfd.events = POLLIN | POLLERR | POLLHUP;
+                            pfd.revents = 0;
+
+                            ret = poll(&pfd, 1, 250);
+
+                            if (ret <= 0)
+                                continue;
+
+                            if (pfd.revents & POLLHUP)
+                                g_fStop = 1;
+
+                            queue->vtbl->ProcessPendingEvents(queue);
+                        }
+                    }
+                    else
+                    {
+                        while (!g_fStop)
+                        {
+                            PLEvent *pEvent = NULL;
+                            rc = queue->vtbl->WaitForEvent(queue, &pEvent);
+                            if (NS_SUCCEEDED(rc))
+                                queue->vtbl->HandleEvent(queue, pEvent);
+                        }
+                    }
+                    signal(SIGINT, SIG_DFL);
+                }
+                es->vtbl->UnregisterListener(es, (IEventListener *)consoleListener);
+                consoleListener->vtbl->ieventlistener.nsisupports.Release((nsISupports *)consoleListener);
+            }
+            else
+            {
+                printf("Failed while allocating memory for console event listener.\n");
+            }
+            es->vtbl->nsisupports.Release((nsISupports *)es);
+        }
+        console->vtbl->nsisupports.Release((nsISupports *)console);
+    }
+}
+
+/**
+ * Print detailed error information if available.
+ * @param   pszExecutable   string with the executable name
+ * @param   pszErrorMsg     string containing the code location specific error message
+ * @param   rc              XPCOM result code
+ */
+static void PrintErrorInfo(const char *pszExecutable, const char *pszErrorMsg, nsresult rc)
+{
+    nsIException *ex;
+    nsresult rc2 = NS_OK;
+    fprintf(stderr, "%s: %s (rc=%#010x)\n", pszExecutable, pszErrorMsg, (unsigned)rc);
+    rc2 = g_pVBoxFuncs->pfnGetException(&ex);
+    if (NS_SUCCEEDED(rc2))
+    {
+        static const nsID vbei = IVIRTUALBOXERRORINFO_IID;
+        IVirtualBoxErrorInfo *ei;
+        rc2 = ex->vtbl->nsisupports.QueryInterface((nsISupports *)ex, &vbei, (void **)&ei);
+        if (NS_FAILED(rc2))
+            ei = NULL;
+        if (ei)
+        {
+            /* got extended error info, maybe multiple infos */
+            do
+            {
+                PRInt32 resultCode = NS_OK;
+                PRUnichar *componentUtf16 = NULL;
+                char *component = NULL;
+                PRUnichar *textUtf16 = NULL;
+                char *text = NULL;
+                IVirtualBoxErrorInfo *ei_next = NULL;
+                fprintf(stderr, "Extended error info (IVirtualBoxErrorInfo):\n");
+
+                ei->vtbl->GetResultCode(ei, &resultCode);
+                fprintf(stderr, "  resultCode=%#010x\n", (unsigned)resultCode);
+
+                ei->vtbl->GetComponent(ei, &componentUtf16);
+                g_pVBoxFuncs->pfnUtf16ToUtf8(componentUtf16, &component);
+                g_pVBoxFuncs->pfnComUnallocMem(componentUtf16);
+                fprintf(stderr, "  component=%s\n", component);
+                g_pVBoxFuncs->pfnUtf8Free(component);
+
+                ei->vtbl->GetText(ei, &textUtf16);
+                g_pVBoxFuncs->pfnUtf16ToUtf8(textUtf16, &text);
+                g_pVBoxFuncs->pfnComUnallocMem(textUtf16);
+                fprintf(stderr, "  text=%s\n", text);
+                g_pVBoxFuncs->pfnUtf8Free(text);
+
+                rc2 = ei->vtbl->GetNext(ei, &ei_next);
+                if (NS_FAILED(rc2))
+                    ei_next = NULL;
+                ei->vtbl->nsiexception.nsisupports.Release((nsISupports *)ei);
+                ei = ei_next;
+            }
+            while (ei);
+        }
+        else
+        {
+            /* got basic error info */
+            nsresult resultCode = NS_OK;
+            PRUnichar *messageUtf16 = NULL;
+            char *message = NULL;
+            fprintf(stderr, "Basic error info (nsIException):\n");
+
+            ex->vtbl->GetResult(ex, &resultCode);
+            fprintf(stderr, "  resultCode=%#010x\n", resultCode);
+
+            ex->vtbl->GetMessage(ex, &messageUtf16);
+            g_pVBoxFuncs->pfnUtf16ToUtf8(messageUtf16, &message);
+            g_pVBoxFuncs->pfnComUnallocMem(messageUtf16);
+            fprintf(stderr, "  message=%s\n", message);
+            g_pVBoxFuncs->pfnUtf8Free(message);
+        }
+
+        ex->vtbl->nsisupports.Release((nsISupports *)ex);
+        g_pVBoxFuncs->pfnClearException();
+    }
+}
+
+/**
+ * Start a VM.
+ *
+ * @param   argv0       executable name
+ * @param   virtualBox  ptr to IVirtualBox object
+ * @param   session     ptr to ISession object
+ * @param   id          identifies the machine to start
+ * @param   queue       ptr to event queue
+ */
+static void startVM(const char *argv0, IVirtualBox *virtualBox, ISession *session, PRUnichar *id, nsIEventQueue *queue)
 {
     nsresult rc;
@@ -42 +477 @@
 
     rc = virtualBox->vtbl->FindMachine(virtualBox, id, &machine);
-
     if (NS_FAILED(rc) || !machine)
     {
-        fprintf(stderr, "Error: Couldn't get the machine handle.\n");
+        PrintErrorInfo(argv0, "Error: Couldn't get the Machine reference", rc);
         return;
     }
 
     g_pVBoxFuncs->pfnUtf8ToUtf16("gui", &sessionType);
-
     rc = machine->vtbl->LaunchVMProcess(machine,
         session,
@@ -57 +490 @@
         &progress
     );
-
     g_pVBoxFuncs->pfnUtf16Free(sessionType);
-
-    if (NS_FAILED(rc))
-    {
-        fprintf(stderr, "Error: OpenRemoteSession failed.\n");
-    }
-    else
+    if (NS_SUCCEEDED(rc))
     {
         PRBool completed;
@@ -74 +501 @@
         rc = progress->vtbl->GetCompleted(progress, &completed);
         if (NS_FAILED(rc))
-        {
-            fprintf (stderr, "Error: GetCompleted status failed.\n");
-        }
+            fprintf(stderr, "Error: GetCompleted status failed\n");
 
         progress->vtbl->GetResultCode(progress, &resultCode);
@@ -95 +520 @@
         else
         {
-            fprintf(stderr, "Remote session has been successfully opened.\n");
+            fprintf(stderr, "VM process has been successfully started\n");
+
+            /* Kick off the event listener demo part, which is quite separate.
+             * Ignore it if you need a more basic sample. */
+            registerEventListener(virtualBox, session, id, queue);
         }
         progress->vtbl->nsisupports.Release((nsISupports *)progress);
     }
+    else
+        PrintErrorInfo(argv0, "Error: LaunchVMProcess failed", rc);
 
     /* It's important to always release resources. */
@@ -107 +538 @@
  * List the registered VMs.
  *
- * @param   virtualBox ptr to IVirtualBox object
- * @param   session    ptr to ISession object
+ * @param   argv0       executable name
+ * @param   virtualBox  ptr to IVirtualBox object
+ * @param   session     ptr to ISession object
+ * @param   queue       ptr to event queue
  */
-static void listVMs(IVirtualBox *virtualBox, ISession *session)
+static void listVMs(const char *argv0, IVirtualBox *virtualBox, ISession *session, nsIEventQueue *queue)
 {
     nsresult rc;
@@ -125 +558 @@
     if (NS_FAILED(rc))
     {
-        fprintf(stderr, "could not get list of machines, rc=%08x\n",
-            (unsigned)rc);
+        PrintErrorInfo(argv0, "could not get list of machines", rc);
         return;
     }
@@ -164 +596 @@
             machine->vtbl->GetName(machine, &machineNameUtf16);
             g_pVBoxFuncs->pfnUtf16ToUtf8(machineNameUtf16,&machineName);
+            g_pVBoxFuncs->pfnComUnallocMem(machineNameUtf16);
             printf("\tName:        %s\n", machineName);
-
             g_pVBoxFuncs->pfnUtf8Free(machineName);
-            g_pVBoxFuncs->pfnComUnallocMem(machineNameUtf16);
         }
         else
@@ -175 +606 @@
 
         {
-            PRUnichar *uuidUtf16 = NULL;
-            char      *uuidUtf8  = NULL;
+            PRUnichar *uuidUtf16;
+            char      *uuidUtf8;
 
             machine->vtbl->GetId(machine, &uuidUtf16);
             g_pVBoxFuncs->pfnUtf16ToUtf8(uuidUtf16, &uuidUtf8);
+            g_pVBoxFuncs->pfnComUnallocMem(uuidUtf16);
             printf("\tUUID:        %s\n", uuidUtf8);
-
             g_pVBoxFuncs->pfnUtf8Free(uuidUtf8);
-            g_pVBoxFuncs->pfnUtf16Free(uuidUtf16);
         }
 
@@ -189 +619 @@
         {
             {
-                PRUnichar *configFile;
-                char      *configFile1 = calloc((size_t)64, (size_t)1);
-
-                machine->vtbl->GetSettingsFilePath(machine, &configFile);
-                g_pVBoxFuncs->pfnUtf16ToUtf8(configFile, &configFile1);
-                printf("\tConfig file: %s\n", configFile1);
-
-                free(configFile1);
-                g_pVBoxFuncs->pfnComUnallocMem(configFile);
+                PRUnichar *configFileUtf16;
+                char      *configFileUtf8;
+
+                machine->vtbl->GetSettingsFilePath(machine, &configFileUtf16);
+                g_pVBoxFuncs->pfnUtf16ToUtf8(configFileUtf16, &configFileUtf8);
+                g_pVBoxFuncs->pfnComUnallocMem(configFileUtf16);
+                printf("\tConfig file: %s\n", configFileUtf8);
+                g_pVBoxFuncs->pfnUtf8Free(configFileUtf8);
             }
 
@@ -215 +644 @@
                 machine->vtbl->GetOSTypeId(machine, &typeId);
                 virtualBox->vtbl->GetGuestOSType(virtualBox, typeId, &osType);
+                g_pVBoxFuncs->pfnComUnallocMem(typeId);
                 osType->vtbl->GetDescription(osType, &osNameUtf16);
                 g_pVBoxFuncs->pfnUtf16ToUtf8(osNameUtf16,&osName);
+                g_pVBoxFuncs->pfnComUnallocMem(osNameUtf16);
                 printf("\tGuest OS:    %s\n\n", osName);
+                g_pVBoxFuncs->pfnUtf8Free(osName);
 
                 osType->vtbl->nsisupports.Release((nsISupports *)osType);
-                g_pVBoxFuncs->pfnUtf8Free(osName);
-                g_pVBoxFuncs->pfnComUnallocMem(osNameUtf16);
-                g_pVBoxFuncs->pfnComUnallocMem(typeId);
             }
         }
@@ -244 +673 @@
 
             machine->vtbl->GetId(machine, &uuidUtf16);
-            startVM(virtualBox, session, uuidUtf16);
-
-            g_pVBoxFuncs->pfnUtf16Free(uuidUtf16);
+            startVM(argv0, virtualBox, session, uuidUtf16, queue);
+            g_pVBoxFuncs->pfnComUnallocMem(uuidUtf16);
         }
     }
@@ -263 +691 @@
         }
     }
+    if (machines)
+        g_pVBoxFuncs->pfnComUnallocMem(machines);
 }
 
@@ -269 +699 @@
 int main(int argc, char **argv)
 {
+    IVirtualBoxClient *vboxclient = NULL;
     IVirtualBox *vbox            = NULL;
     ISession   *session          = NULL;
+    nsIEventQueue *queue         = NULL;
     PRUint32    revision         = 0;
     PRUnichar  *versionUtf16     = NULL;
@@ -276 +708 @@
     nsresult    rc;     /* Result code of various function (method) calls. */
 
-    printf("Starting Main\n");
-
-    /*
-     * VBoxComInitialize does all the necessary startup action and
-     * provides us with pointers to vbox and session handles.
-     * It should be matched by a call to VBoxComUninitialize(vbox)
-     * when done.
-     */
+    printf("Starting main()\n");
 
     if (VBoxCGlueInit() != 0)
@@ -292 +717 @@
     }
 
-    g_pVBoxFuncs->pfnComInitialize(IVIRTUALBOX_IID_STR, &vbox,
-                                   ISESSION_IID_STR, &session);
-    if (vbox == NULL)
-    {
-        fprintf(stderr, "%s: FATAL: could not get vbox handle\n", argv[0]);
+    {
+        unsigned ver = g_pVBoxFuncs->pfnGetVersion();
+        printf("VirtualBox version: %u.%u.%u\n", ver / 1000000, ver / 1000 % 1000, ver % 1000);
+        ver = g_pVBoxFuncs->pfnGetAPIVersion();
+        printf("VirtualBox API version: %u.%u\n", ver / 1000, ver % 1000);
+    }
+
+    g_pVBoxFuncs->pfnClientInitialize(IVIRTUALBOXCLIENT_IID_STR, &vboxclient);
+    if (vboxclient == NULL)
+    {
+        fprintf(stderr, "%s: FATAL: could not get VirtualBoxClient reference\n", argv[0]);
         return EXIT_FAILURE;
     }
-    if (session == NULL)
-    {
-        fprintf(stderr, "%s: FATAL: could not get session handle\n", argv[0]);
+
+    printf("----------------------------------------------------\n");
+
+    rc = vboxclient->vtbl->GetVirtualBox(vboxclient, &vbox);
+    if (NS_FAILED(rc) || !vbox)
+    {
+        PrintErrorInfo(argv[0], "FATAL: could not get VirtualBox reference", rc);
         return EXIT_FAILURE;
     }
+    rc = vboxclient->vtbl->GetSession(vboxclient, &session);
+    if (NS_FAILED(rc) || !session)
+    {
+        PrintErrorInfo(argv[0], "FATAL: could not get Session reference", rc);
+        return EXIT_FAILURE;
+    }
+
+    g_pVBoxFuncs->pfnGetEventQueue(&queue);
 
     /*
@@ -311 +754 @@
      */
 
-    printf("----------------------------------------------------\n");
-
     /* 1. Revision */
 
     rc = vbox->vtbl->GetRevision(vbox, &revision);
     if (NS_SUCCEEDED(rc))
-    {
         printf("\tRevision: %u\n", revision);
-    }
     else
-    {
-        fprintf(stderr, "%s: GetRevision() returned %08x\n",
-            argv[0], (unsigned)rc);
-    }
+        PrintErrorInfo(argv[0], "GetRevision() failed", rc);
 
     /* 2. Version */
@@ -338 +774 @@
     }
     else
-    {
-        fprintf(stderr, "%s: GetVersion() returned %08x\n",
-            argv[0], (unsigned)rc);
-    }
+        PrintErrorInfo(argv[0], "GetVersion() failed", rc);
 
     /* 3. Home Folder */
@@ -355 +788 @@
     }
     else
-    {
-        fprintf(stderr, "%s: GetHomeFolder() returned %08x\n",
-            argv[0], (unsigned)rc);
-    }
-
-    listVMs(vbox, session);
+        PrintErrorInfo(argv[0], "GetHomeFolder() failed", rc);
+
+    listVMs(argv[0], vbox, session, queue);
     session->vtbl->UnlockMachine(session);
 
@@ -369 +799 @@
      */
 
-    g_pVBoxFuncs->pfnComUninitialize();
+    if (session)
+    {
+        session->vtbl->nsisupports.Release((nsISupports *)session);
+        session = NULL;
+    }
+    if (vbox)
+    {
+        vbox->vtbl->nsisupports.Release((nsISupports *)vbox);
+        vbox = NULL;
+    }
+    if (vboxclient)
+    {
+        vboxclient->vtbl->nsisupports.Release((nsISupports *)vboxclient);
+        vboxclient = NULL;
+    }
+    g_pVBoxFuncs->pfnClientUninitialize();
     VBoxCGlueTerm();
-    printf("Finished Main\n");
+    printf("Finished main()\n");
 
     return 0;

trunk/src/VBox/Main/cbinding/xpcidl.xsl

@@ -6 +6 @@
  *  from the generic interface definition expressed in XML.
 
-    Copyright (C) 2008-2012 Oracle Corporation
+    Copyright (C) 2008-2013 Oracle Corporation
 
     This file is part of VirtualBox Open Source Edition (OSE), as
@@ -1008 +1008 @@
     unsigned uVersion;
 
+    /** Gets the VirtualBox version, major * 1000000 + minor * 1000 + patch. */
     unsigned int (*pfnGetVersion)(void);
 
+    /** Gets the VirtualBox API version, major * 1000 + minor, e.g. 4003. */
+    unsigned int (*pfnGetAPIVersion)(void);
+
+    /**
+     * New and preferred way to initialize the C bindings for an API client.
+     *
+     * This way is much more flexible, as it can easily handle multiple
+     * sessions (important with more complicated API clients, including
+     * multithreaded ones), and even VBoxSVC crashes can be detected and
+     * processed appropriately by listening for events from the associated
+     * event source in VirtualBoxClient. It is completely up to the client
+     * to decide what to do (terminate or continue after getting new
+     * object references to server-side objects). Must be called in the
+     * primary thread of the client, later API use can be done in any
+     * thread.
+     *
+     * Note that the returned reference is owned by the caller, and thus it's
+     * the caller's responsibility to handle the reference count appropriately.
+     *
+     * @param pszVirtualBoxClientIID    pass IVIRTUALBOXCLIENT_IID_STR
+     * @param ppVirtualBoxClient        output parameter for VirtualBoxClient
+     *              reference, handled as usual with XPCOM.
+     * @returns XPCOM error code
+     */
+    nsresult (*pfnClientInitialize)(const char *pszVirtualBoxClientIID,
+                                    IVirtualBoxClient **ppVirtualBoxClient);
+    /**
+     * Uninitialize the C bindings for an API client.
+     *
+     * Should be called when the API client is about to terminate and does
+     * not want to use the C bindings any more. It will invalidate all
+     * object references. It is possible, however, to change one's mind,
+     * and call pfnClientInitialize again to continue using the API, as long
+     * as none of the object references from before the re-initialization
+     * are used. Must be called from the primary thread of the client.
+     */
+    void (*pfnClientUninitialize)(void);
+
+    /**
+     * Deprecated way to initialize the C bindings and getting important
+     * object references. Kept for backwards compatibility.
+     *
+     * If any returned reference is NULL then the initialization failed.
+     * Note that the returned references are owned by the C bindings. The
+     * number of calls to Release in the client code must match the number
+     * of calls to AddRef, and additionally at no point in time there can
+     * be more Release calls than AddRef calls.
+     *
+     * @param pszVirtualBoxIID      pass IVIRTUALBOX_IID_STR
+     * @param ppVirtualBox          output parameter for VirtualBox reference,
+     *          owned by C bindings
+     * @param pszSessionIID         pass ISESSION_IID_STR
+     * @param ppSession             output parameter for Session reference,
+     *          owned by C bindings
+     */
     void  (*pfnComInitialize)(const char *pszVirtualBoxIID,
                               IVirtualBox **ppVirtualBox,
                               const char *pszSessionIID,
                               ISession **ppSession);
+    /**
+     * Deprecated way to uninitialize the C bindings for an API client.
+     * Kept for backwards compatibility and must be used if the C bindings
+     * were initialized using pfnComInitialize. */
     void (*pfnComUninitialize)(void);
 
+    /**
+     * Free memory managed by XPCOM.
+     *
+     * @param pv        pointer to memory block to be freed
+     */
     void  (*pfnComUnallocMem)(void *pv);
+
+    /**
+     * Convert string from UTF-16 encoding to UTF-8 encoding.
+     *
+     * @param pwszString    input string
+     * @param ppszString    output string
+     * @returns IPRT status code
+     */
+    int   (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString);
+    /**
+     * Convert string from UTF-8 encoding to UTF-16 encoding.
+     *
+     * @param pszString     input string
+     * @param ppwszString   output string
+     * @returns IPRT status code
+     */
+    int   (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString);
+    /**
+     * Free memory returned by pfnUtf16ToUtf8. Do not use for anything else.
+     *
+     * @param pszString     string to be freed.
+     */
+    void  (*pfnUtf8Free)(char *pszString);
+    /**
+     * Free memory returned by pfnUtf8ToUtf16. Do not use for anything else.
+     *
+     * @param pwszString    string to be freed.
+     */
     void  (*pfnUtf16Free)(PRUnichar *pwszString);
-    void  (*pfnUtf8Free)(char *pszString);
-
-    int   (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString);
-    int   (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString);
-
-    void  (*pfnGetEventQueue)(nsIEventQueue **eventQueue);
+
+    /**
+     * Get main XPCOM event queue.
+     *
+     * @param ppEventQueue      output parameter for nsIEventQueue reference,
+     *              owned by C bindings.
+     */
+    void  (*pfnGetEventQueue)(nsIEventQueue **ppEventQueue);
+
+    /**
+     * Get current XPCOM exception.
+     *
+     * @param ppException       output parameter for nsIException reference,
+     *              may be @c NULL if no exception object has been created by
+     *              a previous XPCOM call.
+     * @returns XPCOM error code
+     */
+    nsresult (*pfnGetException)(nsIException **ppException);
+    /**
+     * Clears current XPCOM exception.
+     *
+     * @returns XPCOM error code
+     */
+    nsresult (*pfnClearException)(void);
 
     /** Tail version, same as uVersion. */
@@ -1034 +1145 @@
  * For use with VBoxGetXPCOMCFunctions and to be found in
  * VBOXXPCOMC::uVersion. */
-#define VBOX_XPCOMC_VERSION     0x00020000U
+#define VBOX_XPCOMC_VERSION     0x00030000U
 
 VBOXXPCOMC_DECL(PCVBOXXPCOM) VBoxGetXPCOMCFunctions(unsigned uVersion);