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 |
|---|---|
|
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) |