Função IoReportResourceForDetection (ntddk.h)
A rotina IoReportResourceForDetection declara recursos de hardware no registro de configuração de um dispositivo herdado.
Sintaxe
NTSTATUS IoReportResourceForDetection(
[in] PDRIVER_OBJECT DriverObject,
[in, optional] PCM_RESOURCE_LIST DriverList,
[in, optional] ULONG DriverListSize,
[in, optional] PDEVICE_OBJECT DeviceObject,
[in, optional] PCM_RESOURCE_LIST DeviceList,
[in, optional] ULONG DeviceListSize,
[out] PBOOLEAN ConflictDetected
);
Parâmetros
[in] DriverObject
Ponteiro para o objeto driver que foi inserido na rotina driverEntry do driver.
[in, optional] DriverList
Opcionalmente, aponta para um buffer fornecido pelo chamador que contém a lista de recursos do driver, se o driver reivindicar os mesmos recursos para todos os seus dispositivos. Se o chamador especificar um DeviceList, esse parâmetro será ignorado.
[in, optional] DriverListSize
Especifica o tamanho em bytes de uma DriverList opcional. Se DriverList for NULL, esse parâmetro deverá ser zero.
[in, optional] DeviceObject
Opcionalmente, aponta para o objeto de dispositivo que representa o dispositivo para o qual o driver está tentando reivindicar recursos.
[in, optional] DeviceList
Opcionalmente, aponta para um buffer fornecido pelo chamador que contém a lista de recursos do dispositivo. Se o driver reivindicar os mesmos recursos para todos os seus dispositivos, o chamador poderá especificar um DriverList .
[in, optional] DeviceListSize
Especifica o tamanho em bytes de um DeviceList opcional. Se DeviceList for NULL, esse parâmetro deverá ser zero.
[out] ConflictDetected
Ponteiro para um valor booliano fornecido pelo chamador definido como TRUE no retorno se os recursos não estiverem disponíveis.
Retornar valor
IoReportResourceForDetection retornará STATUS_SUCCESS se os recursos forem reivindicados. Os valores de retorno de erro possíveis incluem o seguinte.
| Código de retorno | Descrição |
|---|---|
| STATUS_CONFLICTING_ADDRESSES | Os recursos não puderam ser reivindicados porque já estão em uso ou são necessários para um dispositivo Enumerável PnP. |
| STATUS_UNSUCCESSFUL | DeviceList ou DriverList é inválido. |
Comentários
Essa rotina é para drivers que detectam hardware anterior que não pode ser enumerado por Plug and Play (PnP).
Se um driver dá suporte apenas ao hardware PnP, ele não faz nenhuma detecção e, portanto, não chama IoReportResourceForDetection. O sistema PnP enumera cada dispositivo PnP, atribui recursos ao dispositivo e passa esses recursos para os drivers do dispositivo em uma solicitação de IRP_MN_START_DEVICE .
No entanto, se um driver PnP der suporte a hardware herdado, ele deverá chamar IoReportResourceForDetection para reivindicar recursos de hardware antes de tentar detectar o dispositivo.
Os chamadores dessa rotina especificam uma CM_RESOURCE_LIST em um DeviceList ou uma DriverList alocada da memória paginada e que consiste em recursos brutos e não traduzidos. O chamador é responsável por liberar a memória.
Um driver que pode controlar mais de um cartão herdado ao mesmo tempo deve reivindicar os recursos de cada dispositivo em relação ao objeto do dispositivo para o respectivo dispositivo (usando os parâmetros DeviceObject, DeviceList e DeviceListSize). Esse driver não deve reivindicar esses recursos em relação ao objeto de driver.
Um CM_RESOURCE_LIST contém duas matrizes de tamanho variável. Cada matriz tem um tamanho padrão de um. Se uma das matrizes tiver mais de um elemento, o chamador deverá alocar memória dinamicamente para conter os elementos adicionais. Apenas uma CM_PARTIAL_RESOURCE_DESCRIPTOR pode fazer parte de cada CM_FULL_RESOURCE_DESCRIPTOR na lista, exceto pelo último descritor de recursos completo no CM_RESOURCE_LIST, que pode ter descritores de recursos parciais adicionais em sua matriz.
IoReportResourceForDetection, com a ajuda do gerenciador PnP, determina se os recursos que estão sendo solicitados entram em conflito com recursos que já foram reivindicados.
Se um conflito for detectado, essa rotina definirá o BOOLEAN em ConflictDetected como TRUE e retornará STATUS_CONFLICTING_ADDRESSES.
Se nenhum conflito for detectado, essa rotina reivindicará os recursos, definirá BOOLEAN em ConflictDetected como FALSE e retornará STATUS_SUCCESS.
Se essa rotina for bem-sucedida e o driver detectar um dispositivo herdado, o driver relatará o dispositivo ao gerenciador PnP chamando IoReportDetectedDevice. Nessa chamada, o driver define ResourceAssigned como TRUE para que o gerenciador PnP não tente reivindicar os recursos novamente.
Quando um driver não exige mais os recursos reivindicados por uma chamada para essa rotina, o driver chama essa rotina novamente com um DriverList ou DeviceList com uma Contagem de zero.
Se um driver reivindicar recursos em uma base específica do dispositivo para mais de um dispositivo, o driver deverá chamar essa rotina para cada dispositivo desse tipo.
Um driver pode chamar essa rotina mais de uma vez para um determinado dispositivo. Se um conjunto de recursos falhar, o driver poderá chamar a rotina novamente para o mesmo dispositivo com um conjunto diferente de recursos. Se um conjunto de recursos for bem-sucedido, o driver poderá chamar essa rotina novamente com uma nova lista; a nova lista substitui a lista anterior.
Os chamadores de IoReportResourceForDetection devem estar em execução em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Cabeçalho | ntddk.h (inclua Ntddk.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (consulte a seção Comentários) |