Función GetPointerFrameInfo (winuser.h)

Obtiene el marco completo de información de los punteros especificados asociados al mensaje actual.

Sintaxis

BOOL GetPointerFrameInfo(
  [in]      UINT32       pointerId,
  [in, out] UINT32       *pointerCount,
  [out]     POINTER_INFO *pointerInfo
);

Parámetros

[in] pointerId

Identificador del puntero para el que se va a recuperar información de fotogramas.

[in, out] pointerCount

Puntero a una variable que especifica el recuento de estructuras en el búfer al que apunta pointerInfo. Si GetPointerFrameInfo se realiza correctamente, pointerCount se actualiza con el recuento total de punteros en el marco.

[out] pointerInfo

Dirección de una matriz de estructuras POINTER_INFO para recibir la información del puntero. Este parámetro puede ser NULL si *pointerCount es cero.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Los dispositivos en modo paralelo pueden notificar la entrada de puntero en fotogramas, es decir, pueden notificar el estado y la posición de todos los punteros de ese dispositivo en un único informe de entrada al sistema. Lo ideal es que las aplicaciones vean todo el fotograma como una sola entrada a menos que los requisitos específicos de la aplicación dicten lo contrario.

GetPointerFrameInfo recupera todo el marco de entrada del puntero asociado a un mensaje de puntero. Use GetPointerInfo para recuperar información de un único puntero asociado a un mensaje de puntero.

El marco solo contiene punteros que pertenecen actualmente a la misma ventana que el puntero especificado.

La información devuelta por GetPointerFrameInfo está asociada al mensaje de puntero más reciente recuperado por el subproceso que realiza la llamada. Cuando el subproceso que realiza la llamada recupera el siguiente mensaje, es posible que la información asociada al mensaje anterior ya no esté disponible.

Si la aplicación no procesa los mensajes de entrada de puntero tan rápido como se generan, algunos mensajes se pueden fusionar en un mensaje de WM_POINTERUPDATE . Use GetPointerFrameInfoHistory para recuperar el historial de mensajes del mensaje WM_POINTERUPDATE más reciente.

Después de recuperar todo el marco de información, la aplicación puede llamar a la función SkipPointerFrameMessages para omitir los mensajes de puntero restantes asociados a este marco que están pendientes de recuperación. Esto ahorra a la aplicación la sobrecarga de recuperar y procesar los mensajes restantes uno por uno. Sin embargo, la función SkipPointerFrameMessages debe usarse con cuidado y solo cuando el autor de la llamada puede estar seguro de que ninguna otra entidad del subproceso del autor de la llamada espera ver los mensajes de puntero restantes uno por uno a medida que se recuperan.

Tenga en cuenta que la información recuperada está asociada al marco de puntero más recientemente recuperado por el subproceso que realiza la llamada. Una vez que el subproceso que realiza la llamada recupera su siguiente mensaje, es posible que la información asociada al marco de puntero anterior ya no esté disponible.

Si el marco de puntero no contiene punteros adicionales además del puntero especificado, esta función se realiza correctamente y devuelve solo la información del puntero especificado.

Si la información asociada al marco de puntero ya no está disponible, esta función genera el último error establecido en ERROR_NO_DATA.

Si el subproceso que realiza la llamada no posee la ventana (donde se entregó originalmente la entrada o donde se reenvía el mensaje) al que se ha entregado el mensaje de puntero, esta función produce el último error establecido en ERROR_ACCESS_DENIED.

En el caso de las aplicaciones que tienen áreas cliente y no cliente, la trama de entrada puede incluir datos tanto de cliente como de no cliente. Para diferenciar entre los datos de cliente y no cliente, debe realizar pruebas de posicionamiento en la ventana de destino.

Se recomienda lo siguiente si desea filtrar los datos de la trama de entrada:

• Para cada actualización que no incluye un contacto de puntero (un POINTER_FLAG_UPDATE sin POINTER_FLAG_INCONTACT), la prueba de posicionamiento para determinar si la entrada es cliente o no cliente.
• Para cada nuevo contacto (POINTER_FLAG_DOWN), la prueba de posicionamiento para determinar si la entrada es cliente o no cliente y realizar un seguimiento de esta información.
• Para cada actualización que incluya un contacto de puntero (un POINTER_FLAG_UPDATE con POINTER_FLAG_INCONTACT), use la información de seguimiento para determinar si la entrada es cliente o no cliente.
• Para cada POINTER_FLAG_UP, use la información de seguimiento para determinar si la entrada es cliente o no cliente y, a continuación, borra este puntero de los datos de seguimiento.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluir Windows.h)
Library	User32.lib
Archivo DLL	User32.dll

Vea también

Funciones

GetPointerFrameInfoHistory

GetPointerInfo

GetPointerInfoHistory