gabrielmajeri/comptr-rs

Smart pointer for COM interfaces.

comptr-rs

Smart pointer for Component Object Model interfaces.

This crate is designed to be used together with winapi-rs. You can use the COM interfaces declared by it or use RIDL! macro from that same crate to declare your COM interfaces.

Non-null guarantee

The ComPtr type is built around the invariant that the pointer it manages will never be null. Since memory in COM is only freed when the last reference is released, and ComPtr only releases its reference when the destructor is run, the invariant is maintained.

Example

The following (not actually real) example shows how you would use the library:

// Import the crate.
extern crate comptr;
use comptr::ComPtr;

// This function is exported from some DLL.
extern "system" {
    fn CreateInterface(*mut *mut IUnknown);
}

let interface = ComPtr::new({
    let mut ptr = ptr::null_mut();

    unsafe {
        CreateInterface(&mut ptr);
    }

    // The pointer must be non-null or undefined behaviour could occur.
    if ptr == std::ptr::null_mut() {
        panic!("Failed to create COM interface.");
    }

    ptr
});

// Now you can use the interface, with 100% guarantee it is not null.
unsafe {
    interface.CallFunction();
}

Contributing

Issues (i.e. feature requests and bug reports) and pull-requests are welcome!

You can also help by writing code that uses this crate. The more users it has, the better tested in real-life scenarios it will be.

License

This crate is dual licensed under either of MIT / Apache 2.0, at your option.

comptr-rs's Issues

Compilable on stable rust

Currently, due to the Shared type used by ComPtr this crate cannot be used on stable.

Tracking issue: rust-lang/rust#27730

Set up AppVeyor Continuous Integration

Now that some unit tests exit, CI could help catch bugs, and generally make sure the crate is usable.

When #2 is solved, Travis CI could also be set up.

Should work on Linux

According to Microsoft, COM is a cross-platform API. However, Windows is the only OS that embraces the COM API.

Still, it would be great to remove the dependency on winapi-rs / make it optional, and make this crate compile on Linux.