Função IoReportDetectedDevice (ntddk.h)
A rotina IoReportDetectedDevice relata um dispositivo não PnP para o gerenciador PnP.
Sintaxe
NTSTATUS IoReportDetectedDevice(
[in] PDRIVER_OBJECT DriverObject,
[in] INTERFACE_TYPE LegacyBusType,
[in] ULONG BusNumber,
[in] ULONG SlotNumber,
[in, optional] PCM_RESOURCE_LIST ResourceList,
[in, optional] PIO_RESOURCE_REQUIREMENTS_LIST ResourceRequirements,
[in] BOOLEAN ResourceAssigned,
[in, out] PDEVICE_OBJECT *DeviceObject
);
Parâmetros
[in] DriverObject
Ponteiro para o objeto driver do driver que detectou o dispositivo.
[in] LegacyBusType
Especifica o tipo de ônibus no qual o dispositivo reside. O gerenciador PnP usa essas informações para corresponder o dispositivo relatado à instância enumerada por PnP, se houver.
Os tipos de interface, como PCIBus, são definidos em Wdm.h. Se um driver não souber o LegacyBusType para o dispositivo, o driver fornecerá o valor InterfaceTypeUndefined para esse parâmetro.
[in] BusNumber
Especifica o número do barramento para o dispositivo. O gerenciador PnP usa essas informações para corresponder o dispositivo relatado à instância enumerada por PnP, se houver.
O número do ônibus distingue o ônibus no qual o dispositivo reside de outros ônibus do mesmo tipo no computador. O esquema de numeração de ônibus é específico do ônibus. Se um driver não souber o BusNumber para o dispositivo, o driver fornecerá o valor -1 para esse parâmetro.
[in] SlotNumber
Especifica o número de slot lógico do dispositivo. O gerenciador PnP usa essas informações para corresponder o dispositivo relatado à instância enumerada por PnP, se houver.
Se um driver não souber o SlotNumber para o dispositivo, o driver fornecerá o valor -1 para esse parâmetro.
[in, optional] ResourceList
Ponteiro para a lista de recursos que o driver usou para detectar o dispositivo. Os recursos nesta lista estão em forma bruta e não traduzida.
[in, optional] ResourceRequirements
Opcionalmente, aponta para uma lista de requisitos de recursos para o dispositivo detectado. NULL se o chamador não tiver essas informações para o dispositivo.
[in] ResourceAssigned
Especifica se os recursos do dispositivo já foram relatados ao gerenciador PnP. Se ResourceAssigned for VERDADEIRO, os recursos já foram relatados, possivelmente com IoReportResourceForDetection e o gerenciador PnP não tentará reivindicá-los em nome do dispositivo. Se VERDADEIRO, o gerenciador PnP também não solicitará recursos quando o dispositivo for enumerado em inicialização subsequente.
[in, out] DeviceObject
Opcionalmente, aponta para um PDO para o dispositivo detectado.
NULL se o chamador não tiver um PDO para o dispositivo, que normalmente é o caso. Se DeviceObject for NULL, o gerenciador PnP criará um PDO para o dispositivo e retornará um ponteiro para o chamador.
Se o chamador fornecer um PDO, o gerenciador PnP não criará um novo PDO. Em uma determinada chamada para essa rotina, o parâmetro DeviceObject é um parâmetro IN ou OUT, mas não ambos.
Valor de retorno
IoReportDetectedDevice retorna STATUS_SUCCESS com êxito ou o código de erro apropriado sobre falha.
Observações
Os drivers para dispositivos herdados usam IoReportDetectedDevice para relatar seus dispositivos ao sistema. Um driver deve chamar apenas IoReportDetectedDevice para relatar um dispositivo não PnP herdado. Os dispositivos PnP devem ser relatados em resposta a uma solicitação IRP_MN_QUERY_DEVICE_RELATIONS.
Os drivers só precisam chamar IoReportDetectedDevice a primeira vez que são carregados porque o gerenciador PnP armazena em cache as informações relatadas. Os drivers que usam essa rotina devem armazenar um sinalizador no registro para indicar se já fizeram a detecção do dispositivo.
Um driver normalmente chama essa rotina de sua rotina de DriverEntry. Alguns drivers, como determinados drivers NDIS ou EISA, podem chamar essa rotina de uma rotina AddDevice.
Após a conclusão bem-sucedida de IoReportDetectedDevice, o chamador deve anexar um FDO ao PDO retornado em DeviceObject. Depois que o chamador anexa seu FDO, o chamador é o driver de função do dispositivo, pelo menos temporariamente. Não há drivers de filtro. O gerenciador PnP é proprietário do PDO.
O gerenciador PnP considera o dispositivo iniciado e, portanto, não chama a rotina AddDevice do driver e não envia uma solicitação IRP_MN_START_DEVICE. No entanto, o driver deve estar preparado para lidar com todos os outros IRPs PnP.
IoReportDetectedDevice marca o dispositivo como um dispositivo enumerado raiz e essa identificação é persistente entre as inicializações do sistema. Durante o sistema subsequente, o gerenciador PnP "detecta" o dispositivo na lista enumerada raiz e o configura como um dispositivo PnP: o gerenciador PnP consulta informações do dispositivo, identifica os drivers apropriados e chama seus rotinas de AddDevice e envia todos os IRPs PnP apropriados.
O sistema gera duas cadeias de caracteres de ID compatíveis para o dispositivo, do formulário DETECTEDInterface\Driver e DETECTED\Driver. Interface é o nome da cadeia de caracteres do INTERFACE_TYPE do primeiro barramento especificado no parâmetro ResourceList. Interface será definido como "Interno" se nenhum barramento for especificado. Driver é o nome do serviço do driver. Um driver pode fornecer IDs de hardware adicionais ou IDs compatíveis manipulando a solicitação IRP_MN_QUERY_ID.
Um gravador de driver deve fornecer um arquivo INF que corresponda a qualquer uma das IDs de hardware especificadas ou IDs compatíveis. O arquivo INF deve especificar o driver original que chamou IoReportDetectedDevice como o driver a ser carregado para essas IDs. O sistema usa essas informações para recompilar a pilha de driver do dispositivo, por exemplo, na reinicialização. Os chamadores de IoReportDetectedDevice 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 | ntddk.h (inclua Ntddk.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (consulte a seção Comentários) |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |