Share via


CComBSTR Class

This class is a wrapper for BSTRs.

class CComBSTR

Members

Public Constructors

Name

Description

CComBSTR::CComBSTR

The constructor.

CComBSTR::~CComBSTR

The destructor.

Public Methods

Name

Description

CComBSTR::Append

Appends a string to m_str.

CComBSTR::AppendBSTR

Appends a BSTR to m_str.

CComBSTR::AppendBytes

Appends a specified number of bytes to m_str.

CComBSTR::ArrayToBSTR

Creates a BSTR from the first character of each element in the safearray and attaches it to the CComBSTR object.

CComBSTR::AssignBSTR

Assigns a BSTR to m_str.

CComBSTR::Attach

Attaches a BSTR to the CComBSTR object.

CComBSTR::BSTRToArray

Creates a zero-based one-dimensional safearray, where each element of the array is a character from the CComBSTR object.

CComBSTR::ByteLength

Returns the length of m_str in bytes.

CComBSTR::Copy

Returns a copy of m_str.

CComBSTR::CopyTo

Returns a copy of m_str via an [out] parameter

CComBSTR::Detach

Detaches m_str from the CComBSTR object.

CComBSTR::Empty

Frees m_str.

CComBSTR::Length

Returns the length of m_str.

CComBSTR::LoadString

Loads a string resource.

CComBSTR::ReadFromStream

Loads a BSTR object from a stream.

CComBSTR::ToLower

Converts the string to lowercase.

CComBSTR::ToUpper

Converts the string to uppercase.

CComBSTR::WriteToStream

Saves m_str to a stream.

Public Operators

Name

Description

CComBSTR::operator BSTR

Casts a CComBSTR object to a BSTR.

CComBSTR::operator !

Returns true or false, depending on whether m_stris NULL.

CComBSTR::operator !=

Compares a CComBSTR with a string.

CComBSTR::operator &

Returns the address of m_str.

CComBSTR::operator +=

Appends a CComBSTR to the object.

CComBSTR::operator <

Compares a CComBSTR with a string.

CComBSTR::operator =

Assigns a value to m_str.

CComBSTR::operator ==

Compares a CComBSTR with a string.

CComBSTR::operator >

Compares a CComBSTR with a string.

Public Data Members

Name

Description

CComBSTR::m_str

Contains the BSTR associated with the CComBSTR object.

Remarks

The CComBSTR class is a wrapper for BSTRs, which are length-prefixed strings. The length is stored as an integer at the memory location preceding the data in the string.

A BSTR is null-terminated after the last counted character but may also contain null characters embedded within the string. The string length is determined by the character count, not the first null character.

Note

The CComBSTR class provides a number of members (constructors, assignment operators, and comparison operators) that take either ANSI or Unicode strings as arguments. The ANSI versions of these functions are less efficient than their Unicode counterparts because temporary Unicode strings are often created internally. For efficiency, use the Unicode versions where possible.

Note

Because of the improved lookup behavior implemented in Visual Studio .NET, code such as bstr = L"String2" + bstr;, which may have compiled in previous releases, should instead be implemented as bstr = CStringW(L"String2") + bstr.

For a list of cautions when using CComBSTR, see Programming with CComBSTR.

Requirements

Header: atlbase.h

See Also

Concepts

ATL and MFC String Conversion Macros

Other Resources

ATL Class Overview