CStringT::AllocSysString

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.

Remarks

In MFC programs, a CMemoryException Class is thrown if insufficient memory exists. In ATL programs, a CAtlException is thrown. This function is normally used to return strings for Automation.

Commonly, if this string is passed to a COM function as an [in] parameter, then this requires the caller to free the string. This can be done by using SysFreeString, as described in the Windows SDK. For more information, see Allocating and Releasing Memory for a BSTR.

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

Example

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

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str(_T("This is a test string!"));
BSTR bstr = str.AllocSysString();

// bstr now contains "This is a test string!", 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.   

Requirements

Header: cstringt.h

See Also

Reference

CStringT Class

Other Resources

CStringT Members

Change History

Date	History	Reason
July 2010	Updated to include CAtlException.	Customer feedback.