[PATCH libinput] tablet: add libinput_tablet_tool_is_unique()

[Hans de Goede]

Hi,

On 12/20/2015 11:34 PM, Peter Hutterer wrote:
> For checking if a tablet tool can be uniquely identified by libinput. In
> practice this means checking for a nonzero serial number, but let's not
> restrict ourselves to allowing just that.
>
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>

Looks good to me:

Reviewed-by: Hans de Goede <hdegoede at redhat.com>

Regards,

Hans


> ---
>   doc/tablet-support.dox |  4 +++-
>   src/libinput.c         |  6 ++++++
>   src/libinput.h         | 24 ++++++++++++++++++------
>   src/libinput.sym       |  1 +
>   test/tablet.c          | 25 +++++++++++++++++++++++++
>   5 files changed, 53 insertions(+), 7 deletions(-)
>
> diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox
> index ac56e47..fbe778d 100644
> --- a/doc/tablet-support.dox
> +++ b/doc/tablet-support.dox
> @@ -126,7 +126,9 @@ and @ref LIBINPUT_TABLET_TOOL_TYPE_LENS tools.
>   Some tools provide hardware information that enables libinput to uniquely
>   identify the physical device. For example, tools compatible with the Wacom
>   Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely identifiable
> -through a serial number.
> +through a serial number. libinput does not specify how a tool can be
> +identified uniquely, a caller should use libinput_tablet_tool_is_unique() to
> +check if the tool is unique.
>
>   libinput creates a struct libinput_tablet_tool on the first proximity in of
>   this tool. By default, this struct is destroyed on proximity out and
> diff --git a/src/libinput.c b/src/libinput.c
> index 093f318..082c1b0 100644
> --- a/src/libinput.c
> +++ b/src/libinput.c
> @@ -1318,6 +1318,12 @@ libinput_tablet_tool_get_tool_id(struct libinput_tablet_tool *tool)
>   	return tool->tool_id;
>   }
>
> +LIBINPUT_EXPORT int
> +libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool)
> +{
> +	return tool->serial != 0;
> +}
> +
>   LIBINPUT_EXPORT uint64_t
>   libinput_tablet_tool_get_serial(struct libinput_tablet_tool *tool)
>   {
> diff --git a/src/libinput.h b/src/libinput.h
> index 8726dc5..cc1a083 100644
> --- a/src/libinput.h
> +++ b/src/libinput.h
> @@ -144,7 +144,7 @@ enum libinput_pointer_axis_source {
>    * Tablet events generated by such a device are bound to a specific tool
>    * rather than coming from the device directly. Depending on the hardware it
>    * is possible to track the same physical tool across multiple
> - * struct libinput_device devices.
> + * struct libinput_device devices, see @ref tablet-serial-numbers.
>    */
>   struct libinput_tablet_tool;
>
> @@ -1955,14 +1955,26 @@ libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool,
>   /**
>    * @ingroup event_tablet
>    *
> - * Return the serial number of a tool
> + * Return nonzero if the physical tool can be uniquely identified by
> + * libinput, or nonzero otherwise. If a tool can be uniquely identified,
> + * keeping a reference to the tool allows tracking the tool across
> + * proximity out sequences and across compatible tablets.
> + * See @ref tablet-serial-numbers for more details.
>    *
> - * @note Not all tablets report a serial number along with the type of tool
> - * being used. If the hardware does not provide a unique serial number, the
> - * serial number is always 0.
> + * @param tool A tablet tool
> + * @return 1 if the tool can be uniquely identified, 0 otherwise.
> + */
> +int
> +libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool);
> +
> +/**
> + * @ingroup event_tablet
> + *
> + * Return the serial number of a tool. If the tool does not report a serial
> + * number, this function returns zero.
>    *
>    * @param tool The libinput tool
> - * @return The new tool serial triggering this event
> + * @return The tool serial number
>    */
>   uint64_t
>   libinput_tablet_tool_get_serial(struct libinput_tablet_tool *tool);
> diff --git a/src/libinput.sym b/src/libinput.sym
> index ddfe81d..22a8dd8 100644
> --- a/src/libinput.sym
> +++ b/src/libinput.sym
> @@ -226,6 +226,7 @@ LIBINPUT_TABLET_SUPPORT {
>   	libinput_tablet_tool_has_wheel;
>   	libinput_tablet_tool_has_slider;
>   	libinput_tablet_tool_has_button;
> +	libinput_tablet_tool_is_unique;
>   	libinput_tablet_tool_ref;
>   	libinput_tablet_tool_set_user_data;
>   	libinput_tablet_tool_unref;
> diff --git a/test/tablet.c b/test/tablet.c
> index 1afbb51..ff979a8 100644
> --- a/test/tablet.c
> +++ b/test/tablet.c
> @@ -1257,6 +1257,30 @@ START_TEST(normalization)
>   }
>   END_TEST
>
> +START_TEST(tool_unique)
> +{
> +	struct litest_device *dev = litest_current_device();
> +	struct libinput *li = dev->libinput;
> +	struct libinput_event_tablet_tool *tablet_event;
> +	struct libinput_event *event;
> +	struct libinput_tablet_tool *tool;
> +
> +	litest_drain_events(li);
> +
> +	litest_event(dev, EV_KEY, BTN_TOOL_PEN, 1);
> +	litest_event(dev, EV_MSC, MSC_SERIAL, 1000);
> +	litest_event(dev, EV_SYN, SYN_REPORT, 0);
> +
> +	libinput_dispatch(li);
> +	event = libinput_get_event(li);
> +	tablet_event = litest_is_tablet_event(event,
> +				LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY);
> +	tool = libinput_event_tablet_tool_get_tool(tablet_event);
> +	ck_assert(libinput_tablet_tool_is_unique(tool));
> +	libinput_event_destroy(event);
> +}
> +END_TEST
> +
>   START_TEST(tool_serial)
>   {
>   	struct litest_device *dev = litest_current_device();
> @@ -2617,6 +2641,7 @@ litest_setup_tests(void)
>   	litest_add("tablet:tool", tool_ref, LITEST_TABLET | LITEST_TOOL_SERIAL, LITEST_ANY);
>   	litest_add_no_device("tablet:tool", tool_capabilities);
>   	litest_add("tablet:tool", tool_in_prox_before_start, LITEST_TABLET, LITEST_ANY);
> +	litest_add("tablet:tool_serial", tool_unique, LITEST_TABLET | LITEST_TOOL_SERIAL, LITEST_ANY);
>   	litest_add("tablet:tool_serial", tool_serial, LITEST_TABLET | LITEST_TOOL_SERIAL, LITEST_ANY);
>   	litest_add("tablet:tool_serial", serial_changes_tool, LITEST_TABLET | LITEST_TOOL_SERIAL, LITEST_ANY);
>   	litest_add("tablet:tool_serial", invalid_serials, LITEST_TABLET | LITEST_TOOL_SERIAL, LITEST_ANY);
>