Função IoRegisterDeviceInterface (wdm.h)

A rotina IoRegisterDeviceInterface registra uma classe de interface do dispositivo , se não tiver sido registrada anteriormente, e cria uma nova instância da classe de interface, que um driver pode habilitar posteriormente para uso por aplicativos ou outros componentes do sistema.

Sintaxe

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

Parâmetros

[in] PhysicalDeviceObject

Um ponteiro para o PDO para o dispositivo.

[in] InterfaceClassGuid

Um ponteiro para o GUID de classe que identifica a funcionalidade (a classe de interface do dispositivo) que está sendo registrada.

[in, optional] ReferenceString

Opcionalmente, aponta para um UNICODE_STRING. A cadeia de caracteres não deve conter nenhum caractere separador de caminho ("/" ou "\"). Normalmente, os drivers de função especificam NULL para esse parâmetro. Os drivers de filtro devem especificar NULL.

As cadeias de caracteres de referência são usadas apenas por alguns motoristas de ônibus, como swenum, que é um driver de ônibus que usa instâncias de interface do dispositivo como espaços reservados para dispositivos de software criados sob demanda. Quando uma instância de uma interface é aberta, o gerenciador de E/S passa a cadeia de caracteres de referência da instância para o driver. A cadeia de caracteres torna-se parte do nome da instância de interface (como um componente de caminho acrescentado). Em seguida, o driver pode usar a cadeia de caracteres de referência para diferenciar entre duas instâncias de interface da mesma classe para um único dispositivo.

Nos sistemas Microsoft Windows 98/Me, o valor ReferenceString não pode ser mais do que MAX_PATH caracteres. Não há limite de comprimento no Windows 2000 e versões posteriores do Windows.

[out] SymbolicLinkName

Um ponteiro para uma estrutura de cadeia de caracteres Unicode alocada pelo chamador. Se essa rotina for bem-sucedida, ela inicializará a cadeia de caracteres Unicode e alocará o buffer de cadeia de caracteres que contém o caminho do modo kernel para o link simbólico para uma instância da classe de interface do dispositivo especificada.

O chamador deve tratar SymbolicLinkName como opaco e não deve desmontá-lo.

O chamador é responsável por liberar SymbolicLinkName com RtlFreeUnicodeString quando não for mais necessário.

Valor de retorno

IoRegisterDeviceInterface retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Os valores de retorno de erro possíveis incluem o seguinte.

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	Os parâmetros são inválidos. As possibilidades incluem que PhysicalDeviceObject não aponte para um PDO válido ou que o ReferenceString cadeia de caracteres contém um caractere inválido.

Observações

IoRegisterDeviceInterface registrará uma classe de interface do dispositivo, se ela não tiver sido registrada anteriormente, e criará uma nova instância da classe de interface. Um driver pode chamar essa rotina várias vezes para um determinado dispositivo registrar várias classes de interface e criar instâncias das classes. Um driver de função ou filtro normalmente registra interfaces de dispositivo em sua rotina AddDevice. Por exemplo, um driver de volume tolerante a falhas pode registrar uma instância de uma interface de volume tolerante a falhas e uma instância de uma interface de volume para um volume específico.

Se a classe de interface do dispositivo não tiver sido registrada anteriormente, o gerenciador de E/S criará uma chave do Registro para ela, juntamente com o armazenamento persistente específico da instância sob a chave. Os drivers podem acessar esse armazenamento persistente usando IoOpenDeviceInterfaceRegistryKey.

Um driver registra uma instância de interface uma vez e chama IoSetDeviceInterfaceState para habilitar e desabilitar a interface.

As interfaces registradas persistem entre reinicializações do sistema operacional. Se a interface especificada já estiver registrada, o gerente de E/S passará seu nome em SymbolicLinkName e retornará o status de sucesso informativo STATUS_OBJECT_NAME_EXISTS.

A maioria dos drivers usa uma cadeia de referência NULL para uma instância de interface do dispositivo. Se um driver usa uma cadeia de referência null não, ele deve fazer um trabalho adicional, incluindo possivelmente o gerenciamento de seu próprio namespace e segurança. Um driver de filtro que expõe uma interface de dispositivo deve usar um ReferenceString null para evitar conflitos com outros drivers na pilha de dispositivos.

Os chamadores dessa rotina não são necessários para remover o registro de uma interface de dispositivo quando ele não for mais necessário. Os registros da interface do dispositivo podem ser removidos do modo de usuário, se necessário.

Os chamadores de IoRegisterDeviceInterface devem estar em execução no IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível a partir do Windows 2000.
da Plataforma de Destino	Universal
cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

Consulte também

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

rtlFreeUnicodeString