CComBSTR Classe

Esta classe é um wrapper para BSTRs.

Sintaxe

class CComBSTR

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Membros de Dados Públicos

Observações

A CComBSTR classe é um wrapper para BSTRs, que são cadeias com prefixo de comprimento. O comprimento é armazenado como um inteiro na localização de memória anterior aos dados na cadeia.

A BSTR é terminado por nulo após o último carácter contado, mas pode também conter caracteres nulos embutidos na cadeia. O comprimento da cadeia é determinado pelo número de caracteres, não pelo primeiro carácter nulo.

Para uma lista de avisos ao usar CComBSTR, veja Programação com CComBSTR.

Requerimentos

Cabeçalho:atlbase.h

CComBSTR::Append

Acrescenta ou lpsz ou o membro BSTR de bstrSrc a 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();

Parâmetros

bstrSrc
[dentro] Um CComBSTR objeto para acrescentar.

ch
[dentro] Um carácter para acrescentar.

lpsz
[dentro] Uma cadeia de caracteres terminada a zero para adicionar. Podes passar uma string Unicode através do LPCOLESTR overload ou uma string ANSI através da LPCSTR versão.

nLen
[dentro] O número de caracteres de lpsz para anexar.

Valor de retorno

S_OK em caso de sucesso, ou qualquer valor de erro padrão HRESULT .

Observações

Uma cadeia ANSI será convertida para Unicode antes de ser adicionada.

Example

enum { urlASP, urlHTM, urlISAPI } urlType;
urlType = urlASP;

CComBSTR bstrURL = OLESTR("http://SomeSite/");
CComBSTR bstrDEF = OLESTR("/OtherSite");
CComBSTR bstrASP = OLESTR("default.asp");

CComBSTR bstrTemp;
HRESULT hr;

switch (urlType)
{
case urlASP:
   // bstrURL is 'http://SomeSite/default.asp'
   hr = bstrURL.Append(bstrASP);
   break;

case urlHTM:
   // bstrURL is 'http://SomeSite/default.htm'
   hr = bstrURL.Append(OLESTR("default.htm"));
   break;

case urlISAPI:
   // bstrURL is 'http://SomeSite/default.dll?func'
   hr = bstrURL.Append(OLESTR("default.dll?func"));
   break;

default:
   // bstrTemp is 'http://'
   hr = bstrTemp.Append(bstrURL, 7);
   // bstrURL is 'http://OtherSite'
   if (hr == S_OK)
       hr = bstrTemp.Append(bstrDEF);
   bstrURL = bstrTemp;

   break;
}

CComBSTR::AppendBSTR

Acrescenta o especificado BSTR a m_str.

HRESULT AppendBSTR(BSTR p) throw();

Parâmetros

p
[dentro] A BSTR para acrescentar.

Valor de retorno

S_OK em caso de sucesso, ou qualquer valor de erro padrão HRESULT .

Observações

Não passe uma cadeia comum de caracteres largos a este método. O compilador não consegue detetar o erro e ocorrerão erros em tempo de execução.

Example

CComBSTR bstrPre(OLESTR("Hello "));
CComBSTR bstrSuf(OLESTR("World!"));
HRESULT hr;

// Appends "World!" to "Hello "
hr = bstrPre.AppendBSTR(bstrSuf);

// Displays a message box with text "Hello World!"
::MessageBox(NULL, CW2CT(bstrPre), NULL, MB_OK);   

CComBSTR::AppendBytes

Acrescenta o número especificado de bytes a m_str sem conversão.

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

Parâmetros

lpsz
[dentro] Um apontador para um array de bytes a acrescentar.

p
[dentro] O número de bytes a acrescentar.

Valor de retorno

S_OK em caso de sucesso, ou qualquer valor de erro padrão HRESULT .

Example

CComBSTR bstrPre(OLESTR("Hello "));
HRESULT hr;

// Appends "Wo" to "Hello " (4 bytes == 2 characters)
hr = bstrPre.AppendBytes(reinterpret_cast<char*>(OLESTR("World!")), 4);

// Displays a message box with text "Hello Wo"
::MessageBox(NULL, CW2CT(bstrPre), NULL, MB_OK);   

CComBSTR::ArrayToBSTR

Liberta qualquer string existente contida no CComBSTR objeto, depois cria a BSTR partir do primeiro carácter de cada elemento no safearray e anexa-o ao CComBSTR objeto.

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

Parâmetros

pSrc
[dentro] O safearray que contém os elementos usados para criar a cadeia.

Valor de retorno

S_OK em caso de sucesso, ou qualquer valor de erro padrão HRESULT .

CComBSTR::AssignBSTR

Atribui a BSTR a m_stra .

HRESULT AssignBSTR(const BSTR bstrSrc) throw();

Parâmetros

bstrSrc
[dentro] Um BSTR para atribuir ao objeto atual CComBSTR .

Valor de retorno

S_OK em caso de sucesso, ou qualquer valor de erro padrão HRESULT .

CComBSTR::Attach

Anexa a BSTR ao CComBSTR objeto definindo o m_str elemento para src.

void Attach(BSTR src) throw();

Parâmetros

src
[dentro] O BSTR para se prender ao objeto.

Observações

Não passe uma cadeia comum de caracteres largos a este método. O compilador não consegue detetar o erro e ocorrerão erros em tempo de execução.

Example

// STDMETHOD(BSTRToUpper)(/*[in, out]*/ BSTR bstrConv);
STDMETHODIMP InplaceBSTRToUpper(BSTR bstrConv)
{
   // Assign bstrConv to m_str member of CComBSTR
   CComBSTR bstrTemp;
   bstrTemp.Attach(bstrConv); 

   // Make sure BSTR is not NULL string
   if (!bstrTemp)
        return E_POINTER;

   // Make string uppercase 
   HRESULT hr;
   hr = bstrTemp.ToUpper();
   if (hr != S_OK)
       return hr;

   // Set m_str to NULL, so the BSTR is not freed
   bstrTemp.Detach(); 

   return S_OK; 
}

CComBSTR::BSTRToArray

Cria um safearray unidimensional baseado em zero, onde cada elemento do array é um carácter do CComBSTR objeto.

HRESULT BSTRToArray(LPSAFEARRAY* ppArray) throw();

Parâmetros

ppArray
[fora] O ponteiro para o safearray usado para armazenar os resultados da função.

Valor de retorno

S_OK em caso de sucesso, ou qualquer valor de erro padrão HRESULT .

CComBSTR::ByteLength

Devolve o número de bytes em m_str, excluindo o carácter nulo que termina.

unsigned int ByteLength() const throw();

Valor de retorno

O comprimento do m_str membro em bytes.

Observações

Retorna 0 se m_str for NULL.

Example

// string with 11 chars (22 bytes)
CComBSTR bstrTemp(OLESTR("Hello World"));

unsigned int len = bstrTemp.ByteLength();

ATLASSERT(len == 22);   

CComBSTR::CComBSTR

O construtor. O construtor padrão define o m_str elemento para 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)

Parâmetros

nSize
[dentro] O número de caracteres a copiar sz ou o tamanho inicial em caracteres para o CComBSTR.

sz
[dentro] Uma sequência para copiar. A versão Unicode especifica um LPCOLESTR; a versão ANSI especifica um LPCSTR.

pSrc
[dentro] Uma sequência para copiar. A versão Unicode especifica um LPCOLESTR; a versão ANSI especifica um LPCSTR.

src
[dentro] Um CComBSTR objeto.

guid
[dentro] Uma referência a uma GUID estrutura.

Observações

O construtor de cópias define m_str para uma cópia do membro BSTR de src. O REFGUID construtor converte o GUID numa string usando StringFromGUID2 e armazena o resultado.

Os outros construtores definem m_str para uma cópia da cadeia especificada. Se passar um valor para nSize, então apenas nSize os caracteres serão copiados, seguidos de um carácter nulo que termina.

CComBSTR suporta a semântica do movimento. Pode usar o construtor move (o construtor que recebe uma referência rvalue (&&) para criar um novo objeto que use os mesmos dados subjacentes do objeto antigo que passa como argumento, sem a sobrecarga de copiar o objeto.

O destruidor liberta a corda apontada por m_str.

Example

CComBSTR bstr1;   // BSTR points to NULL
bstr1 = "Bye";    // initialize with assignment operator
                  // ANSI string is converted to wide char

OLECHAR* str = OLESTR("Bye bye!");  // wide char string of length 5
int len = (int)wcslen(str);
CComBSTR bstr2(len + 1);// unintialized BSTR of length 6
wcsncpy_s(bstr2.m_str, bstr2.Length(), str, len); // copy wide char string to BSTR

CComBSTR bstr3(5, OLESTR("Hello World")); // BSTR containing 'Hello', 
                                          // input string is wide char
CComBSTR bstr4(5, "Hello World");         // same as above, input string 
                                          // is ANSI

CComBSTR bstr5(OLESTR("Hey there")); // BSTR containing 'Hey there', 
                                     // input string is wide char
CComBSTR bstr6("Hey there");         // same as above, input string 
                                     // is ANSI

CComBSTR bstr7(bstr6);     // copy constructor, bstr7 contains 'Hey there'   

CComBSTR::~CComBSTR

O destruidor.

~CComBSTR();

Observações

O destruidor liberta a corda apontada por m_str.

CComBSTR::Copy

Aloca e devolve uma cópia de m_str.

BSTR Copy() const throw();

Valor de retorno

Uma cópia do m_str membro. Se m_str for NULL, retorna NULL.

Example

CComBSTR m_bstrURL;    // BSTR representing a URL

// put_URL is the put method for the URL property. 
STDMETHOD(put_URL)(BSTR strURL)
{
    ATLTRACE(_T("put_URL\n"));

    // free existing string in m_bstrURL & make a copy 
    // of strURL pointed to by m_bstrURL
    m_bstrURL = strURL;
    return S_OK;
}

// get_URL is the get method for the URL property. 
STDMETHOD(get_URL)(BSTR* pstrURL)
{
    ATLTRACE(_T("get_URL\n"));

    // make a copy of m_bstrURL pointed to by pstrURL
    *pstrURL = m_bstrURL.Copy(); // See CComBSTR::CopyTo
    return S_OK;
}

CComBSTR::CopyTo

Aloca e devolve uma cópia de m_str através do parâmetro.

HRESULT CopyTo(BSTR* pbstr) throw();

HRESULT CopyTo(VARIANT* pvarDest) throw();

Parâmetros

pbstr
[fora] O endereço de a BSTR no qual devolver a cadeia atribuída por este método.

pvarDest
[fora] O endereço de a VARIANT no qual devolver a cadeia atribuída por este método.

Valor de retorno

Um valor padrão HRESULT que indica o sucesso ou fracasso da cópia.

Observações

Após chamar este método, o VARIANT apontado por pvarDest será do tipo VT_BSTR.

Example

CComBSTR m_bstrURL; // BSTR representing a URL

// get_URL is the get method for the URL property. 
STDMETHOD(get_URL)(BSTR* pstrURL)
{
   // Make a copy of m_bstrURL and return it via pstrURL
   return m_bstrURL.CopyTo(pstrURL);
}

CComBSTR::Detach

separa-se m_str do CComBSTR objeto e define m_str para NULL.

BSTR Detach() throw();

Valor de retorno

O BSTR associado ao CComBSTR objeto.

Example

// Method which converts bstrIn to uppercase 
STDMETHODIMP BSTRToUpper(BSTR bstrIn, BSTR* pbstrOut)
{ 
    if (bstrIn == NULL || pbstrOut == NULL) 
        return E_POINTER; 

    // Create a temporary copy of bstrIn
    CComBSTR bstrTemp(bstrIn); 

    if (!bstrTemp) 
        return E_OUTOFMEMORY; 

    // Make string uppercase
    HRESULT hr;
    hr = bstrTemp.ToUpper();
    if (hr != S_OK)
        return hr;
    
    // Return m_str member of bstrTemp 
    *pbstrOut = bstrTemp.Detach(); 

    return S_OK; 
}

CComBSTR::Empty

Liberta o m_str membro.

void Empty() throw();

Example

CComBSTR bstr(OLESTR("abc"));

// Calls SysFreeString to free the BSTR
bstr.Empty();
ATLASSERT(bstr.Length() == 0);   

CComBSTR::Length

Devolve o número de caracteres em m_str, excluindo o carácter nulo que termina.

unsigned int Length() const throw();

Valor de retorno

O comprimento do m_str membro.

Example

// string with 11 chars
CComBSTR bstrTemp(OLESTR("Hello World"));

unsigned int len = bstrTemp.Length();

ATLASSERT(len == 11);

CComBSTR::LoadString

Carrega um recurso de string especificado por nID e armazena-o neste objeto.

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

Parâmetros

Veja LoadString no SDK do Windows.

Valor de retorno

Retorna TRUE se a cadeia for carregada com sucesso; caso contrário, retorna FALSE.

Observações

A primeira função carrega o recurso do módulo identificado por ti através do hInst parâmetro. A segunda função carrega o recurso do módulo de recursos associado ao CComModuleobjeto derivado em usado neste projeto.

Example

CComBSTR bstrTemp;

// IDS_PROJNAME proj name stored as resource in string table
bstrTemp.LoadString(IDS_PROJNAME);

// the above is equivalent to:
// bstrTemp.LoadString(_Module.m_hInstResource, IDS_PROJNAME);

// display message box w/ proj name as title & text
::MessageBox(NULL, CW2CT(bstrTemp), CW2CT(bstrTemp), MB_OK);   

CComBSTR::m_str

Contém o associado BSTR ao CComBSTR objeto.

BSTR m_str;

Example

CComBSTR GuidToBSTR(REFGUID guid) 
{
    // 39 - length of string representation of GUID + 1
    CComBSTR b(39); 

    // Convert GUID to BSTR
    // m_str member of CComBSTR is of type BSTR. When BSTR param 
    // is required, pass the m_str member explicitly or use implicit 
    // BSTR cast operator.
    int nRet = StringFromGUID2(guid, b.m_str, 39); 

    // Above equivalent to:
    // int nRet = StringFromGUID2(guid, b, 39); 
    // implicit BSTR cast operator used for 2nd param

    // Both lines are equivalent to:
    // CComBSTR b(guid);
    // CComBSTR constructor can convert GUIDs

    ATLASSERT(nRet); 
    return b; 
}

CComBSTR::operator BSTR

Lança um CComBSTR objeto para um BSTR.

operator BSTR() const throw();

Observações

Permite passar CComBSTR objetos para funções que têm parâmetros [in BSTR ].

Example

Veja o exemplo para CComBSTR::m_str.

CComBSTR::operator !

Verifica se BSTR a cadeia é NULL.

bool operator!() const throw();

Valor de retorno

Retorna se o m_str membro for NULL; caso contrário, FALSE.TRUE

Observações

Este operador verifica apenas um NULL valor, não uma cadeia vazia.

Example

// STDMETHOD(BSTRToUpper)(/*[in, out]*/ BSTR bstrConv);
STDMETHODIMP InplaceBSTRToUpper(BSTR bstrConv)
{
   // Assign bstrConv to m_str member of CComBSTR
   CComBSTR bstrTemp;
   bstrTemp.Attach(bstrConv); 

   // Make sure BSTR is not NULL string
   if (!bstrTemp)
        return E_POINTER;

   // Make string uppercase 
   HRESULT hr;
   hr = bstrTemp.ToUpper();
   if (hr != S_OK)
       return hr;

   // Set m_str to NULL, so the BSTR is not freed
   bstrTemp.Detach(); 

   return S_OK; 
}

CComBSTR::operator !=

Devolve o oposto lógico de operator ==.

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

Parâmetros

bstrSrc
[dentro] Um CComBSTR objeto.

pszSrc
[dentro] Uma cadeia terminada a zero.

nNull
[dentro] Deve ser NULL.

Valor de retorno

Retorna TRUE se o item a comparar não for igual ao CComBSTR objeto; caso contrário, devolve FALSE.

Observações

CComBSTRs são comparados textualmente no contexto da localização padrão do utilizador. O operador final de comparação apenas compara a cadeia contida com NULL.

CComBSTR::operator &

Devolve o endereço do BSTR armazenado no m_str membro.

BSTR* operator&() throw();

Observações

CComBstr operator & tem uma afirmação especial associada para ajudar a identificar fugas de memória. O programa irá afirmar quando o m_str membro for inicializado. Esta afirmação foi criada para identificar situações em que um programador usa o & operator para atribuir um novo valor a m_str um membro sem libertar a primeira alocação de m_str. Se m_str for NULLigual a , o programa assume que m_str ainda não foi atribuído. Neste caso, o programa não irá afirmar.

Esta afirmação não é ativada por defeito. Defina ATL_CCOMBSTR_ADDRESS_OF_ASSERT para permitir esta afirmação.

Example

#define ATL_NO_CCOMBSTR_ADDRESS_OF_ASSERT

void MyInitFunction(BSTR* pbstr)
{
   ::SysReAllocString(pbstr, OLESTR("Hello World"));
   return;
}

CComBSTR bstrStr ;
// bstrStr is not initialized so this call will not assert.
MyInitFunction(&bstrStr); 

CComBSTR bstrStr2(OLESTR("Hello World"));
// bstrStr2 is initialized so this call will assert.
::SysReAllocString(&bstrStr2, OLESTR("Bye"));

CComBSTR::operator +=

Adiciona uma corda ao CComBSTR objeto.

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

Parâmetros

bstrSrc
[dentro] Um CComBSTR objeto para acrescentar.

pszSrc
[dentro] Uma cadeia terminada a zero para acrescentar.

Observações

CComBSTRs são comparados textualmente no contexto da localização padrão do utilizador. A LPCOLESTR comparação é feita usando memcmp os dados brutos de cada cadeia. A LPCSTR comparação é feita da mesma forma depois de ter sido criada uma cópia temporária do pszSrc Unicode. O operador final de comparação apenas compara a cadeia contida com NULL.

Example

CComBSTR bstrPre(OLESTR("Hello "));
CComBSTR bstrSuf(OLESTR("World!"));

// Appends "World!" to "Hello "
bstrPre += bstrSuf;

// Displays a message box with text "Hello World!"
::MessageBox(NULL, CW2CT(bstrPre), NULL, MB_OK);   

CComBSTR::operator <

Compara a CComBSTR com uma corda.

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

Valor de retorno

Devolve TRUE se o item a comparar for inferior ao CComBSTR objeto; caso contrário, devolve FALSE.

Observações

A comparação é feita usando a localização padrão do utilizador.

CComBSTR::operator =

Define o m_str membro para uma cópia de pSrc ou para uma cópia do BSTR membro de src. O operador de atribuição de movimentos move-se src sem o copiar.

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

Observações

O pSrc parâmetro especifica um LPCOLESTR para versões Unicode ou LPCSTR para versões ANSI.

Example

Veja o exemplo para CComBSTR::Copy.

CComBSTR::operator ==

Compara a CComBSTR com uma corda. CComBSTRs são comparados textualmente no contexto da localização padrão do utilizador.

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

Parâmetros

bstrSrc
[dentro] Um CComBSTR objeto.

pszSrc
[dentro] Uma cadeia terminada a zero.

nNull
[dentro] Deve ser NULL.

Valor de retorno

Retorna TRUE se o item a comparar for igual ao CComBSTR objeto; caso contrário, devolve FALSE.

Observações

O operador final de comparação apenas compara a cadeia contida com NULL.

CComBSTR::operator >

Compara a CComBSTR com uma corda.

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

Valor de retorno

Devolve TRUE se o item a comparar for maior que o CComBSTR objeto; caso contrário, devolve FALSE.

Observações

A comparação é feita usando a localização padrão do utilizador.

CComBSTR::ReadFromStream

Define o m_str membro para o BSTR contido no fluxo especificado.

HRESULT ReadFromStream(IStream* pStream) throw();

Parâmetros

pStream
[dentro] Um ponteiro para a IStream interface no fluxo que contém os dados.

Valor de retorno

Um valor padrão HRESULT .

Observações

ReadToStream requer que o conteúdo do fluxo na posição atual seja compatível com o formato de dados escrito por uma chamada para WriteToStream.

Example

IDataObject* pDataObj;

// Fill in the FORMATETC struct to retrieve desired format 
// from clipboard
FORMATETC formatetcIn = {CF_TEXT, NULL, DVASPECT_CONTENT, -1, TYMED_ISTREAM};
STGMEDIUM medium;
ZeroMemory(&medium, sizeof(STGMEDIUM));

// Get IDataObject from clipboard
HRESULT hr = ::OleGetClipboard(&pDataObj);

// Retrieve data from clipboard
hr = pDataObj->GetData(&formatetcIn, &medium);

if (SUCCEEDED(hr) && medium.tymed == TYMED_ISTREAM)
{
   CComBSTR bstrStr;
   // Get BSTR out of the stream
   hr = bstrStr.ReadFromStream(medium.pstm);

   //release the stream
   ::ReleaseStgMedium(&medium);
}

CComBSTR::ToLower

Converte a corda contida em minúscula.

HRESULT ToLower() throw();

Valor de retorno

Um valor padrão HRESULT .

Observações

Consulte CharLowerBuff para mais informações sobre como a conversão é realizada.

CComBSTR::ToUpper

Converte a corda contida em maiúsculas.

HRESULT ToUpper() throw();

Valor de retorno

Um valor padrão HRESULT .

Observações

Consulte CharUpperBuff para mais informações sobre como a conversão é realizada.

CComBSTR::WriteToStream

Salva o m_str membro para um fluxo.

HRESULT WriteToStream(IStream* pStream) throw();

Parâmetros

pStream
[dentro] Um ponteiro para a IStream interface num fluxo.

Valor de retorno

Um valor padrão HRESULT .

Observações

Podes recriar a BSTR a partir do conteúdo do stream usando a ReadFromStream função.

Example

//implementation of IDataObject::GetData()
STDMETHODIMP CMyDataObj::GetData(FORMATETC *pformatetcIn, STGMEDIUM *pmedium)
{
    HRESULT hr = S_OK;
    if (pformatetcIn->cfFormat == CF_TEXT && pformatetcIn->tymed == TYMED_ISTREAM)
    {
        IStream *pStm;
        // Create an IStream from global memory
        hr = CreateStreamOnHGlobal(NULL, TRUE, &pStm);
        if (FAILED(hr))
            return hr;

        // Initialize CComBSTR
        CComBSTR bstrStr = OLESTR("Hello World");

        // Serialize string into stream
        // the length followed by actual string is serialized into stream
        hr = bstrStr.WriteToStream(pStm);

        // Pass the IStream pointer back through STGMEDIUM struct
        pmedium->tymed = TYMED_ISTREAM;
        pmedium->pstm = pStm;
        pmedium->pUnkForRelease = NULL; 
    }

    return hr;
}

Consulte também

Visão geral da classe
Macros de Conversão de Strings ATL e MFC