Função SHGetKnownFolderItem (shlobj_core.h)

Artigo
03/05/2024

Recupera um objeto IShellItem que representa uma pasta conhecida.

Sintaxe

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

Parâmetros

[in] rfid

Tipo: REFKNOWNFOLDERID

Uma referência ao KNOWNFOLDERID, um GUID que identifica a pasta que contém o item.

[in] flags

Tipo: KNOWN_FOLDER_FLAG

Sinalizadores que especificam opções especiais usadas na recuperação da pasta conhecida IShellItem. Esse valor pode ser KF_FLAG_DEFAULT; caso contrário, um ou mais dos valores KNOWN_FOLDER_FLAG .

[in] hToken

Tipo: HANDLE

Um token de acesso usado para representar um usuário específico. Esse parâmetro geralmente é definido como NULL, caso em que a função tenta acessar a instância do usuário atual da pasta. No entanto, talvez seja necessário atribuir um valor a hToken para as pastas que podem ter vários usuários, mas são tratadas como pertencentes a um único usuário. A pasta mais usada desse tipo é Documentos.

O aplicativo de chamada é responsável pela representação correta quando hToken não é nulo. Ele deve ter privilégios de segurança apropriados para o usuário específico, incluindo TOKEN_QUERY e TOKEN_IMPERSONATE, e o hive do registro do usuário deve estar montado no momento. Confira Controle de Acesso para obter mais discussões sobre problemas de controle de acesso.

Atribuir ao parâmetro hToken um valor de -1 indica o Usuário Padrão. Isso permite que os clientes de SHSetKnownFolderPath definam locais de pasta (como a pasta Desktop ) para o Usuário Padrão. O perfil de usuário usuário padrão é duplicado quando qualquer nova conta de usuário é criada e inclui pastas especiais, como Documentos e Área de Trabalho. Todos os itens adicionados à pasta Usuário Padrão também aparecem em qualquer nova conta de usuário. Observe que o acesso às pastas de Usuário Padrão requer privilégios de administrador.

[in] riid

Tipo: REFIID

Uma referência ao IID da interface que representa o item, geralmente IID_IShellItem ou IID_IShellItem2.

[out] ppv

Tipo: void**

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

Retornar valor

Tipo: HRESULT

Retorna S_OK se tiver êxito ou um valor de erro, caso contrário, incluindo o seguinte:

Código de retorno	Descrição
E_INVALIDARG	Entre outras coisas, esse valor pode indicar que o parâmetro rfid faz referência a um KNOWNFOLDERID que não está presente no sistema. Nem todos os valores KNOWNFOLDERID estão presentes em todos os sistemas. Use IKnownFolderManager::GetFolderIds para recuperar o conjunto de valores KNOWNFOLDERID para o sistema atual.

Comentários

O chamador dessa função deve ter privilégios de Administrador. Para chamar essa função em pastas conhecidas públicas, o chamador deve ter privilégios de Administrador. Para pastas conhecidas por usuário, o chamador requer apenas privilégios de Usuário.

Algumas das pastas conhecidas, por exemplo, a pasta Documentos , são por usuário. Cada usuário tem um caminho diferente para a pasta Documentos . Se hToken for NULL, a API tentará acessar a instância do aplicativo de chamada da pasta , que é a do usuário atual. Se hToken for um token de usuário válido, a API tentará representar o usuário usando esse token e tentará acessar a instância desse usuário.

Essa função não pode ser chamada em pastas do tipo KF_CATEGORY_FIXED e KF_CATEGORY_VIRTUAL.

Para chamar essa função em uma pasta do tipo KF_CATEGORY_COMMON, o aplicativo de chamada deve estar em execução com privilégios elevados.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shlobj_core.h (inclua Shlobj.h)
Biblioteca	Shell32.lib
DLL	Shell32.dll (versão 6.1 ou posterior)
Conjunto de APIs	ext-ms-win-shell-shell32-l1-2-1 (introduzido no Windows 10, versão 10.0.10240)