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:

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

Confira também

IKnownFolder::GetPath

Exemplo de pastas conhecidas

SHGetKnownFolderPath

SHSetKnownFolderPath