VirtualDesktopAccessor

When working with COM objects, follow these three fundamental rules for reference management:

1. In Parameters (Caller to Callee): The caller maintains the reference for the duration of the method call. The callee (you) should not call AddRef or Release on these objects during the synchronous call.
2. Out Parameters (Callee to Caller): The callee provides the object with a reference already taken. The caller owns the reference and is responsible for calling Release when finished.
3. Copying Pointers: If you need to store a COM object pointer for use outside the immediate scope of a method call (e.g., in an async handler), you must manually call AddRef to create a copy and Release once the asynchronous work is complete.

To use the Virtual Desktop features in external applications like AutoHotkey, download the pre-compiled VirtualDesktopAccessor.dll from the official GitHub releases page.

Requirements:

• Windows 11 (requires at least 24H2 26100.2605).
• Tested with 25H2 OS Build 26200.8117.

https://github.com/Ciantic/VirtualDesktopAccessor/releases/

The ComObjects struct is the primary interface for interacting with the Windows Virtual Desktop API. Because Virtual Desktop COM objects are sensitive to multi-threaded access, you must wrap your logic in the with_com_objects function. This ensures all COM calls are executed within a single thread, preventing instability.

with_com_objects provides a reference to a thread-local ComObjects instance to your closure.

use virtualdesktopaccessor::{with_com_objects, DesktopInternal};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    with_com_objects(|com| {
        let desktops = com.get_desktops()?;
        println!("Found {} desktops", desktops.len());
        Ok(())
    })?;
    Ok(())
}

The DesktopInternal enum is used to reference specific virtual desktops. It allows you to identify a desktop in three ways:

• Index(u32): The zero-based index of the desktop.
• Guid(GUID): The unique identifier of the desktop.
• IndexGuid(u32, GUID): A combination of both the index and the GUID.

Most ComObjects methods accept DesktopInternal as an argument, allowing you to switch, move windows, or rename desktops using any of these identifiers.

// Example of creating a DesktopInternal from an index
let my_desktop = DesktopInternal::Index(0);

In this project's Rust bindings, ComIn<T> is a wrapper used for COM objects passed as input parameters. It ensures the COM object's lifetime is maintained for the duration of the function call without requiring the caller to manually manage AddRef or Release during the call.

When you receive a COM object as an out parameter (e.g., *mut Option<T>), you should wrap it in ComIn::new(&object) before passing it to a function that expects a ComIn<T> input.

// Example: Passing an obtained desktop to a switch function
let mut desktop: Option<IVirtualDesktop> = None;
get_current_desktop(&mut desktop);

if let Some(desktop) = desktop {
    // Wrap the owned desktop in ComIn to pass it as an input parameter
    switch_desktop(ComIn::new(&desktop));
}

The winvd crate allows you to interact with Windows Virtual Desktops using either a zero-based integer index or a unique GUID. Any function that accepts a Desktop type can be satisfied by passing an index or a GUID object.

Common tasks include:

• Accessing a desktop by index: get_desktop(index)
• Accessing a desktop by GUID: get_desktop(GUID(uuid_string))
• Switching desktops: switch_desktop(index_or_guid)

// Get first desktop name by index
let name = get_desktop(0).get_name();

// Get second desktop name by index
let name = get_desktop(1).get_name();

// Get desktop name by GUID
let name = get_desktop(GUID(some_uuid)).get_name();

// Switch to fifth desktop by index
switch_desktop(4);

When using IVirtualDesktopNotification::register, be aware that the Windows shell may reuse cookies if explorer.exe crashes and restarts.

If you attempt to register a new notification without unregistering the previous one after an explorer crash, the new registration might receive the same cookie ID as the old one. Consequently, attempting to unregister the 'old' cookie will actually unregister the 'new' one.

Best Practice: Always unregister the existing notification/cookie before attempting to register a new one to ensure clean state management.

You can use the DLL to automate virtual desktop switching and window management in AutoHotkey. Examples are provided for both AutoHotkey V1 and V2 in the repository.

• For AutoHotkey V1, refer to example.ahk.
• For AutoHotkey V2, refer to example.ah2.

Functions to create new desktops or remove existing ones.

// Create a new virtual desktop. 
// Returns the index of the newly created desktop, or -1 on error.
int32_t CreateDesktop();

// Remove a virtual desktop.
// remove_desktop_number: The index of the desktop to remove.
// fallback_desktop_number: The index of the desktop to switch to if the removal leaves no desktops.
// Returns 1 on success, -1 on error.
int32_t RemoveDesktop(int32_t remove_desktop_number, int32_t fallback_desktop_number);

If you need to stop the background event listener before the DesktopEventThread object is dropped, call the stop() method. This sends a quit message to the listener thread and waits for the thread to finish (joins it).

// Explicitly stop the listener and join the thread
listener_thread.stop().expect("Failed to stop listener thread");