Função SHGetKnownFolderIDList (shlobj_core.h)

Recupera o caminho de uma pasta conhecida como uma estrutura ITEMIDLIST .

Sintaxe

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parâmetros

[in] rfid

Tipo: REFKNOWNFOLDERID

Uma referência à KNOWNFOLDERID que identifica a pasta. As pastas associadas às IDs de pasta conhecidas podem não existir em um sistema específico.

[in] dwFlags

Tipo: DWORD

Sinalizadores que especificam opções de recuperação especiais. Esse valor pode ser 0; caso contrário, ele é um ou mais dos valores de 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 SHGetKnownFolderIDList encontrem 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.

[out] ppidl

Tipo: PIDLIST_ABSOLUTE*

Quando esse método retorna, contém um ponteiro para o PIDL da pasta. Este parâmetro é passado não inicializado. O chamador é responsável por liberar o PIDL retornado quando ele não é mais necessário chamando ILFree.

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

Essa função substitui SHGetFolderLocation. Essa função mais antiga agora é simplesmente um wrapper para SHGetKnownFolderIDList.

Os chamadores que usam essa função devem ter pelo menos privilégios de usuário.

Algumas 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 usuário atual da pasta. 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 da pasta.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [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.0.6000 ou posterior)

Confira também

IKnownFolder::GetPath

Exemplo de pastas conhecidas

SHGetKnownFolderPath

SHSetKnownFolderPath