# outlook-mapi

This crate implements Rust bindings for the [Outlook MAPI](https://learn.microsoft.com/en-us/office/client-developer/outlook/mapi/outlook-mapi-reference) COM APIs. The bindings are generated by the [Windows](https://github.com/microsoft/windows-rs) crate in [outlook-mapi-sys](https://crates.io/crates/outlook-mapi-sys).

## Getting Started

Include a reference to the latest version of `outlook-mapi` in your `Cargo.toml`.

See the [docs](https://docs.rs/outlook-mapi/) for more details.

## Safety

Most of the bindings are re-exported transparently from `outlook-mapi-sys` as the `outlook-mapi::sys` module, and they are still marked `unsafe`. Unlike typical idiomatic Rust crates wrapped around a `-sys` crate, the emphasis of this crate is on writing as little manual wrapper code as possible. This way, `outlook-mapi` can project 100% of the Outlook MAPI COM API, but the downside is you will need to wrap most uses in an `unsafe` block or function.

## Convenience Types

This crate does add several Rust structs and macro definitions to make it easier to work with MAPI types, and to add some lifetime guarantees when used in place of the raw MAPI API. For instance, the typical sequence of MAPI calls in C++ looks something like this:

```cpp
MAPIInitialize(...);

// Logon with a new session.
MAPILogonEx(..., &session);

// Do stuff with the session...

// This should be the last reference to the session!
session->Release();

MAPIUninitialize();
```

The convenience types ensure that you have a matching pair of `MAPIInitialize` and `MAPIUninitialize` calls, and they live at least as long as the `session` is in use. They also constrain which flags you can pass to each of these calls:

```rs
println!("Initializing MAPI...");
let initialized = Initialize::new(Default::default()).expect("failed to initialize MAPI");
println!("Trying to logon to the default profile...");
let logon = Logon::new(
    initialized,
    Default::default(),
    None,
    None,
    LogonFlags {
        extended: true,
        unicode: true,
        logon_ui: true,
        use_default: true,
        ..Default::default()
    },
)
.expect("should be able to logon to the default MAPI profile");
println!("Success!");
```