Crate variant_rs

variant-rs

variant-rs is a Rust crate that provides idiomatic handling of COM VARIANT types. Rust supports discriminated union types out of the box, so although VARIANTs are usually a pain to work with, Rust makes it easy to encode and decode them.

The crate is designed to work with the VARIANT type from the winapi crate.

Basic usage

use variant_rs::*;

fn main() {
    let v1 = Variant::I32(123); // manual instanciation
    let v2 = 123i32.to_variant(); // ToVariant trait
    let v3 = 123.into(); // From / Into traits
    assert_eq!(v1, v2);
    assert_eq!(v1, v3);
  
    let bstr: Variant = "Hello, world!".into();
    let ptr: VARIANT = bstr.clone().try_into().unwrap(); // convert to COM VARIANT
    let back: Variant = ptr.try_into().unwrap(); // convert back
    assert_eq!(bstr, back);
}

Supported VARIANT types and corresponding types

VARIANT type	Rust type	Rust type (BY_REF)
VT_EMPTY	()	N/A
VT_NULL	()	N/A
VT_I1	i8	PSTR
VT_I2	i16	&'static mut i16
VT_I4	i32	&'static mut i32
VT_I8	i64	&'static mut i64
VT_UI1	u8	&'static mut u8
VT_UI2	u16	&'static mut u16
VT_UI4	u32	&'static mut u32
VT_UI8	u64	&'static mut u64
VT_INT	i32	&'static mut i32
VT_UINT	u32	&'static mut u32
VT_R4	f32	&'static mut f32
VT_R8	f64	&'static mut f64
VT_BOOL	bool	&'static mut ComBool
VT_BSTR	BSTR	&'static mut BSTR
VT_ERROR	HRESULT (i32)	&'static mut HRESULT (i32)
VT_CY	Currency	&'static mut ComCurrency
VT_DATE	NaiveDateTime	&'static mut ComDate
VT_DECIMAL	Decimal	&'static mut ComDecimal
VT_UNKNOWN	Option<IUnknown>	N/A
VT_DISPATCH	Option<IDispatch>	N/A
VT_VARIANT	N/A	PtrWrapper<VARIANT>

Wrapper types

ComBool

i16-backed enum.

ComCurrency

Maps COM’s i64 currency data CY to Decimal.

ComDecimal

Maps COM’s 96-bit decimals DECIMAL to Decimal.

ComData

Maps COM’s DATE (f64 milliseconds from 1899-12-30) to NaiveDateTime.

PtrWrapper

Safe wrapper around COM interface pointers.

Installation

Add this to your Cargo.toml:

[dependencies]
variant-rs = "0.4.0"

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT) at your option.

Re-exports

• pub use crate::variant::*;

Modules

• com_types
  Utilities for handling COM types ([BOOL], [CY], [DECIMAL], etc.)
• convert
  Conversion between native VARIANT and Rust Variant
• dispatch
  Utilities for using [IDispatch] from Rust in an ergonomic fashion
• variant
  Rust wrapper for the VARIANT type

Macros

• call
  Call a method on the COM object
• get
  Get a property from the COM object
• put
  Set a property on the COM object

Structs

• VARENUM
• VARIANT
  Required features: "Win32_Foundation", "Win32_System_Com", "Win32_System_Ole"