Metodo IWDFFileHandleTargetFactory::CreateFileHandleTarget (wudfddi.h)

Articolo
08/08/2023

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre info, vedi Introduzione con UMDF.]

Il metodo CreateFileHandleTarget crea un oggetto di destinazione di I/O basato su handle file.

Sintassi

HRESULT CreateFileHandleTarget(
  [in]  HANDLE       hTarget,
  [out] IWDFIoTarget **ppTarget
);

Parametri

[in] hTarget

Handle per il dispositivo di destinazione. L'handle deve essere stato aperto in precedenza con il flag FILE_FLAG_OVERLAPPED. Ad esempio, FILE_FLAG_OVERLAPPED deve essere stato specificato nel parametro dwFlagsAndAttributes della funzione CreateFile Di Microsoft Win32.

[out] ppTarget

Puntatore a una posizione che riceve un puntatore all'interfaccia IWDFIoTarget dell'oggetto di destinazione I/O.

Valore restituito

CreateFileHandleTarget restituisce uno dei valori seguenti:

Codice restituito	Descrizione
S_OK	CreateFileHandleTarget ha creato correttamente un oggetto di destinazione di I/O basato su handle file.
E_OUTOFMEMORY	CreateFileHandleTarget ha rilevato un errore di allocazione.

CreateFileHandleTarget potrebbe anche restituire altri valori HRESULT definiti in Winerror.h.

Commenti

Se il driver usa una destinazione di I/O basata su handle file, la sezione DDInstall.WDF del file INF del driver deve impostare la direttiva UmdfDispatcher su FileHandle. Per altre informazioni su UmdfDispatcher, vedere Specifica delle direttive WDF.

Dopo che il driver crea un oggetto di destinazione di I/O basato su handle file, può formattare le richieste di I/O e inviarle alla destinazione di I/O. In genere, se il driver chiama IWDFIoTarget::FormatRequestForRead, IWDFIoTarget::FormatRequestForWrite o IWDFIoTarget::FormatRequestForIoctl, il driver imposta il parametro pFile su NULL. Null fa in modo che il framework usi il nome file specificato dal driver in CreateFileHandleTarget. Se il driver fornisce un parametro pFile non NULL, il file specificato sostituisce il file specificato dal driver specificato in CreateFileHandleTarget. I driver possono anche chiamare IWDFIoRequest::FormatUsingCurrentType per formattare una richiesta di I/O.

Quando il driver chiama IWDFIoRequest::Send per inviare la richiesta di I/O alla destinazione di I/O, il driver non deve impostare il valore WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET nel parametro Flags .

L'handle Win32 che il driver passa a CreateFileHandleTarget deve rimanere valido per tutta la durata dell'oggetto di destinazione di I/O basato su handle file. Il framework non accetta un riferimento su questo handle di destinazione, quindi il driver deve assicurarsi che l'handle Win32 rimanga valido.

Al termine dell'uso dell'interfaccia IWDFIoTarget fornita da CreateFileHandleTarget , il driver deve rilasciare l'interfaccia IWDFIoTarget .

Per altre informazioni sulle destinazioni CreateFileHandleTarget e I/O, vedere Inizializzazione di una destinazione di I/O generale in UMDF.

Esempio

Nell'esempio di codice seguente viene illustrato come creare una destinazione di I/O basata su handle file per una named pipe. In questo esempio , m_FxDevice è il puntatore all'interfaccia fornito da IWDFDriver::CreateDevice .

HRESULT hr = S_OK;
CComPtr<IWDFFileHandleTargetFactory> pFileHandleTargetFactory;
//
// Create a pipe and get the handle.
//
m_WriteHandle = CreateNamedPipe(NP_NAME, 
                                PIPE_ACCESS_DUPLEX|FILE_FLAG_OVERLAPPED, 
                                PIPE_TYPE_MESSAGE|PIPE_READMODE_MESSAGE|PIPE_WAIT,
                                2,
                                MAX_TRANSFER_SIZE,
                                MAX_TRANSFER_SIZE,
                                1000,
                                NULL);
if (m_WriteHandle == INVALID_HANDLE_VALUE) {
    DWORD err = GetLastError();
    hr = HRESULT_FROM_WIN32(err);
}
//
// Obtain the IWDFFileHandleTargetFactory interface
// by calling IWDFDevice::QueryInterface. 
//
if (SUCCEEDED(hr)) {
    hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&pFileHandleTargetFactory));
}
//
// Create a file handle target.
//
if (SUCCEEDED(hr)) {
    hr = pFileHandleTargetFactory->CreateFileHandleTarget(m_WriteHandle,
                                                          &m_WriteTarget);
}

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.5
Intestazione	wudfddi.h (include Wudfusb.h)
DLL	WUDFx.dll

Vedi anche

IWDFFileHandleTargetFactory

IWDFIoRequest::Send

IWDFIoTarget

Condividi tramite