ArcGIS Engine Developer Guide

VISUAL C++
switches are used to change Windows API functions (for example,
SetWindowText) to resolve to an ANSI version (SetWindowTextA) or a Unicode
version (SetWindowTextW). In addition, character-independent types (TCHAR
defined in tchar.h) were introduced to represent a character; on an ANSI build
this is defined to be a char, and on a Unicode build this is a wchar_t, a typedef
defined as unsigned short. To perform standard C string manipulation, there are
typically three different definitions of the same function; for example, for a caseinsensitive
comparison, strcmp provides the ANSI version, wcscmp provides the
Unicode version, and _tcscmp provides the TCHAR version. There is also a fourth
version—_mbscmp—which is a variation of the 8-bit ANSI version that will
interpret multibyte character sequences (MBCS) within the 8-bit string.
To check if two CComBSTR strings are different,
do not use the not equal (“!=”) operator. The
“==” operator performs a case-sensitive comparison
of the string contents; however, “!=” will
compare pointer values and not the string
contents, typically returning false.
106 • ArcGIS Engine Developer Guide
// Initialize some fixed length strings.
char* pNameANSI = "Bill"; // 5 bytes (4 characters plus a terminator)
wchar_t* pNameUNICODE = L"Bill"; // 10 bytes (4 16-bit characters plus a
16-bit terminator)
TCHAR* pNameTCHAR = _T("Bill"); // either 5 or 10 depending on compiler
settings
COM APIs represent variable length strings with a BSTR type; this is a pointer to
a sequence of OLECHAR characters, which is defined as Unicode characters and
is the same as a wchar_t. A BSTR must be allocated and released with the
SysAllocString and SysFreeString windows functions. Unlike C strings, they can
contain embedded zero characters, although this is unusual. The BSTR also has a
count value, which is stored four bytes before the BSTR pointer address. The
CComBSTR wrappers are often used to manage the lifetime of a string.
Do not pass a pointer to a C style array of Unicode characters (OLECHAR or
wchar_t) to a function expecting a BSTR. The compiler will not raise an error as
the types are identical. However, the function receiving the BSTR can behave
incorrectly or crash when accessing the string length, which will be random
memory values.
ipFoo->put_WindowTitle(L"Hello"); // This is bad!
ipFoo->put_WindowTitle(CComBSTR(L"Hello")); // This correctly initializes
and passes a BSTR.
ATL provides conversion macros to switch strings between ANSI (A), TCHAR
(T), Unicode (W), and OLECHAR (OLE). In addition, the types can have a
const modifier (C). These macros use the abbreviations shown in brackets with a
“2” between them. For example, to convert between OLECHAR (such as an
input BSTR) to const TCHAR (for use in a Windows function), use the OLE2CT
conversion macro. To convert ANSI to Unicode, use A2W. These macros require
the USES_CONVERSION macro to be placed at the top of a method; this will
create some local variables that are used by the conversion macros. When the
source and destination character sets are different and the destination type is not
a BSTR, the macro allocates the destination string on the call stack (using the
_alloca runtime function). It’s important to realize this especially when using
these macros within a loop; otherwise, the stack may grow large and run out of
stack space.
STDMETHODIMP CFoo::put_WindowTitle(BSTR bstrTitle)
{
USES_CONVERSION;
if (::SysStringLen(bstrTitle) == 0)
return E_INVALIDARG;