Função SHGetDataFromIDListW (shlobj_core.h)

Artigo
11/20/2024

Recupera dados de propriedade estendida de uma lista de identificadores relativos.

Sintaxe

SHSTDAPI SHGetDataFromIDListW(
  [in]  IShellFolder    *psf,
  [in]  PCUITEMID_CHILD pidl,
        int             nFormat,
  [out] void            *pv,
        int             cb
);

Parâmetros

[in] psf

Tipo: * IShellFolder

O endereço da interface de IShellFolder do pai. Esse deve ser o pai imediato da estrutura de ITEMIDLIST referenciada pelo parâmetro pidl .

[in] pidl

Tipo: PCUITEMID_CHILD

Um ponteiro para uma estrutura ITEMIDLIST que identifica o objeto relativo à pasta especificada em psf.

nFormat

Tipo: int

O formato no qual os dados estão sendo solicitados. Esse parâmetro deve ser definido como um dos valores a seguir.

SHGDFIL_FINDDATA

Formato usado para objetos do sistema de arquivos. O parâmetro pv é o endereço de uma estrutura WIN32_FIND_DATA.

SHGDFIL_NETRESOURCE

Formato usado para recursos de rede. O parâmetro pv é o endereço de uma estrutura de NETRESOURCE .

SHGDFIL_DESCRIPTIONID

versão 4.71. Formato usado para recursos de rede. O parâmetro pv é o endereço de uma estrutura de SHDESCRIPTIONID .

[out] pv

Tipo: void*

Um ponteiro para um buffer que, quando essa função retorna com êxito, recebe os dados solicitados. O formato desse buffer é determinado por nFormat.

Se nFormat for SHGDFIL_NETRESOURCE, haverá dois casos possíveis. Se o buffer for grande o suficiente, as informações de cadeia de caracteres do recurso líquido (campos para o nome da rede, nome local, provedor e comentários) serão colocadas no buffer. Se o buffer não for grande o suficiente, somente a estrutura de recursos líquidos será colocada no buffer e os ponteiros de informações da cadeia de caracteres serão NULL.

cb

Tipo: int

Tamanho do buffer em pv, em bytes.

Valor de retorno

Tipo: HRESULT

Retorna S_OK se tiver êxito ou E_INVALIDARG caso contrário.

Observações

Essa função extrai apenas informações presentes no ponteiro para uma PIDL (lista de identificadores de item). Como o conteúdo de um PIDL depende do objeto de pasta que criou o PIDL, não há garantia de que todas as informações solicitadas estarão disponíveis. Além disso, as informações retornadas refletem o estado do objeto no momento em que o PIDL foi criado. O estado atual do objeto pode ser diferente. Por exemplo, se você definir nFormat como SHGDFIL_FINDDATA, a função poderá atribuir valores significativos a apenas alguns dos membros da estrutura WIN32_FIND_DATA. Os membros restantes serão definidos como zero. Para recuperar informações atuais completas em um arquivo ou pasta do sistema de arquivos, use funções padrão do sistema de arquivos, como GetFileTime ou FindFirstFile.

E_INVALIDARG será retornado se o parâmetro psf, pidl, pvou cb não corresponder ao parâmetro nFormat ou se nFormat não for um dos valores SHGDFIL_ específicos mostrados acima.

Nota

O cabeçalho shlobj_core.h define SHGetDataFromIDList 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	shlobj_core.h (inclua Shlobj.h, Shlobj_core.h)
biblioteca	Shell32.lib
de DLL	Shell32.dll (versão 4.0 ou posterior)
conjunto de API	ext-ms-win-shell-shell32-l1-2-1 (introduzido no Windows 10, versão 10.0.10240)

Compartilhar via