BSTR class

A string data type that is commonly used by OLE Automation, as well as some COM methods.

BSTR types differ from Pointer<Utf16> in that they include a four byte prefix stored immediately prior to the string itself that represents its length in bytes. The pointer points to the first character of the data string, not to the length prefix.

BSTRs should never be created using Dart's memory allocation functions. For instance, the following code is incorrect, since it does not allocate and store the length prefix.

final bstr = 'I am a happy BSTR'.toNativeUtf16();

This class wraps the COM memory allocation functions so that BSTR types can be created without concern. Instead of the above code, you can write:

final bstr = BSTR.fromString('I am a happy BSTR');

A debugger that examines the four bytes prior to this location will see a 32-bit int containing the value 34, representing the length of the string in Utf-16.

Dart does not garbage collect BSTR objects; instead, you are responsible for freeing the memory allocated for a BSTR when it is no longer used. To release its memory, you can call an object's free method.

Constructors

BSTR.fromString(String str)
Create a BSTR from a given Dart string.
factory

Properties

byteLength int
Returns the length in bytes.
no setter
hashCode int
The hash code for this object.
no setterinherited
length int
Returns the length in characters.
no setter
ptr Pointer<Utf16>
A pointer to the start of the string itself.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited

Methods

clone() BSTR
Allocates a new string that is a copy of the existing string.
free() → void
Releases the native memory allocated to the BSTR.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() String
Returns the contents of the BSTR as a regular Dart string.
override

Operators

operator +(BSTR other) BSTR
Concatenate two BSTR objects and returns a newly-allocated object with the results.
operator ==(Object other) bool
The equality operator.
inherited