Crate com_scrape_types

Support types and traits for bindings generated by com-scrape.

ComPtr and ComRef are smart pointers for interacting with COM objects (calling methods, casting between interfaces, and managing reference counts). The Class trait can be used for defining COM classes in Rust, and ComWrapper is a smart pointer used for instantiating those classes.

Reference counting

COM objects are reference-counted. The ComPtr and ComRef smart pointers manage this automatically where possible, but the function signatures generated by com-scrape still pass COM objects as raw pointers, and care must be taken to handle issues of ownership correctly when converting between ComPtr or ComRef and raw pointers at these boundaries.

A thorough overview of how to manage reference counts for COM objects in a variety of situations can be found on the “Rules for Managing Reference Counts” page in the Microsoft COM documentation, and the documentation for each individual ComPtr andComRef method specifies its effect on an object’s reference count. However, the following rules of thumb should suffice in the majority of situations:

1. When passing an interface pointer as a function parameter, use ComPtr::as_ptr to obtain a raw pointer from a ComPtr, or use ComRef::as_ptr to obtain a raw pointer from a ComRef.

2. When receiving an interface pointer as the return value of a function (or via an out parameter), always use ComPtr::from_raw to obtain a ComPtr from the raw pointer.

3. When receiving an interface pointer as a function parameter, always use ComRef::from_raw to obtain a ComRef from the raw pointer. If the received interface pointer will be stored beyond the duration of the current function, use ComRef::to_com_ptr to upgrade the ComRef to a ComPtr.

4. When returning an interface pointer from a function (or when returning it via an out parameter), always use ComPtr::into_raw to obtain a raw pointer from a ComPtr.

Implementing COM interfaces from Rust

The Class trait can be used to define COM classes in Rust, and the ComWrapper smart pointer can be used to instantiate objects of these classes. To define a COM class, start by defining a Rust type:

struct MyClass { /* ... */ }

Then implement the desired interface traits for the type:

impl ISomeInterfaceTrait for MyClass {
    unsafe fn some_method(&self) {
        /* ... */
    }
}

impl IAnotherInterfaceTrait for MyClass {
    unsafe fn another_method(&self) {
        /* ... */
    }
}

Finally, implement the Class trait for the type, specifying the set of COM interfaces as a tuple:

impl Class for MyClass {
    type Interfaces = (ISomeInterface, IAnotherInterface);
}

With these definitions in place, ComWrapper can be used to instantiate a COM object supporting the above interfaces:

let my_obj = ComWrapper::new(MyClass);

let ptr = my_obj.to_com_ptr::<ISomeInterface>().unwrap();
ptr.some_method();

let ptr = my_obj.to_com_ptr::<IAnotherInterface>().unwrap();
ptr.another_method();

Structs

• ComPtr
  An owning smart pointer to a COM object.
• ComRef
  A non-owning smart pointer to a COM object.
• ComWrapper
  A wrapper for constructing a reference-counted COM object from a Rust value.

Traits

• Class
  A Rust type that defines a COM class.
• Construct
  Generates the virtual table and base class object for a given class and interface.
• Inherits
  Represents the “is-a” relationship for interfaces.
• Interface
  Implemented by all COM interface types.
• InterfaceList
  A list of COM interfaces implemented by a Rust type.
• MakeHeader
  Generates the object header for a given class and list of interfaces.
• SmartPtr
  Trait for types that represent a smart pointer to a COM object.
• Unknown
  Implemented by interfaces that derive from the IUnknown interface (or an equivalent thereof).
• Wrapper
  Helper functionality used in generated virtual tables for Rust types.

Type Aliases

• Guid
  A 16-byte unique identifier for a COM interface.
• Header
  Convenience alias for getting the object header of a Class.