Trait oaidl::BStringExt
source · pub trait BStringExt {
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(())
}
Required Methods§
sourcefn allocate_bstr(&mut self) -> Result<Ptr<u16>, BStringError>
fn allocate_bstr(&mut self) -> Result<Ptr<u16>, BStringError>
Allocates a Ptr<u16>
(aka a *mut u16
aka a BSTR)
sourcefn consume_to_bstr(self) -> Result<Ptr<u16>, BStringError>
fn consume_to_bstr(self) -> Result<Ptr<u16>, BStringError>
Allocates a Ptr<u16>
(aka a *mut u16
aka a BSTR)
Memory handling
Consumes input. Input value will be dropped.
sourcefn allocate_managed_bstr(&mut self) -> Result<DroppableBString, BStringError>
fn allocate_managed_bstr(&mut self) -> Result<DroppableBString, BStringError>
Allocates a DroppableBString
container - automatically frees the memory properly if dropped.
sourcefn consume_to_managed_bstr(self) -> Result<DroppableBString, BStringError>
fn consume_to_managed_bstr(self) -> Result<DroppableBString, BStringError>
Allocates a DroppableBString
container - automatically frees the memory properly if dropped.
Memory handling
Consumes input. Input value will be dropped.
sourcefn deallocate_bstr(bstr: Ptr<u16>)
fn deallocate_bstr(bstr: Ptr<u16>)
Manually and correctly free the memory allocated via Sys* methods
sourcefn from_bstr(bstr: *mut u16) -> U16String
fn from_bstr(bstr: *mut u16) -> U16String
Convenience method for conversion to a good intermediary type
sourcefn from_pbstr(bstr: Ptr<u16>) -> U16String
fn from_pbstr(bstr: Ptr<u16>) -> U16String
Convenience method for conversion to a good intermediary type
sourcefn from_boxed_bstr(bstr: Box<u16>) -> U16String
fn from_boxed_bstr(bstr: Box<u16>) -> U16String
Convenience method for conversion to a good intermediary type