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 barramento 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 do dispositivo, o driver fornecerá o valor -1 para esse parâmetro.

[in] SlotNumber

Especifica o número do 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 do 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 formato bruto e não traduzido.

[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 TRUE, os recursos já foram relatados, possivelmente com IoReportResourceForDetection, e o gerenciador PnP não tentará reivindicá-los em nome do dispositivo. Se TRUE, o gerenciador PnP também não solicitará recursos quando o dispositivo for enumerado por raiz nas inicializações subsequentes.

[in, out] DeviceObject

Opcionalmente, aponta para um PDO para o dispositivo detectado.

NULL se o chamador não tiver um PDO para o dispositivo, o que normalmente é o caso. Se DeviceObject for NULL, o gerenciador de 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.

Retornar valor

IoReportDetectedDevice retorna STATUS_SUCCESS em caso de êxito ou o código de erro apropriado em caso de falha.

Comentários

Os drivers para dispositivos herdados usam IoReportDetectedDevice para relatar seus dispositivos ao sistema. Um driver só deve chamar IoReportDetectedDevice para relatar um dispositivo não PnP herdado. Os dispositivos PnP devem ser relatados em resposta a uma solicitação de IRP_MN_QUERY_DEVICE_RELATIONS .

Os drivers só precisam chamar IoReportDetectedDevice na 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 de dispositivo.

Um driver normalmente chama essa rotina de sua rotina 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 como iniciado e, portanto, não chama a rotina AddDevice do driver e não envia uma solicitação de 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 por raiz e essa identificação é persistente entre as inicializações do sistema. Durante a inicialização subsequente do sistema, 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 suas rotinas AddDevice e envia todos os IRPs PnP apropriados.

O sistema gera duas cadeias de caracteres de ID compatíveis para o dispositivo, do formatoDriver deInterface\ DETECTADO e DETECTED\Driver. Interface é o nome da cadeia de caracteres do INTERFACE_TYPE do primeiro barramento especificado no parâmetro ResourceList . A interface será definida como "Interna" 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 de 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 em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.

Requisitos

Confira também

IRP_MN_QUERY_DEVICE_RELATIONS

IoReportResourceForDetection