Fonction IoReportResourceForDetection (ntddk.h)

La routine IoReportResourceForDetection revendique des ressources matérielles dans le registre de configuration d’un appareil hérité.

Syntaxe

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
);

Paramètres

[in] DriverObject

Pointeur vers l’objet pilote qui a été entré dans la routine DriverEntry du pilote.

[in, optional] DriverList

Pointe éventuellement vers une mémoire tampon fournie par l’appelant qui contient la liste des ressources du pilote, si le pilote revendique les mêmes ressources pour tous ses appareils. Si l’appelant spécifie un DeviceList, ce paramètre est ignoré.

[in, optional] DriverListSize

Spécifie la taille en octets d’une liste de pilotes facultative. Si DriverList a la valeurNULL, ce paramètre doit être égal à zéro.

[in, optional] DeviceObject

Pointe éventuellement vers l’objet d’appareil représentant l’appareil pour lequel le pilote tente de réclamer des ressources.

[in, optional] DeviceList

Pointe éventuellement vers une mémoire tampon fournie par l’appelant contenant la liste de ressources de l’appareil. Si le pilote revendique les mêmes ressources pour tous ses appareils, l’appelant peut spécifier une liste de pilotes à la place.

[in, optional] DeviceListSize

Spécifie la taille en octets d’une deviceList facultative. Si DeviceList a la valeur NULL, ce paramètre doit être égal à zéro.

[out] ConflictDetected

Pointeur vers une valeur booléenne fournie par l’appelant qui a la valeur TRUE au retour si les ressources ne sont pas disponibles.

Valeur retournée

IoReportResourceForDetection retourne STATUS_SUCCESS si les ressources sont revendiquées. Les valeurs de retour d’erreur possibles sont les suivantes.

Code de retour	Description
STATUS_CONFLICTING_ADDRESSES	Les ressources n’ont pas pu être revendiquées, car elles sont déjà en cours d’utilisation ou sont nécessaires pour un appareil énumérable PnP.
STATUS_UNSUCCESSFUL	DeviceList ou DriverList n’est pas valide.

Remarques

Cette routine concerne les pilotes qui détectent le matériel antérieur qui ne peut pas être énuméré par Plug-and-Play (PnP).

Si un pilote prend uniquement en charge le matériel PnP, il n’effectue aucune détection et n’appelle donc pas IoReportResourceForDetection. Le système PnP énumère chaque appareil PnP, affecte des ressources à l’appareil et transmet ces ressources aux pilotes de l’appareil dans une demande de IRP_MN_START_DEVICE .

Toutefois, si un pilote PnP prend en charge le matériel hérité, il doit appeler IoReportResourceForDetection pour réclamer des ressources matérielles avant de tenter de détecter l’appareil.

Les appelants de cette routine spécifient un CM_RESOURCE_LIST dans une DeviceList ou une DriverList allouée à partir de la mémoire paginée et qui se compose de ressources brutes et non traduites. L’appelant est responsable de libérer la mémoire.

Un pilote qui peut contrôler plusieurs carte hérités en même temps doit revendiquer les ressources de chaque appareil sur l’objet d’appareil correspondant (à l’aide des paramètres DeviceObject, DeviceListet DeviceListSize). Un tel pilote ne doit pas revendiquer ces ressources sur son objet de pilote.

Un CM_RESOURCE_LIST contient deux tableaux de taille variable. Chaque tableau a une taille par défaut d’un. Si l’un des tableaux a plusieurs éléments, l’appelant doit allouer de la mémoire dynamiquement pour contenir les éléments supplémentaires. Un seul CM_PARTIAL_RESOURCE_DESCRIPTOR peut faire partie de chaque CM_FULL_RESOURCE_DESCRIPTOR de la liste, à l’exception du dernier descripteur de ressources complet dans le CM_RESOURCE_LIST, qui peut avoir des descripteurs de ressources partiels supplémentaires dans son tableau.

IoReportResourceForDetection, à l’aide du gestionnaire PnP, détermine si les ressources demandées sont en conflit avec les ressources qui ont déjà été revendiquées.

Si un conflit est détecté, cette routine définit la valeur BOOLEAN sur ConflictDetected sur TRUE et retourne STATUS_CONFLICTING_ADDRESSES.

Si aucun conflit n’est détecté, cette routine réclame les ressources, définit la valeur BOOLEAN sur ConflictDetected sur FALSE et retourne STATUS_SUCCESS.

Si cette routine réussit et que le pilote détecte un appareil hérité, le pilote signale l’appareil au gestionnaire PnP en appelant IoReportDetectedDevice. Dans cet appel, le pilote définit ResourceAssigned surTRUE afin que le gestionnaire PnP ne tente pas de réclamer à nouveau les ressources.

Lorsqu’un pilote n’a plus besoin des ressources revendiquées par un appel à cette routine, le pilote appelle à nouveau cette routine avec un DriverList ou DeviceList avec un nombre de zéro.

Si un pilote réclame des ressources sur une base spécifique à l’appareil pour plusieurs appareils, le pilote doit appeler cette routine pour chaque appareil de ce type.

Un pilote peut appeler cette routine plusieurs fois pour un appareil donné. Si un ensemble de ressources échoue, le pilote peut appeler à nouveau la routine pour le même appareil avec un autre ensemble de ressources. Si un ensemble de ressources réussit, le pilote peut appeler à nouveau cette routine avec une nouvelle liste ; la nouvelle liste remplace la liste précédente.

Les appelants d’IoReportResourceForDetection doivent s’exécuter à IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	ntddk.h (inclure Ntddk.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)

Voir aussi

CM_RESOURCE_LIST

IoReportDetectedDevice