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

Confira também

IKnownFolder::GetPath

Exemplo de pastas conhecidas

SHGetKnownFolderIDList

SHSetKnownFolderPath