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
| Topic | Description |
|---|---|
| SysAddRefString |
Increases the pinning reference count for the specified string by one. |
| 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. |
| SysReleaseString |
Decreases the pinning reference count for the specified string by one. When that count reaches 0, the memory for that string is no longer prevented from being freed. |
| 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.