{"id":17329415,"url":"https://github.com/zrax/libvbox","last_synced_at":"2025-04-14T16:33:22.467Z","repository":{"id":43958822,"uuid":"188091318","full_name":"zrax/libvbox","owner":"zrax","description":"C++11 wrapper for the VirtualBox COM/XPCOM APIs","archived":false,"fork":false,"pushed_at":"2025-04-08T23:40:53.000Z","size":735,"stargazers_count":29,"open_issues_count":2,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-09T00:35:13.507Z","etag":null,"topics":["cxx11","virtualbox"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zrax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-22T18:16:35.000Z","updated_at":"2025-04-08T23:40:57.000Z","dependencies_parsed_at":"2024-09-13T04:13:45.890Z","dependency_job_id":"556c4900-eb2b-4178-bb2b-4a3565b735ab","html_url":"https://github.com/zrax/libvbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zrax%2Flibvbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zrax%2Flibvbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zrax%2Flibvbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zrax%2Flibvbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zrax","download_url":"https://codeload.github.com/zrax/libvbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248916938,"owners_count":21182896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cxx11","virtualbox"],"created_at":"2024-10-15T14:47:58.032Z","updated_at":"2025-04-14T16:33:21.825Z","avatar_url":"https://github.com/zrax.png","language":"C++","readme":"# libvbox\n\nA C++11 wrapper for the VirtualBox COM/XPCOM API.\n\nlibvbox provides a way to interact with the VirtualBOX COM interface\nwithout having to deal with the messy MS COM or XPCOM layers directly.\nIn fact, after building libvbox, client applications do not need any\nCOM headers, nor the VirtualBox SDK itself.\n\nlibvbox currently supports VirtualBox SDK versions 5.0 through 7.1.\n\n## Building\n\nlibvbox uses the [CMake](https://cmake.org/) build system.  To build\nlibvbox, you will also need a version of the\n[VirtualBox SDK](https://www.virtualbox.org/wiki/Downloads) matching your\ninstalled VirtualBox application version.  Be sure to specify which version\nof the SDK you're using, as this unfortunately cannot be auto-detected due\nto limitations in the SDK.\n\n    \u003e cd C:\\path\\to\\libvbox\n    \u003e mkdir build\n    \u003e cd build\n    \u003e cmake .. -DVirtualBoxSDK_DIR=C:/path/to/virtualbox/sdk \\\n        -DVirtualBoxSDK_VERSION=7.0.20\n    \u003e cmake --build .\n\nNOTE: For XPCOM-based platforms, you may also need to specify the path to the\nVirtualBox XPCOM library if it isn't auto-detected:\n\n    $ cd /path/to/libvbox\n    $ mkdir build\n    $ cd build\n    $ cmake .. -DVirtualBoxSDK_DIR=/path/to/virtualbox/sdk \\\n        -DVirtualBoxSDK_VERSION=7.0.20 \\\n        -DVirtualBox_XPCOM_LIB=/usr/lib/virtualbox/VBoxXPCOM.so\n    $ cmake --build .\n\n## Client Examples\n\n**List Machines**\n~~~c++\n#include \u003clibvbox.h\u003e\n\nauto vboxClient = VBox::virtualBoxClient();\nauto vbox = vboxClient-\u003evirtualBox();\nauto machines = vbox-\u003emachines();\nfor (const auto \u0026machine : machines)\n    std::wcout \u003c\u003c VBox::utf16ToWide(machine-\u003ename()) \u003c\u003c std::endl;\n~~~\n\n**Launch a VM by name**\n~~~c++\n#include \u003clibvbox.h\u003e\n\nauto vboxClient = VBox::virtualBoxClient();\nauto vbox = vboxClient-\u003evirtualBox();\nauto session = vboxClient-\u003esession();\nauto machine = vbox-\u003efindMachine(u\"Windows\");\nif (machine) {\n    auto progress = machine-\u003elaunchVMProcess(session, u\"gui\", {});\n    progress-\u003ewaitForCompletion(-1);\n}\n~~~\n\n**Event Listener**\n~~~c++\n#include \u003clibvbox.h\u003e\n#include \u003cthread\u003e\n\nauto evSource = someObject-\u003eeventSource();\nauto listener = evSource-\u003ecreateListener();\nevSource-\u003eregisterListener(listener, {VBox::VBoxEventType::Any}, false);\n\nstd::thread event_thread([evSource, listener]() {\n    for ( ;; ) {\n        auto event = evSource-\u003egetEvent(listener, 500);\n        if (!event)\n            continue;\n\n        std::wcout \u003c\u003c L\"Got event type \" \u003c\u003c static_cast\u003cint\u003e(event-\u003etype())\n                   \u003c\u003c std::endl;\n        if (auto stateChangedEvent = event-\u003eQueryInterface\u003cVBox::IStateChangedEvent\u003e()) {\n            std::wcout \u003c\u003c L\"    State change: \"\n                       \u003c\u003c static_cast\u003cint\u003e(stateChangedEvent-\u003estate())\n                       \u003c\u003c std::endl;\n        }\n        evSource-\u003eeventProcessed(listener, event);\n    }\n});\n~~~\n\n## Enumerations\n\nlibvbox wraps all enumerations described in the VirtualBox SDK in a\nC++11 `enum class`.  As such, regardless of the underlying COM\nimplementation, enum values can be accessed by their fully qualified name.\n\n~~~c++\nswitch (machine-\u003estate()) {\ncase VBox::MachineState::PoweredOff:\n    // ...\n    break;\n}\n~~~\n\n## Interfaces\n\nlibvbox wraps COM and XPCOM interfaces using the same naming convection\nas is used in the manual (that is, methods and attributes are not converted\nto upper-case).  Attribute getters use the same name as the attribute,\nand setters use the convention `set_`*attribute*`(`*value*`)`.  \"out\"\nparameters are passed by pointer, and can be `nullptr` if the returned value\nis not needed (all wrappers test for `nullptr` before setting \"out\"\nparameters, even if the underlying COM class does not).\n\nFor Interface types in the API, a COM-aware smart pointer (`VBox::COMPtr`)\nis used to manage reference counting.  Generally speaking, all libvbox\ninterfaces should live only inside a `VBox::COMPtr`, and manual reference\ncounting should not be necessary.\n\nNote that, unlike in the VirtualBox SDK, the same interface is used\nregardless of whether the underlying SDK uses XPCOM or MS COM.\n\n### COMUnknown\n\nFor consistency, the base class of all wrapped interfaces is\n`VBox::COMUnknown`, which supports the `IUnknown` (MS COM) / `nsISupports`\n(XPCOM) interface.  This class contains a pointer to the underlying\ninterface type, which can be manipulated with `get_IFC()` and `set_IFC()`,\nqueried for existence with `have_IFC()` and cleared with `clear_IFC()`.\nHowever, most of the time, you should not use these methods and instead\ncontrol access via a `VBox::COMPtr` smart pointer instead.\n\n`VBox::COMUnknown` classes also support a template-based `QueryInterface`,\nwhich will return a pointer to the queried type or `nullptr` if the COM\nimplementation would return `E_NOINTERFACE`.  For example:\n\n~~~c++\nauto event = source-\u003egetEvent(listener, -1);\nif (auto stateChangedEvent = event-\u003eQueryInterface\u003cVBox::IStateChangedEvent\u003e()) {\n    // Handle stateChangedEvent\n}\n~~~\n\n### COMErrorInfo\n\nFor consistency, the base class for exception interfaces is wrapped as a\n`VBOX::COMErrorInfo` class.  Unfortunately, MS COM and XPCOM do not provide\na consistent API for their base exception classes, so the only attribute\nprovided is a `message`, which maps to `GetMessage()` on XPCOM and\n`GetDescription` on MS COM.  The VirtualBox SDK may provide a more detailed\nexception object however, which can be gotten by querying the\n`VBox::IVirtualBoxErrorInfo` interface:\n\n~~~c++\nauto error = VBox::currentError();\nif (auto vboxError = error-\u003eQueryInterface\u003cVBox::IVirtualBoxErrorInfo\u003e()) {\n    // More detailed handling of vboxError\n} else {\n    // only error-\u003emessage() available.\n}\n~~~\n\n## SDK Types\n\nlibvbox uses standard C++11/STL types for the following types used in the\nSDK manual:\n\n| VirtualBox SDK Type  | libvbox Type |\n|----------------------|--------------|\n| `boolean`            | `bool`       |\n| `octet`              | `uint8_t`    |\n| `short`              | `int16_t`    |\n| `unsigned short`     | `uint16_t`   |\n| `long`               | `int32_t`    |\n| `unsigned long`      | `uint32_t`   |\n| `long long`          | `int64_t`    |\n| `unsigned long long` | `uint64_t`   |\n| `wstring`  | [`std::u16string`](https://en.cppreference.com/w/cpp/string/basic_string) |\n| `I`*Interface*       | `VBox::COMPtr\u003cVBox::I`*Interface*`\u003e` |\n| *Type*`[]` | [`std::vector`](https://en.cppreference.com/w/cpp/container/vector)`\u003c`*Type*`\u003e` |\n\n## Error Handling\n\nWith the exception of `E_NOINTERFACE` (see [`COMUnknown::QueryInterface`](#comunknown)\nabove for details), error result codes from MS COM / XPCOM are raised as\nC++ exceptions.  All exceptions are derived from `VBox::COMError`, which\nprovides the underlying COM result code in `error_code()`, as well as a\ntextual version of the error enum in\n[`what()`](https://en.cppreference.com/w/cpp/error/exception/what).\n\nFor common error types returned by the VirtualBox SDK, a subclass exception\nwill be thrown for easier exception handling by client code:\n\n| Error Code                | libvbox Exception         |\n|---------------------------|---------------------------|\n| *Generic COM Exceptions*                              |\n| `E_NOTIMPL`               | `VBox::ENotImpl`          |\n| `E_POINTER`               | `VBox::EPointer`          |\n| `E_ABORT`                 | `VBox::EAbort`            |\n| `E_FAIL`                  | `VBox::EFail`             |\n| `E_ACCESSDENIED`          | `VBox::EAccessDenied`     |\n| `E_OUTOFMEMORY`           | `VBox::EOutOfMemory`      |\n| `E_INVALIDARG`            | `VBox::EInvalidArg`       |\n| `E_UNEXPECTED`            | `VBox::EUnexpected`       |\n| *VirtualBox specific Exceptions*                      |\n| `E_OBJECT_NOT_FOUND`      | `VBox::EObjectNotFound`   |\n| `E_INVALID_VM_STATE`      | `VBox::EInvalidVMState`   |\n| `E_VM_ERROR`              | `VBox::EVMError`          |\n| `E_FILE_ERROR`            | `VBox::EFileError`        |\n| `E_IPRT_ERROR`            | `VBox::EIPRTError`        |\n| `E_PDM_ERROR`             | `VBox::EPDMError`         |\n| `E_INVALID_OBJECT_STATE`  | `VBox::EInvalidObjectState` |\n| `E_HOST_ERROR`            | `VBox::EHostError`        |\n| `E_NOT_SUPPORTED`         | `VBox::ENotSupported`     |\n| `E_XML_ERROR`             | `VBox::EXMLError`         |\n| `E_INVALID_SESSION_STATE` | `VBox::EInvalidSessionState` |\n| `E_OBJECT_IN_USE`         | `VBox::EObjectInUse`      |\n| `E_PASSWORD_INCORRECT`    | `VBox::EPasswordIncorrect` |\n| `E_MAXIMUM_REACHED`       | `VBox::EMaximumReached`   |\n| `E_GSTCTL_GUEST_ERROR`    | `VBox::EGstctlGuestError` |\n| `E_TIMEOUT`               | `VBox::ETimeout`          |\n| `E_DND_ERROR`             | `VBox::EDndError`         |\n| `E_PLATFORM_ARCH_NOT_SUPPORTED` | `VBox::EPlatformArchNotSupported` |\n| `E_RECORDING_ERROR`       | `VBox::ERecordingError`   |\n\n## libvbox Entry Points and Helpers\n\n### VBox::virtualBoxClient\n\nTo get started with libvbox, one must first acquire the `IVirtualBoxClient`\ninterface from `VBox::virtualBoxClient()`.  The first call to this function\nwill initialize the MS COM or XPCOM API and acquire the required VirtualBox\nSDK objects.  At the end of the application lifetime, libvbox will clean\nitself up automatically.\n\n### VBox::currentError\n\nIf a [`VBox::COMError`](#error-handling) exception is thrown, the COM\nexception class for the current thread can be obtained with\n`VBox::currentError()`.  This function will also clear the current error in\nthe appropriate manner for the COM implementation.\n\n~~~c++\ntry {\n    auto machine = vbox-\u003efindMachine(u\"Foobar\");\n} catch (const VBox::COMError \u0026err) {\n    auto errorInfo = VBox::currentError();\n    // Display error information...\n}\n~~~\n\n### VBox::utf16ToUtf8\n\n* `std::string VBox::utf16ToUtf8(const std::u16string \u0026)`\n* `std::string VBox::utf16ToUtf8(const char16_t *, size_t)`\n* `std::string VBox::utf16ToUtf8(const char16_t *)`\n\nUse the platform's native routines (XPCOM or Win32 API) to convert a\nlibvbox `std::u16string` to UTF-8.\n\n### VBox::utf8ToUtf16\n\n* `std::u16string VBox::utf8ToUtf16(const std::string \u0026)`\n* `std::u16string VBox::utf8ToUtf16(const char *, size_t)`\n* `std::u16string VBox::utf8ToUtf16(const char *)`\n\nUse the platform's native routines (XPCOM or Win32 API) to convert a\nUTF-8 string to `std::u16string` for libvbox.\n\n### VBox::utf16ToWide\n\n* `std::wstring VBox::utf16ToWide(const std::u16string \u0026)`\n* `std::wstring VBox::utf16ToWide(const char16_t *, size_t)`\n* `std::wstring VBox::utf16ToWide(const char16_t *)`\n\nConvert a libvbox `std::u16string` to wide format (`std::wstring`), as\nappropriate for the target operating system.  This function is provided\nby libvbox for convenience.\n\n### VBox::wideToUtf16\n\n* `std::u16string VBox::wideToUtf16(const std::wstring \u0026)`\n* `std::u16string VBox::wideToUtf16(const wchar_t *, size_t)`\n* `std::u16string VBox::wideToUtf16(const wchar_t *)`\n\nConvert a wide string to `std::u16string` for libvbox.  This function is\nprovided by libvbox for convenience.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzrax%2Flibvbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzrax%2Flibvbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzrax%2Flibvbox/lists"}