WdfControlDeviceInitAllocate, fonction (wdfcontrol.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La méthode WdfControlDeviceInitAllocate alloue une structure WDFDEVICE_INIT qu’un pilote utilise lors de la création d’un objet de périphérique de contrôle.

Syntaxe

PWDFDEVICE_INIT WdfControlDeviceInitAllocate(
  [in] WDFDRIVER            Driver,
  [in] const UNICODE_STRING *SDDLString
);

Paramètres

[in] Driver

Handle pour un objet de pilote d’infrastructure.

[in] SDDLString

Pointeur vers une structure UNICODE_STRING qui décrit une chaîne Unicode. Cette chaîne est une représentation SDDL (Security Descriptor Definition Language) d’un descripteur de sécurité. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

WdfControlDeviceInitAllocate retourne un pointeur vers une structure de WDFDEVICE_INIT allouée par l’infrastructure, si l’opération réussit. Sinon, la méthode retourne NULL.

Remarques

Si vous souhaitez que votre pilote crée un objet de périphérique de contrôle, il doit appeler WdfControlDeviceInitAllocate pour obtenir une structure WDFDEVICE_INIT qu’il peut passer à WdfDeviceCreate.

Votre pilote peut spécifier un paramètre de sécurité à l’aide d’un sous-ensemble de SDDL. Le fichier Wdmsec.h définit un ensemble de constantes au format SDDL_DEVOBJ_Xxx que vous pouvez utiliser. Pour plus d’informations sur les descripteurs de sécurité et SDDL, consultez Sécurisation des objets d’appareil.

La méthode WdfDeviceInitAssignSDLString remplace le paramètre de sécurité, le cas échéant, spécifié par WdfControlDeviceInitAllocate .

Pour plus d’informations sur l’appel de WdfControlDeviceInitAllocate, consultez Utilisation d’objets d’appareil de contrôle.

Exemples

L’exemple de code suivant alloue une structure de DEVICE_INIT, attribue un nom d’objet d’appareil, inscrit une fonction de rappel de notification d’arrêt et crée un objet d’appareil de contrôle. Pour obtenir un exemple plus complexe qui utilise WdfControlDeviceInitAllocate, consultez l’exemple de pilote NONPNP ou l’exemple de pilote NDISProt .

PWDFDEVICE_INIT  deviceInit = NULL;
NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  objectAttribs;

deviceInit = WdfControlDeviceInitAllocate(
                                          hDriver,
                                          &SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_RW_RES_R
                                          );
if (deviceInit == NULL) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    goto Error;
}
status = WdfDeviceInitAssignName(
                                 deviceInit,
                                 &ntDeviceName
                                 );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlDeviceInitSetShutdownNotification(
                                            deviceInit,
                                            EvtShutdownNotification,
                                            WdfDeviceShutdown
                                            );
WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);

status = WdfDeviceCreate(
                         &deviceInit,
                         &objectAttribs,
                         &controlDevice
                         );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlFinishInitializing(controlDevice);

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfcontrol.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDrEntry(kmdf), DoubleDeviceInitFree(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)