bionic (3) wl_message.3.gz

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.