Struct intercom::BString

pub struct BString(_);

An owned BSTR string Rust type.

Used for passing strings with their ownership through the COM interfaces.

BSTR details

The BSTR is both a length prefixed and zero terminated string with UTF-16 encoding. It is the string type widely used with Microsoft COM for interoperability purposes.

What makes the BSTR exotic is that the *mut u16 pointer references the start of the string data. The length prefix is located before the pointed value.

It is important to note that when COM servers return BSTR strings, they pass ownership of the string to the COM client. After this the COM client is responsible for de-allocating the memory. Because of this it is important that the memory allocation for BSTR values is well defined.

On Windows this means allocating the strings using SysAllocString or SysAllocStringLen methods and freeing them with SysFreeString by default.

Implementations

impl BString

pub unsafe fn from_ptr(ptr: *mut u16) -> BString

Safety

The parameter must be a valid BSTR pointer. This includes both the memory layout and allocation using BSTR-compatible allocation functions.

In addition the pointer ownership moves to the BString and the pointer must not be freed outside of BString drop.

pub fn from_cstr(s: &CStr) -> Result<BString, Utf8Error>

Converts a C-string into a BString.

pub fn as_mut_ptr(&mut self) -> *mut u16

Returns the pointer as a 16-bit wide character pointer.

pub fn into_ptr(self) -> *mut u16

Converts the BString into a raw pointer.

Methods from Deref<Target = BStr>

pub fn as_ptr(&self) -> *const u16

Returns the pointer as a 16-bit wide character pointer.

pub fn len_bytes(&self) -> u32

Returns the string length in bytes.

Does not include the length prefix or the terminating zero. However any zero bytes in the middle of the string are included.

pub fn len(&self) -> u32

Returns the string length in characters.

pub fn is_empty(&self) -> bool

pub fn as_slice(&self) -> &[u8]

Gets the BStr as a slice of 16-bit characters.

pub fn to_string(&self) -> Result<String, FormatError>

Trait Implementations

impl AsRef<BStr> for BString

fn as_ref(&self) -> &BStr

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<BStr> for BString

fn borrow(&self) -> &BStr

Immutably borrows from an owned value.

impl Clone for BString

fn clone(&self) -> BString

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BString

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BString

fn default() -> BString

Returns the “default value” for a type.

impl Deref for BString

type Target = BStr

The resulting type after dereferencing.

fn deref(&self) -> &BStr

Dereferences the value.

impl Drop for BString

fn drop(&mut self)

Executes the destructor for this type.

impl ExternInput<AutomationTypeSystem> for BString

type Lease = BString

unsafe fn into_foreign_parameter(
    self
) -> ComResult<(Self::ForeignType, Self::Lease)>

Safety

type Owned = BString

unsafe fn from_foreign_parameter(
    source: Self::ForeignType
) -> ComResult<Self::Owned>

Safety

impl ExternInput<RawTypeSystem> for BString

type Lease = CString

unsafe fn into_foreign_parameter(
    self
) -> ComResult<(Self::ForeignType, Self::Lease)>

Safety

type Owned = BString

unsafe fn from_foreign_parameter(
    source: Self::ForeignType
) -> ComResult<Self::Owned>

Safety

impl ExternOutput<AutomationTypeSystem> for BString

fn into_foreign_output(self) -> ComResult<Self::ForeignType>

unsafe fn from_foreign_output(source: Self::ForeignType) -> ComResult<Self>

Safety

unsafe fn drop_foreign_output(source: Self::ForeignType)

Safety

impl ExternOutput<RawTypeSystem> for BString

fn into_foreign_output(self) -> ComResult<Self::ForeignType>

unsafe fn from_foreign_output(source: Self::ForeignType) -> ComResult<Self>

Safety

unsafe fn drop_foreign_output(source: Self::ForeignType)

Safety

impl ExternType<AutomationTypeSystem> for BString

type ForeignType = BSTR

impl ExternType<RawTypeSystem> for BString

type ForeignType = *mut i8

impl<'a> From<&'a str> for BString

fn from(source: &str) -> BString

Converts to this type from the input type.

impl From<BString> for IntercomString

fn from(source: BString) -> Self

Converts to this type from the input type.

impl From<String> for BString

fn from(source: String) -> BString

Converts to this type from the input type.

impl FromStr for BString

fn from_str(s: &str) -> Result<BString, Self::Err>

Converts a Rust string into a BString.

type Err = Infallible

The associated error which can be returned from parsing.

impl PartialEq<BString> for BString

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl TryFrom<IntercomString> for BString

type Error = ComError

The type returned in the event of a conversion error.

fn try_from(source: IntercomString) -> Result<BString, ComError>

Performs the conversion.

impl TryFrom<Variant> for BString

type Error = VariantError

The type returned in the event of a conversion error.

fn try_from(src: Variant) -> Result<BString, Self::Error>

Performs the conversion.