Função InjectTouchInput (winuser.h)

Simula a entrada por toque.

ObservaçãoInitializeTouchInjection deve preceder qualquer chamada para InjectTouchInput.

 

Sintaxe

BOOL InjectTouchInput(
  [in] UINT32                   count,
  [in] const POINTER_TOUCH_INFO *contacts
);

Parâmetros

[in] count

O tamanho da matriz em contatos.

O valor máximo de count é especificado pelo parâmetro maxCount da função InitializeTouchInjection .

[in] contacts

Matriz de estruturas POINTER_TOUCH_INFO que representa todos os contatos na área de trabalho. As coordenadas de tela de cada contato devem estar dentro dos limites da área de trabalho.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A entrada injetada é enviada para a área de trabalho da sessão em que o processo de injeção está em execução.

Há dois estados de entrada para injeção de entrada por toque (interativo e focalizado) que são indicados pelas seguintes combinações de pointerFlags em contatos:

pointerFlags (POINTER_FLAG_*)	Status
INRANGE | ATUALIZAÇÃO	O foco de toque inicia ou move
INRANGE | INCONTACT | PARA BAIXO	Tocar contato para baixo
INRANGE | INCONTACT | ATUALIZAÇÃO	Movimentos de contato de toque
INRANGE | UP	Toque em contato e faça a transição para passar o mouse
UPDATE	Extremidades de foco de toque
UP	Extremidades de toque

 

Nota O estado interativo representa um contato por toque que está na tela e pode interagir com qualquer aplicativo com capacidade de toque. O estado de foco representa a entrada por toque que não está em contato com a tela e não pode interagir com aplicativos. A injeção de toque pode começar em estado de foco ou interativo, mas o estado só pode fazer a transição por INRANGE | INCONTACT | PARA BAIXO para passar o mouse para o estado interativo ou por meio de INRANGE | UP para o estado interativo de focalização.

 

Todas as sequências de injeção de toque terminam com UPDATE ou UP.

O diagrama a seguir demonstra uma sequência de injeção de toque que começa com um estado de foco, faz a transição para interativa e conclui com o foco.

Para gestos de pressionar e segurar, vários quadros devem ser enviados para garantir que a entrada não seja cancelada. Para pressionar e segurar no ponto (x,y), envie WM_POINTERDOWN no ponto (x,y) seguido por WM_POINTERUPDATE mensagens em point(x,y).

Ouça WM_DISPLAYCHANGE para lidar com alterações para exibir resolução e orientação e gerenciar atualizações de coordenadas de tela. Todos os contatos ativos são cancelados quando um WM_DISPLAYCHANGE é recebido.

Cancele contatos individuais definindo POINTER_FLAG_CANCELED com POINTER_FLAG_UP ou POINTER_FLAG_UPDATE. Cancelar a injeção de toque sem POINTER_FLAG_UP ou POINTER_FLAG_UPDATE invalida a injeção.

Quando POINTER_FLAG_UP é definido, ptPixelLocation de POINTER_INFO deve ser igual ao valor do quadro de injeção de toque anterior com POINTER_FLAG_UPDATE. Caso contrário, a injeção falhará com ERROR_INVALID_PARAMETER e todos os contatos de injeção ativos serão cancelados. O sistema modifica o ptPixelLocation do evento WM_POINTERUP à medida que cancela a injeção.

O carimbo de data/hora de entrada pode ser especificado no campo dwTime ou PerformanceCount de POINTER_INFO. O valor não pode ser mais recente do que a contagem de tiques atual ou o valor QueryPerformanceCounter do thread de injeção. Depois que um quadro é injetado com um carimbo de data/hora, todos os quadros subsequentes devem incluir um carimbo de data/hora até que todos os contatos no quadro acessem o estado UP. O valor de carimbo de data/hora personalizado deve ser fornecido para o primeiro elemento na matriz de contatos. Os valores de carimbo de data/hora após o primeiro elemento são ignorados. O valor de carimbo de data/hora personalizado deve ser incrementado em cada quadro de injeção.

Quando um campo PerformanceCount é especificado, o carimbo de data/hora é convertido em hora atual em resolução de 0,1 milissegundo após a injeção real. Se um PerformanceCount personalizado resultou na mesma janela de milissegundos da injeção anterior, a API retornará um erro (ERROR_NOT_READY) e não injetará os dados. Embora a injeção não seja imediatamente invalidada pelo erro, a próxima injeção bem-sucedida deve ter o valor PerformanceCount de pelo menos 0,1 milissegundos, além da injeção bem-sucedida anteriormente. Da mesma forma, um valor dwTime personalizado deverá ter pelo menos 1 milissegundo de distância se o campo tiver sido usado.

Se dwTime e PerformanceCount forem especificados no parâmetro de injeção, InjectTouchInput falhará com um código de erro (ERROR_INVALID_PARAMETER). Depois que o aplicativo de injeção começar com um parâmetro dwTime ou PerformanceCount, o campo de carimbo de data/hora deverá ser preenchido corretamente. A injeção não pode alternar o campo de carimbo de data/hora personalizado de um para outro depois que a sequência de injeção for iniciada.

Quando nem os valores dwTime ou PerformanceCount são especificados, o InjectTouchInput aloca o carimbo de data/hora com base no tempo da chamada à API. Se as chamadas tiverem menos de 0,1 milissegundo de distância, a API poderá retornar um erro (ERROR_NOT_READY). O erro não invalidará a entrada imediatamente, mas o aplicativo de injeção precisa repetir o mesmo quadro novamente para garantir que a injeção seja bem-sucedida.

Requisitos

Cliente mínimo com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (introduzido no Windows 10, versão 10.0.14393)

Confira também

Funções