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

Artigo
07/16/2024

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui o UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum recurso novo está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução aoda UMDF .]

O método CreateFileHandleTarget cria um objeto de destino de E/S baseado em identificador de arquivo.

Sintaxe

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

Parâmetros

[in] hTarget

Um identificador para o dispositivo de destino. O identificador deve ter sido aberto anteriormente com o sinalizador FILE_FLAG_OVERLAPPED. Por exemplo, FILE_FLAG_OVERLAPPED deve ter sido especificado no parâmetro dwFlagsAndAttributes da função CreateFile do Microsoft Win32 .

[out] ppTarget

Um ponteiro para um local que recebe um ponteiro para a interface IWDFIoTarget do objeto de destino de E/S.

Valor de retorno

CreateFileHandleTarget retorna um dos seguintes valores:

Código de retorno	Descrição
S_OK	CreateFileHandleTarget criou com êxito um objeto de destino de E/S baseado em identificador de arquivo.
E_OUTOFMEMORY	CreateFileHandleTarget encontrou uma falha de alocação.

CreateFileHandleTarget também pode retornar outros valores HRESULT definidos em Winerror.h.

Observações

Se o driver usar um destino de E/S baseado em identificador de arquivo, a seção DDInstall.WDF do arquivo INF do driver deverá definir a diretiva UmdfDispatcher para filehandle. Para obter mais informações sobre UmdfDispatcher, consulte Especificando diretivas do WDF.

Depois que o driver cria um objeto de destino de E/S baseado em identificador de arquivo, ele pode formatar solicitações de E/S e enviá-las para o destino de E/S. Normalmente, se o driver chamar IWDFIoTarget::FormatRequestForRead, IWDFIoTarget::FormatRequestForWriteou IWDFIoTarget::FormatRequestForIoctl, o driver definirá o parâmetro pFile como NULL. O NULL faz com que a estrutura use o nome de arquivo especificado pelo driver para CreateFileHandleTarget. Se o driver fornecer um parâmetro null null não, o arquivo especificado substituirá o arquivo especificado para CreateFileHandleTarget. (Os drivers também podem chamar IWDFIoRequest::FormatUsingCurrentType para formatar uma solicitação de E/S.)

Quando o driver chama IWDFIoRequest::Send para enviar a solicitação de E/S para o destino de E/S, o driver não deve definir o valor de WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET no parâmetro sinalizadores de .

O identificador Win32 que o driver passa para CreateFileHandleTarget deve permanecer válido durante o tempo de vida do objeto de destino de E/S baseado em identificador de arquivo. (A estrutura não usa uma referência nesse identificador de destino, portanto, o driver deve garantir que o identificador Win32 permaneça válido.)

Quando o driver terminar de usar a interface IWDFIoTarget que createFileHandleTarget fornece, ele deve liberar a interface IWDFIoTarget .

Para obter mais informações sobre destinos de E/S e CreateFileHandleTarget, consulte Inicializando um destino de E/S geral noUMDF.

Exemplos

O exemplo de código a seguir mostra como criar um destino de E/S baseado em identificador de arquivo para um pipe nomeado. Neste exemplo, m_FxDevice é o ponteiro de interface que 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);
}

Requisitos

Requisito	Valor
fim do suporte	Indisponível no UMDF 2.0 e posterior.
da Plataforma de Destino	Área de trabalho
versão mínima do UMDF	1.5
cabeçalho	wudfddi.h (inclua Wudfusb.h)
de DLL	WUDFx.dll

Consulte também

IWDFFileHandleTargetFactory

IWDFIoRequest::Send

IWDFIoTarget

Compartilhar via