Função SHGetFolderPathA (shlobj_core.h)

  • Artigo

Preterido. Obtém o caminho de uma pasta identificada por um valor CSIDL .

Nota A partir do Windows Vista, essa função é apenas um wrapper para SHGetKnownFolderPath. O valor csidl é convertido em seu KNOWNFOLDERID associado e, em seguida, SHGetKnownFolderPath é 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.
 

Sintaxe

SHFOLDERAPI SHGetFolderPathA(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPSTR  pszPath
);

Parâmetros

[in] hwnd

Digite: HWND

Reservado.

[in] csidl

Tipo: int

Um valor CSIDL que identifica a pasta cujo caminho deve ser recuperado. Somente pastas reais são válidas. Se uma pasta virtual for especificada, essa função falhará. Você pode forçar a criação de uma pasta combinando o CSIDL da pasta com CSIDL_FLAG_CREATE.

[in] hToken

Tipo: HANDLE

Um token de acesso que pode ser usado para representar um usuário específico.

Microsoft Windows 2000 e versões anteriores: Sempre defina esse parâmetro como NULL.

Windows XP e posterior: Esse parâmetro geralmente é definido como NULL, mas talvez seja necessário atribuir um valor não NULL ao 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 processo de chamada é responsável pela representação correta quando hToken não é NULL. O processo de chamada 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 do SHGetFolderPath encontrem 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

Sinalizadores que especificam o caminho a ser retornado. Esse valor é usado nos casos em que a pasta associada a um KNOWNFOLDERID (ou CSIDL) pode ser movida, renomeada, redirecionada ou perambulada entre idiomas por um usuário ou administrador.

O sistema de pastas conhecido que está por trás de SHGetFolderPath permite que usuários ou administradores redirecionem uma pasta conhecida para um local que atenda às suas necessidades. Isso é feito chamando IKnownFolderManager::Redirect, que define o valor "atual" da pasta associada ao sinalizador SHGFP_TYPE_CURRENT.

O valor padrão da pasta, que é o local da pasta se um usuário ou administrador não a tiver redirecionado para outro lugar, será recuperado especificando o sinalizador SHGFP_TYPE_DEFAULT. Esse valor pode ser usado para implementar um recurso de "restaurar padrões" para uma pasta conhecida.

Por exemplo, o valor padrão (SHGFP_TYPE_DEFAULT) para FOLDERID_Music (CSIDL_MYMUSIC) é "C:\Users\user name\Music". Se a pasta tiver sido redirecionada, o valor atual (SHGFP_TYPE_CURRENT) poderá ser "D:\Música". Se a pasta não tiver sido redirecionada, SHGFP_TYPE_DEFAULT e SHGFP_TYPE_CURRENT recuperar o mesmo caminho.

SHGFP_TYPE_CURRENT

Recupere o caminho atual da pasta.

SHGFP_TYPE_DEFAULT

Recupere o caminho padrão da pasta.

[out] pszPath

Tipo: LPTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento MAX_PATH que receberá o caminho. Se ocorrer um erro ou S_FALSE for retornado, essa cadeia de caracteres estará vazia. O caminho retornado não inclui uma barra invertida à direita. Por exemplo, "C:\Users" é retornado em vez de "C:\Users\".

Retornar valor

Tipo: HRESULT

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Essa função é um superconjunto de SHGetSpecialFolderPath.

Há suporte apenas para alguns valores CSIDL , incluindo o seguinte:

Exemplos

O exemplo de código a seguir usa SHGetFolderPath para localizar ou criar uma pasta e, em seguida, cria um arquivo nela.

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

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 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shlobj_core.h (inclua Shlobj.h, Shlobj_core.h)
Biblioteca Shell32.lib
DLL Shell32.dll (versão 5.0 ou posterior)

Confira também

IKnownFolder::GetPath