Função SetupDiCreateDeviceInterfaceW (setupapi.h)

A função SetupDiCreateDeviceInterface registra uma interface do dispositivo em um sistema local ou em um sistema remoto.

Sintaxe

WINSETUPAPI BOOL SetupDiCreateDeviceInterfaceW(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA          DeviceInfoData,
  [in]            const GUID                *InterfaceClassGuid,
  [in, optional]  PCWSTR                    ReferenceString,
  [in]            DWORD                     CreationFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parâmetros

[in] DeviceInfoSet

Um identificador para um conjunto de informações do dispositivo. Esse conjunto contém um elemento de informações do dispositivo que representa o dispositivo para o qual registrar uma interface. Esse identificador normalmente é retornado por SetupDiGetClassDevs.

[in] DeviceInfoData

Um ponteiro para uma estrutura SP_DEVINFO_DATA que especifica o elemento de informações do dispositivo em DeviceInfoSet.

[in] InterfaceClassGuid

Um ponteiro para um GUID de classe que especifica a classe de interface para a nova interface.

[in, optional] ReferenceString

Um ponteiro para uma cadeia de caracteres terminada em NULL que fornece uma cadeia de caracteres de referência. Esse ponteiro é opcional e pode ser NULL. As cadeias de caracteres de referência são usadas apenas por alguns drivers de barramento que usam interfaces de dispositivo como espaços reservados para dispositivos de software criados sob demanda.

[in] CreationFlags

Reservado. Deve ser zero.

[out, optional] DeviceInterfaceData

Um ponteiro para uma estrutura de SP_DEVICE_INTERFACE_DATA inicializada pelo chamador para receber informações sobre a nova interface do dispositivo. Esse ponteiro é opcional e pode ser NULL. Se a estrutura for fornecida, o chamador deverá definir o membro cbSize dessa estrutura como sizeof(SP_DEVICE_INTERFACE_DATA) antes de chamar essa função. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

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

Comentários

O chamador dessa função deve ser um membro do grupo Administradores.

SetupDiCreateDeviceInterface registra uma interface para um dispositivo. Se um dispositivo tiver mais de uma interface, chame essa função uma vez para cada interface que está sendo registrada.

Se essa função registrar com êxito uma interface para o dispositivo que corresponde ao elemento de informações do dispositivo especificado, ela também adicionará a interface à lista de interfaces associada ao elemento de informações do dispositivo no conjunto de informações do dispositivo especificado.

Antes que uma interface registrada possa ser usada por aplicativos e outros componentes do sistema, a interface deve ser habilitada pelo driver para o dispositivo.

Essa função cria uma chave do Registro para a nova interface do dispositivo. Os chamadores dessa função podem acessar o armazenamento não potencial sob essa chave usando SetupDiOpenDeviceInterfaceRegKey.

Se SetupDiCreateDeviceInterface criar com êxito uma nova interface do dispositivo, mas o buffer fornecido pelo chamador no parâmetro DeviceInterfaceData for inválido, essa função retornará FALSE e uma chamada subsequente para GetLastError retornará ERROR_INVALID_USER_BUFFER. No entanto, a função cria e registra a nova interface do dispositivo.

Observação

O cabeçalho setupapi.h define SetupDiCreateDeviceInterface 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	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

SetupDiOpenDeviceInterfaceRegKey

SetupDiRemoveDeviceInterface