github.com/rajveermalviya/gamen@v0.1.2-0.20220930195403-9be15877c1aa/internal/wayland/wayland-util.h (about)

     1  //go:build linux && !android
     2  /*
     3   * Copyright © 2008 Kristian Høgsberg
     4   *
     5   * Permission is hereby granted, free of charge, to any person obtaining
     6   * a copy of this software and associated documentation files (the
     7   * "Software"), to deal in the Software without restriction, including
     8   * without limitation the rights to use, copy, modify, merge, publish,
     9   * distribute, sublicense, and/or sell copies of the Software, and to
    10   * permit persons to whom the Software is furnished to do so, subject to
    11   * the following conditions:
    12   *
    13   * The above copyright notice and this permission notice (including the
    14   * next paragraph) shall be included in all copies or substantial
    15   * portions of the Software.
    16   *
    17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    18   * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    20   * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
    21   * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
    22   * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
    23   * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    24   * SOFTWARE.
    25   */
    26  
    27  /** \file wayland-util.h
    28   *
    29   * \brief Utility classes, functions, and macros.
    30   */
    31  
    32  #ifndef WAYLAND_UTIL_H
    33  #define WAYLAND_UTIL_H
    34  
    35  #include <math.h>
    36  #include <stddef.h>
    37  #include <inttypes.h>
    38  #include <stdarg.h>
    39  
    40  #ifdef  __cplusplus
    41  extern "C" {
    42  #endif
    43  
    44  /** Visibility attribute */
    45  #if defined(__GNUC__) && __GNUC__ >= 4
    46  #define WL_EXPORT __attribute__ ((visibility("default")))
    47  #else
    48  #define WL_EXPORT
    49  #endif
    50  
    51  /** Deprecated attribute */
    52  #if defined(__GNUC__) && __GNUC__ >= 4
    53  #define WL_DEPRECATED __attribute__ ((deprecated))
    54  #else
    55  #define WL_DEPRECATED
    56  #endif
    57  
    58  /**
    59   * Printf-style argument attribute
    60   *
    61   * \param x Ordinality of the format string argument
    62   * \param y Ordinality of the argument to check against the format string
    63   *
    64   * \sa https://gcc.gnu.org/onlinedocs/gcc-3.2.1/gcc/Function-Attributes.html
    65   */
    66  #if defined(__GNUC__) && __GNUC__ >= 4
    67  #define WL_PRINTF(x, y) __attribute__((__format__(__printf__, x, y)))
    68  #else
    69  #define WL_PRINTF(x, y)
    70  #endif
    71  
    72  /** \class wl_object
    73   *
    74   * \brief A protocol object.
    75   *
    76   * A `wl_object` is an opaque struct identifying the protocol object
    77   * underlying a `wl_proxy` or `wl_resource`.
    78   *
    79   * \note Functions accessing a `wl_object` are not normally used by client code.
    80   * Clients should normally use the higher level interface generated by the
    81   * scanner to interact with compositor objects.
    82   *
    83   */
    84  struct wl_object;
    85  
    86  /**
    87   * Protocol message signature
    88   *
    89   * A wl_message describes the signature of an actual protocol message, such as a
    90   * request or event, that adheres to the Wayland protocol wire format. The
    91   * protocol implementation uses a wl_message within its demarshal machinery for
    92   * decoding messages between a compositor and its clients. In a sense, a
    93   * wl_message is to a protocol message like a class is to an object.
    94   *
    95   * The `name` of a wl_message is the name of the corresponding protocol message.
    96   *
    97   * The `signature` is an ordered list of symbols representing the data types
    98   * of message arguments and, optionally, a protocol version and indicators for
    99   * nullability. A leading integer in the `signature` indicates the _since_
   100   * version of the protocol message. A `?` preceding a data type symbol indicates
   101   * that the following argument type is nullable. While it is a protocol violation
   102   * to send messages with non-nullable arguments set to `NULL`, event handlers in
   103   * clients might still get called with non-nullable object arguments set to
   104   * `NULL`. This can happen when the client destroyed the object being used as
   105   * argument on its side and an event referencing that object was sent before the
   106   * server knew about its destruction. As this race cannot be prevented, clients
   107   * should - as a general rule - program their event handlers such that they can
   108   * handle object arguments declared non-nullable being `NULL` gracefully.
   109   *
   110   * When no arguments accompany a message, `signature` is an empty string.
   111   *
   112   * Symbols:
   113   *
   114   * * `i`: int
   115   * * `u`: uint
   116   * * `f`: fixed
   117   * * `s`: string
   118   * * `o`: object
   119   * * `n`: new_id
   120   * * `a`: array
   121   * * `h`: fd
   122   * * `?`: following argument is nullable
   123   *
   124   * While demarshaling primitive arguments is straightforward, when demarshaling
   125   * messages containing `object` or `new_id` arguments, the protocol
   126   * implementation often must determine the type of the object. The `types` of a
   127   * wl_message is an array of wl_interface references that correspond to `o` and
   128   * `n` arguments in `signature`, with `NULL` placeholders for arguments with
   129   * non-object types.
   130   *
   131   * Consider the protocol event wl_display `delete_id` that has a single `uint`
   132   * argument. The wl_message is:
   133   *
   134   * \code
   135   * { "delete_id", "u", [NULL] }
   136   * \endcode
   137   *
   138   * Here, the message `name` is `"delete_id"`, the `signature` is `"u"`, and the
   139   * argument `types` is `[NULL]`, indicating that the `uint` argument has no
   140   * corresponding wl_interface since it is a primitive argument.
   141   *
   142   * In contrast, consider a `wl_foo` interface supporting protocol request `bar`
   143   * that has existed since version 2, and has two arguments: a `uint` and an
   144   * object of type `wl_baz_interface` that may be `NULL`. Such a `wl_message`
   145   * might be:
   146   *
   147   * \code
   148   * { "bar", "2u?o", [NULL, &wl_baz_interface] }
   149   * \endcode
   150   *
   151   * Here, the message `name` is `"bar"`, and the `signature` is `"2u?o"`. Notice
   152   * how the `2` indicates the protocol version, the `u` indicates the first
   153   * argument type is `uint`, and the `?o` indicates that the second argument
   154   * is an object that may be `NULL`. Lastly, the argument `types` array indicates
   155   * that no wl_interface corresponds to the first argument, while the type
   156   * `wl_baz_interface` corresponds to the second argument.
   157   *
   158   * \sa wl_argument
   159   * \sa wl_interface
   160   * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Wire-Format">Wire Format</a>
   161   */
   162  struct wl_message {
   163  	/** Message name */
   164  	const char *name;
   165  	/** Message signature */
   166  	const char *signature;
   167  	/** Object argument interfaces */
   168  	const struct wl_interface **types;
   169  };
   170  
   171  /**
   172   * Protocol object interface
   173   *
   174   * A wl_interface describes the API of a protocol object defined in the Wayland
   175   * protocol specification. The protocol implementation uses a wl_interface
   176   * within its marshalling machinery for encoding client requests.
   177   *
   178   * The `name` of a wl_interface is the name of the corresponding protocol
   179   * interface, and `version` represents the version of the interface. The members
   180   * `method_count` and `event_count` represent the number of `methods` (requests)
   181   * and `events` in the respective wl_message members.
   182   *
   183   * For example, consider a protocol interface `foo`, marked as version `1`, with
   184   * two requests and one event.
   185   *
   186   * \code{.xml}
   187   * <interface name="foo" version="1">
   188   *   <request name="a"></request>
   189   *   <request name="b"></request>
   190   *   <event name="c"></event>
   191   * </interface>
   192   * \endcode
   193   *
   194   * Given two wl_message arrays `foo_requests` and `foo_events`, a wl_interface
   195   * for `foo` might be:
   196   *
   197   * \code
   198   * struct wl_interface foo_interface = {
   199   *         "foo", 1,
   200   *         2, foo_requests,
   201   *         1, foo_events
   202   * };
   203   * \endcode
   204   *
   205   * \note The server side of the protocol may define interface <em>implementation
   206   *       types</em> that incorporate the term `interface` in their name. Take
   207   *       care to not confuse these server-side `struct`s with a wl_interface
   208   *       variable whose name also ends in `interface`. For example, while the
   209   *       server may define a type `struct wl_foo_interface`, the client may
   210   *       define a `struct wl_interface wl_foo_interface`.
   211   *
   212   * \sa wl_message
   213   * \sa wl_proxy
   214   * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Interfaces">Interfaces</a>
   215   * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning">Versioning</a>
   216   */
   217  struct wl_interface {
   218  	/** Interface name */
   219  	const char *name;
   220  	/** Interface version */
   221  	int version;
   222  	/** Number of methods (requests) */
   223  	int method_count;
   224  	/** Method (request) signatures */
   225  	const struct wl_message *methods;
   226  	/** Number of events */
   227  	int event_count;
   228  	/** Event signatures */
   229  	const struct wl_message *events;
   230  };
   231  
   232  /** \class wl_list
   233   *
   234   * \brief Doubly-linked list
   235   *
   236   * On its own, an instance of `struct wl_list` represents the sentinel head of
   237   * a doubly-linked list, and must be initialized using wl_list_init().
   238   * When empty, the list head's `next` and `prev` members point to the list head
   239   * itself, otherwise `next` references the first element in the list, and `prev`
   240   * refers to the last element in the list.
   241   *
   242   * Use the `struct wl_list` type to represent both the list head and the links
   243   * between elements within the list. Use wl_list_empty() to determine if the
   244   * list is empty in O(1).
   245   *
   246   * All elements in the list must be of the same type. The element type must have
   247   * a `struct wl_list` member, often named `link` by convention. Prior to
   248   * insertion, there is no need to initialize an element's `link` - invoking
   249   * wl_list_init() on an individual list element's `struct wl_list` member is
   250   * unnecessary if the very next operation is wl_list_insert(). However, a
   251   * common idiom is to initialize an element's `link` prior to removal - ensure
   252   * safety by invoking wl_list_init() before wl_list_remove().
   253   *
   254   * Consider a list reference `struct wl_list foo_list`, an element type as
   255   * `struct element`, and an element's link member as `struct wl_list link`.
   256   *
   257   * The following code initializes a list and adds three elements to it.
   258   *
   259   * \code
   260   * struct wl_list foo_list;
   261   *
   262   * struct element {
   263   *         int foo;
   264   *         struct wl_list link;
   265   * };
   266   * struct element e1, e2, e3;
   267   *
   268   * wl_list_init(&foo_list);
   269   * wl_list_insert(&foo_list, &e1.link);   // e1 is the first element
   270   * wl_list_insert(&foo_list, &e2.link);   // e2 is now the first element
   271   * wl_list_insert(&e2.link, &e3.link); // insert e3 after e2
   272   * \endcode
   273   *
   274   * The list now looks like <em>[e2, e3, e1]</em>.
   275   *
   276   * The `wl_list` API provides some iterator macros. For example, to iterate
   277   * a list in ascending order:
   278   *
   279   * \code
   280   * struct element *e;
   281   * wl_list_for_each(e, foo_list, link) {
   282   *         do_something_with_element(e);
   283   * }
   284   * \endcode
   285   *
   286   * See the documentation of each iterator for details.
   287   * \sa http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/linux/list.h
   288   */
   289  struct wl_list {
   290  	/** Previous list element */
   291  	struct wl_list *prev;
   292  	/** Next list element */
   293  	struct wl_list *next;
   294  };
   295  
   296  /**
   297   * Initializes the list.
   298   *
   299   * \param list List to initialize
   300   *
   301   * \memberof wl_list
   302   */
   303  void
   304  wl_list_init(struct wl_list *list);
   305  
   306  /**
   307   * Inserts an element into the list, after the element represented by \p list.
   308   * When \p list is a reference to the list itself (the head), set the containing
   309   * struct of \p elm as the first element in the list.
   310   *
   311   * \note If \p elm is already part of a list, inserting it again will lead to
   312   *       list corruption.
   313   *
   314   * \param list List element after which the new element is inserted
   315   * \param elm Link of the containing struct to insert into the list
   316   *
   317   * \memberof wl_list
   318   */
   319  void
   320  wl_list_insert(struct wl_list *list, struct wl_list *elm);
   321  
   322  /**
   323   * Removes an element from the list.
   324   *
   325   * \note This operation leaves \p elm in an invalid state.
   326   *
   327   * \param elm Link of the containing struct to remove from the list
   328   *
   329   * \memberof wl_list
   330   */
   331  void
   332  wl_list_remove(struct wl_list *elm);
   333  
   334  /**
   335   * Determines the length of the list.
   336   *
   337   * \note This is an O(n) operation.
   338   *
   339   * \param list List whose length is to be determined
   340   *
   341   * \return Number of elements in the list
   342   *
   343   * \memberof wl_list
   344   */
   345  int
   346  wl_list_length(const struct wl_list *list);
   347  
   348  /**
   349   * Determines if the list is empty.
   350   *
   351   * \param list List whose emptiness is to be determined
   352   *
   353   * \return 1 if empty, or 0 if not empty
   354   *
   355   * \memberof wl_list
   356   */
   357  int
   358  wl_list_empty(const struct wl_list *list);
   359  
   360  /**
   361   * Inserts all of the elements of one list into another, after the element
   362   * represented by \p list.
   363   *
   364   * \note This leaves \p other in an invalid state.
   365   *
   366   * \param list List element after which the other list elements will be inserted
   367   * \param other List of elements to insert
   368   *
   369   * \memberof wl_list
   370   */
   371  void
   372  wl_list_insert_list(struct wl_list *list, struct wl_list *other);
   373  
   374  /**
   375   * Retrieves a pointer to a containing struct, given a member name.
   376   *
   377   * This macro allows "conversion" from a pointer to a member to its containing
   378   * struct. This is useful if you have a contained item like a wl_list,
   379   * wl_listener, or wl_signal, provided via a callback or other means, and would
   380   * like to retrieve the struct that contains it.
   381   *
   382   * To demonstrate, the following example retrieves a pointer to
   383   * `example_container` given only its `destroy_listener` member:
   384   *
   385   * \code
   386   * struct example_container {
   387   *         struct wl_listener destroy_listener;
   388   *         // other members...
   389   * };
   390   *
   391   * void example_container_destroy(struct wl_listener *listener, void *data)
   392   * {
   393   *         struct example_container *ctr;
   394   *
   395   *         ctr = wl_container_of(listener, ctr, destroy_listener);
   396   *         // destroy ctr...
   397   * }
   398   * \endcode
   399   *
   400   * \note `sample` need not be a valid pointer. A null or uninitialised pointer
   401   *       is sufficient.
   402   *
   403   * \param ptr Valid pointer to the contained member
   404   * \param sample Pointer to a struct whose type contains \p ptr
   405   * \param member Named location of \p ptr within the \p sample type
   406   *
   407   * \return The container for the specified pointer
   408   */
   409  #define wl_container_of(ptr, sample, member)				\
   410  	(__typeof__(sample))((char *)(ptr) -				\
   411  			     offsetof(__typeof__(*sample), member))
   412  
   413  /**
   414   * Iterates over a list.
   415   *
   416   * This macro expresses a for-each iterator for wl_list. Given a list and
   417   * wl_list link member name (often named `link` by convention), this macro
   418   * assigns each element in the list to \p pos, which can then be referenced in
   419   * a trailing code block. For example, given a wl_list of `struct message`
   420   * elements:
   421   *
   422   * \code
   423   * struct message {
   424   *         char *contents;
   425   *         wl_list link;
   426   * };
   427   *
   428   * struct wl_list *message_list;
   429   * // Assume message_list now "contains" many messages
   430   *
   431   * struct message *m;
   432   * wl_list_for_each(m, message_list, link) {
   433   *         do_something_with_message(m);
   434   * }
   435   * \endcode
   436   *
   437   * \param pos Cursor that each list element will be assigned to
   438   * \param head Head of the list to iterate over
   439   * \param member Name of the link member within the element struct
   440   *
   441   * \relates wl_list
   442   */
   443  #define wl_list_for_each(pos, head, member)				\
   444  	for (pos = wl_container_of((head)->next, pos, member);	\
   445  	     &pos->member != (head);					\
   446  	     pos = wl_container_of(pos->member.next, pos, member))
   447  
   448  /**
   449   * Iterates over a list, safe against removal of the list element.
   450   *
   451   * \note Only removal of the current element, \p pos, is safe. Removing
   452   *       any other element during traversal may lead to a loop malfunction.
   453   *
   454   * \sa wl_list_for_each()
   455   *
   456   * \param pos Cursor that each list element will be assigned to
   457   * \param tmp Temporary pointer of the same type as \p pos
   458   * \param head Head of the list to iterate over
   459   * \param member Name of the link member within the element struct
   460   *
   461   * \relates wl_list
   462   */
   463  #define wl_list_for_each_safe(pos, tmp, head, member)			\
   464  	for (pos = wl_container_of((head)->next, pos, member),		\
   465  	     tmp = wl_container_of((pos)->member.next, tmp, member);	\
   466  	     &pos->member != (head);					\
   467  	     pos = tmp,							\
   468  	     tmp = wl_container_of(pos->member.next, tmp, member))
   469  
   470  /**
   471   * Iterates backwards over a list.
   472   *
   473   * \sa wl_list_for_each()
   474   *
   475   * \param pos Cursor that each list element will be assigned to
   476   * \param head Head of the list to iterate over
   477   * \param member Name of the link member within the element struct
   478   *
   479   * \relates wl_list
   480   */
   481  #define wl_list_for_each_reverse(pos, head, member)			\
   482  	for (pos = wl_container_of((head)->prev, pos, member);	\
   483  	     &pos->member != (head);					\
   484  	     pos = wl_container_of(pos->member.prev, pos, member))
   485  
   486  /**
   487   * Iterates backwards over a list, safe against removal of the list element.
   488   *
   489   * \note Only removal of the current element, \p pos, is safe. Removing
   490   *       any other element during traversal may lead to a loop malfunction.
   491   *
   492   * \sa wl_list_for_each()
   493   *
   494   * \param pos Cursor that each list element will be assigned to
   495   * \param tmp Temporary pointer of the same type as \p pos
   496   * \param head Head of the list to iterate over
   497   * \param member Name of the link member within the element struct
   498   *
   499   * \relates wl_list
   500   */
   501  #define wl_list_for_each_reverse_safe(pos, tmp, head, member)		\
   502  	for (pos = wl_container_of((head)->prev, pos, member),	\
   503  	     tmp = wl_container_of((pos)->member.prev, tmp, member);	\
   504  	     &pos->member != (head);					\
   505  	     pos = tmp,							\
   506  	     tmp = wl_container_of(pos->member.prev, tmp, member))
   507  
   508  /**
   509   * \class wl_array
   510   *
   511   * Dynamic array
   512   *
   513   * A wl_array is a dynamic array that can only grow until released. It is
   514   * intended for relatively small allocations whose size is variable or not known
   515   * in advance. While construction of a wl_array does not require all elements to
   516   * be of the same size, wl_array_for_each() does require all elements to have
   517   * the same type and size.
   518   *
   519   */
   520  struct wl_array {
   521  	/** Array size */
   522  	size_t size;
   523  	/** Allocated space */
   524  	size_t alloc;
   525  	/** Array data */
   526  	void *data;
   527  };
   528  
   529  /**
   530   * Initializes the array.
   531   *
   532   * \param array Array to initialize
   533   *
   534   * \memberof wl_array
   535   */
   536  void
   537  wl_array_init(struct wl_array *array);
   538  
   539  /**
   540   * Releases the array data.
   541   *
   542   * \note Leaves the array in an invalid state.
   543   *
   544   * \param array Array whose data is to be released
   545   *
   546   * \memberof wl_array
   547   */
   548  void
   549  wl_array_release(struct wl_array *array);
   550  
   551  /**
   552   * Increases the size of the array by \p size bytes.
   553   *
   554   * \param array Array whose size is to be increased
   555   * \param size Number of bytes to increase the size of the array by
   556   *
   557   * \return A pointer to the beginning of the newly appended space, or NULL when
   558   *         resizing fails.
   559   *
   560   * \memberof wl_array
   561   */
   562  void *
   563  wl_array_add(struct wl_array *array, size_t size);
   564  
   565  /**
   566   * Copies the contents of \p source to \p array.
   567   *
   568   * \param array Destination array to copy to
   569   * \param source Source array to copy from
   570   *
   571   * \return 0 on success, or -1 on failure
   572   *
   573   * \memberof wl_array
   574   */
   575  int
   576  wl_array_copy(struct wl_array *array, struct wl_array *source);
   577  
   578  /**
   579   * Iterates over an array.
   580   *
   581   * This macro expresses a for-each iterator for wl_array. It assigns each
   582   * element in the array to \p pos, which can then be referenced in a trailing
   583   * code block. \p pos must be a pointer to the array element type, and all
   584   * array elements must be of the same type and size.
   585   *
   586   * \param pos Cursor that each array element will be assigned to
   587   * \param array Array to iterate over
   588   *
   589   * \relates wl_array
   590   * \sa wl_list_for_each()
   591   */
   592  #define wl_array_for_each(pos, array)					\
   593  	for (pos = (array)->data;					\
   594  	     (const char *) pos < ((const char *) (array)->data + (array)->size); \
   595  	     (pos)++)
   596  
   597  /**
   598   * Fixed-point number
   599   *
   600   * A `wl_fixed_t` is a 24.8 signed fixed-point number with a sign bit, 23 bits
   601   * of integer precision and 8 bits of decimal precision. Consider `wl_fixed_t`
   602   * as an opaque struct with methods that facilitate conversion to and from
   603   * `double` and `int` types.
   604   */
   605  typedef int32_t wl_fixed_t;
   606  
   607  /**
   608   * Converts a fixed-point number to a floating-point number.
   609   *
   610   * \param f Fixed-point number to convert
   611   *
   612   * \return Floating-point representation of the fixed-point argument
   613   */
   614  static inline double
   615  wl_fixed_to_double(wl_fixed_t f)
   616  {
   617  	union {
   618  		double d;
   619  		int64_t i;
   620  	} u;
   621  
   622  	u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f;
   623  
   624  	return u.d - (3LL << 43);
   625  }
   626  
   627  /**
   628   * Converts a floating-point number to a fixed-point number.
   629   *
   630   * \param d Floating-point number to convert
   631   *
   632   * \return Fixed-point representation of the floating-point argument
   633   */
   634  static inline wl_fixed_t
   635  wl_fixed_from_double(double d)
   636  {
   637  	union {
   638  		double d;
   639  		int64_t i;
   640  	} u;
   641  
   642  	u.d = d + (3LL << (51 - 8));
   643  
   644  	return (wl_fixed_t)u.i;
   645  }
   646  
   647  /**
   648   * Converts a fixed-point number to an integer.
   649   *
   650   * \param f Fixed-point number to convert
   651   *
   652   * \return Integer component of the fixed-point argument
   653   */
   654  static inline int
   655  wl_fixed_to_int(wl_fixed_t f)
   656  {
   657  	return f / 256;
   658  }
   659  
   660  /**
   661   * Converts an integer to a fixed-point number.
   662   *
   663   * \param i Integer to convert
   664   *
   665   * \return Fixed-point representation of the integer argument
   666   */
   667  static inline wl_fixed_t
   668  wl_fixed_from_int(int i)
   669  {
   670  	return i * 256;
   671  }
   672  
   673  /**
   674   * Protocol message argument data types
   675   *
   676   * This union represents all of the argument types in the Wayland protocol wire
   677   * format. The protocol implementation uses wl_argument within its marshalling
   678   * machinery for dispatching messages between a client and a compositor.
   679   *
   680   * \sa wl_message
   681   * \sa wl_interface
   682   * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-wire-Format">Wire Format</a>
   683   */
   684  union wl_argument {
   685  	int32_t i;           /**< `int`    */
   686  	uint32_t u;          /**< `uint`   */
   687  	wl_fixed_t f;        /**< `fixed`  */
   688  	const char *s;       /**< `string` */
   689  	struct wl_object *o; /**< `object` */
   690  	uint32_t n;          /**< `new_id` */
   691  	struct wl_array *a;  /**< `array`  */
   692  	int32_t h;           /**< `fd`     */
   693  };
   694  
   695  /**
   696   * Dispatcher function type alias
   697   *
   698   * A dispatcher is a function that handles the emitting of callbacks in client
   699   * code. For programs directly using the C library, this is done by using
   700   * libffi to call function pointers. When binding to languages other than C,
   701   * dispatchers provide a way to abstract the function calling process to be
   702   * friendlier to other function calling systems.
   703   *
   704   * A dispatcher takes five arguments: The first is the dispatcher-specific
   705   * implementation associated with the target object. The second is the object
   706   * upon which the callback is being invoked (either wl_proxy or wl_resource).
   707   * The third and fourth arguments are the opcode and the wl_message
   708   * corresponding to the callback. The final argument is an array of arguments
   709   * received from the other process via the wire protocol.
   710   *
   711   * \param "const void *" Dispatcher-specific implementation data
   712   * \param "void *" Callback invocation target (wl_proxy or `wl_resource`)
   713   * \param uint32_t Callback opcode
   714   * \param "const struct wl_message *" Callback message signature
   715   * \param "union wl_argument *" Array of received arguments
   716   *
   717   * \return 0 on success, or -1 on failure
   718   */
   719  typedef int (*wl_dispatcher_func_t)(const void *, void *, uint32_t,
   720  				    const struct wl_message *,
   721  				    union wl_argument *);
   722  
   723  /**
   724   * Log function type alias
   725   *
   726   * The C implementation of the Wayland protocol abstracts the details of
   727   * logging. Users may customize the logging behavior, with a function conforming
   728   * to the `wl_log_func_t` type, via `wl_log_set_handler_client` and
   729   * `wl_log_set_handler_server`.
   730   *
   731   * A `wl_log_func_t` must conform to the expectations of `vprintf`, and
   732   * expects two arguments: a string to write and a corresponding variable
   733   * argument list. While the string to write may contain format specifiers and
   734   * use values in the variable argument list, the behavior of any `wl_log_func_t`
   735   * depends on the implementation.
   736   *
   737   * \note Take care to not confuse this with `wl_protocol_logger_func_t`, which
   738   *       is a specific server-side logger for requests and events.
   739   *
   740   * \param "const char *" String to write to the log, containing optional format
   741   *                       specifiers
   742   * \param "va_list" Variable argument list
   743   *
   744   * \sa wl_log_set_handler_client
   745   * \sa wl_log_set_handler_server
   746   */
   747  typedef void (*wl_log_func_t)(const char *, va_list) WL_PRINTF(1, 0);
   748  
   749  /**
   750   * Return value of an iterator function
   751   *
   752   * \sa wl_client_for_each_resource_iterator_func_t
   753   * \sa wl_client_for_each_resource
   754   */
   755  enum wl_iterator_result {
   756  	/** Stop the iteration */
   757  	WL_ITERATOR_STOP,
   758  	/** Continue the iteration */
   759  	WL_ITERATOR_CONTINUE
   760  };
   761  
   762  #ifdef  __cplusplus
   763  }
   764  #endif
   765  
   766  #endif