Função SHGetKnownFolderPath (shlobj_core.h)
Recupera o caminho completo de uma pasta conhecida identificada pelo KNOWNFOLDERID da pasta.
Sintaxe
HRESULT SHGetKnownFolderPath(
[in] REFKNOWNFOLDERID rfid,
[in] DWORD dwFlags,
[in, optional] HANDLE hToken,
[out] PWSTR *ppszPath
);
Parâmetros
[in] rfid
Tipo: REFKNOWNFOLDERID
Uma referência à KNOWNFOLDERID que identifica a pasta.
[in] dwFlags
Tipo: DWORD
Sinalizadores que especificam opções de recuperação especiais. Esse valor pode ser 0; caso contrário, um ou mais dos valores KNOWN_FOLDER_FLAG .
[in, optional] hToken
Tipo: HANDLE
Um token de acesso que representa um usuário específico. Se esse parâmetro for NULL, que é o uso mais comum, a função solicitará a pasta conhecida para o usuário atual.
Solicite a pasta de um usuário específico passando o hToken desse usuário. Isso normalmente é feito no contexto de um serviço que tem privilégios suficientes para recuperar o token de um determinado usuário. Esse token deve ser aberto com direitos de TOKEN_QUERY e TOKEN_IMPERSONATE . Em alguns casos, você também precisa incluir TOKEN_DUPLICATE. Além de passar o hToken do usuário, o hive do registro desse usuário específico deve ser montado. 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 SHGetKnownFolderPath 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] ppszPath
Tipo: PWSTR*
Quando esse método retorna, contém o endereço de um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que especifica o caminho da pasta conhecida. O processo de chamada é responsável por liberar esse recurso depois que ele não for mais necessário chamando CoTaskMemFree, se SHGetKnownFolderPath for bem-sucedido ou não. O caminho retornado não inclui uma barra invertida à direita. Por exemplo, "C:\Users" é retornado em vez de "C:\Users\".
Valor retornado
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 tem um caminho (como uma pasta marcada como KF_CATEGORY_VIRTUAL). |
|
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 SHGetFolderPath. Essa função mais antiga agora é simplesmente um wrapper para SHGetKnownFolderPath.
Requisitos
| 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) |
| DLL | Shell32.dll (versão 6.0.6000 ou posterior) |