Funzione WdfControlDeviceInitAllocate (wdfcontrol.h)

Articolo
02/29/2024

[Si applica solo a KMDF]

Il metodo WdfControlDeviceInitAllocate alloca una struttura WDFDEVICE_INIT utilizzata da un driver durante la creazione di un nuovo oggetto dispositivo di controllo.

Sintassi

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

Parametri

[in] Driver

Handle a un oggetto driver framework.

[in] SDDLString

Puntatore a una struttura UNICODE_STRING che descrive una stringa Unicode. Questa stringa è una rappresentazione SDDL (Security Descriptor Definition Language) di un descrittore di sicurezza. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

WdfControlDeviceInitAllocate restituisce un puntatore a una struttura di WDFDEVICE_INIT allocata da framework, se l'operazione ha esito positivo. In caso contrario, il metodo restituisce NULL.

Commenti

Se si vuole che il driver crei un oggetto dispositivo di controllo, il driver deve chiamare WdfControlDeviceInitAllocate per ottenere una struttura WDFDEVICE_INIT che può passare a WdfDeviceCreate.

Il driver può specificare un'impostazione di sicurezza usando un subset di SDDL. Il file Wdmsec.h definisce un set di costanti formattate SDDL_DEVOBJ_Xxx che è possibile usare. Per altre informazioni sui descrittori di sicurezza e SDDL, vedere Protezione degli oggetti dispositivo.

Il metodo WdfDeviceInitAssignSDDLString sovrascrive l'impostazione di sicurezza, se presente, specificata da WdfControlDeviceInitAllocate .

Per altre informazioni sulla chiamata a WdfControlDeviceInitAllocate, vedere Uso di oggetti dispositivo di controllo.

Esempio

L'esempio di codice seguente alloca una struttura DEVICE_INIT, assegna un nome dell'oggetto dispositivo, registra una funzione di callback di notifica di arresto e crea un oggetto dispositivo di controllo. Per un esempio più complesso che usa WdfControlDeviceInitAllocate, vedere il driver di esempio NONPNP o il driver di esempio 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);

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Intestazione	wdfcontrol.h (includere Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	PASSIVE_LEVEL
Regole di 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)