libwacom
Wacom model identification library
 All Files Functions Typedefs Enumerations Enumerator Defines
Defines | Typedefs | Enumerations | Functions
/home/whot/code/libwacom/libwacom/libwacom.h File Reference
#include <stdint.h>
#include <stdio.h>

Go to the source code of this file.

Defines

#define WACOM_STYLUS_FALLBACK_ID   0xfffff
#define WACOM_ERASER_FALLBACK_ID   0xffffe

Typedefs

typedef struct _WacomDevice WacomDevice
typedef struct _WacomMatch WacomMatch
typedef struct _WacomStylus WacomStylus
typedef struct _WacomError WacomError
typedef struct _WacomDeviceDatabase WacomDeviceDatabase

Enumerations

enum  WacomErrorCode {
  WERROR_NONE, WERROR_BAD_ALLOC, WERROR_INVALID_PATH, WERROR_INVALID_DB,
  WERROR_BAD_ACCESS, WERROR_UNKNOWN_MODEL
}
 Possible error codes. More...
enum  WacomBusType { WBUSTYPE_UNKNOWN, WBUSTYPE_USB, WBUSTYPE_SERIAL, WBUSTYPE_BLUETOOTH }
 Bus types for tablets. More...
enum  WacomClass {
  WCLASS_UNKNOWN, WCLASS_INTUOS3, WCLASS_INTUOS4, WCLASS_INTUOS5,
  WCLASS_CINTIQ, WCLASS_BAMBOO, WCLASS_GRAPHIRE, WCLASS_ISDV4,
  WCLASS_INTUOS, WCLASS_INTUOS2, WCLASS_PEN_DISPLAYS
}
 Classes of devices. More...
enum  WacomStylusType {
  WSTYLUS_UNKNOWN, WSTYLUS_GENERAL, WSTYLUS_INKING, WSTYLUS_AIRBRUSH,
  WSTYLUS_CLASSIC, WSTYLUS_MARKER, WSTYLUS_STROKE, WSTYLUS_PUCK
}
 Class of stylus. More...
enum  WacomButtonFlags {
  WACOM_BUTTON_NONE = 0, WACOM_BUTTON_POSITION_LEFT = (1 << 1), WACOM_BUTTON_POSITION_RIGHT = (1 << 2), WACOM_BUTTON_POSITION_TOP = (1 << 3),
  WACOM_BUTTON_POSITION_BOTTOM = (1 << 4), WACOM_BUTTON_RING_MODESWITCH = (1 << 5), WACOM_BUTTON_RING2_MODESWITCH = (1 << 6), WACOM_BUTTON_TOUCHSTRIP_MODESWITCH = (1 << 7),
  WACOM_BUTTON_TOUCHSTRIP2_MODESWITCH = (1 << 8), WACOM_BUTTON_OLED = (1 << 9), WACOM_BUTTON_MODESWITCH = (WACOM_BUTTON_RING_MODESWITCH | WACOM_BUTTON_RING2_MODESWITCH | WACOM_BUTTON_TOUCHSTRIP_MODESWITCH | WACOM_BUTTON_TOUCHSTRIP2_MODESWITCH), WACOM_BUTTON_DIRECTION = (WACOM_BUTTON_POSITION_LEFT | WACOM_BUTTON_POSITION_RIGHT | WACOM_BUTTON_POSITION_TOP | WACOM_BUTTON_POSITION_BOTTOM),
  WACOM_BUTTON_RINGS_MODESWITCH = (WACOM_BUTTON_RING_MODESWITCH | WACOM_BUTTON_RING2_MODESWITCH), WACOM_BUTTON_TOUCHSTRIPS_MODESWITCH = (WACOM_BUTTON_TOUCHSTRIP_MODESWITCH | WACOM_BUTTON_TOUCHSTRIP2_MODESWITCH)
}
 Capabilities of the various tablet buttons. More...
enum  WacomFallbackFlags { WFALLBACK_NONE = 0, WFALLBACK_GENERIC = 1 }
enum  WacomCompareFlags { WCOMPARE_NORMAL = 0, WCOMPARE_MATCHES = (1 << 1) }

Functions

WacomErrorlibwacom_error_new (void)
 Allocate a new structure for error reporting.
void libwacom_error_free (WacomError **error)
 Free the error and associated memory.
enum WacomErrorCode libwacom_error_get_code (WacomError *error)
const char * libwacom_error_get_message (WacomError *error)
WacomDeviceDatabaselibwacom_database_new (void)
 Loads the Tablet and Stylus databases, to be used in libwacom_new_*() functions.
WacomDeviceDatabaselibwacom_database_new_for_path (const char *datadir)
 Loads the Tablet and Stylus databases, to be used in libwacom_new_*() functions, from the prefix path passes.
void libwacom_database_destroy (WacomDeviceDatabase *db)
 Free all memory used by the database.
WacomDevicelibwacom_new_from_path (WacomDeviceDatabase *db, const char *path, WacomFallbackFlags fallback, WacomError *error)
 Create a new device reference from the given device path.
WacomDevicelibwacom_new_from_usbid (WacomDeviceDatabase *db, int vendor_id, int product_id, WacomError *error)
 Create a new device reference from the given vendor/product IDs.
WacomDevicelibwacom_new_from_name (WacomDeviceDatabase *db, const char *name, WacomError *error)
 Create a new device reference from the given name.
WacomDevice ** libwacom_list_devices_from_database (WacomDeviceDatabase *db, WacomError *error)
 Returns the list of devices in the given database.
void libwacom_print_device_description (int fd, WacomDevice *device)
 Print the description of this device to the given file.
void libwacom_destroy (WacomDevice *device)
 Remove the device and free all memory and references to it.
int libwacom_compare (WacomDevice *a, WacomDevice *b, WacomCompareFlags flags)
 Compare the two devices for equal-ness.
WacomClass libwacom_get_class (WacomDevice *device)
const char * libwacom_get_name (WacomDevice *device)
int libwacom_get_vendor_id (WacomDevice *device)
const char * libwacom_get_match (WacomDevice *device)
const WacomMatch ** libwacom_get_matches (WacomDevice *device)
int libwacom_get_product_id (WacomDevice *device)
int libwacom_get_width (WacomDevice *device)
 Retrieve the width of the device.
int libwacom_get_height (WacomDevice *device)
 Retrieve the height of the device.
int libwacom_has_stylus (WacomDevice *device)
int libwacom_has_touch (WacomDevice *device)
int libwacom_get_num_buttons (WacomDevice *device)
 Tablet buttons are numbered 'A' through to 'A' + number of buttons.
const int * libwacom_get_supported_styli (WacomDevice *device, int *num_styli)
int libwacom_has_ring (WacomDevice *device)
int libwacom_has_ring2 (WacomDevice *device)
int libwacom_get_ring_num_modes (WacomDevice *device)
int libwacom_get_ring2_num_modes (WacomDevice *device)
int libwacom_get_num_strips (WacomDevice *device)
int libwacom_get_strips_num_modes (WacomDevice *device)
int libwacom_is_builtin (WacomDevice *device)
int libwacom_is_reversible (WacomDevice *device)
WacomBusType libwacom_get_bustype (WacomDevice *device)
WacomButtonFlags libwacom_get_button_flag (WacomDevice *device, char button)
const WacomStyluslibwacom_stylus_get_for_id (WacomDeviceDatabase *db, int id)
 Get the WacomStylus for the given tool ID.
int libwacom_stylus_get_id (const WacomStylus *stylus)
const char * libwacom_stylus_get_name (const WacomStylus *stylus)
int libwacom_stylus_get_num_buttons (const WacomStylus *stylus)
int libwacom_stylus_has_eraser (const WacomStylus *stylus)
int libwacom_stylus_is_eraser (const WacomStylus *stylus)
int libwacom_stylus_has_lens (const WacomStylus *stylus)
WacomStylusType libwacom_stylus_get_type (const WacomStylus *stylus)
void libwacom_print_stylus_description (int fd, const WacomStylus *stylus)
 Print the description of this stylus to the given file.
WacomBusType libwacom_match_get_bustype (const WacomMatch *match)
uint32_t libwacom_match_get_product_id (const WacomMatch *match)
uint32_t libwacom_match_get_vendor_id (const WacomMatch *match)
const char * libwacom_match_get_match_string (const WacomMatch *match)

Detailed Description


Define Documentation

#define WACOM_ERASER_FALLBACK_ID   0xffffe
#define WACOM_STYLUS_FALLBACK_ID   0xfffff

Typedef Documentation

typedef struct _WacomDevice WacomDevice
typedef struct _WacomDeviceDatabase WacomDeviceDatabase
typedef struct _WacomError WacomError
typedef struct _WacomMatch WacomMatch
typedef struct _WacomStylus WacomStylus

Enumeration Type Documentation

Bus types for tablets.

Enumerator:
WBUSTYPE_UNKNOWN 

Unknown/unsupported bus type.

WBUSTYPE_USB 

USB tablet.

WBUSTYPE_SERIAL 

Serial tablet.

WBUSTYPE_BLUETOOTH 

Bluetooth tablet.

Capabilities of the various tablet buttons.

Enumerator:
WACOM_BUTTON_NONE 
WACOM_BUTTON_POSITION_LEFT 
WACOM_BUTTON_POSITION_RIGHT 
WACOM_BUTTON_POSITION_TOP 
WACOM_BUTTON_POSITION_BOTTOM 
WACOM_BUTTON_RING_MODESWITCH 
WACOM_BUTTON_RING2_MODESWITCH 
WACOM_BUTTON_TOUCHSTRIP_MODESWITCH 
WACOM_BUTTON_TOUCHSTRIP2_MODESWITCH 
WACOM_BUTTON_OLED 
WACOM_BUTTON_MODESWITCH 
WACOM_BUTTON_DIRECTION 
WACOM_BUTTON_RINGS_MODESWITCH 
WACOM_BUTTON_TOUCHSTRIPS_MODESWITCH 
enum WacomClass

Classes of devices.

Enumerator:
WCLASS_UNKNOWN 

Unknown/unsupported device class.

WCLASS_INTUOS3 

Any Intuos3 series.

WCLASS_INTUOS4 

Any Intuos4 series.

WCLASS_INTUOS5 

Any Intuos5 series.

WCLASS_CINTIQ 

Any Cintiq device.

WCLASS_BAMBOO 

Any Bamboo device.

WCLASS_GRAPHIRE 

Any Graphire device.

WCLASS_ISDV4 

Any serial ISDV4 device.

WCLASS_INTUOS 

Any Intuos series.

WCLASS_INTUOS2 

Any Intuos2 series.

WCLASS_PEN_DISPLAYS 

Any "interactive pen display".

Enumerator:
WCOMPARE_NORMAL 

compare the device only

WCOMPARE_MATCHES 

compare all possible matches too

Possible error codes.

Enumerator:
WERROR_NONE 

No error has occured.

WERROR_BAD_ALLOC 

Allocation error.

WERROR_INVALID_PATH 

A path specified is invalid.

WERROR_INVALID_DB 

The passed DB is invalid.

WERROR_BAD_ACCESS 

Invalid permissions to access the path.

WERROR_UNKNOWN_MODEL 

Unsupported/unknown device.

Enumerator:
WFALLBACK_NONE 
WFALLBACK_GENERIC 

Class of stylus.

Enumerator:
WSTYLUS_UNKNOWN 
WSTYLUS_GENERAL 
WSTYLUS_INKING 
WSTYLUS_AIRBRUSH 
WSTYLUS_CLASSIC 
WSTYLUS_MARKER 
WSTYLUS_STROKE 
WSTYLUS_PUCK 

Function Documentation

int libwacom_compare ( WacomDevice a,
WacomDevice b,
WacomCompareFlags  flags 
)

Compare the two devices for equal-ness.

Parameters:
aThe first device
bThe second device
flagsFlags to dictate what constitutes a match
Returns:
0 if the devices are identical, nonzero otherwise

Free all memory used by the database.

Parameters:
dbA Tablet and Stylus database.

Loads the Tablet and Stylus databases, to be used in libwacom_new_*() functions.

Returns:
A new database or NULL on error.

Loads the Tablet and Stylus databases, to be used in libwacom_new_*() functions, from the prefix path passes.

This is only useful for diagnostics applications.

Returns:
A new database or NULL on error.
void libwacom_destroy ( WacomDevice device)

Remove the device and free all memory and references to it.

Parameters:
deviceThe device to delete
void libwacom_error_free ( WacomError **  error)

Free the error and associated memory.

Resets error to NULL.

Parameters:
errorA reference to a error struct.
See also:
libwacom_error_new
Returns:
The code for this error.
const char* libwacom_error_get_message ( WacomError error)
Returns:
A human-readable message for this error

Allocate a new structure for error reporting.

Returns:
A newly allocated error structure or NULL if the allocation failed.
Parameters:
deviceThe tablet to query
Returns:
The bustype of this device.
WacomButtonFlags libwacom_get_button_flag ( WacomDevice device,
char  button 
)
Parameters:
deviceThe tablet to query
Returns:
The class of the device
int libwacom_get_height ( WacomDevice device)

Retrieve the height of the device.

This is the height of the usable area as advertised, not the total size of the physical tablet. For e.g. an Intuos4 6x9 this will return 6.

Parameters:
deviceThe tablet to query
Returns:
The width of this device in inches
const char* libwacom_get_match ( WacomDevice device)
Parameters:
deviceThe tablet to query
Returns:
The current match string used for this device (if set) or the first match string in the tablet definition.
Parameters:
deviceThe tablet to query
Returns:
A pointer to the null-terminated list of possible matches for this device. Do not modify this pointer or any content!
const char* libwacom_get_name ( WacomDevice device)
Parameters:
deviceThe tablet to query
Returns:
The human-readable name for this device

Tablet buttons are numbered 'A' through to 'A' + number of buttons.

Parameters:
deviceThe tablet to query
Returns:
The number of buttons on the tablet
Parameters:
deviceThe tablet to query
Returns:
the number of touch strips on the tablet otherwise
Parameters:
deviceThe tablet to query
Returns:
The numeric product ID for this device
Parameters:
deviceThe tablet to query
Returns:
the number of modes for the second touchring if it has a mode switch
Parameters:
deviceThe tablet to query
Returns:
the number of modes for the touchring if it has a mode switch
Parameters:
deviceThe tablet to query
Returns:
the number of modes for each of the touchstrips if any
const int* libwacom_get_supported_styli ( WacomDevice device,
int *  num_styli 
)
Parameters:
deviceThe tablet to query
num_styliReturn location for the number of listed styli
Returns:
an array of Styli IDs supported by the device
Parameters:
deviceThe tablet to query
Returns:
The numeric vendor ID for this device
int libwacom_get_width ( WacomDevice device)

Retrieve the width of the device.

This is the width of the usable area as advertised, not the total size of the physical tablet. For e.g. an Intuos4 6x9 this will return 9.

Parameters:
deviceThe tablet to query
Returns:
The width of this device in inches
int libwacom_has_ring ( WacomDevice device)
Parameters:
deviceThe tablet to query
Returns:
non-zero if the device has a touch ring or zero otherwise
int libwacom_has_ring2 ( WacomDevice device)
Parameters:
deviceThe tablet to query
Returns:
non-zero if the device has a second touch ring or zero otherwise
int libwacom_has_stylus ( WacomDevice device)
Parameters:
deviceThe tablet to query
Returns:
non-zero if the device supports styli or zero otherwise
int libwacom_has_touch ( WacomDevice device)
Parameters:
deviceThe tablet to query
Returns:
non-zero if the device supports touch or zero otherwise
int libwacom_is_builtin ( WacomDevice device)
Parameters:
deviceThe tablet to query
Returns:
non-zero if the device is built-in or zero if the device is an external tablet
Parameters:
deviceThe tablet to query
Returns:
non-zero if the device can be used left-handed (rotated 180 degrees)

Returns the list of devices in the given database.

Parameters:
dbA device database
errorIf not NULL, set to the error if any occurs
Returns:
A NULL terminated list of pointers to all the devices inside the database. The content of the list is owned by the database and should not be modified of freed. Use free() to free the list.
const char* libwacom_match_get_match_string ( const WacomMatch match)
uint32_t libwacom_match_get_product_id ( const WacomMatch match)
uint32_t libwacom_match_get_vendor_id ( const WacomMatch match)
WacomDevice* libwacom_new_from_name ( WacomDeviceDatabase db,
const char *  name,
WacomError error 
)

Create a new device reference from the given name.

In case of error, NULL is returned and the error is set to the appropriate value.

Parameters:
dbA device database
nameThe name identifying the device
errorIf not NULL, set to the error if any occurs
Returns:
A new reference to this device or NULL on error.
WacomDevice* libwacom_new_from_path ( WacomDeviceDatabase db,
const char *  path,
WacomFallbackFlags  fallback,
WacomError error 
)

Create a new device reference from the given device path.

In case of error, NULL is returned and the error is set to the appropriate value.

Parameters:
dbA device database
pathA device path in the form of e.g. /dev/input/event0
fallbackWhether we should create a generic if model is unknown
errorIf not NULL, set to the error if any occurs
Returns:
A new reference to this device or NULL on errror.
WacomDevice* libwacom_new_from_usbid ( WacomDeviceDatabase db,
int  vendor_id,
int  product_id,
WacomError error 
)

Create a new device reference from the given vendor/product IDs.

In case of error, NULL is returned and the error is set to the appropriate value.

Parameters:
dbA device database
vendor_idThe vendor ID of the device
product_idThe product ID of the device
errorIf not NULL, set to the error if any occurs
Returns:
A new reference to this device or NULL on errror.
void libwacom_print_device_description ( int  fd,
WacomDevice device 
)

Print the description of this device to the given file.

Parameters:
fdThe file descriptor to print to
deviceThe device to print the description for.
void libwacom_print_stylus_description ( int  fd,
const WacomStylus stylus 
)

Print the description of this stylus to the given file.

Parameters:
fdThe file descriptor
stylusThe stylus to print the description for.

Get the WacomStylus for the given tool ID.

Parameters:
dbA Tablet and Stylus database.
idThe Tool ID for this stylus
Returns:
A WacomStylus representing the stylus. Do not free.
int libwacom_stylus_get_id ( const WacomStylus stylus)
Parameters:
stylusThe stylus to query
Returns:
the ID of the tool
const char* libwacom_stylus_get_name ( const WacomStylus stylus)
Parameters:
stylusThe stylus to query
Returns:
The name of the stylus
Parameters:
stylusThe stylus to query
Returns:
The number of buttons on the stylus
Parameters:
stylusThe stylus to query
Returns:
The type of stylus
int libwacom_stylus_has_eraser ( const WacomStylus stylus)
Parameters:
stylusThe stylus to query
Returns:
Whether the stylus has an eraser
int libwacom_stylus_has_lens ( const WacomStylus stylus)
Parameters:
stylusThe stylus to query
Returns:
Whether the stylus has a lens
int libwacom_stylus_is_eraser ( const WacomStylus stylus)
Parameters:
stylusThe stylus to query
Returns:
Whether the stylus is actually an eraser