drath/libratbag
1
0
Fork 1
mirror of https://github.com/libratbag/libratbag.git synced 2026-11-07 23:23:52 +01:00
Code Issues Projects Releases Wiki Activity

Fix driver struct documentation

Browse Source 
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer
2015-08-20 14:55:22 +10:00
parent 2894ece95a
commit e8d13057f9
1 changed files with 65 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
src/libratbag-private.h
View File

@@ -78,94 +78,94 @@ struct ratbag_id {
* struct ratbag_driver - user space driver for a ratbag device
*/
struct ratbag_driver {
/** the name of the driver */
char *name;
/** the name of the driver */
/** a list of devices supported by this driver. The last element
* must be empty to mark the end. */
const struct ratbag_id *table_ids;
/** a list of devices supported by this driver. The last element
* must be empty to mark the end. */
/** callback called while trying to open a device by libratbag.
* This function should decide whether or not this driver will
* handle the given device.
*
* Return -ENODEV to ignore the device and let other drivers
* probe the device. Any other error code will stop the probing.
*/
int (*probe)(struct ratbag_device *device, const struct ratbag_id id);
/** callback called while trying to open a device by libratbag.
* This function should decide whether or not this driver will
* handle the given device.
*
* Return -ENODEV to ignore the device and let other drivers
* probe the device. Any other error code will stop the probing.
*/
/** callback called right before the struct ratbag_device is
* unref-ed.
*
* In this callback, the extra memory allocated in probe should
* be freed.
*/
void (*remove)(struct ratbag_device *device);
/** callback called right before the struct ratbag_device is
* unref-ed.
*
* In this callback, the extra memory allocated in probe should
* be freed.
*/
/** callback called when a read profile is requested by the
* caller of the library.
*
* The driver should probe here the device for the requested
* profile and populate the related information.
* There is no need to populate the various struct ratbag_button
* as they are allocated when the user needs it.
*/
void (*read_profile)(struct ratbag_profile *profile, unsigned int index);
/** callback called when a read profile is requested by the
* caller of the library.
*
* The driver should probe here the device for the requested
* profile and populate the related information.
* There is no need to populate the various struct ratbag_button
* as they are allocated when the user needs it.
*/
/** here, the driver should actually write the profile to the
* device.
*/
int (*write_profile)(struct ratbag_profile *profile);
/** here, the driver should actually write the profile to the
* device.
*/
/** called when the user of libratbag wants to know which
* current profile is in use.
*
* It is fundamentally racy.
*/
int (*get_active_profile)(struct ratbag_device *device);
/** called when the user of libratbag wants to know which
* current profile is in use.
*
* It is fundamentally racy.
*/
/** called to mark a previously writen profile as active.
*
* There should be no need to write the profile here, a
* .write_profile() call is issued before calling this.
*/
int (*set_active_profile)(struct ratbag_device *device, unsigned int index);
/** called to mark a previously writen profile as active.
*
* There should be no need to write the profile here, a
* .write_profile() call is issued before calling this.
*/
/** This should return a boolean whether or not the device
* supports the given capability.
*
* In most cases, the .probe() should store a list of capabilities
* for each device, but most of the time, it can be statically
* stored.
*/
int (*has_capability)(const struct ratbag_device *device, enum ratbag_capability cap);
/** This should return a boolean whether or not the device
* supports the given capability.
*
* In most cases, the .probe() should store a list of capabilities
* for each device, but most of the time, it can be statically
* stored.
*/
/** For the given button, fill in the struct ratbag_button
* with the available information.
*
* For devices with profiles, profile will not be NULL. For
* device without, profile will be set to NULL.
*
* For devices with profile, there should not be the need to
* actually read the profile from the device. The caller
* should make sure that the profile is up to date.
*/
void (*read_button)(struct ratbag_device *device, struct ratbag_profile *profile,
struct ratbag_button *button);
/** For the given button, fill in the struct ratbag_button
* with the available information.
*
* For devices with profiles, profile will not be NULL. For
* device without, profile will be set to NULL.
*
* For devices with profile, there should not be the need to
* actually read the profile from the device. The caller
* should make sure that the profile is up to date.
*/
/** For the given button, store in the profile or in the device
* the given struct ratbag_button.
*
* For devices with profiles, profile will not be NULL. For
* device without, profile will be set to NULL.
*
* For devices with profile, there should not be the need to
* actually write the button to the device. The caller
* should later on write the profile in one call to
* .write_profile().
*/
int (*write_button)(struct ratbag_device *device, struct ratbag_profile *profile,
struct ratbag_button *button);
/** For the given button, store in the profile or in the device
* the given struct ratbag_button.
*
* For devices with profiles, profile will not be NULL. For
* device without, profile will be set to NULL.
*
* For devices with profile, there should not be the need to
* actually write the button to the device. The caller
* should later on write the profile in one call to
* .write_profile().
*/
/* private */
struct list link;