Función WdfControlDeviceInitAllocate (wdfcontrol.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfControlDeviceInitAllocate asigna una estructura de WDFDEVICE_INIT que un controlador usa al crear un nuevo objeto de dispositivo de control.

Sintaxis

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

Parámetros

[in] Driver

Identificador de un objeto de controlador de marco.

[in] SDDLString

Puntero a una estructura UNICODE_STRING que describe una cadena Unicode. Esta cadena es una representación del Lenguaje de definición de descriptores de seguridad (SDDL) de un descriptor de seguridad. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Valor devuelto

WdfControlDeviceInitAllocate devuelve un puntero a una estructura de WDFDEVICE_INIT asignada por el marco, si la operación se realiza correctamente. De lo contrario, el método devuelve NULL.

Comentarios

Si desea que el controlador cree un objeto de dispositivo de control, el controlador debe llamar a WdfControlDeviceInitAllocate para obtener una estructura de WDFDEVICE_INIT que pueda pasar a WdfDeviceCreate.

El controlador puede especificar una configuración de seguridad mediante un subconjunto de SDDL. El archivo Wdmsec.h define un conjunto de constantes con formato SDDL_DEVOBJ_Xxx que puede usar. Para obtener más información sobre los descriptores de seguridad y SDDL, consulte Protección de objetos de dispositivo.

El método WdfDeviceInitAssignSDDLString sobrescribe la configuración de seguridad, si existe, que WdfControlDeviceInitAllocate especifica.

Para obtener más información sobre cómo llamar a WdfControlDeviceInitAllocate, vea Usar objetos de dispositivo de control.

Ejemplos

En el ejemplo de código siguiente se asigna una estructura de DEVICE_INIT, se asigna un nombre de objeto de dispositivo, se registra una función de devolución de llamada de notificación de apagado y se crea un objeto de dispositivo de control. Para obtener un ejemplo más complejo que usa WdfControlDeviceInitAllocate, consulte el controlador de ejemplo NONPNP o el controlador de ejemplo 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);

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfcontrol.h (incluya Wdf.h)
Library	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de 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)