Função SHGetFileInfoA (shellapi.h)

Recupera informações sobre um objeto no sistema de arquivos, como um arquivo, pasta, diretório ou raiz da unidade.

Sintaxe

DWORD_PTR SHGetFileInfoA(
  [in]      LPCSTR      pszPath,
            DWORD       dwFileAttributes,
  [in, out] SHFILEINFOA *psfi,
            UINT        cbFileInfo,
            UINT        uFlags
);

Parâmetros

[in] pszPath

Tipo: LPCTSTR

Um ponteiro para um cadeia de caracteres nulaterminada de comprimento máximo MAX_PATH que contém o caminho e o nome do arquivo. Os caminhos absolutos e relativos 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 PIDL ( ITEMIDLIST) 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 curtos (o formulário 8.3) ou longos.

dwFileAttributes

Tipo: DWORD

Uma combinação de um ou mais sinalizadores de atributo de arquivo (valores FILE_ATTRIBUTE_ 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 de 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 valores a seguir.

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 dwAttributes membro da estrutura de 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 de SHGFI_ICON.

SHGFI_ATTRIBUTES (0x000000800)

Recupere os atributos do item. Os atributos são copiados para o dwAttributes membro 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 szDisplayName membro da estrutura especificada em psfi. O nome de exibição retornado usará 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 hIcon membro da estrutura especificada por psfie o índice é copiado para o membro do iIcon .

SHGFI_ICONLOCATION (0x000001000)

Recupere o nome do arquivo que contém o ícone que representa o arquivo especificado por 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 por psfi. O índice do ícone é copiado para o membro iIcon da 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. Retorne o índice do ícone de sobreposição. O valor do índice de sobreposição é retornado nos oito bits superiores do iIcon membro da estrutura especificada por psfi. Esse sinalizador requer que a SHGFI_ICON também seja definida.

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 pequenas imagens de ícone. 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 bem-sucedido, o índice será copiado para o iIcon membro 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 em psfi.

SHGFI_USEFILEATTRIBUTES (0x000000010)

Indica que a função não deve tentar acessar o arquivo especificado por pszPath. Em vez disso, ele deve agir como se o arquivo especificado por pszPath exista com os atributos de arquivo passados em dwFileAttributes. Esse sinalizador não pode ser combinado com os sinalizadores SHGFI_ATTRIBUTES, SHGFI_EXETYPEou SHGFI_PIDL.

Valor de retorno

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 não será zero se tiver êxito ou zero de outra forma.

Se uFlags contiver o sinalizador SHGFI_EXETYPE, o valor retornado especificará o tipo do arquivo executável. Será um dos seguintes valores.

Código de retorno	Descrição
0	Arquivo inexecutável ou uma condição de erro.
LOWORD = NE ou PE e HIWORD = versão do Windows	Aplicativo do Windows.
LOWORD = MZ e HIWORD = 0	arquivo MS-DOS .exe ou .com
LOWORD = PE e HIWORD = 0	Aplicativo de console ou arquivo de .bat

Observações

Você deve chamar essa função de um thread em segundo plano. Falha ao fazer isso pode fazer com que a interface do usuário pare de responder.

Se SHGetFileInfo retornar um identificador de ícone no hIcon membro da estrutura de SHFILEINFO apontada por psfi, você será responsável por liberá-la com DestroyIcon quando não precisar mais dela.

Observação Depois de ter um identificador para uma lista de imagens do sistema, você pode usar a API de Lista de Imagens para manipulá-la como qualquer outra lista de imagens. Como as listas de imagens do sistema são criadas por processo, você deve tratá-las como objetos somente leitura. Gravar em uma lista de imagens do sistema pode substituir ou excluir uma das imagens do sistema, tornando-a indisponível ou incorreta para o restante do processo.

 

Você deve inicializar o COM (Component Object Model) com CoInitialize ou OleInitialize antes de chamar SHGetFileInfo.

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. Esta 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);

Nota

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 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 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shellapi.h
biblioteca	Shell32.lib
de DLL	Shell32.dll (versão 4.0 ou posterior)

Consulte também

FileIconInit