Função SHGetViewStatePropertyBag (shlwapi.h)

Artigo
03/05/2025

[SHGetViewStatePropertyBag está disponível para uso nos sistemas operacionais especificados na seção Requisitos. Ele pode estar alterado ou indisponível em versões subsequentes.]

Recupera um recipiente de propriedades no qual as informações de estado de exibição de uma pasta podem ser armazenadas e posteriormente recuperadas. As configurações do usuário são mantidas para a próxima vez que o usuário visitar a pasta.

Sintaxe

LWSTDAPI SHGetViewStatePropertyBag(
  [in, optional] PCIDLIST_ABSOLUTE pidl,
  [in, optional] PCWSTR            pszBagName,
                 DWORD             dwFlags,
  [in]           REFIID            riid,
  [out]          void              **ppv
);

Parâmetros

[in, optional] pidl

Tipo: PCIDLIST_ABSOLUTE

Um PIDL da pasta para a qual você está solicitando propriedades. Esse parâmetro deve ser NULL se o sinalizador de SHGVSPB_ALLFOLDERS for passado.

[in, optional] pszBagName

Tipo: PCWSTR

Um ponteiro para uma cadeia de caracteres que contém o nome do recipiente de propriedades solicitado.

dwFlags

Tipo: DWORD

Um valor que especifica uma combinação dos sinalizadores a seguir.

Um valor do seguinte conjunto de sinalizadores é necessário.

SHGVSPB_PERUSER

Retorna as propriedades por usuário do pidlespecificado.

SHGVSPB_ALLUSERS

Retorna as propriedades de Todos os Usuários para o pidlespecificado.

Um valor do seguinte conjunto de sinalizadores é necessário.

SHGVSPB_PERFOLDER

Retorna o recipiente de propriedades da pasta especificada pelo parâmetro pidl.

SHGVSPB_ALLFOLDERS

Retorna o recipiente de propriedades que se aplica a todas as pastas.

SHGVSPB_INHERIT

Retorna o recipiente de propriedades usado para fornecer padrões para subpastas que não têm seu recipiente de propriedades.

Os sinalizadores a seguir são opcionais.

SHGVSPB_ROAM

Permite que o recipiente de propriedades percorra. Consulte perfis de usuário móvel. Esse sinalizador não pode ser combinado com SHGVSPB_ALLFOLDERS.

SHGVSPB_NOAUTODEFAULTS

Suprime a pesquisa por um padrão adequado quando o recipiente de propriedades não puder ser encontrado para a pasta especificada. Por padrão, se SHGVSPB_INHERIT não for especificado e um recipiente de propriedades não puder ser encontrado para a pasta especificada, o sistema procurará por sacos de propriedade nomeados de forma idêntica em outros locais que possam fornecer valores padrão. Por exemplo, o sistema pesquisa nos ancestrais da pasta para ver se algum deles fornece um recipiente de propriedades SHGVSPB_INHERIT. Outros locais em que as pesquisas do sistema estão nos padrões do usuário e nos padrões globais.

O conjunto de sinalizadores a seguir consiste em valores que combinam alguns sinalizadores listados acima e são usados para brevidade e conveniência.

SHGVSPB_FOLDER

Combina SHGVSPB_PERUSER e SHGVSPB_PERFOLDER.

SHGVSPB_FOLDERNODEFAULTS

Combina SHGVSPB_PERUSER, SHGVSPB_PERFOLDER e SHGVSPB_NOAUTODEFAULTS.

SHGVSPB_USERDEFAULTS

Combina SHGVSPB_PERUSER e SHGVSPB_ALLFOLDERS.

SHGVSPB_GLOBALDEFAULTS

Combina SHGVSPB_ALLUSERS e SHGVSPB_ALLFOLDERS.

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Esse sinalizador é nomeado SHGVSPB_GLOBALDEAFAULTS.

[in] riid

Tipo: REFIID

Uma referência à IID da interface a ser recuperada por meio de ppv.

[out] ppv

Tipo: void**

Quando esse método retorna com êxito, contém o ponteiro de interface solicitado em riid.

Valor de retorno

Tipo: HRESULT

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

Observações

Informações críticas não devem ser armazenadas no recipiente de propriedades de estado de exibição porque o sistema mantém apenas um número limitado de estados de exibição. Se uma pasta não for visitada por muito tempo, seu estado de exibição será eventualmente excluído.

Recomendamos que você use a macro IID_PPV_ARGS, definida em Objbase.h, para empacotar os parâmetros riid e ppv. Essa macro fornece a IID correta com base na interface apontada pelo valor em ppv, o que elimina a possibilidade de um erro de codificação em riid que pode levar a resultados inesperados.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shlwapi.h
biblioteca	Shlwapi.lib
de DLL	Shlwapi.dll (versão 5.0 ou posterior)

Compartilhar via