Função SHGetFolderLocation (shlobj_core.h)

  • Artigo

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

Sintaxe

SHSTDAPI SHGetFolderLocation(
  [in]  HWND             hwnd,
  [in]  int              csidl,
  [in]  HANDLE           hToken,
  [in]  DWORD            dwFlags,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parâmetros

[in] hwnd

Digite: HWND

Reservado.

[in] csidl

Tipo: int

Um valor CSIDL que identifica a pasta a ser localizada. As pastas associadas às CSIDLs podem não existir em um sistema específico.

[in] hToken

Tipo: HANDLE

Um token de acesso que pode ser usado para representar um usuário específico. Geralmente, ele é definido como NULL, mas pode ser necessário quando há vários usuários para essas pastas que são tratadas como pertencentes a um único usuário. A pasta mais usada desse tipo é Meus Documentos. O aplicativo de chamada é responsável pela representação correta quando hToken não é NULL. Ele deve ter privilégios de segurança apropriados para o usuário específico 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 SHGetFolderLocation localizem locais de pasta (como a pasta Área de Trabalho) 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 Meus Documentos e Área de Trabalho. Todos os itens adicionados à pasta Usuário Padrão também aparecem em qualquer nova conta de usuário.

[in] dwFlags

Tipo: DWORD

[out] ppidl

Tipo: PIDLIST_ABSOLUTE*

O endereço de um ponteiro para uma estrutura de lista de identificadores de item que especifica o local da pasta em relação à raiz do namespace (a área de trabalho). O parâmetro ppidl é definido como NULL em caso de falha. O aplicativo de chamada é responsável por liberar esse recurso 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
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
 O CSIDL em nFolder é válido, mas a pasta não existe.
E_INVALIDARG
 O CSIDL em nFolder não é válido.

Comentários

Nota A partir do Windows Vista, essa função é apenas um wrapper para SHGetKnownFolderIDList. O valor csidl é convertido em seu KNOWNFOLDERID associado e SHGetKnownFolderIDList é chamado. Novos aplicativos devem usar o sistema de pastas conhecido em vez do sistema CSIDL mais antigo, que tem suporte apenas para compatibilidade com versões anteriores.
 
As funções SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation e SHGetSpecialFolderPath são as maneiras preferenciais de obter identificadores para pastas em sistemas anteriores ao Windows Vista. Funções como ExpandEnvironmentStrings que usam os nomes de variáveis de ambiente diretamente, no formato %VariableName%, podem não ser confiáveis.

Essa função é um superconjunto de SHGetSpecialFolderLocation, incluído com versões anteriores do Shell.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [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 5.0 ou posterior)

Confira também

IKnownFolder::GetIDList