This class is a wrapper for BSTRs.

class CComBSTR

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.

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

Header: atlbase.h

Appends either lpsz or the BSTR member of bstrSrc to m_str.

HRESULT Append(const CComBSTR& bstrSrc) throw();
HRESULT Append(wchar_t ch) throw();
HRESULT Append(char ch) throw();
HRESULT Append(LPCOLESTR lpsz) throw();
HRESULT Append(LPCSTR lpsz) throw();
HRESULT Append(LPCOLESTR lpsz, int nLen) throw();

bstrSrc
[in] A CComBSTR object to append.

ch
[in] A character to append.

lpsz
[in] A zero-terminated character string to append. You can pass a Unicode string via the LPCOLESTR overload or an ANSI string via the LPCSTR version.

nLen
[in] The number of characters from lpsz to append.

S_OK on success, or any standard HRESULT error value.

An ANSI string will be converted to Unicode before being appended.

[!code-cppNVC_ATL_Utilities#32]

Appends the specified BSTR to m_str.

HRESULT AppendBSTR(BSTR p) throw();

p
[in] A BSTR to append.

S_OK on success, or any standard HRESULT error value.

Do not pass an ordinary wide-character string to this method. The compiler cannot catch the error and run time errors will occur.

[!code-cppNVC_ATL_Utilities#33]

Appends the specified number of bytes to m_str without conversion.

HRESULT AppendBytes(const char* lpsz, int nLen) throw();

lpsz
[in] A pointer to an array of bytes to append.

p
[in] The number of bytes to append.

S_OK on success, or any standard HRESULT error value.

[!code-cppNVC_ATL_Utilities#34]

Frees any existing string held in the CComBSTR object, then creates a BSTR from the first character of each element in the safearray and attaches it to the CComBSTR object.

HRESULT ArrayToBSTR(const SAFEARRAY* pSrc) throw();

pSrc
[in] The safearray containing the elements used to create the string.

S_OK on success, or any standard HRESULT error value.

Assigns a BSTR to m_str.

HRESULT AssignBSTR(const BSTR bstrSrc) throw();

bstrSrc
[in] A BSTR to assign to the current CComBSTR object.

S_OK on success, or any standard HRESULT error value.

Attaches a BSTR to the CComBSTR object by setting the m_str member to src.

void Attach(BSTR src) throw();

src
[in] The BSTR to attach to the object.

Do not pass an ordinary wide-character string to this method. The compiler cannot catch the error and run time errors will occur.

[!code-cppNVC_ATL_Utilities#35]

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

HRESULT BSTRToArray(LPSAFEARRAY* ppArray) throw();

ppArray
[out] The pointer to the safearray used to hold the results of the function.

S_OK on success, or any standard HRESULT error value.

Returns the number of bytes in m_str, excluding the terminating null character.

unsigned int ByteLength() const throw();

The length of the m_str member in bytes.

Returns 0 if m_str is NULL.

[!code-cppNVC_ATL_Utilities#36]

The constructor. The default constructor sets the m_str member to NULL.

CComBSTR() throw();
CComBSTR(const CComBSTR& src);
CComBSTR(REFGUID  guid);
CComBSTR(int nSize);
CComBSTR(int nSize, LPCOLESTR sz);
CComBSTR(int nSize, LPCSTR sz);
CComBSTR(LPCOLESTR pSrc);
CComBSTR(LPCSTR pSrc);
CComBSTR(CComBSTR&& src) throw(); // (Visual Studio 2017)

nSize
[in] The number of characters to copy from sz or the initial size in characters for the CComBSTR.

sz
[in] A string to copy. The Unicode version specifies an LPCOLESTR; the ANSI version specifies an LPCSTR.

pSrc
[in] A string to copy. The Unicode version specifies an LPCOLESTR; the ANSI version specifies an LPCSTR.

src
[in] A CComBSTR object.

guid
[in] A reference to a GUID structure.

The copy constructor sets m_str to a copy of the BSTR member of src. The REFGUID constructor converts the GUID to a string using StringFromGUID2 and stores the result.

The other constructors set m_str to a copy of the specified string. If you pass a value for nSize, then only nSize characters will be copied, followed by a terminating null character.

CComBSTR supports move semantics. You can use the move constructor (the constructor that takes an rvalue reference (&&) to create a new object that uses the same underlying data as the old object you pass in as an argument, without the overhead of copying the object.

The destructor frees the string pointed to by m_str.

[!code-cppNVC_ATL_Utilities#37]

The destructor.

~CComBSTR();

The destructor frees the string pointed to by m_str.

Allocates and returns a copy of m_str.

BSTR Copy() const throw();

A copy of the m_str member. If m_str is NULL, returns NULL.

[!code-cppNVC_ATL_Utilities#38]

Allocates and returns a copy of m_str via the parameter.

HRESULT CopyTo(BSTR* pbstr) throw();

HRESULT CopyTo(VARIANT* pvarDest) throw();

pbstr
[out] The address of a BSTR in which to return the string allocated by this method.

pvarDest
[out] The address of a VARIANT in which to return the string allocated by this method.

A standard HRESULT value indicating the success or failure of the copy.

After calling this method, the VARIANT pointed to by pvarDest will be of type VT_BSTR.

[!code-cppNVC_ATL_Utilities#39]

Detaches m_str from the CComBSTR object and sets m_str to NULL.

BSTR Detach() throw();

The BSTR associated with the CComBSTR object.

[!code-cppNVC_ATL_Utilities#40]

Frees the m_str member.

void Empty() throw();

[!code-cppNVC_ATL_Utilities#41]

Returns the number of characters in m_str, excluding the terminating null character.

unsigned int Length() const throw();

The length of the m_str member.

[!code-cppNVC_ATL_Utilities#42]

Loads a string resource specified by nID and stores it in this object.

bool LoadString(HINSTANCE hInst, UINT nID) throw();
bool LoadString(UINT nID) throw();

See LoadString in the Windows SDK.

Returns TRUE if the string is successfully loaded; otherwise, returns FALSE.

The first function loads the resource from the module identified by you via the hInst parameter. The second function loads the resource from the resource module associated with the CComModule-derived object used in this project.

[!code-cppNVC_ATL_Utilities#43]

Contains the BSTR associated with the CComBSTR object.

BSTR m_str;

[!code-cppNVC_ATL_Utilities#49]

Casts a CComBSTR object to a BSTR.

operator BSTR() const throw();

Allows you to pass CComBSTR objects to functions that have [in] BSTR parameters.

See the example for CComBSTR::m_str.

Checks whether BSTR string is NULL.

bool operator!() const throw();

Returns TRUE if the m_str member is NULL; otherwise, FALSE.

This operator only checks for a NULL value, not for an empty string.

[!code-cppNVC_ATL_Utilities#35]

Returns the logical opposite of operator ==.

bool operator!= (const CComBSTR& bstrSrc) const throw();
bool operator!= (LPCOLESTR pszSrc) const;
bool operator!= (LPCSTR pszSrc) const;
bool operator!= (int nNull) const throw();

bstrSrc
[in] A CComBSTR object.

pszSrc
[in] A zero-terminated string.

nNull
[in] Must be NULL.

Returns TRUE if the item being compared is not equal to the CComBSTR object; otherwise, returns FALSE.

CComBSTRs are compared textually in the context of the user's default locale. The final comparison operator just compares the contained string against NULL.

Returns the address of the BSTR stored in the m_str member.

BSTR* operator&() throw();

CComBstr operator & has a special assertion associated with it to help identify memory leaks. The program will assert when the m_str member is initialized. This assertion was created to identify situations where a programmer uses the & operator to assign a new value to m_str member without freeing the first allocation of m_str. If m_str equals NULL, the program assumes that m_str wasn't allocated yet. In this case, the program will not assert.

This assertion is not enabled by default. Define ATL_CCOMBSTR_ADDRESS_OF_ASSERT to enable this assertion.

[!code-cppNVC_ATL_Utilities#46]

[!code-cppNVC_ATL_Utilities#47]

Appends a string to the CComBSTR object.

CComBSTR& operator+= (const CComBSTR& bstrSrc);
CComBSTR& operator+= (const LPCOLESTR pszSrc);

bstrSrc
[in] A CComBSTR object to append.

pszSrc
[in] A zero-terminated string to append.

CComBSTRs are compared textually in the context of the user's default locale. The LPCOLESTR comparison is done using memcmp on the raw data in each string. The LPCSTR comparison is carried out in the same way once a temporary Unicode copy of pszSrc has been created. The final comparison operator just compares the contained string against NULL.

[!code-cppNVC_ATL_Utilities#48]

Compares a CComBSTR with a string.

bool operator<(const CComBSTR& bstrSrc) const throw();
bool operator<(LPCOLESTR pszSrc) const throw();
bool operator<(LPCSTR pszSrc) const throw();

Returns TRUE if the item being compared is less than the CComBSTR object; otherwise, returns FALSE.

The comparison is performed using the user's default locale.

Sets the m_str member to a copy of pSrc or to a copy of the BSTR member of src. The move assignment operator moves src without copying it.

CComBSTR& operator= (const CComBSTR& src);
CComBSTR& operator= (LPCOLESTR pSrc);
CComBSTR& operator= (LPCSTR pSrc);
CComBSTR& operator= (CComBSTR&& src) throw(); // (Visual Studio 2017)

The pSrc parameter specifies either an LPCOLESTR for Unicode versions or LPCSTR for ANSI versions.

See the example for CComBSTR::Copy.

Compares a CComBSTR with a string. CComBSTRs are compared textually in the context of the user's default locale.

bool operator== (const CComBSTR& bstrSrc) const throw();
bool operator== (LPCOLESTR pszSrc) const;
bool operator== (LPCSTR pszSrc) const;
bool operator== (int nNull) const throw();

bstrSrc
[in] A CComBSTR object.

pszSrc
[in] A zero-terminated string.

nNull
[in] Must be NULL.

Returns TRUE if the item being compared is equal to the CComBSTR object; otherwise, returns FALSE.

The final comparison operator just compares the contained string against NULL.

Compares a CComBSTR with a string.

bool operator>(const CComBSTR& bstrSrc) const throw();

Returns TRUE if the item being compared is greater than the CComBSTR object; otherwise, returns FALSE.

The comparison is performed using the user's default locale.

Sets the m_str member to the BSTR contained in the specified stream.

HRESULT ReadFromStream(IStream* pStream) throw();

pStream
[in] A pointer to the IStream interface on the stream containing the data.

A standard HRESULT value.

ReadToStream requires the contents of the stream at the current position to be compatible with the data format written out by a call to WriteToStream.

[!code-cppNVC_ATL_Utilities#44]

Converts the contained string to lowercase.

HRESULT ToLower() throw();

A standard HRESULT value.

See CharLowerBuff for more information on how the conversion is performed.

Converts the contained string to uppercase.

HRESULT ToUpper() throw();

A standard HRESULT value.

See CharUpperBuff for more information on how the conversion is performed.

Saves the m_str member to a stream.

HRESULT WriteToStream(IStream* pStream) throw();

pStream
[in] A pointer to the IStream interface on a stream.

A standard HRESULT value.

You can recreate a BSTR from the contents of the stream using the ReadFromStream function.

[!code-cppNVC_ATL_Utilities#45]

Class Overview
ATL and MFC String Conversion Macros