Função SetupDiGetDeviceInterfaceDetailA (setupapi.h)

  • Artigo

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 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 deverá ser NULL se DeviceInterfaceDetailSize for zero. Se esse parâmetro for especificado, o chamador deverá definir DeviceInterfaceDetailData.cbSize como sizeof(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 (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) bytes, para conter a parte fixa da estrutura e um único NULL para encerrar uma cadeia de MULTI_SZ vazia.

Esse parâmetro deverá ser zero se DeviceInterfaceDetailData for 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 como sizeof(SP_DEVINFO_DATA). Esse parâmetro é opcional e pode ser NULL.

Valor retornado

SetupDiGetDeviceInterfaceDetail retornará TRUE 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 para a falha poderá ser recuperado chamando GetLastError.

Comentários

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

  1. Obtenha o tamanho do buffer necessário. Chame SetupDiGetDeviceInterfaceDetail com um ponteiro NULLDeviceInterfaceDetailData , deviceInterfaceDetailDataSize de zero e uma variável 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.
  2. Aloque um buffer de tamanho apropriado e chame a função novamente para obter os detalhes da interface.
Os detalhes da interface retornados por essa função consistem 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 usado para obter apenas o DeviceInfoData. Se a interface existir, mas DeviceInterfaceDetailData for 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.

Observação

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 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

   
Cliente mínimo com suporte Disponível no Microsoft Windows 2000 e versões posteriores do Windows.
Plataforma de Destino Área de Trabalho
Cabeçalho setupapi.h (inclua Setupapi.h)
Biblioteca Setupapi.lib

Confira também

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs