Função SetupDiGetDeviceInterfaceDetailA (setupapi.h)

Artigo
11/20/2024

A função SetupDiGetDeviceInterfaceDetail retorna detalhes sobre uma interface do dispositivo.

Sintaxe

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceDetailA(
  [in]            HDEVINFO                           DeviceInfoSet,
  [in]            PSP_DEVICE_INTERFACE_DATA          DeviceInterfaceData,
  [out, optional] PSP_DEVICE_INTERFACE_DETAIL_DATA_A DeviceInterfaceDetailData,
  [in]            DWORD                              DeviceInterfaceDetailDataSize,
  [out, optional] PDWORD                             RequiredSize,
  [out, optional] PSP_DEVINFO_DATA                   DeviceInfoData
);

Parâmetros

[in] DeviceInfoSet

Um ponteiro para o conjunto de informações do dispositivo que contém a interface para a qual recuperar detalhes. Esse identificador normalmente é retornado por SetupDiGetClassDevs.

[in] DeviceInterfaceData

Um ponteiro para uma estrutura de SP_DEVICE_INTERFACE_DATA que especifica a interface em DeviceInfoSet para a qual recuperar detalhes. Um ponteiro desse tipo normalmente é retornado por SetupDiEnumDeviceInterfaces.

[out, optional] DeviceInterfaceDetailData

Um ponteiro para uma estrutura SP_DEVICE_INTERFACE_DETAIL_DATA para receber informações sobre a interface especificada. Esse parâmetro é opcional e pode ser NULL. Esse parâmetro deve ser NULL se DeviceInterfaceDetailSize for zero. Se esse parâmetro for especificado, o chamador deverá definir DeviceInterfaceDetailData.cbSize para tamanhos de(SP_DEVICE_INTERFACE_DETAIL_DATA) antes de chamar essa função. O membro cbSize sempre contém o tamanho da parte fixa da estrutura de dados, não um tamanho que reflete a cadeia de caracteres de comprimento variável no final.

[in] DeviceInterfaceDetailDataSize

O tamanho do buffer DeviceInterfaceDetailData . O buffer deve ser pelo menos (deslocamento de(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + tamanho de(TCHAR)) bytes, para conter a parte fixa da estrutura e um único NULL para encerrar uma cadeia de caracteres de MULTI_SZ vazia.

Esse parâmetro deverá ser zero se deviceInterfaceDetailData estiver NULL.

[out, optional] RequiredSize

Um ponteiro para uma variável do tipo DWORD que recebe o tamanho necessário do buffer DeviceInterfaceDetailData . Esse tamanho inclui o tamanho da parte fixa da estrutura mais o número de bytes necessários para a cadeia de caracteres de caminho do dispositivo de comprimento variável. Esse parâmetro é opcional e pode ser NULL.

[out, optional] DeviceInfoData

Um ponteiro para um buffer que recebe informações sobre o dispositivo que dá suporte à interface solicitada. O chamador deve definir DeviceInfoData.cbSize para tamanhos de(SP_DEVINFO_DATA). Esse parâmetro é opcional e pode ser NULL.

Valor de retorno

SetupDiGetDeviceInterfaceDetail retornará verdadeiro se a função for concluída sem erros. Se a função for concluída com um erro, FALSE será retornado e o código de erro da falha poderá ser recuperado chamando GetLastError.

Observações

Usar essa função para obter detalhes sobre uma interface normalmente é um processo de duas etapas:

Obtenha o tamanho do buffer necessário. Chame SetupDiGetDeviceInterfaceDetail com um ponteiroNULL DeviceInterfaceDetailData, um DeviceInterfaceDetailDataSize de zero e uma variável de requiredSize válida. Em resposta a essa chamada, essa função retorna o tamanho do buffer necessário em RequiredSize e falha com GetLastError retornando ERROR_INSUFFICIENT_BUFFER.
Aloque um buffer de tamanho apropriado e chame a função novamente para obter os detalhes da interface.

O detalhe da interface retornado por essa função consiste em um caminho de dispositivo que pode ser passado para funções Win32, como CreateFile. Não tente analisar o nome simbólico do caminho do dispositivo. O caminho do dispositivo pode ser reutilizado entre as inicializações do sistema.

SetupDiGetDeviceInterfaceDetail pode ser usada para obter apenas odeviceInfoData . Se a interface existir, mas DeviceInterfaceDetailData estiver NULL, essa função falhará, GetLastError retornará ERROR_INSUFFICIENT_BUFFER e a estrutura deviceInfoData será preenchida com informações sobre o dispositivo que expõe a interface.

Nota

O cabeçalho setupapi.h define SetupDiGetDeviceInterfaceDetail 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	Disponível no Microsoft Windows 2000 e versões posteriores do Windows.
da Plataforma de Destino	Área de trabalho
cabeçalho	setupapi.h (inclua Setupapi.h)
biblioteca	Setupapi.lib

Consulte também

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs

Compartilhar via