https://github.com/gabrielmajeri/comptr-rs

Smart pointer for COM interfaces.
https://github.com/gabrielmajeri/comptr-rs

component-object-model rust windows

Last synced: 1 day ago
JSON representation

Smart pointer for COM interfaces.

• Host: GitHub
• URL: https://github.com/gabrielmajeri/comptr-rs
• Owner: GabrielMajeri
• Created: 2017-07-14T14:41:35.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2018-08-14T09:01:08.000Z (about 6 years ago)
• Last Synced: 2023-03-04T02:02:09.800Z (over 1 year ago)
• Topics: component-object-model, rust, windows
• Language: Rust
• Size: 18.6 KB
• Stars: 0
• Watchers: 2
• Forks: 2
• Open Issues: 3
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# comptr-rs

Smart pointer for [Component Object Model](https://msdn.microsoft.com/en-us/library/windows/desktop/ms680573(v=vs.85).aspx) 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:

```rust

// 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.