[PATCH wayland] util: Document wl_message

[Peter Hutterer]

On Thu, Oct 27, 2016 at 08:55:01AM -0700, Yong Bakos wrote:
> From: Yong Bakos <ybakos at humanoriented.com>
> 
> Signed-off-by: Yong Bakos <ybakos at humanoriented.com>

excellent, very informative!

Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>

Cheers,
   Peter

> ---
>  src/wayland-util.h | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 68 insertions(+)
> 
> diff --git a/src/wayland-util.h b/src/wayland-util.h
> index 7b280d1..4dba1ed 100644
> --- a/src/wayland-util.h
> +++ b/src/wayland-util.h
> @@ -68,9 +68,77 @@ extern "C" {
>  #define WL_PRINTF(x, y)
>  #endif
>  
> +/**
> + * 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. When no arguments accompany a
> + * message, `signature` is an empty string.
> + *
> + * * `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:
> + *
> + * \code
> + * { "delete_id", "u", [NULL] }
> + * \endcode
> + *
> + * 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:
> + *
> + * \code
> + * { "bar", "2u?o", [NULL, &wl_baz_interface] }
> + * \endcode
> + *
> + * 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.
> + *
> + * \sa wl_argument
> + * \sa wl_interface
> + * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Wire-Format">Wire Format</a>
> + */
>  struct wl_message {
> +	/** Message name */
>  	const char *name;
> +	/** Message signature */
>  	const char *signature;
> +	/** Object argument interfaces */
>  	const struct wl_interface **types;
>  };
>  
> -- 
> 2.7.2
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
>