Função SHGetFolderPathAndSubDirA (shlobj_core.h)

Artigo
11/20/2024

Obtém o caminho de uma pasta e acrescenta um caminho de subpasta fornecido pelo usuário.

Sintaxe

HRESULT SHGetFolderPathAndSubDirA(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [in]  LPCSTR pszSubDir,
  [out] LPSTR  pszPath
);

Parâmetros

[in] hwnd

Tipo: 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 com SHGetFolderPathAndSubDir combinando a CSIDL da pasta com CSIDL_FLAG_CREATE.

[in] hToken

Tipo: HANDLE

Um token de acesso que representa um usuário específico. Para sistemas anteriores ao Windows 2000, defina esse valor como NULL. Para sistemas posteriores, hToken geralmente é, mas nem sempre, definido como NULL. Talvez seja necessário atribuir um valor a hToken para as pastas que podem ter vários usuários, mas que são tratadas como pertencentes a um único usuário. A pasta mais usada desse tipo é My Documents.

[in] dwFlags

Tipo: DWORD

Especifica se o caminho a ser retornado é o caminho real da pasta ou o caminho padrão. Esse valor é usado nos casos em que a pasta associada a um valor CSIDL pode ser movida ou renomeada pelo usuário.

SHGFP_TYPE_CURRENT

Retorne o caminho atual da pasta.

SHGFP_TYPE_DEFAULT

Retorne o caminho padrão da pasta.

[in] pszSubDir

Tipo: LPCTSTR

Um ponteiro para o subcaminho a ser acrescentado ao caminho da pasta. Esta é uma cadeia de caracteres de comprimentonula terminada MAX_PATH. Se você não estiver criando um novo diretório, ele deverá ser um subdiretório existente ou a função retornará um erro. Esse valor pode ser NULL se nenhum subcaminho for acrescentado.

[out] pszPath

Tipo: LPTSTR

Quando essa função retorna, esse valor aponta para o caminho do diretório e o subcaminho acrescentado. Esta é uma cadeia de caracteres de comprimentonula terminada MAX_PATH. Essa cadeia de caracteres fica vazia quando a função retorna um código de erro.

Valor de retorno

Tipo: HRESULT

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

Observações

Nota

O cabeçalho shlobj_core.h define SHGetFolderPathAndSubDir como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shlobj_core.h (inclua Shlobj.h, Shlobj_core.h)
biblioteca	Shell32.lib
de DLL	Shell32.dll (versão 5.60 ou posterior)

Consulte também

SHGetFolderPath

Compartilhar via