1xe / netevent Goto Github PK

License:
	See the LICENSE file.

Compilation:
	Simply run
	  make
	or compile the .cpp files into a binary using the CFLAGS -pthread -DWITH_INOTIFY
	If you do not want inotify-support, run:
	  make inotify=no
	or leave out -DWITH_INOTIFY

Installation:
	Put the netevent binary wherever you want it...

Usage:
	This tool operates in 2 modes:
	./netevent [-nograb] [-toggler <toggle file>] [-ontoggle <shell command>] -read <device file>
	./netevent -write <device file>
	./netevent [-nograb] [-countsyn] -showevents <count> <device file>

	Without inotify support, the toggle-file has to exist and be a FIFO, because otherwise it would
	constantly reopen and read form the file.
	With inotify support the file doesn't need to exist yet. It will be read upon creation or modification.

	The -showevents switch allows you to simply print event information to stdout. This is useful because
	there's going to be the possibility to configure hotkeys using the information you get out of it.
	By default SYN events are not counted, unless you add the -countsyn switch.

	Additional options include:
	  -quiet
	    Do not print that much spam
	    In -showevents mode: do not print events. Use it if you want it to only act as a
	    hotkey-tool without spam.
	  -hotkey TYPE:CODE:VALUE <command>
	    Create a hotkey: Execute the specified command if the event with the given
	    type, code and value is read from or written to the device.
	    When a hotkey is hit, the event will not appear in the output (-read) or the event
	    device (-write).
	    The command can access the GRAB variable (which is useless in -write mode).
	    TYPE can be a numerical type, or an EV_* type found in the input headers.
	    for EV_KEY events, code corresponds to the key and value to the 'pressed' state.
	    You can find out what kind of event you're looking for by letting -showevents print
	    the event for you.
	    There are a few special hotkey commands available:
	      @toggle
	        Toggle device grabbing
	      @toggle-on
	        Activate device grabbing
	      @toggle-off
	        Deactivate device grabbing

What does it do?
	This utility lets you clone a linux event device. In read mode it reads from the device
	and dumps the data to stdout, and in write mode it creates the same device
	using the uinput feature, and pipes the data into the new device.
	Since this utility operates only on device files, it does not depend on X11.
	It even allows you to use the devices in the console.
	The same mechanism could be used to create an utility for device-specific non-X-dependent hotkeys.

Read Mode:
	In read mode, it opens an event file, grabs it, and dumps its capabilities, and then
	all its events as binary data to stdout.

	In this mode, the -toggler parameter specifies a file which is read (on change, or without inotify
	support it is read over and over again so it would be goot to use a fifo)
	which causes the program to either ungrab or (re-)grab the event device. If the file contains
	data which corresponds to "false" (ie. a zero digit), the device is released, and no events
	are sent to stdout. On "true" (ie. a 1 digit), the device is re-grabbed, and the events passed
	to stdout again.
	The -ontoggle option can be used to execute a shell command whenever the device is grabbed
	or ungrabbed. The command is executed using "sh -c", and the environment variable GRAB is set
	to 0 when un-grabbed, or 1 when grabbed.
	This can be used to chain multiple devices together.

	Example:
	  Machine where the devices are connected to physically:
	    mkfifo ~/toggler
	    ./netevent -toggler ~/maintoggler -ontoggle 'echo $GRAB > ~/toggler' \
	        -read /dev/input/event7 | netcat -t 192.168.0.50 1955 &
	    ./netevent -toggler ~/toggler -read /dev/input/event15 | netcat -t 192.168.0.50 1956
	  NOTE: If you want to grab the current keyboard, add a 'sleep 0.3 &' before the command, otherwise
	        it is possible that the release of your 'return' key when executing the command is already
		read by the utility and you'll endup with 'return' being key-repeated :P

	  Other machine (192.168.0.50 in our case)
	    netcat -t -l -p 1955 | ./netevent -write &
	    netcat -t -l -p 1956 | ./netevent -write

	  In this example, one machine simply waits on ports 1955 and 1956 for a device to connect, and
	  the other machine reads from 2 devices, /dev/input/event7 and 15.
	  Whenever the even7 devices is toggled using for example:
	    echo 0 > ~/maintoggler
	  It also executes 'echo $GRAB > ~/toggler' which sets the second netevent process to also ungrab
	  or grab its device, thus, the two devices work together.

	  Of course, instead of a fifo you could just use a normal file, and have both read from the
	  same file. But this is just an example.

	  NOTE: You need 'read' access to the event device to be able to read and grab it!

Write Mode:
	In write mode, the utility simply waits for the output of a 'read' mode process on stdin, and uses
	this to clone the device using the 'uinput' special device file.
	You must either have uinput compiled into your kernel, or the 'uinput' module loaded.

	Example:
	  modeprobe uinput
	  netcat -t -l -p 1955 | ./netevent -write

client.sh
	wrapper script to execute netcat and read from a device
host.sh
	wrapper script to execute netcat and pass its output to netevent