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 (o or s) 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.22.0                               Mon Apr 8 2024 16:21:56                               wl_message(3)