libratbag.h

Go to the documentation of this file.

/*
 * Copyright © 2015 Red Hat, Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

#ifndef LIBRATBAG_H
#define LIBRATBAG_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdlib.h>
#include <stdarg.h>
#include <libudev.h>

#define LIBRATBAG_ATTRIBUTE_PRINTF(_format, _args) \
        __attribute__ ((format (printf, _format, _args)))
#define LIBRATBAG_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated))

struct ratbag;

struct ratbag_device;

struct ratbag_profile;

struct ratbag_button;

struct ratbag_resolution;


enum ratbag_log_priority {
        RATBAG_LOG_PRIORITY_RAW = 10,
        RATBAG_LOG_PRIORITY_DEBUG = 20,
        RATBAG_LOG_PRIORITY_INFO = 30,
        RATBAG_LOG_PRIORITY_ERROR = 40,
};

typedef void (*ratbag_log_handler)(struct ratbag *ratbag,
                                      enum ratbag_log_priority priority,
                                      const char *format, va_list args)
           LIBRATBAG_ATTRIBUTE_PRINTF(3, 0);

void
ratbag_log_set_priority(struct ratbag *ratbag,
                        enum ratbag_log_priority priority);

enum ratbag_log_priority
ratbag_log_get_priority(const struct ratbag *ratbag);

void
ratbag_log_set_handler(struct ratbag *ratbag,
                       ratbag_log_handler log_handler);


struct ratbag_interface {
        int (*open_restricted)(const char *path, int flags, void *user_data);
        void (*close_restricted)(int fd, void *user_data);
};

struct ratbag *
ratbag_create_context(const struct ratbag_interface *interface,
                         void *userdata);

void
ratbag_set_user_data(struct ratbag *ratbag, void *userdata);

void*
ratbag_get_user_data(const struct ratbag *ratbag);

struct ratbag *
ratbag_ref(struct ratbag *ratbag);

struct ratbag *
ratbag_unref(struct ratbag *ratbag);

struct ratbag_device*
ratbag_device_new_from_udev_device(struct ratbag *ratbag,
                                   struct udev_device *device);

struct ratbag_device *
ratbag_device_ref(struct ratbag_device *device);

struct ratbag_device *
ratbag_device_unref(struct ratbag_device *device);

void
ratbag_device_set_user_data(struct ratbag_device *device, void *userdata);

void*
ratbag_device_get_user_data(const struct ratbag_device *device);

const char *
ratbag_device_get_name(const struct ratbag_device* device);

const char *
ratbag_device_get_svg_name(const struct ratbag_device* device);

enum ratbag_device_capability {
        RATBAG_DEVICE_CAP_NONE = 0,
        RATBAG_DEVICE_CAP_SWITCHABLE_RESOLUTION,
        RATBAG_DEVICE_CAP_SWITCHABLE_PROFILE,

        RATBAG_DEVICE_CAP_BUTTON_KEY,

        RATBAG_DEVICE_CAP_BUTTON_MACROS,

        RATBAG_DEVICE_CAP_DEFAULT_PROFILE,
};

int
ratbag_device_has_capability(const struct ratbag_device *device,
                             enum ratbag_device_capability cap);

unsigned int
ratbag_device_get_num_profiles(struct ratbag_device *device);

unsigned int
ratbag_device_get_num_buttons(struct ratbag_device *device);

struct ratbag_profile *
ratbag_profile_ref(struct ratbag_profile *profile);

struct ratbag_profile *
ratbag_profile_unref(struct ratbag_profile *profile);

void
ratbag_profile_set_user_data(struct ratbag_profile *profile, void *userdata);

void*
ratbag_profile_get_user_data(const struct ratbag_profile *profile);

struct ratbag_profile *
ratbag_device_get_profile(struct ratbag_device *device, unsigned int index);

int
ratbag_profile_is_active(struct ratbag_profile *profile);

int
ratbag_profile_set_active(struct ratbag_profile *profile);

int
ratbag_profile_get_num_resolutions(struct ratbag_profile *profile);

struct ratbag_resolution *
ratbag_profile_get_resolution(struct ratbag_profile *profile, unsigned int idx);

struct ratbag_resolution *
ratbag_resolution_ref(struct ratbag_resolution *resolution);

struct ratbag_resolution *
ratbag_resolution_unref(struct ratbag_resolution *resolution);

void
ratbag_resolution_set_user_data(struct ratbag_resolution *resolution, void *userdata);

void*
ratbag_resolution_get_user_data(const struct ratbag_resolution *resolution);

enum ratbag_resolution_capability {
        RATBAG_RESOLUTION_CAP_INDIVIDUAL_REPORT_RATE = 1,

        RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION,
};

int
ratbag_resolution_has_capability(struct ratbag_resolution *resolution,
                                 enum ratbag_resolution_capability cap);

int
ratbag_resolution_set_dpi(struct ratbag_resolution *resolution,
                          unsigned int dpi);

int
ratbag_resolution_set_dpi_xy(struct ratbag_resolution *resolution,
                             unsigned int x, unsigned int y);

int
ratbag_resolution_get_dpi(struct ratbag_resolution *resolution);

int
ratbag_resolution_get_dpi_x(struct ratbag_resolution *resolution);

int
ratbag_resolution_get_dpi_y(struct ratbag_resolution *resolution);

int
ratbag_resolution_set_report_rate(struct ratbag_resolution *resolution,
                                  unsigned int hz);

int
ratbag_resolution_get_report_rate(struct ratbag_resolution *resolution);

int
ratbag_resolution_set_active(struct ratbag_resolution *resolution);

int
ratbag_resolution_is_active(const struct ratbag_resolution *resolution);

int
ratbag_resolution_set_default(struct ratbag_resolution *resolution);

int
ratbag_resolution_is_default(const struct ratbag_resolution *resolution);

struct ratbag_button*
ratbag_profile_get_button(struct ratbag_profile *profile, unsigned int index);

void
ratbag_button_set_user_data(struct ratbag_button *button, void *userdata);

void*
ratbag_button_get_user_data(const struct ratbag_button *button);

enum ratbag_button_type {
        RATBAG_BUTTON_TYPE_UNKNOWN = 0,

        /* mouse buttons */
        RATBAG_BUTTON_TYPE_LEFT,
        RATBAG_BUTTON_TYPE_MIDDLE,
        RATBAG_BUTTON_TYPE_RIGHT,
        RATBAG_BUTTON_TYPE_THUMB,
        RATBAG_BUTTON_TYPE_THUMB2,
        RATBAG_BUTTON_TYPE_THUMB3,
        RATBAG_BUTTON_TYPE_THUMB4,
        RATBAG_BUTTON_TYPE_WHEEL_LEFT,
        RATBAG_BUTTON_TYPE_WHEEL_RIGHT,
        RATBAG_BUTTON_TYPE_WHEEL_CLICK,
        RATBAG_BUTTON_TYPE_WHEEL_UP,
        RATBAG_BUTTON_TYPE_WHEEL_DOWN,
        RATBAG_BUTTON_TYPE_WHEEL_RATCHET_MODE_SHIFT,
        RATBAG_BUTTON_TYPE_EXTRA,
        RATBAG_BUTTON_TYPE_SIDE,
        RATBAG_BUTTON_TYPE_PINKIE,
        RATBAG_BUTTON_TYPE_PINKIE2,

        /* DPI switch */
        RATBAG_BUTTON_TYPE_RESOLUTION_CYCLE_UP,
        RATBAG_BUTTON_TYPE_RESOLUTION_UP,
        RATBAG_BUTTON_TYPE_RESOLUTION_DOWN,

        /* Profile */
        RATBAG_BUTTON_TYPE_PROFILE_CYCLE_UP,
        RATBAG_BUTTON_TYPE_PROFILE_UP,
        RATBAG_BUTTON_TYPE_PROFILE_DOWN,
};

enum ratbag_button_type
ratbag_button_get_type(struct ratbag_button *button);

enum ratbag_button_action_type {
        RATBAG_BUTTON_ACTION_TYPE_UNKNOWN = -1,
        RATBAG_BUTTON_ACTION_TYPE_NONE = 0,
        RATBAG_BUTTON_ACTION_TYPE_BUTTON,
        RATBAG_BUTTON_ACTION_TYPE_SPECIAL,
        RATBAG_BUTTON_ACTION_TYPE_KEY,
        RATBAG_BUTTON_ACTION_TYPE_MACRO,
};

enum ratbag_button_action_type
ratbag_button_get_action_type(struct ratbag_button *button);

int
ratbag_button_has_action_type(struct ratbag_button *button,
                              enum ratbag_button_action_type action_type);

enum ratbag_button_action_special {
        RATBAG_BUTTON_ACTION_SPECIAL_INVALID = -1,
        RATBAG_BUTTON_ACTION_SPECIAL_UNKNOWN = (1 << 30),

        RATBAG_BUTTON_ACTION_SPECIAL_DOUBLECLICK,

        /* Wheel mappings */
        RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_LEFT,
        RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_RIGHT,
        RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_UP,
        RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_DOWN,
        RATBAG_BUTTON_ACTION_SPECIAL_RATCHET_MODE_SWITCH,

        /* DPI switch */
        RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_CYCLE_UP,
        RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_UP,
        RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_DOWN,
        RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_ALTERNATE,
        RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_DEFAULT,

        /* Profile */
        RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_CYCLE_UP,
        RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_UP,
        RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_DOWN,

        /* second mode for buttons */
        RATBAG_BUTTON_ACTION_SPECIAL_SECOND_MODE,

        /* battery level */
        RATBAG_BUTTON_ACTION_SPECIAL_BATTERY_LEVEL,

};

unsigned int
ratbag_button_get_button(struct ratbag_button *button);

int
ratbag_button_set_button(struct ratbag_button *button,
                         unsigned int btn);

enum ratbag_button_action_special
ratbag_button_get_special(struct ratbag_button *button);

int
ratbag_button_set_special(struct ratbag_button *button,
                          enum ratbag_button_action_special action);

unsigned int
ratbag_button_get_key(struct ratbag_button *button,
                      unsigned int *modifiers,
                      size_t *sz);

int
ratbag_button_set_key(struct ratbag_button *button,
                      unsigned int key,
                      unsigned int *modifiers,
                      size_t sz);

int
ratbag_button_disable(struct ratbag_button *button);

enum ratbag_macro_event_type {
        RATBAG_MACRO_EVENT_INVALID = -1,
        RATBAG_MACRO_EVENT_NONE = 0,
        RATBAG_MACRO_EVENT_KEY_PRESSED,
        RATBAG_MACRO_EVENT_KEY_RELEASED,
        RATBAG_MACRO_EVENT_WAIT,
};

const char *
ratbag_button_get_macro_name(struct ratbag_button *button);

enum ratbag_macro_event_type
ratbag_button_get_macro_event_type(struct ratbag_button *button, unsigned int index);

int
ratbag_button_get_macro_event_key(struct ratbag_button *button, unsigned int index);

int
ratbag_button_get_macro_event_timeout(struct ratbag_button *button, unsigned int index);

int
ratbag_button_set_macro(struct ratbag_button *button, const char *name);

int
ratbag_button_write_macro(struct ratbag_button *button);

int
ratbag_button_set_macro_event(struct ratbag_button *button,
                              unsigned int index,
                              enum ratbag_macro_event_type type,
                              unsigned int data);

struct ratbag_button *
ratbag_button_ref(struct ratbag_button *button);

struct ratbag_button *
ratbag_button_unref(struct ratbag_button *button);

#ifdef __cplusplus
}
#endif
#endif /* LIBRATBAG_H */