wl_message - Man Page
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
: intu
: uintf
: fixeds
: stringo
: objectn
: new_ida
: arrayh
: 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.