This documentation is archived and is not being maintained.


Allocates an Automation–compatible string of the type BSTR and copies the contents of the CStringT object into it, including the terminating null character.

BSTR AllocSysString() const;

Return Value

The newly allocated string.


A CMemoryException is thrown if insufficient memory exists. This function is normally used to return strings for Automation.

Commonly, if this string is passed to a COM function (as an [in] parameter) this requires the caller to free the string. This can be done by using SysFreeString, as described in the Platform SDK. See Strings: Allocating and Releasing Memory for a BSTR for more information on determining when the string is freed by the caller.

For more information about OLE allocation functions in Windows, see SysAllocString in the Platform SDK.


The following example demonstrates the use of CStringT::AllocSysString.

//typedef CStringT< TCHAR, StrTraitATL< TCHAR > > CAtlString;

CAtlString str("Soccer is best!");
BSTR bstr = str.AllocSysString();

// bstr now contains "Soccer is best!", and can be
// passed to any OLE function requiring a BSTR.
// Normally, if you pass the BSTR, you will
// need to free the string after returning from the function call.

See Also

CStringT Overview | Class Members