global-input wayland protocol DRAFT PREVIEW

global-input-unstable-v1.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="global_input_v1">
    <copyright>
        Copyright (C) 2017 Greg V (greg@unrelenting.technology)

        Permission to use, copy, modify, and/or distribute this software for any
        purpose with or without fee is hereby granted.

        THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
        WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
        AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
        INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
        OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
        TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
        THIS SOFTWARE.
    </copyright>

    <interface name="global_input" version="1">
        <description summary="intercept and inject input events globally">
            Clients can use this interface to request copying of input events
            from all other clients, as well as inject input events into all other
            clients. This interface should be suitable for the implementation of
            many desktop utilities such as standalone modifier key press handlers
            (like xcape in X), text snippet expansion tools, input automation /
            macro recording and playback / GUI testing tools, and, yes, keyloggers.
            Compositors should implement security controls for clients that use
            this protocol.
        </description>

        <request name="destroy" type="destructor">
            <description summary="destroy the subscriptions">
                Destroy the global_input instance, unsubscribing from all events
                previously requested using that instance.
            </description>
        </request>

        <request name="subscribe_pointer">
            <description summary="subscribe to global wl_pointer events">
                Register interest in receiving all pointer events on the current seat.

                This request is dangerous for security, especially when on-screen
                keyboards are used to enter secrets like passwords.
            </description>
        </request>

        <request name="subscribe_keyboard_key">
            <description summary="subscribe to global wl_keyboard::key events">
                Register interest in receiving all key press events on the current seat.

                THIS REQUEST IS VERY DANGEROUS FOR SECURITY AS IT ALLOWS THE CLIENT
                TO SNIFF PASSWORDS AND OTHER SECRETS. COMPOSITORS MUST IMPLEMENT
                ACCESS CONTROLS THAT ONLY ALLOW HIGHLY PRIVILEGED APPLICATIONS TO
                RECEIVE ALL KEY PRESSES.
            </description>
        </request>

        <request name="subscribe_keyboard_modifiers">
            <description summary="subscribe to global wl_keyboard::modifiers events">
                Register interest in receiving all modifier key state change
                events on the current seat.
            </description>
        </request>

        <request name="subscribe_touch">
            <description summary="subscribe to global wl_touch events">
                Register interest in receiving all touch events on the current seat.

                This request is dangerous for security, especially when on-screen
                keyboards are used to enter secrets like passwords.
            </description>
        </request>

        <request name="inject_pointer_motion">
            <description summary="move the pointer">
                Move the pointer, emitting a wl_pointer::motion event into the focused
                surface and visually moving the cursor on the screen.
            </description>
            <arg name="x" type="fixed" summary="display-local x coordinate" />
            <arg name="y" type="fixed" summary="display-local y coordinate" />
        </request>

        <request name="inject_pointer_button">
            <description summary="click/release a mouse button">
                Click or release a mouse button, emitting a wl_pointer::button event
                into the focused surface.

                This request is dangerous for security, as it can be used to perform
                potentially destructive actions on the user's behalf, especially when
                combined with other capabilities such as screen recording.
            </description>
            <arg name="button" type="uint" summary="button code" />
            <arg name="state" type="uint" summary="state of the button (wl_pointer.button_state)" />
        </request>

        <request name="inject_pointer_axis">
            <description summary="send a scroll event">
                Scroll, emitting a wl_pointer::axis event into the focused surface.
            </description>
            <arg name="axis" type="uint" summary="axis of the event (wl_pointer.axis)" />
            <arg name="value" type="fixed" />
        </request>

        <request name="inject_pointer_frame">
            <description summary="send a frame event">
                Signal the end of a group of events, emitting a wl_pointer::frame
                event into the focused surface.
            </description>
        </request>

        <request name="inject_pointer_axis_source">
            <description summary="send an axis source event">
                Provide source information for scrolling, emitting a
                wl_pointer::axis_source event into the focused surface.
            </description>
            <arg name="axis" type="uint" summary="axis of the event (wl_pointer.axis)" />
        </request>

        <request name="inject_pointer_axis_stop">
            <description summary="send an axis stop event">
                Send a stop notification for scrolling, emitting a
                wl_pointer::axis_stop event into the focused surface.
            </description>
            <arg name="axis" type="uint" summary="axis of the event (wl_pointer.axis)" />
        </request>

        <request name="inject_pointer_axis_discrete">
            <description summary="send an axis click event">
                Send discrete step information for scrolling, emitting a
                wl_pointer::axis_discrete event into the focused surface.
            </description>
            <arg name="axis" type="uint" summary="axis of the event (wl_pointer.axis)" />
            <arg name="discrete" type="int" />
        </request>

        <request name="inject_keyboard_key">
            <description summary="send a keyboard key event">
                Press or release a keyboard key, emitting a wl_keyboard::key event
                into the focused surface.

                This request is dangerous for security, as it can be used to perform
                potentially destructive actions on the user's behalf, especially when
                combined with other capabilities such as screen recording.
            </description>
            <arg name="key" type="uint" summary="key code" />
            <arg name="state" type="uint" summary="state of the key (wl_keyboard.key_state)" />
        </request>

        <request name="inject_keyboard_modifiers">
            <description summary="send a keyboard modifiers event">
                Change the state of modifier keys, emitting a wl_keyboard::modifier
                event into the focused surface.
            </description>
            <arg name="mods_depressed" type="uint" summary="depressed modifiers" />
            <arg name="mods_latched" type="uint" summary="latched modifiers" />
            <arg name="mods_locked" type="uint" summary="locked modifiers" />
            <arg name="group" type="uint" summary="keyboard layout" />
        </request>

        <!-- XXX: touch event injection (how should ids be generated?) -->
    </interface>
</protocol>