Função PropVariantToStrRet (propvarutil.h)

Artigo
08/25/2023

Extrai uma cadeia de caracteres de uma estrutura PROPVARIANT e a coloca em uma estrutura STRRET .

Sintaxe

PSSTDAPI PropVariantToStrRet(
  [in]  REFPROPVARIANT propvar,
  [out] STRRET         *pstrret
);

Parâmetros

[in] propvar

Tipo: REFPROPVARIANT

Referência a uma estrutura PROPVARIANT de origem .

[out] pstrret

Tipo: STRRET*

Aponta para a estrutura STRRET . Quando essa função retorna, a estrutura foi inicializada para conter uma cópia da cadeia de caracteres extraída.

Retornar valor

Tipo: HRESULT

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Essa função auxiliar é usada em aplicativos que desejam converter um valor de cadeia de caracteres em uma estrutura PROPVARIANT em uma estrutura STRRET . Por exemplo, um aplicativo que implementa IShellFolder::GetDisplayNameOf pode achar essa função útil.

Se o PROPVARIANT de origem tiver tipo VT_LPWSTR ou VT_BSTR, essa função extrairá a cadeia de caracteres e a colocará na estrutura STRRET . Caso contrário, ele tentará converter o valor na estrutura PROPVARIANT em uma cadeia de caracteres. Se uma conversão não for possível, PropVariantToString retornará um código de falha. Consulte PropVariantChangeType para obter uma lista de conversões possíveis. Observe que VT_EMPTY é convertido com êxito em "".

Além das conversões fornecidas por PropVariantChangeType, os casos especiais a seguir se aplicam a PropVariantToString.

PROPVARIANTscom valor vetor são convertidos em cadeias de caracteres separando cada elemento com "; ". Por exemplo, PropVariantToString converte um vetor de 3 inteiros, {3, 1, 4}, na cadeia de caracteres "3; 1; 4". O ponto e vírgula é independente da localidade atual.
VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT e valores de VT_UNKNOWN são convertidos em cadeias de caracteres usando uma codificação sem suporte. Não é possível decodificar cadeias de caracteres criadas dessa forma e o formato pode mudar no futuro.

Se a extração for bem-sucedida, a função inicializará o membro uType da estrutura STRRET com STRRET_WSTR e definirá o membro pOleStr dessa estrutura para apontar para uma cópia alocada da cadeia de caracteres. O aplicativo de chamada é responsável por usar CoTaskMemFree ou StrRetToStr para liberar essa cadeia de caracteres quando ela não for mais necessária.

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar PropVariantToString para acessar um valor de cadeia de caracteres em um PROPVARIANT.

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_FileName, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_FileName is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    else

    {

        // the extraction failed

    }

    PropVariantClear(&propvar);

}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP com SP2, Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 com SP1 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	propvarutil.h
Biblioteca	Propsys.lib
DLL	Propsys.dll (versão 6.0 ou posterior)
Redistribuível	Pesquisa da Área de Trabalho do Windows (WDS) 3.0