Função IoReportResourceForDetection (ntddk.h)
O IoReportResourceForDetection recursos de hardware de declarações de rotina 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 de 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 um 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 em vez disso.
[in, optional] DeviceListSize
Especifica o tamanho em bytes de uma lista de dispositivos opcional. Se DeviceList for NULL, esse parâmetro deverá ser zero.
[out] ConflictDetected
Ponteiro para um valor booliano fornecido pelo chamador que é definido como VERDADEIRO no retorno se os recursos não estiverem disponíveis.
Valor de retorno
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 | O DeviceList ou DriverList é inválido. |
Observações
Essa rotina é para drivers que detectam hardware anterior que não pode ser enumerado pelo PnP (Plug and Play).
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 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 um CM_RESOURCE_LIST em um DeviceList ou um DriverList alocado 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 de dispositivo do respectivo dispositivo (usando os parâmetros DeviceObject, DeviceListe DeviceListSize parâmetros). 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 um CM_PARTIAL_RESOURCE_DESCRIPTOR pode fazer parte de cada CM_FULL_RESOURCE_DESCRIPTOR na lista, exceto pelo último descritor de recurso 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 solicitados entram em conflito com os recursos que já foram reivindicados.
Se um conflito for detectado, essa rotina definirá o BOOLEAN em ConflictDetected para TRUE e retornará STATUS_CONFLICTING_ADDRESSES.
Se nenhum conflito for detectado, essa rotina reivindicará os recursos, definirá o BOOLEAN em ConflictDetected para 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 para verdadeiro para que o gerenciador PnP não tente reivindicar os recursos novamente.
Quando um driver não requer 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 solicitar 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 no IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.
Requisitos
| Requisito | Valor |
|---|---|
| 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) |