Trait oaidl::BStringExt

source ·

pub trait BStringExt {
    // Required methods
    fn allocate_bstr(&mut self) -> Result<Ptr<u16>, BStringError>;
    fn consume_to_bstr(self) -> Result<Ptr<u16>, BStringError>;
    fn allocate_managed_bstr(
        &mut self
    ) -> Result<DroppableBString, BStringError>;
    fn consume_to_managed_bstr(self) -> Result<DroppableBString, BStringError>;
    fn deallocate_bstr(bstr: Ptr<u16>);
    fn from_bstr(bstr: *mut u16) -> U16String;
    fn from_pbstr(bstr: Ptr<u16>) -> U16String;
    fn from_boxed_bstr(bstr: Box<u16>) -> U16String;
}

Expand description

This trait is implemented on U16String to enable the convenient and safe conversion of It utilizes the Sys* functions to manage the allocated memory. Generally you will want to use allocate_managed_bstr because it provides a type that will automatically free the BSTR when dropped.

For FFI, you cannot use a straight up *mut u16 when an interface calls for a BSTR. The reason being is that at the four bytes before where the BSTR pointer points to, there is a length prefix. In addition, the memory will be freed by the same allocator used in SysAllocString, which can cause UB if you didn’t allocate the memory that way. Any other allocation method will cause UB and crashes.

Example

extern crate oaidl;
extern crate widestring;
 
use oaidl::{BStringError, BStringExt};
use widestring::U16String;
 
fn main() -> Result<(), BStringError> {
    let mut ustr = U16String::from_str("testing abc1267 ?Ťũřǐꝥꞔ");
    // Automagically dropped once you leave scope. 
    let bstr = ustr.allocate_managed_bstr()?;
 
    //Unless you call .consume() on it
    // bstr.consume(); <-- THIS WILL LEAK if you don't take care.
    Ok(())
}