WdfDpcCreate, fonction (wdfdpc.h)

Article
02/27/2024

[S’applique uniquement à KMDF]

La méthode WdfDpcCreate crée un objet DPC framework et inscrit une fonction de rappel EvtDpcFunc .

Syntaxe

NTSTATUS WdfDpcCreate(
  [in]  PWDF_DPC_CONFIG        Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFDPC                 *Dpc
);

Paramètres

[in] Config

Pointeur vers une structure de WDF_DPC_CONFIG allouée par l’appelant.

[in] Attributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES allouée par l’appelant qui spécifie les attributs du nouvel objet DPC.

[out] Dpc

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet DPC d’infrastructure.

Valeur retournée

WdfDpcCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer un objet DPC.
STATUS_WDF_PARENT_NOT_SPECIFIED	Aucun objet parent n’a été spécifié dans la structure WDF_OBJECT_ATTRIBUTES .
STATUS_INVALID_DEVICE_REQUEST	Le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES ne référence pas un objet d’appareil framework ou un objet dont la chaîne de parents conduit à un objet d’appareil framework.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Le membre AutomaticSerialization de la structure WDF_DPC_CONFIG a la valeur TRUE, mais le niveau d’exécution de l’objet parent est défini sur WdfExecutionLevelPassive.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfDpcCreate peut retourner, consultez Erreurs de création d’objet Framework.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Remarques

Un pilote appelle généralement WdfDpcCreate à partir de sa fonction de rappel EvtDriverDeviceAdd .

Lorsqu’un pilote crée un objet DPC, il doit spécifier un objet parent dans le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES . L’objet parent peut être un objet d’appareil framework ou tout objet dont la chaîne de parents conduit à un objet d’appareil framework. L’infrastructure supprime l’objet DPC lorsqu’il supprime l’objet d’appareil.

L’appel de WdfDpcCreate crée un objet DPC framework et inscrit une fonction de rappel EvtDpcFunc. Pour planifier l’exécution de la fonction de rappel, le pilote doit appeler WdfDpcEnqueue.

Si votre pilote fournit des fonctions de rappel EvtCleanupCallback ou EvtDestroyCallback pour l’objet de minuteur d’infrastructure, notez que l’infrastructure appelle ces fonctions de rappel à l’adresse IRQL = PASSIVE_LEVEL.

Pour plus d’informations sur l’utilisation d’objets DPC, consultez Maintenance d’une interruption.

Exemples

L’exemple de code suivant initialise une structure WDF_DPC_CONFIG_INIT , puis crée un objet DPC.

WDF_DPC_CONFIG dpcConfig;
WDF_OBJECT_ATTRIBUTES dpcAttributes;
NTSTATUS status;

WDF_DPC_CONFIG_INIT(
                    &dpcConfig,
                    MyEvtDpcFunc
                    );
dpcConfig.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&dpcAttributes);
dpcAttributes.ParentObject = pDevExt->WdfDevice;
status = WdfDpcCreate(
                      &dpcConfig,
                      &dpcAttributes,
                      &pDevExt->CompleteWriteDpc
                      );
if (!NT_SUCCESS(status)) {
    return status;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfdpc.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)