Funzione WdfIoTargetOpen (wdfiotarget.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfIoTargetOpen apre una destinazione di I/O remota in modo che il driver possa inviare richieste di I/O.

Sintassi

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

Parametri

[in] IoTarget

Handle a un oggetto di destinazione di I/O ottenuto da una chiamata precedente a WdfIoTargetCreate.

[in] OpenParams

Puntatore a una struttura WDF_IO_TARGET_OPEN_PARAMS allocata dal chiamante.

Valore restituito

WdfIoTargetOpen restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_STATE	La destinazione di I/O specificata è già aperta.
STATUS_INSUFFICIENT_RESOURCES	Le risorse di sistema disponibili non sono sufficienti per completare l'operazione.
STATUS_INFO_LENGTH_MISMATCH	La dimensione della struttura WDF_IO_TARGET_OPEN_PARAMS specificata da OpenParams non è corretta.
STATUS_NO_SUCH_DEVICE	Il membro TargetFileObject della struttura WDF_IO_TARGET_OPEN_PARAMS del chiamante ha specificato un oggetto file non valido.
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_NOT_FOUND	Impossibile trovare il nome del dispositivo identificato nel parametro OpenParams .

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

I driver possono aprire destinazioni di I/O remote fornendo una stringa Unicode che rappresenta un nome dell'oggetto o fornendo un puntatore a una struttura WDM (Windows Driver Model) DEVICE_OBJECT . I driver basati su framework in genere non dispongono di puntatori alle strutture DEVICE_OBJECT di altri driver.

Per ottenere un nome dell'interfaccia del dispositivo prima di chiamare WdfIoTargetOpen, un driver UMDF deve chiamare CM_Register_Notification per registrare la notifica di arrivo e rimozione dell'interfaccia. Può quindi aprire la destinazione remota usando il nome simbolico dell'interfaccia che riceve nella routine di callback di notifica dell'interfaccia. Il driver deve continuare ad ascoltare la notifica di rimozione mentre l'handle è aperto. Se il driver di destinazione ha esito negativo, il driver UMDF deve chiudere l'handle.

Se l'interfaccia esiste già, un driver UMDF deve chiamare CM_Get_Device_Interface_List, eventualmente chiamando prima CM_Get_Device_Interface_List_Size per determinare le dimensioni del buffer necessarie.

Se si vuole che il driver usi la destinazione I/O locale, il driver deve chiamare WdfDeviceGetIoTarget anziché WdfIoTargetOpen.

Se una chiamata a WdfIoTargetOpen ha esito negativo, il driver deve chiamare WdfObjectDelete per eliminare l'oggetto di destinazione I/O.

Per altre informazioni su WdfIoTargetOpen, vedere Inizializzazione di una destinazione di I/O generale.

Per altre informazioni sulle destinazioni di I/O, vedere Uso delle destinazioni di I/O.

Esempio

L'esempio seguente crea un oggetto di destinazione I/O, inizializza una struttura WDF_IO_TARGET_OPEN_PARAMS e apre una destinazione di I/O remota specificando il nome simbolico del collegamento di un dispositivo.

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfiotarget.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)