← Back to branch summary

~ubuntu-branches/debian/sid/libevdev/sid

« back to all changes in this revision

Viewing changes to libevdev/libevdev.h

  • Committer: Package Import Robot
  • Author(s): Stephen Kitt
  • Date: 2014-09-09 07:59:54 UTC
  • mfrom: (1.1.13)
  • Revision ID: package-import@ubuntu.com-20140909075954-wuic1ooxes68u2er
Tags: 1.3+dfsg-1
* New upstream release.
* libevdev should really have priority optional rather than extra.
* Add upstream's signing key and use it in debian/watch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
libevdev/libevdev.h
541
541
 */
542
542
 
543
543
/**
 
544
 * @page static_linking Statically linking libevdev
 
545
 *
 
546
 * Statically linking libevdev.a is not recommended. Symbol visibility is
 
547
 * difficult to control in a static library, so extra care must be taken to
 
548
 * only use symbols that are explicitly exported. libevdev's API stability
 
549
 * guarantee only applies to those symbols.
 
550
 *
 
551
 * If you do link libevdev statically, note that in addition to the exported
 
552
 * symbols, libevdev reserves the <b>_libevdev_*</b> namespace. Do not use
 
553
 * or create symbols with that prefix, they are subject to change at any
 
554
 * time.
 
555
 */
 
556
 
 
557
/**
544
558
 * @page testing libevdev-internal test suite
545
559
 *
546
560
 * libevdev's internal test suite uses the
615
629
 */
616
630
 
617
631
/**
 
632
 * @defgroup logging Library logging facilities
 
633
 *
 
634
 * libevdev provides two methods of logging library-internal messages. The
 
635
 * old method is to provide a global log handler in
 
636
 * libevdev_set_log_function(). The new method is to provide a per-context
 
637
 * log handler in libevdev_set_device_log_function(). Developers are encouraged
 
638
 * to use the per-context logging facilities over the global log handler as
 
639
 * it provides access to the libevdev instance that caused a message, and is
 
640
 * more flexible when libevdev is used from within a shared library.
 
641
 *
 
642
 * If a caller sets both the global log handler and a per-context log
 
643
 * handler, each device with a per-context log handler will only invoke that
 
644
 * log handler.
 
645
 *
 
646
 * @note To set a context-specific log handler, a context is needed.
 
647
 * Thus developers are discouraged from using libevdev_new_from_fd() as
 
648
 * important messages from the device initialization process may get lost.
 
649
 *
 
650
 * @note A context-specific handler cannot be used for libevdev's uinput
 
651
 * devices. @ref uinput must use the global log handler.
 
652
 */
 
653
 
 
654
/**
618
655
 * @defgroup bits Querying device capabilities
619
656
 *
620
657
 * Abstraction functions to handle device capabilities, specificially
764
801
void libevdev_free(struct libevdev *dev);
765
802
 
766
803
/**
767
 
 * @ingroup init
 
804
 * @ingroup logging
768
805
 */
769
806
enum libevdev_log_priority {
770
807
        LIBEVDEV_LOG_ERROR = 10,        /**< critical errors and application bugs */
773
810
};
774
811
 
775
812
/**
776
 
 * @ingroup init
 
813
 * @ingroup logging
777
814
 *
778
815
 * Logging function called by library-internal logging.
779
816
 * This function is expected to treat its input like printf would.
796
833
        LIBEVDEV_ATTRIBUTE_PRINTF(6, 0);
797
834
 
798
835
/**
799
 
 * @ingroup init
 
836
 * @ingroup logging
800
837
 *
801
838
 * Set a printf-style logging handler for library-internal logging. The default
802
839
 * logging function is to stdout.
803
840
 *
 
841
 * @note The global log handler is only called if no context-specific log
 
842
 * handler has been set with libevdev_set_device_log_function().
 
843
 *
804
844
 * @param logfunc The logging function for this device. If NULL, the current
805
845
 * logging function is unset and no logging is performed.
806
846
 * @param data User-specific data passed to the log handler.
807
847
 *
808
848
 * @note This function may be called before libevdev_set_fd().
 
849
 *
 
850
 * @deprecated Use per-context logging instead, see
 
851
 * libevdev_set_device_log_function().
809
852
 */
810
853
void libevdev_set_log_function(libevdev_log_func_t logfunc, void *data);
811
854
 
812
855
/**
813
 
 * @ingroup init
 
856
 * @ingroup logging
814
857
 *
815
858
 * Define the minimum level to be printed to the log handler.
816
859
 * Messages higher than this level are printed, others are discarded. This
818
861
 *
819
862
 * @param priority Minimum priority to be printed to the log.
820
863
 *
 
864
 * @deprecated Use per-context logging instead, see
 
865
 * libevdev_set_device_log_function().
821
866
 */
822
867
void libevdev_set_log_priority(enum libevdev_log_priority priority);
823
868
 
824
869
/**
825
 
 * @ingroup init
 
870
 * @ingroup logging
826
871
 *
827
872
 * Return the current log priority level. Messages higher than this level
828
873
 * are printed, others are discarded. This is a global setting.
829
874
 *
830
875
 * @return the current log level
 
876
 *
 
877
 * @deprecated Use per-context logging instead, see
 
878
 * libevdev_set_device_log_function().
831
879
 */
832
880
enum libevdev_log_priority libevdev_get_log_priority(void);
833
881
 
834
882
/**
 
883
 * @ingroup logging
 
884
 *
 
885
 * Logging function called by library-internal logging for a specific
 
886
 * libevdev context. This function is expected to treat its input like
 
887
 * printf would.
 
888
 *
 
889
 * @param dev The evdev device
 
890
 * @param priority Log priority of this message
 
891
 * @param data User-supplied data pointer (see libevdev_set_log_function())
 
892
 * @param file libevdev source code file generating this message
 
893
 * @param line libevdev source code line generating this message
 
894
 * @param func libevdev source code function generating this message
 
895
 * @param format printf-style format string
 
896
 * @param args List of arguments
 
897
 *
 
898
 * @see libevdev_set_log_function
 
899
 * @since 1.3
 
900
 */
 
901
typedef void (*libevdev_device_log_func_t)(const struct libevdev *dev,
 
902
                                           enum libevdev_log_priority priority,
 
903
                                           void *data,
 
904
                                           const char *file, int line,
 
905
                                           const char *func,
 
906
                                           const char *format, va_list args)
 
907
        LIBEVDEV_ATTRIBUTE_PRINTF(7, 0);
 
908
 
 
909
/**
 
910
 * @ingroup logging
 
911
 *
 
912
 * Set a printf-style logging handler for library-internal logging for this
 
913
 * device context. The default logging function is NULL, i.e. the global log
 
914
 * handler is invoked. If a context-specific log handler is set, the global
 
915
 * log handler is not invoked for this device.
 
916
 *
 
917
 * @note This log function applies for this device context only, even if
 
918
 * another context exists for the same fd.
 
919
 *
 
920
 * @param dev The evdev device
 
921
 * @param logfunc The logging function for this device. If NULL, the current
 
922
 * logging function is unset and logging falls back to the global log
 
923
 * handler, if any.
 
924
 * @param priority Minimum priority to be printed to the log.
 
925
 * @param data User-specific data passed to the log handler.
 
926
 *
 
927
 * @note This function may be called before libevdev_set_fd().
 
928
 * @since 1.3
 
929
 */
 
930
void libevdev_set_device_log_function(struct libevdev *dev,
 
931
                                      libevdev_device_log_func_t logfunc,
 
932
                                      enum libevdev_log_priority priority,
 
933
                                      void *data);
 
934
 
 
935
/**
835
936
 * @ingroup init
836
937
 */
837
938
enum libevdev_grab_mode {
1673
1774
/**
1674
1775
 * @ingroup kernel
1675
1776
 *
1676
 
 * Forcibly enable an event type on this device, even if the underlying
 
1777
 * Forcibly enable an event code on this device, even if the underlying
1677
1778
 * device does not support it. While this cannot make the device actually
1678
1779
 * report such events, it will now return true for libevdev_has_event_code().
1679
1780
 *
1720
1821
 * This is a local modification only affecting only this representation of
1721
1822
 * this device.
1722
1823
 *
1723
 
 * Disabling EV_SYN will not work. Don't shoot yourself in the foot.
1724
 
 * It hurts.
 
1824
 * Disabling codes of type EV_SYN will not work. Don't shoot yourself in the
 
1825
 * foot. It hurts.
1725
1826
 *
1726
1827
 * @param dev The evdev device, already initialized with libevdev_set_fd()
1727
1828
 * @param type The event type to disable (EV_ABS, EV_KEY, ...)
1998
2099
                                    size_t len);
1999
2100
 
2000
2101
/**
 
2102
 * @ingroup misc
 
2103
 *
 
2104
 * Look up an input property by its name. Properties start with the fixed
 
2105
 * prefix "INPUT_PROP_" followed by their name (eg., "INPUT_PROP_POINTER").
 
2106
 * The prefix must be included in the name. It returns the constant assigned
 
2107
 * to the property or -1 if not found.
 
2108
 *
 
2109
 * @param name A non-NULL string describing an input property
 
2110
 *
 
2111
 * @return The given code constant for the name or -1 if not found.
 
2112
 */
 
2113
int libevdev_property_from_name(const char *name);
 
2114
 
 
2115
/**
 
2116
 * @ingroup misc
 
2117
 *
 
2118
 * Look up an input property by its name. Properties start with the fixed
 
2119
 * prefix "INPUT_PROP_" followed by their name (eg., "INPUT_PROP_POINTER").
 
2120
 * The prefix must be included in the name. It returns the constant assigned
 
2121
 * to the property or -1 if not found.
 
2122
 *
 
2123
 * @param name A non-NULL string describing an input property
 
2124
 * @param len The length of the string in @p name excluding any terminating 0
 
2125
 * character.
 
2126
 *
 
2127
 * @return The given code constant for the name or -1 if not found.
 
2128
 */
 
2129
int libevdev_property_from_name_n(const char *name, size_t len);
 
2130
 
 
2131
/**
2001
2132
 * @ingroup bits
2002
2133
 *
2003
2134
 * Get the repeat delay and repeat period values for this device. This