Fonction IoReportResourceForDetection (ntddk.h)

Le IoReportResourceForDetection ressources matérielles de revendications de routine 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 de pilote qui a été entré dans la routine DriverEntry du pilote.

[in, optional] DriverList

Le pilote 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’un DriverList facultatif. Si DriverList est NULL, ce paramètre doit être égal à zéro.

[in, optional] DeviceObject

Si vous le souhaitez, il pointe vers l’objet de périphérique représentant l’appareil pour lequel le pilote tente de revendiquer des ressources.

[in, optional] DeviceList

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

[in, optional] DeviceListSize

Spécifie la taille en octets d’un DeviceList facultatif. Si deviceList est NULL, ce paramètre doit être égal à zéro.

[out] ConflictDetected

Pointeur vers une valeur booléenne fournie par l’appelant qui est définie sur TRUE lors du retour si les ressources ne sont pas disponibles.

Valeur de retour

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

Retourner le code	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	L'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.

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

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

Un pilote qui peut contrôler plusieurs cartes héritées en même temps doit revendiquer les ressources de chaque appareil par rapport à l’objet d’appareil pour l’appareil respectif (à l’aide de l'DeviceObject, DeviceListet Paramètres DeviceListSize). Un tel pilote ne doit pas revendiquer ces ressources sur leur objet de pilote.

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

IoReportResourceForDetection, avec 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 à ConflictDetected sur TRUE et retourne STATUS_CONFLICTING_ADDRESSES.

Si aucun conflit n’est détecté, cette routine demande les ressources, définit la valeur BOOLEAN sur ConflictDetected sur FALSEet 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 pour TRUE 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 de zéro.

Si un pilote demande 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 cette routine à nouveau avec une nouvelle liste ; la nouvelle liste remplace la liste précédente.

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

Exigences

Exigence	Valeur
plateforme cible	Universel
d’en-tête	ntddk.h (include Ntddk.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)

Voir aussi

CM_RESOURCE_LIST

IoReportDetectedDevice