Export (0) Print
Expand All

String Manipulation Functions

To handle strings that are allocated by one component and freed by another, Automation defines a special set of functions. These functions use the following data type:


typedef OLECHAR * BSTR;

These strings are zero-terminated, and in most cases they can be treated just like OLECHAR* strings. However, you can query a BSTR for its length rather than scan it, so it can contain embedded null characters. The length is stored as a 32-bit integer at the memory location preceding the data in the string. Instead of reading this location directly, applications should use the string manipulation functions to access the length of a BSTR.

Automation may cache the space allocated for BSTRs. This speeds up the SysAllocString/SysFreeString sequence. However, this may also cause IMallocSpy to assign leaks to the wrong memory user because it is not aware of the caching done by Automation.

For example, if the application allocates a BSTR and frees it, the free block of memory is put into the BSTR cache by Automation. If the application then allocates another BSTR, it can get the free block from the cache. If the second BSTR allocation is not freed, IMallocSpy will attribute the leak to the first allocation of the BSTR. You can determine the correct source of the leak (the second allocation) by disabling the BSTR caching using the debug version of Oleaut32.dll, and by setting the environment variable OANOCACHE=1 before running the application.

In this section

TopicDescription

SysAllocString

Allocates a new string and copies the passed string into it.

SysAllocStringByteLen

Takes an ANSI string as input, and returns a BSTR that contains an ANSI string. Does not perform any ANSI-to-Unicode translation.

SysAllocStringLen

Allocates a new string, copies the specified number of characters from the passed string, and appends a null-terminating character.

SysFreeString

Deallocates a string allocated previously by SysAllocString, SysAllocStringByteLen, SysReAllocString, SysAllocStringLen, or SysReAllocStringLen.

SysReAllocString

Reallocates a previously allocated string to be the size of a second string and copies the second string into the reallocated memory.

SysReAllocStringLen

Creates a new BSTR containing a specified number of characters from an old BSTR, and frees the old BSTR.

SysStringByteLen

Returns the length (in bytes) of a BSTR.

SysStringLen

Returns the length of a BSTR.

 

Note  A null pointer is a valid value for a BSTR variable. By convention, it is always treated the same as a pointer to a BSTR that contains zero characters. Also by convention, calls to functions that take a BSTR reference parameter must pass either a null pointer, or a pointer to an allocated BSTR. If the implementation of a function that takes a BSTR reference parameter assigns a new BSTR to the parameter, it must free the previously referenced BSTR.

Related topics

Conversion and Manipulation Functions

 

 

Community Additions

ADD
Show:
© 2014 Microsoft