wl_message(3) Wayland wl_message(3)
NAME
wl_message
SYNOPSIS
#include <wayland-util.h>
Data Fields
const char * name
const char * signature
const struct wl_interface ** types
Detailed Description
Protocol message signature
A wl_message describes the signature of an actual protocol message,
such as a request or event, that adheres to the Wayland protocol wire
format. The protocol implementation uses a wl_message within its
demarshal machinery for decoding messages between a compositor and its
clients. In a sense, a wl_message is to a protocol message like a class
is to an object.
The name of a wl_message is the name of the corresponding protocol
message.
The signature is an ordered list of symbols representing the data types
of message arguments and, optionally, a protocol version and indicators
for nullability. A leading integer in the signature indicates the since
version of the protocol message. A ? preceding a data type symbol
indicates that the following argument type is nullable. While it is a
protocol violation to send messages with non-nullable arguments set to
NULL, event handlers in clients might still get called with non-
nullable object arguments set to NULL. This can happen when the client
destroyed the object being used as argument on its side and an event
referencing that object was sent before the server knew about its
destruction. As this race cannot be prevented, clients should - as a
general rule - program their event handlers such that they can handle
object arguments declared non-nullable being NULL gracefully.
When no arguments accompany a message, signature is an empty string.
Symbols:
• i: int
• u: uint
• f: fixed
• s: string
• o: object
• n: new_id
• a: array
• h: fd
• ?: following argument is nullable
While demarshaling primitive arguments is straightforward, when
demarshaling messages containing object or new_id arguments, the
protocol implementation often must determine the type of the object.
The types of a wl_message is an array of wl_interface references that
correspond to o and n arguments in signature, with NULL placeholders
for arguments with non-object types.
Consider the protocol event wl_display delete_id that has a single uint
argument. The wl_message is:
{ "delete_id", "u", [NULL] }
Here, the message name is 'delete_id', the signature is 'u', and the
argument types is [NULL], indicating that the uint argument has no
corresponding wl_interface since it is a primitive argument.
In contrast, consider a wl_foo interface supporting protocol request
bar that has existed since version 2, and has two arguments: a uint and
an object of type wl_baz_interface that may be NULL. Such a wl_message
might be:
{ "bar", "2u?o", [NULL, &wl_baz_interface] }
Here, the message name is 'bar', and the signature is '2u?o'. Notice
how the 2 indicates the protocol version, the u indicates the first
argument type is uint, and the ?o indicates that the second argument is
an object that may be NULL. Lastly, the argument types array indicates
that no wl_interface corresponds to the first argument, while the type
wl_baz_interface corresponds to the second argument.
See also
wl_argument
wl_interface
Wire Format
Field Documentation
const char* wl_message::name
Message name
const char* wl_message::signature
Message signature
const struct wl_interface** wl_message::types
Object argument interfaces
Author
Generated automatically by Doxygen for Wayland from the source code.
Version 1.20.0 Wed Sep 14 2022 wl_message(3)
Generated by dwww version 1.14 on Fri Jan 24 06:13:10 CET 2025.