Keymap Serialization

Collaboration diagram for Keymap Serialization:

Modules
	Keymap formats

Data Structures
struct	xkb_keymap_serialize_config
struct	xkb_keymap_serialize_result

Macros
#define	XKB_KEYMAP_USE_ORIGINAL_FORMAT   ((enum xkb_keymap_format) -1)

Enumerations
enum	xkb_keymap_serialize_flags {   XKB_KEYMAP_SERIALIZE_NO_FLAGS = 0 ,   XKB_KEYMAP_SERIALIZE_PRETTY = (1 << 0) ,   XKB_KEYMAP_SERIALIZE_KEEP_UNUSED = (1 << 1) ,   XKB_KEYMAP_SERIALIZE_STRICT_MODE = (1 << 2) ,   XKB_KEYMAP_SERIALIZE_EXPLICIT_DEFAULT_VALUES = (1 << 3) ,   XKB_KEYMAP_SERIALIZE_EXPLICIT_VMODS = (1 << 4) ,   XKB_KEYMAP_SERIALIZE_EXPLICIT_KEY_VALUES = (1 << 5) }

Functions
XKB_EXPORT enum xkb_error_code	xkb_keymap::xkb_keymap_serialize (const struct xkb_keymap *keymap, const struct xkb_keymap_serialize_config *config, struct xkb_keymap_serialize_result *result)
XKB_EXPORT char *	xkb_keymap::xkb_keymap_get_as_string (struct xkb_keymap *keymap, enum xkb_keymap_format format)
XKB_EXPORT char *	xkb_keymap::xkb_keymap_get_as_string2 (struct xkb_keymap *keymap, enum xkb_keymap_format format, enum xkb_keymap_serialize_flags flags)

Detailed Description

Serializing keymaps.

Macro Definition Documentation

XKB_KEYMAP_USE_ORIGINAL_FORMAT

#define XKB_KEYMAP_USE_ORIGINAL_FORMAT   ((enum xkb_keymap_format) -1)

Get the keymap as a string in the format from which it was created.

See also

xkb_keymap::xkb_keymap_get_as_string()

Enumeration Type Documentation

xkb_keymap_serialize_flags

enum xkb_keymap_serialize_flags

Flags to control keymap serialization.

Since

1.12.0

Enumerator
XKB_KEYMAP_SERIALIZE_NO_FLAGS	Do not apply any flags. Since 1.12.0
XKB_KEYMAP_SERIALIZE_PRETTY	Enable pretty-printing. Since 1.12.0
XKB_KEYMAP_SERIALIZE_KEEP_UNUSED	Do not drop unused bits (key types, compatibility entries) Since 1.12.0
XKB_KEYMAP_SERIALIZE_STRICT_MODE	Make the serializer operate in strict mode. This is useful mainly for debugging. When this flag is set, the following will raise an error: Exceeded layout count for the corresponding format (see XKB_ERROR_LAYOUT_COUNT_LIMIT_EXCEEDED) Since 1.14.0
XKB_KEYMAP_SERIALIZE_EXPLICIT_DEFAULT_VALUES	Force default values to be explicit. This is useful mainly for debugging. Since 1.14.0
XKB_KEYMAP_SERIALIZE_EXPLICIT_VMODS	Force virtual modifier encoding to be explicit. This is useful mainly for debugging. Since 1.14.0
XKB_KEYMAP_SERIALIZE_EXPLICIT_KEY_VALUES	Force key values to be explicit. This is useful mainly for debugging, as it may increase considerably the size of the serialization. Since 1.14.0

Function Documentation

xkb_keymap_serialize()

XKB_EXPORT enum xkb_error_code xkb_keymap_serialize	(	const struct xkb_keymap *	keymap,
		const struct xkb_keymap_serialize_config *	config,
		struct xkb_keymap_serialize_result *	result
	)

Serialize a compiled keymap to a string.

On success, returns a newly allocated serialized keymap in `result->serialized`, together with additional metadata. It is suitable to use with xkb_keymap_new_from_string().

Use this function instead of xkb_keymap_get_as_string() or xkb_keymap_get_as_string2() when more control on serializing or its result is required.

Note

This function enables to serialize an X11-incompatible keymap with more than 4 layouts to an X11-compatible keymap with up to 4 layouts:

• set `config->format` to XKB_KEYMAP_FORMAT_TEXT_V1,
• set up to 4 bits in `config->layouts` to select a subset of layouts to serialized.

Parameters

[in]	keymap	The keymap to serialize.
[in]	config	Configuration guiding the serialization.
[in,out]	result	Result of the serialization.

Precondition

config must point to a zero-initialized struct with `size` set per Extensible structure ABI contract.

result must point to a zero-initialized struct with `size` set per Extensible structure ABI contract.

Invariant

The library writes only to fields of result that fall within `result->size`.

Postcondition

If the return value is XKB_SUCCESS, the caller is responsible for freeing `result->serialized`.

Otherwise, `result->serialized` is set to NULL and all fields of result beyond it are left unspecified.

Returns

XKB_SUCCESS on success; otherwise an error code. Possible errors are:

• Errors from ABI Version resolution.
• XKB_ERROR_ALLOCATION_FAILURE
• XKB_ERROR_UNSUPPORTED_KEYMAP_SERIALIZATION_FLAGS
• ::XKB_ERROR_UNSUPPORTED_KEYMAP_FORMAT
• XKB_ERROR_UNSUPPORTED_LAYOUT_INDEX
• XKB_ERROR_LAYOUT_COUNT_LIMIT_EXCEEDED

Since

1.14.0

xkb_keymap_get_as_string()

XKB_EXPORT char * xkb_keymap_get_as_string	(	struct xkb_keymap *	keymap,
		enum xkb_keymap_format	format
	)

Get the compiled keymap as a string.

Same as xkb_keymap::xkb_keymap_get_as_string2() using XKB_KEYMAP_SERIALIZE_NO_FLAGS.

See also

xkb_keymap::xkb_keymap_serialize()

xkb_keymap::xkb_keymap_get_as_string2()

Since

1.12.0: Drop unused types and compatibility entries and do not pretty-print.

xkb_keymap_get_as_string2()

XKB_EXPORT char * xkb_keymap_get_as_string2	(	struct xkb_keymap *	keymap,
		enum xkb_keymap_format	format,
		enum xkb_keymap_serialize_flags	flags
	)

Get the compiled keymap as a string.

Parameters

[in]	keymap	The keymap to get as a string.
[in]	format	The keymap format to use for the string. You can pass in the special value XKB_KEYMAP_USE_ORIGINAL_FORMAT to use the format from which the keymap was originally created. When used as an interchange format such as Wayland xkb_v1, the format should be explicit.
[in]	flags	Optional flags to control the serialization, or 0.

Returns

The keymap as a NULL-terminated string, or NULL if unsuccessful.

The returned string may be fed back into xkb_keymap_new_from_string() to get the exact same keymap (possibly in another process, etc.).

The returned string is dynamically allocated and should be freed by the caller.

See also

xkb_keymap_serialize()

xkb_keymap_get_as_string()

xkb_keymap_new_from_string()

Since

1.12.0