vkm.h File Reference

Functions, structures and enumerations for the virtual keyboard/mouse interface library (VKM). More...

Go to the source code of this file.

Macros
#define	VKM_KEY_MOD_CTRL   VKM_KEY_MOD_LCTRL
#define	VKM_KEY_MOD_SHIFT   VKM_KEY_MOD_LSHIFT
#define	VKM_KEY_MOD_ALT   VKM_KEY_MOD_LALT
#define	VKM_KEY_MOD_GUI   VKM_KEY_MOD_LGUI

Typedefs
typedef struct vkm_context	vkm_context
	Virtual device context structure used by the VKM framework.
typedef int32_t	vkm_result
	Return type used by VKM API functions.

Enumerations
enum	vkm_feature { VKM_FEAT_MOUSE = (1 << 0) , VKM_FEAT_KEYBOARD = (1 << 1) , VKM_FEAT_KEYBOARD_MODIFIERS = (1 << 2) }
	Feature identifiers for vkm_feature_supported. More...
enum	vkm_error_code {   VKM_SUCCESS = 0 , VKM_ERROR_UNKNOWN , VKM_ERROR_NOT_READY , VKM_ERROR_OUT_OF_MEMORY ,   VKM_ERROR_INVALID_PARAM , VKM_ERROR_NOT_SUPPORTED , VKM_ERROR_DEV_FAILURE , VKM_ERROR_EVENT ,   VKM_ERROR_NO_CHANGE , VKM_ERROR_MAX }
	Error code list. More...
enum	vkm_option { VKM_OPT_HI_RES_SCROLL , VKM_OPT_HORIZONTAL_SCROLL , VKM_OPT_DEVICE_NAME , VKM_OPT_MAX }
	Option list. More...
enum	vkm_button_state { VKM_BUTTON_RELEASED , VKM_BUTTON_PRESSED , VKM_BUTTON_STATE_MAX }
	Button state. More...
enum	vkm_mouse_button { VKM_MOUSE_BTN_LEFT , VKM_MOUSE_BTN_RIGHT , VKM_MOUSE_BTN_MIDDLE , VKM_MOUSE_BTN_MAX }
	Mouse button identifiers. More...
enum	vkm_mouse_scroll_direction { VKM_MOUSE_SCROLL_UP , VKM_MOUSE_SCROLL_DOWN , VKM_MOUSE_SCROLL_LEFT , VKM_MOUSE_SCROLL_RIGHT , VKM_MOUSE_SCROLL_MAX }
	Scroll directions. More...
enum	vkm_key {   VKM_KEY_NONE = 0x00 , VKM_KEY_A = 0x04 , VKM_KEY_B , VKM_KEY_C ,   VKM_KEY_D , VKM_KEY_E , VKM_KEY_F , VKM_KEY_G ,   VKM_KEY_H , VKM_KEY_I , VKM_KEY_J , VKM_KEY_K ,   VKM_KEY_L , VKM_KEY_M , VKM_KEY_N , VKM_KEY_O ,   VKM_KEY_P , VKM_KEY_Q , VKM_KEY_R , VKM_KEY_S ,   VKM_KEY_T , VKM_KEY_U , VKM_KEY_V , VKM_KEY_W ,   VKM_KEY_X , VKM_KEY_Y , VKM_KEY_Z , VKM_KEY_1 = 0x1E ,   VKM_KEY_2 , VKM_KEY_3 , VKM_KEY_4 , VKM_KEY_5 ,   VKM_KEY_6 , VKM_KEY_7 , VKM_KEY_8 , VKM_KEY_9 ,   VKM_KEY_0 , VKM_KEY_ENTER = 0x28 , VKM_KEY_ESCAPE , VKM_KEY_BACKSPACE ,   VKM_KEY_TAB , VKM_KEY_SPACE , VKM_KEY_MINUS , VKM_KEY_EQUAL ,   VKM_KEY_LEFT_BRACKET , VKM_KEY_RIGHT_BRACKET , VKM_KEY_BACKSLASH , VKM_KEY_NONUS_HASH ,   VKM_KEY_SEMICOLON , VKM_KEY_APOSTROPHE , VKM_KEY_GRAVE_ACCENT , VKM_KEY_COMMA ,   VKM_KEY_PERIOD , VKM_KEY_SLASH , VKM_KEY_CAPS_LOCK = 0x39 , VKM_KEY_F1 = 0x3A ,   VKM_KEY_F2 , VKM_KEY_F3 , VKM_KEY_F4 , VKM_KEY_F5 ,   VKM_KEY_F6 , VKM_KEY_F7 , VKM_KEY_F8 , VKM_KEY_F9 ,   VKM_KEY_F10 , VKM_KEY_F11 , VKM_KEY_F12 , VKM_KEY_PRINT_SCREEN = 0x46 ,   VKM_KEY_SCROLL_LOCK , VKM_KEY_PAUSE , VKM_KEY_INSERT , VKM_KEY_HOME ,   VKM_KEY_PAGE_UP , VKM_KEY_DELETE_FORWARD , VKM_KEY_END , VKM_KEY_PAGE_DOWN ,   VKM_KEY_RIGHT_ARROW , VKM_KEY_LEFT_ARROW , VKM_KEY_DOWN_ARROW , VKM_KEY_UP_ARROW ,   VKM_KEY_KEYPAD_NUM_LOCK = 0x53 , VKM_KEY_KEYPAD_DIVIDE , VKM_KEY_KEYPAD_MULTIPLY , VKM_KEY_KEYPAD_MINUS ,   VKM_KEY_KEYPAD_PLUS , VKM_KEY_KEYPAD_ENTER , VKM_KEY_KEYPAD_1 , VKM_KEY_KEYPAD_2 ,   VKM_KEY_KEYPAD_3 , VKM_KEY_KEYPAD_4 , VKM_KEY_KEYPAD_5 , VKM_KEY_KEYPAD_6 ,   VKM_KEY_KEYPAD_7 , VKM_KEY_KEYPAD_8 , VKM_KEY_KEYPAD_9 , VKM_KEY_KEYPAD_0 ,   VKM_KEY_KEYPAD_DECIMAL , VKM_KEY_INTL_BACKSLASH , VKM_KEY_APPLICATION , VKM_KEY_KEYPAD_COMMA = 0x85 ,   VKM_KEY_LEFT_CTRL = 0xE0 , VKM_KEY_LEFT_SHIFT , VKM_KEY_LEFT_ALT , VKM_KEY_LEFT_GUI ,   VKM_KEY_RIGHT_CTRL , VKM_KEY_RIGHT_SHIFT , VKM_KEY_RIGHT_ALT , VKM_KEY_RIGHT_GUI ,   VKM_KEY_MAX }
	Physical key identifiers (USB HID keyboard/keypad page, usage page 0x07) More...
enum	vkm_key_modifiers {   VKM_KEY_MOD_NONE = 0 , VKM_KEY_MOD_LCTRL = (1 << 0) , VKM_KEY_MOD_LSHIFT = (1 << 1) , VKM_KEY_MOD_LALT = (1 << 2) ,   VKM_KEY_MOD_LGUI = (1 << 3) , VKM_KEY_MOD_RCTRL = (1 << 4) , VKM_KEY_MOD_RSHIFT = (1 << 5) , VKM_KEY_MOD_RALT = (1 << 6) ,   VKM_KEY_MOD_RGUI = (1 << 7) }
	Modifier bitmask for vkm_keyboard_send. More...
enum	vkm_key_state { VKM_KEY_STATE_RELEASED , VKM_KEY_STATE_PRESSED , VKM_KEY_STATE_MAX }
	Physical key action (press or release) for vkm_keyboard_send. More...

Functions
VKM_API const char *	vkm_strerror (vkm_result code)
	Return a short description for a vkm_result / vkm_error_code value.
VKM_API vkm_result	vkm_init (vkm_context **ctx)
	Initialize the VKM library.
VKM_API void	vkm_exit (vkm_context *ctx)
	Exit the VKM library and free up any resources used.
VKM_API vkm_result	vkm_reset (vkm_context *ctx)
	Release all virtual keys and mouse buttons that are still down.
VKM_API vkm_result	vkm_start (vkm_context *ctx)
	Start any virtual keyboard/mouse devices on the platform.
VKM_API bool	vkm_is_ready (vkm_context *ctx)
	check if VKM is started and ready
VKM_API bool	vkm_platform_supported (void)
	Check if VKM is supported on this platform.
VKM_API bool	vkm_feature_supported (vkm_feature feat)
	Check if a particular feature is enabled on this platform.
VKM_API vkm_result	vkm_set_option (vkm_context *ctx, vkm_option option,...)
	Set an option flag for VKM.
VKM_API vkm_result	vkm_mouse_move (vkm_context *ctx, int dx, int dy)
	Move the mouse by the specified amount.
VKM_API vkm_result	vkm_mouse_click (vkm_context *ctx, vkm_mouse_button button, vkm_button_state state)
	Click the mouse button.
VKM_API vkm_result	vkm_mouse_scroll (vkm_context *ctx, vkm_mouse_scroll_direction dir)
	Scroll the mouse wheel.
VKM_API vkm_result	vkm_keyboard_send (vkm_context *ctx, vkm_key key, vkm_key_modifiers modifiers, vkm_key_state state)
	Send a single keyboard event.
VKM_API vkm_result	vkm_sync (vkm_context *ctx)
	Send a sync packet to the OS.

Detailed Description

Functions, structures and enumerations for the virtual keyboard/mouse interface library (VKM).

This file contains the type, enum and function prototypes for VKM. These functions allow an application to inject keyboard/mouse events into the host OS, as long as it has the necessary permissions.

Author

Nirenjan Krishnan (niren.nosp@m.jan@.nosp@m.niren.nosp@m.jan..nosp@m.org)

Macro Definition Documentation

VKM_KEY_MOD_ALT

#define VKM_KEY_MOD_ALT   VKM_KEY_MOD_LALT

Convenience alias for VKM_KEY_MOD_LALT

VKM_KEY_MOD_CTRL

#define VKM_KEY_MOD_CTRL   VKM_KEY_MOD_LCTRL

Convenience alias for VKM_KEY_MOD_LCTRL

VKM_KEY_MOD_GUI

#define VKM_KEY_MOD_GUI   VKM_KEY_MOD_LGUI

Convenience alias for VKM_KEY_MOD_LGUI

VKM_KEY_MOD_SHIFT

#define VKM_KEY_MOD_SHIFT   VKM_KEY_MOD_LSHIFT

Convenience alias for VKM_KEY_MOD_LSHIFT

Typedef Documentation

vkm_context

typedef struct vkm_context vkm_context

Virtual device context structure used by the VKM framework.

All VKM API functions require the application to pass in a pointer to a valid context structure. A pointer can be obtained by calling vkm_init

Enumeration Type Documentation

vkm_button_state

enum vkm_button_state

Button state.

Enumerator
VKM_BUTTON_RELEASED	Button is released
VKM_BUTTON_PRESSED	Button is pressed

vkm_error_code

enum vkm_error_code

Error code list.

Enumerator
VKM_SUCCESS	No error, indicates success
VKM_ERROR_UNKNOWN	Unknown error, used as a catch-all error state
VKM_ERROR_NOT_READY	Not started, must call vkm_start first
VKM_ERROR_OUT_OF_MEMORY	Out of memory
VKM_ERROR_INVALID_PARAM	Invalid parameter(s)
VKM_ERROR_NOT_SUPPORTED	Not supported
VKM_ERROR_DEV_FAILURE	Unable to create virtual devices
VKM_ERROR_EVENT	Unable to write event
VKM_ERROR_NO_CHANGE	No state change in the event, please retry

vkm_feature

enum vkm_feature

Feature identifiers for vkm_feature_supported.

Bit flags describing optional VKM capabilities on the current platform. Pass one enumerator at a time to vkm_feature_supported.

Enumerator
VKM_FEAT_MOUSE	Relative mouse move, buttons, and wheel
VKM_FEAT_KEYBOARD	Full vkm_keyboard_send key map (platform virtual keyboard)
VKM_FEAT_KEYBOARD_MODIFIERS	Separate left/right logical modifiers in vkm_keyboard_send

vkm_key

enum vkm_key

Physical key identifiers (USB HID keyboard/keypad page, usage page 0x07)

Logical key codes for vkm_keyboard_send. Each enumerator's numeric value is the USB HID usage ID for that key (same encoding as the keyboard bitmap in HID report descriptors, except for VKM_KEY_NONE). Letters use the HID ordering (A=0x04 … Z=0x1D), not QWERTY row order. VKM_KEY_MAX is 0xE8, one past the highest usage used here, so valid keys satisfy key < VKM_KEY_MAX.

Enumerator
VKM_KEY_NONE	Sentinel: no key (e.g. modifier-only update)
VKM_KEY_A	A / a (HID Latin alphabet block)
VKM_KEY_B	B
VKM_KEY_C	C
VKM_KEY_D	D
VKM_KEY_E	E
VKM_KEY_F	F
VKM_KEY_G	G
VKM_KEY_H	H
VKM_KEY_I	I
VKM_KEY_J	J
VKM_KEY_K	K
VKM_KEY_L	L
VKM_KEY_M	M
VKM_KEY_N	N
VKM_KEY_O	O
VKM_KEY_P	P
VKM_KEY_Q	Q
VKM_KEY_R	R
VKM_KEY_S	S
VKM_KEY_T	T
VKM_KEY_U	U
VKM_KEY_V	V
VKM_KEY_W	W
VKM_KEY_X	X
VKM_KEY_Y	Y
VKM_KEY_Z	Z
VKM_KEY_1	1 / !
VKM_KEY_2	2 / @
VKM_KEY_3	3 / #
VKM_KEY_4	4 / $
VKM_KEY_5	5 / %
VKM_KEY_6	6 / ^
VKM_KEY_7	7 / &
VKM_KEY_8	8 / *
VKM_KEY_9	9 / (
VKM_KEY_0	0 / )
VKM_KEY_ENTER	Return / Enter
VKM_KEY_ESCAPE	Escape
VKM_KEY_BACKSPACE	Delete / Backspace
VKM_KEY_TAB	Tab
VKM_KEY_SPACE	Space bar
VKM_KEY_MINUS	Minus / underscore
VKM_KEY_EQUAL	Equals / plus
VKM_KEY_LEFT_BRACKET	Left bracket / brace
VKM_KEY_RIGHT_BRACKET	Right bracket / brace
VKM_KEY_BACKSLASH	Backslash / pipe (US placement; JIS Yen)
VKM_KEY_NONUS_HASH	Non-US # / ~ (HID usage 0x32)
VKM_KEY_SEMICOLON	Semicolon / colon
VKM_KEY_APOSTROPHE	Apostrophe / quote
VKM_KEY_GRAVE_ACCENT	Grave accent / tilde
VKM_KEY_COMMA	Comma / less-than
VKM_KEY_PERIOD	Period / greater-than
VKM_KEY_SLASH	Slash / question
VKM_KEY_CAPS_LOCK	Caps Lock
VKM_KEY_F1	F1
VKM_KEY_F2	F2
VKM_KEY_F3	F3
VKM_KEY_F4	F4
VKM_KEY_F5	F5
VKM_KEY_F6	F6
VKM_KEY_F7	F7
VKM_KEY_F8	F8
VKM_KEY_F9	F9
VKM_KEY_F10	F10
VKM_KEY_F11	F11
VKM_KEY_F12	F12
VKM_KEY_PRINT_SCREEN	Print Screen
VKM_KEY_SCROLL_LOCK	Scroll Lock
VKM_KEY_PAUSE	Pause / Break
VKM_KEY_INSERT	Insert
VKM_KEY_HOME	Home
VKM_KEY_PAGE_UP	Page Up
VKM_KEY_DELETE_FORWARD	Delete (forward)
VKM_KEY_END	End
VKM_KEY_PAGE_DOWN	Page Down
VKM_KEY_RIGHT_ARROW	Arrow right
VKM_KEY_LEFT_ARROW	Arrow left
VKM_KEY_DOWN_ARROW	Arrow down
VKM_KEY_UP_ARROW	Arrow up
VKM_KEY_KEYPAD_NUM_LOCK	Keypad Num Lock
VKM_KEY_KEYPAD_DIVIDE	Keypad /
VKM_KEY_KEYPAD_MULTIPLY	Keypad *
VKM_KEY_KEYPAD_MINUS	Keypad -
VKM_KEY_KEYPAD_PLUS	Keypad +
VKM_KEY_KEYPAD_ENTER	Keypad Enter
VKM_KEY_KEYPAD_1	Keypad 1 / End
VKM_KEY_KEYPAD_2	Keypad 2 / Down
VKM_KEY_KEYPAD_3	Keypad 3 / Page Down
VKM_KEY_KEYPAD_4	Keypad 4 / Left
VKM_KEY_KEYPAD_5	Keypad 5
VKM_KEY_KEYPAD_6	Keypad 6 / Right
VKM_KEY_KEYPAD_7	Keypad 7 / Home
VKM_KEY_KEYPAD_8	Keypad 8 / Up
VKM_KEY_KEYPAD_9	Keypad 9 / Page Up
VKM_KEY_KEYPAD_0	Keypad 0 / Insert
VKM_KEY_KEYPAD_DECIMAL	Keypad decimal / Delete
VKM_KEY_INTL_BACKSLASH	Non-US \ / | (ISO key; HID 0x64)
VKM_KEY_APPLICATION	Application / Menu
VKM_KEY_KEYPAD_COMMA	Keypad comma (Braz. keypad, etc.)
VKM_KEY_LEFT_CTRL	Left Control
VKM_KEY_LEFT_SHIFT	Left Shift
VKM_KEY_LEFT_ALT	Left Alt
VKM_KEY_LEFT_GUI	Left GUI / Meta / Windows key
VKM_KEY_RIGHT_CTRL	Right Control
VKM_KEY_RIGHT_SHIFT	Right Shift
VKM_KEY_RIGHT_ALT	Right Alt / AltGr
VKM_KEY_RIGHT_GUI	Right GUI / Meta
VKM_KEY_MAX	One past highest usage; bounds checks and tables

vkm_key_modifiers

enum vkm_key_modifiers

Modifier bitmask for vkm_keyboard_send.

Left and right modifier keys use the same bit layout as the USB HID keyboard modifier byte. Combine values with bitwise OR. These are separate from physical modifier key events in vkm_key.

Convenience macros VKM_KEY_MOD_CTRL, VKM_KEY_MOD_SHIFT, VKM_KEY_MOD_ALT, and VKM_KEY_MOD_GUI alias the left-hand modifiers only; use VKM_KEY_MOD_L* / VKM_KEY_MOD_R* when a specific side is required.

Enumerator
VKM_KEY_MOD_NONE	No modifiers
VKM_KEY_MOD_LCTRL	Left Control (HID modifier byte bit 0)
VKM_KEY_MOD_LSHIFT	Left Shift (bit 1)
VKM_KEY_MOD_LALT	Left Alt (bit 2)
VKM_KEY_MOD_LGUI	Left GUI / Meta (bit 3)
VKM_KEY_MOD_RCTRL	Right Control (bit 4)
VKM_KEY_MOD_RSHIFT	Right Shift (bit 5)
VKM_KEY_MOD_RALT	Right Alt / AltGr (bit 6)
VKM_KEY_MOD_RGUI	Right GUI / Meta (bit 7)

vkm_key_state

enum vkm_key_state

Physical key action (press or release) for vkm_keyboard_send.

Determines the value sent with the non-modifier vkm_key (and, on release, how the modifier mask is reconciled after the key event).

Enumerator
VKM_KEY_STATE_RELEASED	Key or button is up
VKM_KEY_STATE_PRESSED	Key or button is down
VKM_KEY_STATE_MAX	Sentinel; do not use in application code

vkm_mouse_button

enum vkm_mouse_button

Mouse button identifiers.

Enumerator
VKM_MOUSE_BTN_LEFT	Mouse left button
VKM_MOUSE_BTN_RIGHT	Mouse right button
VKM_MOUSE_BTN_MIDDLE	Mouse middle button

vkm_mouse_scroll_direction

enum vkm_mouse_scroll_direction

Scroll directions.

Enumerator
VKM_MOUSE_SCROLL_UP	Scroll up
VKM_MOUSE_SCROLL_DOWN	Scroll down
VKM_MOUSE_SCROLL_LEFT	Scroll left (horizontal scrolling)
VKM_MOUSE_SCROLL_RIGHT	Scroll right (horizontal scrolling)

vkm_option

enum vkm_option

Option list.

Enumerator
VKM_OPT_HI_RES_SCROLL	Set the high resolution scrolling behavior of the mouse. This option must be passed a boolean which lets VKM know whether to enable or disable high resolution scrolling. Defaults to false. When enabled together with vkm_start, vkm_mouse_scroll emits high-resolution REL_*_HI_RES events (120 units per step) in addition to discrete REL_WHEEL / REL_HWHEEL ticks.
VKM_OPT_HORIZONTAL_SCROLL	Enable or disable horizontal scrolling of the mouse. This option must be passed in a boolean which lets VKM know whether to enable or disable horizontal scrolling. If horizontal scrolling is disabled, then any requests to vkm_mouse_scroll with VKM_MOUSE_SCROLL_LEFT or VKM_MOUSE_SCROLL_RIGHT will return VKM_ERROR_INVALID_PARAM. Defaults to false.
VKM_OPT_DEVICE_NAME	Set the virtual device name in the system. This option sets the name of the virtual input device in the system. If not set, the virtual device will have a name determined by the timestamp at which it was initialized. Only applicable on Linux.

Function Documentation

vkm_exit()

VKM_API void vkm_exit

(

vkm_context *

ctx

)

Exit the VKM library and free up any resources used.

This function calls vkm_reset, releases any resources allocated by vkm_init, and terminates the library. Using the freed context after this returns is invalid and can cause errors.

Parameters

[in]

ctx

Context pointer

vkm_feature_supported()

VKM_API bool vkm_feature_supported

(

vkm_feature

feat

)

Check if a particular feature is enabled on this platform.

Features may be limited on a per-platform basis.

Parameters

[in]

feat

Feature identifier

Returns

boolean indicating if feature is supported or not.

vkm_init()

VKM_API vkm_result vkm_init

(

vkm_context **

ctx

)

Initialize the VKM library.

This function initializes the VKM library, sets up any internal data structures to send input events, and returns a vkm_context pointer in the output parameter. All calls to VKM use the returned pointer to inject keyboard/mouse events.

Example

vkm_result rc;
vkm_context *ctx;
rc = vkm_init(&ctx);
if (rc != LIBX52_SUCCESS) {
    // Error handling omitted for brevity
}
// Save ctx for use later

Parameters

[out]

ctx

Pointer to a vkm_context *. This function will allocate a context and return the pointer to the context in this variable.

Returns

vkm_error_code indicating status

vkm_is_ready()

VKM_API bool vkm_is_ready

(

vkm_context *

ctx

)

check if VKM is started and ready

Parameters

[in]

ctx

Context pointer

Returns

boolean indicating if ready or not.

vkm_keyboard_send()

VKM_API vkm_result vkm_keyboard_send	(	vkm_context *	ctx,
		vkm_key	key,
		vkm_key_modifiers	modifiers,
		vkm_key_state	state
	)

Send a single keyboard event.

Send a single keyboard event to the OS. This will send a single key event, with modifiers enabled (Ctrl, Shift, Alt, GUI).

Parameters

[in]	ctx	Context pointer
[in]	key	Key identifier
[in]	modifiers	Modifier keys to enable (Ctrl, Shift, Alt, GUI)
[in]	state	Key state (press or release)

Returns

• VKM_SUCCESS on successful send
• VKM_ERROR_UNKNOWN on a generic error
• VKM_ERROR_INVALID_PARAM if parameters are invalid
• VKM_ERROR_NOT_SUPPORTED if the keyboard event is not enabled or supported on this platform
• VKM_ERROR_NOT_READY if VKM is not started

vkm_mouse_click()

VKM_API vkm_result vkm_mouse_click	(	vkm_context *	ctx,
		vkm_mouse_button	button,
		vkm_button_state	state
	)

Click the mouse button.

Send a mouse button event, this may be either a button down or button up event.

Parameters

[in]	ctx	Context pointer
[in]	button	Button identifier
[in]	state	Button state (press or release)

Returns

• VKM_SUCCESS on successful move
• VKM_ERROR_UNKNOWN on a generic error
• VKM_ERROR_NOT_SUPPORTED if the mouse button click is not supported on this platform
• VKM_ERROR_NOT_READY if VKM is not started

vkm_mouse_move()

VKM_API vkm_result vkm_mouse_move	(	vkm_context *	ctx,
		int	dx,
		int	dy
	)

Move the mouse by the specified amount.

The move mouse takes in a delta of x and y coordinates that tell the system to move the mouse by those relative numbers.

Parameters

[in]	ctx	Context pointer
[in]	dx	Delta by which to move the mouse in the horizontal axis
[in]	dy	Delta by which to move the mouse in the vertical axis

Returns

• VKM_SUCCESS on successful move
• VKM_ERROR_UNKNOWN on a generic error
• VKM_ERROR_NOT_SUPPORTED if the mouse move is not supported on this platform
• VKM_ERROR_NOT_READY if VKM is not started

vkm_mouse_scroll()

VKM_API vkm_result vkm_mouse_scroll	(	vkm_context *	ctx,
		vkm_mouse_scroll_direction	dir
	)

Scroll the mouse wheel.

Send a single scroll event to the mouse wheel (one detent in the chosen direction). If VKM_OPT_HI_RES_SCROLL was enabled before vkm_start, also emits REL_WHEEL_HI_RES / REL_HWHEEL_HI_RES using the standard 120 units per detent scale before the corresponding discrete REL_WHEEL / REL_HWHEEL event.

Parameters

[in]	ctx	Context pointer
[in]	dir	Scroll direction

Returns

• VKM_SUCCESS on successful move
• VKM_ERROR_UNKNOWN on a generic error
• VKM_ERROR_INVALID_PARAM if horizontal scrolling is not enabled and dir is VKM_MOUSE_SCROLL_LEFT or VKM_MOUSE_SCROLL_RIGHT
• VKM_ERROR_NOT_SUPPORTED if the mouse scrolling is not supported on this platform
• VKM_ERROR_NOT_READY if VKM is not started

vkm_platform_supported()

VKM_API bool vkm_platform_supported

(

void

)

Check if VKM is supported on this platform.

On some platforms, there is no support yet for the virtual keyboard/mouse. This function will return a boolean indicating if it is supported or not.

Returns

boolean indicating support.

vkm_reset()

VKM_API vkm_result vkm_reset

(

vkm_context *

ctx

)

Release all virtual keys and mouse buttons that are still down.

Synthesizes release events for any keys pressed through vkm_keyboard_send, clears the logical modifier mask from that API, and releases mouse buttons that are still pressed. Internal bookkeeping is cleared even if the virtual device is not ready (no events are written until vkm_start succeeds).

vkm_exit calls this automatically before freeing the context.

Parameters

[in]

ctx

Context pointer

Returns

• VKM_SUCCESS on success or if there was nothing to release
• VKM_ERROR_INVALID_PARAM on bad pointer
• VKM_ERROR_EVENT if writing a release event failed

vkm_set_option()

VKM_API vkm_result vkm_set_option	(	vkm_context *	ctx,
		vkm_option	option,
			...
	)

Set an option flag for VKM.

Option flags control the behavior of VKM. All options must be set before calling vkm_start.

Parameters

[in]	ctx	Context pointer
[in]	option	Which option to set
[in]	...	Any required arguments for the specified option

Returns

• VKM_SUCCESS on success
• VKM_ERROR_INVALID_PARAM if the option or arguments are invalid
• VKM_ERROR_NOT_SUPPORTED if the option is valid but not supported on this platform

vkm_start()

VKM_API vkm_result vkm_start

(

vkm_context *

ctx

)

Start any virtual keyboard/mouse devices on the platform.

This must be done before injecting any events, and after setting all options through vkm_set_option.

Parameters

[in]

ctx

Context pointer

Returns

• VKM_SUCCESS on successful start
• VKM_ERROR_INVALID_PARAM on bad pointer
• VKM_ERROR_UNKNOWN on other errors

vkm_strerror()

VKM_API const char * vkm_strerror

(

vkm_result

code

)

Return a short description for a vkm_result / vkm_error_code value.

The returned pointer refers to static storage and must not be freed. For unrecognized codes, the same static buffer may be overwritten by a later call.

When native language support (NLS) is enabled at build time, these messages are translated like libx52_strerror. Bind the libx52 text domain and set LC_MESSAGES as for other libx52 components.

Parameters

[in]

code

Value returned from a VKM API function

Returns

Pointer to a NUL-terminated description string

vkm_sync()

VKM_API vkm_result vkm_sync

(

vkm_context *

ctx

)

Send a sync packet to the OS.

On some platforms, a sync packet is necessary for the previously injected events to actually get reflected in the system. For platforms where this is not needed, this is a noop.

Parameters

[in]

ctx

Context pointer

Returns

• VKM_SUCCESS on successful move
• VKM_ERROR_UNKNOWN on a generic error
• VKM_ERROR_INVALID_PARAM if parameters are invalid
• VKM_ERROR_NOT_READY if VKM is not started