IWDFFileHandleTargetFactory ::CreateFileHandleTarget, méthode (wudfddi.h)

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

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

Syntaxe

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

Paramètres

[in] hTarget

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

[out] ppTarget

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

Valeur de retour

CreateFileHandleTarget retourne l’une des valeurs suivantes :

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 fichiers, 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 des 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 NULL entraîne l’utilisation du nom de fichier spécifié par le pilote pour CreateFileHandleTarget. Si le pilote fournit un paramètrenullpFile, le fichier spécifié remplace le fichier spécifié par 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 requête 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 Indicateurs de.

Le handle Win32 que le pilote passe à CreateFileHandleTarget doit rester valide pendant toute la durée de vie de l’objet cible basé sur le 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.)

Lorsque le pilote a terminé d’utiliser l’interface IWDFIoTarget qui CreateFileHandleTarget fournit, elle doit libérer l’interface IWDFIoTarget.

Pour plus d’informations sur cibles createFileHandleTarget et D’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 qui IWDFDriver ::CreateDevice fournit.

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);
}

Exigences

Voir aussi

IWDFFileHandleTargetFactory

IWDFIoRequest ::Send

IWDFIoTarget