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
Methods | |
Append | Appends a string to m_str. |
AppendBSTR | Appends a BSTR to m_str. |
Attach | Attaches a BSTR to the CComBSTR object. |
CComBstr | Constructor. |
Copy | Returns a copy of m_str. |
Detach | Detaches m_str from the CComBSTR object. |
Empty | Frees m_str. |
Length | Returns the length of m_str. |
ReadFromStream | Loads a BSTR from a stream. |
WriteToStream | Saves m_str to a stream. |
Operators | |
operator BSTR | Converts 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_str | Contains the BSTR associated with the CComBSTR object. |
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 +=
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 +=
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( 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
BSTR Copy( ) const;
Return Value
A copy of the m_str.
Remarks
Allocates and returns a copy of m_str.
CComBSTR Overview | Class Members
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
void Empty( );
Remarks
Frees the m_str member.
CComBSTR Overview | Class Members
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
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
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
operator BSTR( ) const;
Remarks
Converts a CComBSTR object to a BSTR.
CComBSTR Overview | Class Members
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 +=( const CComBSTR& bstrSrc );
Remarks
Appends the BSTR member of bstrSrc to m_str.
CComBSTR Overview | Class Members
See Also CComBSTR::Append, CComBSTR::AppendBSTR
BSTR* operator &( );
Remarks
Returns the address of the BSTR stored in the m_str member.
CComBSTR Overview | Class Members
BOOL operator !( );
Remarks
Returns TRUE if the m_str member is NULL; otherwise, FALSE.
CComBSTR Overview | Class Members
BSTR m_str;
Remarks
Contains the BSTR associated with the CComBSTR object.