CComBSTR

class CComBSTR

The CComBSTR class is a wrapper for BSTRs, 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.

#include <atlbase.h>

See Also BSTR in the Win32 SDK


CComBSTR Class Members

Methods
AppendAppends a string to m_str.
AppendBSTRAppends a BSTR to m_str.
AttachAttaches a BSTR to the CComBSTR object.
CComBstrConstructor.
CopyReturns a copy of m_str.
DetachDetaches m_str from the CComBSTR object.
EmptyFrees m_str.
LengthReturns the length of m_str.
ReadFromStreamLoads a BSTR from a stream.
WriteToStreamSaves m_str to a stream.
Operators
operator BSTRConverts a CComBSTR object to a BSTR.
operator =Assigns a value to m_str.
operator +=Appends a CComBSTR to the object.
operator &Returns the address m_str.
operator !Returns TRUE or FALSE, depending on whether m_str is NULL.
Data Members
m_strContains the BSTR associated with the CComBSTR object.

CComBSTR Overview


Methods


CComBSTR::Append

void Append( const CComBSTR& bstrSrc );
void Append( LPCOLESTR lpsz );
void Append( LPCSTR lpsz );
void Append( LPCOLESTR lpsz, int nLen );

Parameters

bstrSrc [in] A CComBSTR object.

lpsz [in] A character string. The Unicode version specifies an LPCOLESTR; the ANSI version specifies an LPCSTR.

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

Remarks

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

CComBSTR Overview | Class Members

See Also CComBSTR::AppendBSTR, CComBSTR::operator +=


CComBSTR::AppendBSTR

void AppendBSTR( BSTR p );

Parameters

p [in] A BSTR to append.

Remarks

Appends the specified BSTR to m_str.

CComBSTR Overview | Class Members

See Also CComBSTR::Append, CComBSTR::operator +=


CComBSTR::Attach

void Attach( BSTR src );

Parameters

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

Remarks

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

Note This method will assert if m_str is non-NULL.

CComBSTR Overview | Class Members

See Also CComBSTR::Detach, CComBSTR::operator =


CComBSTR::CComBSTR

CComBSTR( );
CComBSTR( int nSize, LPCOLESTR sz = NULL );
CComBSTR( int nSize, LPCSTR sz = NULL );
CComBSTR( LPCOLESTR pSrc );
CComBSTR( LPCSTR pSrc );
CComBSTR( const CComBSTR& src );

Parameters

nSize [in] The number of characters to copy from sz.

sz [in] A string to copy. The Unicode version specifies an LPCOLESTR; the ANSI version specifies an LPCSTR. Only nSize characters will be copied. The default value is NULL.

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

src [in] A CComBSTR object.

Remarks

The default constructor sets the m_str member to NULL. The copy constructor sets m_str to a copy of the BSTR member of src.

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

The destructor frees the string pointed to by m_str.

CComBSTR Overview | Class Members


CComBSTR::Copy

BSTR Copy( ) const;

Return Value

A copy of the m_str.

Remarks

Allocates and returns a copy of m_str.

CComBSTR Overview | Class Members


CComBSTR::Detach

BSTR Detach( );

Return Value

The BSTR associated with the CComBSTR object.

Remarks

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

CComBSTR Overview | Class Members

See Also CComBSTR::Attach


CComBSTR::Empty

void Empty( );

Remarks

Frees the m_str member.

CComBSTR Overview | Class Members


CComBSTR::Length

unsigned int Length( ) const;

Return Value

The length of the m_str member.

Remarks

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

CComBSTR Overview | Class Members


CComBSTR::ReadFromStream

HRESULT ReadFromStream( IStream* pStream );

Return Value

A standard HRESULT value.

Parameters

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

Remarks

Sets the m_str member to the BSTR contained in the specified stream. ReadToStream requires a previous call to WriteToStream.

CComBSTR Overview | Class Members

See Also IStream in the Win32 SDK


CComBSTR::WriteToStream

HRESULT WriteToStream( IStream* pStream );

Return Value

A standard HRESULT value.

Parameters

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

Remarks

Saves the m_str member to a stream.

CComBSTR Overview | Class Members

See Also CComBSTR::ReadFromStream, IStream in the Win32 SDK


Operators


CComBSTR::operator BSTR

operator BSTR( ) const;

Remarks

Converts a CComBSTR object to a BSTR.

CComBSTR Overview | Class Members


CComBSTR::operator =

CComBSTR& operator =( LPCOLESTR pSrc );
CComBSTR& operator =( LPCSTR
pSrc );
CComBSTR& operator =( const CComBSTR& src );

Remarks

Sets the m_str member to a copy of pSrc or to a copy of the BSTR member of src. The pSrc parameter specifies either an LPCOLESTR for Unicode versions or LPCSTR for ANSI versions.

CComBSTR Overview | Class Members


CComBSTR::operator +=

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

Remarks

Appends the BSTR member of bstrSrc to m_str.

CComBSTR Overview | Class Members

See Also CComBSTR::Append, CComBSTR::AppendBSTR


CComBSTR::operator &

BSTR* operator &( );

Remarks

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

CComBSTR Overview | Class Members


CComBSTR::operator !

BOOL operator !( );

Remarks

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

CComBSTR Overview | Class Members


Data Members


CComBSTR::m_str

BSTR m_str;

Remarks

Contains the BSTR associated with the CComBSTR object.

CComBSTR Overview | Class Members