Méthode IWDFFileHandleTargetFactory ::CreateFileHandleTarget (wudfddi.h)

Article
02/27/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthode CreateFileHandleTarget crée un objet cible d’E/S basé sur un handle de fichier.

Syntaxe

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

Paramètres

[in] hTarget

Handle pour l’appareil cible. Le handle doit avoir été précédemment ouvert avec l’indicateur FILE_FLAG_OVERLAPPED. Par exemple, FILE_FLAG_OVERLAPPED doivent avoir été spécifiés dans le paramètre dwFlagsAndAttributes de la fonction Microsoft Win32 CreateFile .

[out] ppTarget

Pointeur vers un emplacement qui reçoit un pointeur vers l’interface IWDFIoTarget de l’objet cible d’E/S.

Valeur retournée

CreateFileHandleTarget retourne l’une des valeurs suivantes :

Code de retour	Description
S_OK	CreateFileHandleTarget a correctement créé un objet cible d’E/S basé sur un handle de fichier.
E_OUTOFMEMORY	CreateFileHandleTarget a rencontré un échec d’allocation.

CreateFileHandleTarget peut également retourner d’autres valeurs HRESULT définies dans Winerror.h.

Remarques

Si votre pilote utilise une cible d’E/S basée sur un handle de fichier, la section DDInstall.WDF du fichier INF du pilote doit définir la directive UmdfDispatcher sur FileHandle. Pour plus d’informations sur UmdfDispatcher, consultez Spécification de directives WDF.

Une fois que le pilote a créé un objet cible d’E/S basé sur un handle de fichier, il peut mettre en forme les demandes d’E/S et les envoyer à la cible d’E/S. En règle générale, si le pilote appelle IWDFIoTarget ::FormatRequestForRead, IWDFIoTarget ::FormatRequestForWrite ou IWDFIoTarget ::FormatRequestForIoctl, le pilote définit le paramètre pFile sur NULL. La valeur NULL amène l’infrastructure à utiliser le nom de fichier spécifié par le pilote sur CreateFileHandleTarget. Si le pilote fournit un paramètre pFile non NULL, le fichier spécifié remplace le fichier spécifié par le pilote dans CreateFileHandleTarget. (Les pilotes peuvent également appeler IWDFIoRequest ::FormatUsingCurrentType pour mettre en forme une requête d’E/S.)

Lorsque le pilote appelle IWDFIoRequest ::Send pour envoyer la demande d’E/S à la cible d’E/S, le pilote ne doit pas définir la valeur WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET dans le paramètre Flags .

Le handle Win32 que le pilote transmet à CreateFileHandleTarget doit rester valide pendant la durée de vie de l’objet cible d’E/S basé sur un handle de fichier. (L’infrastructure ne prend pas de référence sur ce handle cible, de sorte que votre pilote doit s’assurer que le handle Win32 reste valide.)

Une fois que le pilote a terminé d’utiliser l’interface IWDFIoTarget fourni par CreateFileHandleTarget , il doit libérer l’interface IWDFIoTarget .

Pour plus d’informations sur les cibles CreateFileHandleTarget et E/S, consultez Initialisation d’une cible d’E/S générale dans UMDF.

Exemples

L’exemple de code suivant montre comment créer une cible d’E/S basée sur un handle de fichier pour un canal nommé. Dans cet exemple, m_FxDevice est le pointeur d’interface fourni par 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);
}

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1.5
En-tête	wudfddi.h (inclure Wudfusb.h)
DLL	WUDFx.dll

Voir aussi

IWDFFileHandleTargetFactory

IWDFIoRequest ::Send

IWDFIoTarget

Partager via