Arnavion / winapi-tlb-bindgen

Generates Rust bindings to COM interfaces, enums and coclasses.

This crate is no longer maintained because I do not use Windows any more.

If you have questions about this repository, open an issue at https://github.com/Arnavion/archived-repos-issues

---

Generates bindings to COM interfaces, enums and coclasses.

Usage

See the test-msxml and test-wmi subdirectories for full examples of using this library to generate bindings for the MSXML library and the WMI library respectively.

1. Find the typelib for the COM library you want to generate bindings for:

   • If you have a .tlb file, use that.
   • If you have a .dll with an embedded .tlb resource, use that.
   • If you have a .idl, generate a .tlb with midl.exe from the Windows SDK via midl.exe .\foo.idl /tlb .\foo.tlb and use that.

   To be sure that a .tlb / .dll will work with winapi-tlb-bindgen, you can create a C++ project in MSVC and try to #import the .tlb / .dll. If that compiles, then it should work with winapi-tlb-bindgen

2. Write a build script that uses this crate to generate the bindgen output for the COM library.

   // build.rs
   
   winapi_tlb_bindgen::build(
   	std::path::Path::new(r"C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\MsXml.Tlb"),
   	false,
   	out_file, // $OUT_DIR/msxml.rs
   ).unwrap();

3. Add an empty mod file that include!s the bindgen output.

   // src/msxml.rs
   
   include!(concat!(env!("OUT_DIR"), "/msxml.rs"));

4. Add a dependency to your crate on winapi = { version = "0.3.6" } You will likely want to enable (atleast) the objbase, oleauto, and winerror features to get access to HRESULT, IUnknown and other COM types.

5. Build your crate.

6. Silence warnings for identifier names and unused functions as necessary, and prepend imports from winapi for any types the compiler can't find.

   // src/msxml.rs
   
   #![allow(non_camel_case_types, non_snake_case, unused)]
   
   use winapi::{ENUM, RIDL, STRUCT};
   use winapi::shared::guiddef::GUID;
   use winapi::shared::minwindef::UINT;
   use winapi::shared::winerror::HRESULT;
   use winapi::shared::wtypes::{BSTR, VARIANT_BOOL};
   use winapi::um::oaidl::{IDispatch, IDispatchVtbl, LPDISPATCH, VARIANT};
   use winapi::um::unknwnbase::{IUnknown, IUnknownVtbl, LPUNKNOWN};
   
   include!(concat!(env!("OUT_DIR"), "/msxml.rs"));

   Repeat till there are no more missing imports and the crate compiles.

   (Issue #2 is about automating this step or atleast making it easier.)

7. Compare the output against the C++ headers generated by MSVC with #import. File a bug if something was emitted incorrectly.

8. Enjoy your COM API bindings.

   // src/main.rs
   
   mod msxml;
   
   fn main() {
   	unsafe {
   		let hr = winapi::um::objbase::CoInitialize(std::ptr::null_mut());
   		assert!(winapi::shared::winerror::SUCCEEDED(hr));
   
   		let mut document: *mut winapi::ctypes::c_void = std::ptr::null_mut();
   		let hr =
   			winapi::um::combaseapi::CoCreateInstance(
   				&<msxml::DOMDocument as winapi::Class>::uuidof(),
   				std::ptr::null_mut(),
   				winapi::um::combaseapi::CLSCTX_ALL,
   				&<msxml::IXMLDOMDocument as winapi::Interface>::uuidof(),
   				&mut document,
   			);
   		assert!(winapi::shared::winerror::SUCCEEDED(hr));
   		let document = &*(document as *mut msxml::IXMLDOMDocument);
   
   		// ...
   
   		document.Release();
   	}
   }

winapi-tlb-bindgen-bin

The winapi-tlb-bindgen-bin crate is a binary that takes in the path of the typelib as a command-line parameter, and writes the bindgen output to stdout. This can be used to generate bindings manually for greater control, as opposed to using a build script to automatically generate the bindings on every build. You would also do this if you wanted your crate to be able to be built on non-Windows platforms.

cd winapi-tlb-bindgen-bin
cargo run -- 'C:\Program Files (x86)\Windows Kits\10\Lib\10.0.16299.0\um\x64\MsXml.Tlb'

License

winapi-tlb-bindgen

https://github.com/Arnavion/winapi-tlb-bindgen

Copyright 2023 Arnav Singh

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.