Função SHGetFileInfoW (shellapi.h)
Recupera informações sobre um objeto no sistema de arquivos, como um arquivo, pasta, diretório ou raiz de unidade.
Sintaxe
DWORD_PTR SHGetFileInfoW(
[in] LPCWSTR pszPath,
DWORD dwFileAttributes,
[in, out] SHFILEINFOW *psfi,
UINT cbFileInfo,
UINT uFlags
);
Parâmetros
[in] pszPath
Tipo: LPCTSTR
Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento máximo MAX_PATH que contém o caminho e o nome do arquivo. Os caminhos absoluto e relativo são válidos.
Se o parâmetro uFlags incluir o sinalizador SHGFI_PIDL , esse parâmetro deverá ser o endereço de uma estrutura ITEMIDLIST (PIDL) que contém a lista de identificadores de item que identifica exclusivamente o arquivo no namespace do Shell. O PIDL deve ser um PIDL totalmente qualificado. PIDLs relativos não são permitidos.
Se o parâmetro uFlags incluir o sinalizador SHGFI_USEFILEATTRIBUTES , esse parâmetro não precisará ser um nome de arquivo válido. A função continuará como se o arquivo existisse com o nome especificado e com os atributos de arquivo passados no parâmetro dwFileAttributes . Isso permite que você obtenha informações sobre um tipo de arquivo passando apenas a extensão para pszPath e passando FILE_ATTRIBUTE_NORMAL em dwFileAttributes.
Essa cadeia de caracteres pode usar nomes de arquivo curtos (o formulário 8.3) ou longos.
dwFileAttributes
Tipo: DWORD
Uma combinação de um ou mais sinalizadores de atributo de arquivo (FILE_ATTRIBUTE_ valores conforme definido em Winnt.h). Se uFlags não incluir o sinalizador SHGFI_USEFILEATTRIBUTES , esse parâmetro será ignorado.
[in, out] psfi
Tipo: SHFILEINFO*
Ponteiro para uma estrutura SHFILEINFO para receber as informações do arquivo.
cbFileInfo
Tipo: UINT
O tamanho, em bytes, da estrutura SHFILEINFO apontada pelo parâmetro psfi .
uFlags
Tipo: UINT
Os sinalizadores que especificam as informações de arquivo a serem recuperadas. Esse parâmetro pode ser uma combinação dos seguintes valores.
SHGFI_ADDOVERLAYS (0x000000020)
Versão 5.0. Aplique as sobreposições apropriadas ao ícone do arquivo. O sinalizador SHGFI_ICON também deve ser definido.
SHGFI_ATTR_SPECIFIED (0x000020000)
Modifique SHGFI_ATTRIBUTES para indicar que o membro dwAttributes da estrutura SHFILEINFO em psfi contém os atributos específicos desejados. Esses atributos são passados para IShellFolder::GetAttributesOf. Se esse sinalizador não for especificado, 0xFFFFFFFF será passado para IShellFolder::GetAttributesOf, solicitando todos os atributos. Esse sinalizador não pode ser especificado com o sinalizador SHGFI_ICON .
SHGFI_ATTRIBUTES (0x000000800)
Recupere os atributos do item. Os atributos são copiados para o membro dwAttributes da estrutura especificada no parâmetro psfi . Esses são os mesmos atributos obtidos de IShellFolder::GetAttributesOf.
SHGFI_DISPLAYNAME (0x000000200)
Recupere o nome de exibição do arquivo, que é o nome que aparece no Windows Explorer. O nome é copiado para o membro szDisplayName da estrutura especificada no psfi. O nome de exibição retornado usa o nome de arquivo longo, se houver um, em vez da forma 8.3 do nome do arquivo. Observe que o nome de exibição pode ser afetado por configurações como se as extensões são mostradas.
SHGFI_EXETYPE (0x000002000)
Recupere o tipo do arquivo executável se pszPath identificar um arquivo executável. As informações são empacotadas no valor retornado. Esse sinalizador não pode ser especificado com nenhum outro sinalizador.
SHGFI_ICON (0x000000100)
Recupere o identificador para o ícone que representa o arquivo e o índice do ícone na lista de imagens do sistema. O identificador é copiado para o membro hIcon da estrutura especificada pelo psfi e o índice é copiado para o membro iIcon .
SHGFI_ICONLOCATION (0x000001000)
Recupere o nome do arquivo que contém o ícone que representa o arquivo especificado pelo pszPath, conforme retornado pelo método IExtractIcon::GetIconLocation do manipulador de ícones do arquivo. Recupere também o índice de ícone dentro desse arquivo. O nome do arquivo que contém o ícone é copiado para o membro szDisplayName da estrutura especificada pelo psfi. O índice do ícone é copiado para o membro iIcon dessa estrutura.
SHGFI_LARGEICON (0x000000000)
Modifique SHGFI_ICON, fazendo com que a função recupere o ícone grande do arquivo. O sinalizador SHGFI_ICON também deve ser definido.
SHGFI_LINKOVERLAY (0x000008000)
Modifique SHGFI_ICON, fazendo com que a função adicione a sobreposição de link ao ícone do arquivo. O sinalizador SHGFI_ICON também deve ser definido.
SHGFI_OPENICON (0x000000002)
Modifique SHGFI_ICON, fazendo com que a função recupere o ícone aberto do arquivo. Também usado para modificar SHGFI_SYSICONINDEX, fazendo com que a função retorne o identificador para a lista de imagens do sistema que contém o pequeno ícone aberto do arquivo. Um objeto de contêiner exibe um ícone aberto para indicar que o contêiner está aberto. O sinalizador SHGFI_ICON e/ou SHGFI_SYSICONINDEX também deve ser definido.
SHGFI_OVERLAYINDEX (0x000000040)
Versão 5.0. Retornar o índice do ícone de sobreposição. O valor do índice de sobreposição é retornado nos oito bits superiores do membro iIcon da estrutura especificada por psfi. Esse sinalizador requer que o SHGFI_ICON também seja definido.
SHGFI_PIDL (0x000000008)
Indique que pszPath é o endereço de uma estrutura ITEMIDLIST em vez de um nome de caminho.
SHGFI_SELECTED (0x000010000)
Modifique SHGFI_ICON, fazendo com que a função misture o ícone do arquivo com a cor de realce do sistema. O sinalizador SHGFI_ICON também deve ser definido.
SHGFI_SHELLICONSIZE (0x000000004)
Modifique SHGFI_ICON, fazendo com que a função recupere um ícone do tamanho do Shell. Se esse sinalizador não for especificado, a função dimensiona o ícone de acordo com os valores de métrica do sistema. O sinalizador SHGFI_ICON também deve ser definido.
SHGFI_SMALLICON (0x000000001)
Modifique SHGFI_ICON, fazendo com que a função recupere o ícone pequeno do arquivo. Também usado para modificar SHGFI_SYSICONINDEX, fazendo com que a função retorne o identificador para a lista de imagens do sistema que contém imagens de ícone pequenas. O sinalizador SHGFI_ICON e/ou SHGFI_SYSICONINDEX também deve ser definido.
SHGFI_SYSICONINDEX (0x000004000)
Recupere o índice de um ícone de lista de imagens do sistema. Se tiver êxito, o índice será copiado para o membro iIcon do psfi. O valor retornado é um identificador para a lista de imagens do sistema. Somente as imagens cujos índices são copiados com êxito para iIcon são válidas. A tentativa de acessar outras imagens na lista de imagens do sistema resultará em um comportamento indefinido.
SHGFI_TYPENAME (0x000000400)
Recupere a cadeia de caracteres que descreve o tipo do arquivo. A cadeia de caracteres é copiada para o membro szTypeName da estrutura especificada no psfi.
SHGFI_USEFILEATTRIBUTES (0x000000010)
Indica que a função não deve tentar acessar o arquivo especificado pelo pszPath. Em vez disso, ele deve agir como se o arquivo especificado por pszPath existisse com os atributos de arquivo passados em dwFileAttributes. Esse sinalizador não pode ser combinado com os sinalizadores SHGFI_ATTRIBUTES, SHGFI_EXETYPE ou SHGFI_PIDL .
Retornar valor
Tipo: DWORD_PTR
Retorna um valor cujo significado depende do parâmetro uFlags .
Se uFlags não contiver SHGFI_EXETYPE ou SHGFI_SYSICONINDEX, o valor retornado será diferente de zero se tiver êxito ou zero caso contrário.
Se uFlags contiver o sinalizador SHGFI_EXETYPE , o valor retornado especificará o tipo do arquivo executável. Ele será um dos valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
Arquivo não recortado ou uma condição de erro. |
|
Aplicativo do Windows. |
|
Arquivo de .exe ou .com do MS-DOS |
|
Aplicativo de console ou arquivo de .bat |
Comentários
Você deve chamar essa função de um thread em segundo plano. Não fazer isso pode fazer com que a interface do usuário pare de responder.
Se SHGetFileInfo retornar um identificador de ícone no membro hIcon da estrutura SHFILEINFO apontada pelo psfi, você será responsável por liberá-lo com DestroyIcon quando não precisar mais dele.
Quando você usa o sinalizador SHGFI_EXETYPE com um aplicativo do Windows, a versão do Windows do executável é fornecida no HIWORD do valor retornado. Essa versão é retornada como um valor hexadecimal. Para obter detalhes sobre como equiparar esse valor com uma versão específica do Windows, consulte Usando os cabeçalhos do Windows.
Exemplos
O exemplo de código a seguir usa SHGetFileInfo para recuperar o nome de exibição da Lixeira, identificado por seu PIDL.
LPITEMIDLIST pidl = NULL;
hr = SHGetFolderLocation(NULL, CSIDL_BITBUCKET, NULL, 0, &pidl);
if (SUCCEEDED(hr))
{
SHFILEINFOW sfi = {0};
hr = SHGetFileInfo((LPCTSTR)pidl,
-1,
&sfi,
sizeof(sfi),
SHGFI_PIDL | SHGFI_DISPLAYNAME)
if (SUCCEEDED(hr))
{
// The display name is now held in sfi.szDisplayName.
}
}
ILFree(pidl);
Observação
O cabeçalho shellapi.h define SHGetFileInfo como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | 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 | shellapi.h |
| Biblioteca | Shell32.lib |
| DLL | Shell32.dll (versão 4.0 ou posterior) |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de