Appendix C. Server API
Prev |  |

# Appendix C. Server API

## Introduction

The open-source reference implementation of Wayland protocol is split in two C libraries, libwayland-client and libwayland-server. Their main responsibility is to handle the Inter-process communication (IPC) with each other, therefore guaranteeing the protocol objects marshaling and messages synchronization.

The server library is designed to work much like libwayland-client, although it is considerably complicated due to the server needing to support multiple versions of the protocol. It is best to learn libwayland-client first.

Each open socket to a client is represented by a wl_client. The equivalent of the wl_proxy that libwayland-client uses to represent an object is wl_resource for client-created objects, and wl_global for objects created by the server.

Often a server is also a client for another Wayland server, and thus must link with both libwayland-client and libwayland-server. This produces some type name conflicts (such as the client wl_display and server wl_display, but the duplicate-but-not-the-same types are opaque, and accessed only inside the correct library where it came from. Naturally that means that the program writer needs to always know if a pointer to a wl_display is for the server or client side and use the corresponding functions.

## wl_argument - Protocol message argument data types.

This union represents all of the argument types in the Wayland protocol wire format. The protocol implementation uses wl_argument within its marshalling machinery for dispatching messages between a client and a compositor.

See also: wl_message See also: wl_interface See also: Wire Format

i - int

      int32_t wl_argument::i

u - uint

      uint32_t wl_argument::u

f - fixed

      wl_fixed_t wl_argument::f

s - string

      const char* wl_argument::s

o - object

      struct wl_object* wl_argument::o

n - new_id

      uint32_t wl_argument::n

a - array

      struct wl_array* wl_argument::a

h - fd

      int32_t wl_argument::h

## wl_array - Dynamic array.

A wl_array is a dynamic array that can only grow until released. It is intended for relatively small allocations whose size is variable or not known in advance. While construction of a wl_array does not require all elements to be of the same size, wl_array_for_each() does require all elements to have the same type and size.

size - Array size.

      size_t wl_array::size

alloc - Allocated space.

      size_t wl_array::alloc

data - Array data.

      void* wl_array::data

wl_array_init - Initializes the array.

      void wl_array_init(struct wl_array *array)

  array
    Array to initialize

wl_array_release - Releases the array data.

      void wl_array_release(struct wl_array *array)

  Note: Leaves the array in an invalid state.

  array
    Array whose data is to be released

wl_array_add - Increases the size of the array by size bytes.

      void * wl_array_add(struct wl_array *array, size_t size)

  array
    Array whose size is to be increased
  size
    Number of bytes to increase the size of the array by

  Returns:
    A pointer to the beginning of the newly appended space, or NULL when resizing fails.

wl_array_copy - Copies the contents of source to array.

      int wl_array_copy(struct wl_array *array, struct wl_array *source)

  array
    Destination array to copy to
  source
    Source array to copy from

  Returns:
    0 on success, or -1 on failure

wl_array_for_each - Iterates over an array.

  This macro expresses a for-each iterator for wl_array. It assigns each element in the array to pos, which can then be referenced in a trailing code block. pos must be a pointer to the array element type, and all array elements must be of the same type and size.

  pos
    Cursor that each array element will be assigned to
  array
    Array to iterate over

  See also: wl_list_for_each()

## wl_client

wl_client_flush - Flush pending events to the client.

      void wl_client_flush(struct wl_client *client)

  client
    The client object

  Events sent to clients are queued in a buffer and written to the socket later - typically when the compositor has handled all requests and goes back to block in the event loop. This function flushes all queued up events for a client immediately.

wl_client_get_display - Get the display object for the given client.

      struct wl_display * wl_client_get_display(struct wl_client *client)

  client
    The client object

  Returns:
    The display object the client is associated with.

wl_client_get_credentials - Return Unix credentials for the client.

      void wl_client_get_credentials(const struct wl_client *client, pid_t *pid, uid_t *uid, gid_t *gid)

  client
    The display object
  pid
    Returns the process ID
  uid
    Returns the user ID
  gid
    Returns the group ID

  This function returns the process ID, the user ID and the group ID for the given client. The credentials come from getsockopt() with SO_PEERCRED, on the client socket fd. All the pointers can be NULL, if the caller is not interested in a particular ID.

  Note, process IDs are subject to race conditions and are not a reliable way to identify a client.

  Be aware that for clients that a compositor forks and execs and then connects using socketpair(), this function will return the credentials for the compositor. The credentials for the socketpair are set at creation time in the compositor.

wl_client_get_fd - Get the file descriptor for the client.

      int wl_client_get_fd(struct wl_client *client)

  client
    The display object

  Returns:
    The file descriptor to use for the connection

  This function returns the file descriptor for the given client.

  Be sure to use the file descriptor from the client for inspection only. If the caller does anything to the file descriptor that changes its state, it will likely cause problems.

  See also wl_client_get_credentials(). It is recommended that you evaluate whether wl_client_get_credentials() can be applied to your use case instead of this function.

  If you would like to distinguish just between the client and the compositor itself from the client's request, it can be done by getting the client credentials and by checking the PID of the client and the compositor's PID. Regarding the case in which the socketpair() is being used, you need to be careful. Please note the documentation for wl_client_get_credentials().

  This function can be used for a compositor to validate a request from a client if there are additional information provided from the client's file descriptor. For instance, suppose you can get the security contexts from the client's file descriptor. The compositor can validate the client's request with the contexts and make a decision whether it permits or deny it.

wl_client_get_object - Look up an object in the client name space.

      struct wl_resource * wl_client_get_object(struct wl_client *client, uint32_t id)

  client
    The client object
  id
    The object id

  Returns:
    The object or NULL if there is not object for the given ID

  This looks up an object in the client object name space by its object ID.

wl_client_post_implementation_error - Report an internal server error.

      void wl_client_post_implementation_error(struct wl_client *client, char const *msg,...)

  client
    The client object
  msg
    A printf-style format string
  ...
    Format string arguments

  Report an unspecified internal implementation error and disconnect the client.

wl_client_add_destroy_listener - Add a listener to be called at the beginning of wl_client destruction.

      void wl_client_add_destroy_listener(struct wl_client *client, struct wl_listener *listener)

  The listener provided will be called when wl_client destroy has begun, before any of that client's resources have been destroyed.

  There is no requirement to remove the link of the wl_listener when the signal is emitted.

wl_client_add_destroy_late_listener - Add a listener to be called at the end of wl_client destruction.

      void wl_client_add_destroy_late_listener(struct wl_client *client, struct wl_listener *listener)

  The listener provided will be called when wl_client destroy is nearly complete, after all of that client's resources have been destroyed.

  There is no requirement to remove the link of the wl_listener when the signal is emitted.

  Since: 1.22.0

wl_client_get_link - Get the link by which a client is inserted in the client list.

      struct wl_list * wl_client_get_link(struct wl_client *client)

  client
    The client object

  See also: wl_client_for_each() See also: wl_display_get_client_list() See also: wl_client_from_link()

wl_client_from_link - Get a wl_client by its link.

      struct wl_client * wl_client_from_link(struct wl_list *link)

  link
    The link of a wl_client

  See also: wl_client_for_each() See also: wl_display_get_client_list() See also: wl_client_get_link()

wl_client_add_resource_created_listener - Add a listener for the client's resource creation signal.

      void wl_client_add_resource_created_listener(struct wl_client *client, struct wl_listener *listener)

  client
    The client object
  listener
    The listener to be added

  When a new resource is created for this client the listener will be notified, carrying the new resource as the data argument.

wl_client_for_each_resource - Iterate over all the resources of a client.

      void wl_client_for_each_resource(struct wl_client *client, wl_client_for_each_resource_iterator_func_t iterator, void *user_data)

  client
    The client object
  iterator
    The iterator function
  user_data
    The user data pointer

  The function pointed by iterator will be called for each resource owned by the client. The user_data will be passed as the second argument of the iterator function. If the iterator function returns WL_ITERATOR_CONTINUE the iteration will continue, if it returns WL_ITERATOR_STOP it will stop.

  Creating and destroying resources while iterating is safe, but new resources may or may not be picked up by the iterator.

  See also: wl_iterator_result

wl_client_set_max_buffer_size - Adjust the maximum size of the client connection buffers.

      void wl_client_set_max_buffer_size(struct wl_client *client, size_t max_buffer_size)

  client
    The client object
  max_buffer_size
    The maximum size of the connection buffers

  The actual size of the connection buffers is a power of two, the requested max_buffer_size is therefore rounded up to the nearest power of two value.

  Lowering the maximum size may not take effect immediately if the current content of the buffer does not fit within the new size limit.

  The minimum buffer size is 4096. The default buffers size can be set using wl_display_set_default_max_buffer_size().

  See also: wl_display_set_default_max_buffer_size() Since: 1.22.90

## wl_display

wl_client_create - Create a client for the given file descriptor.

      struct wl_client * wl_client_create(struct wl_display *display, int fd)

  display
    The display object
  fd
    The file descriptor for the socket to the client

  Returns:
    The new client object or NULL on failure.

  Given a file descriptor corresponding to one end of a socket, this function will create a wl_client struct and add the new client to the compositors client list. At that point, the client is initialized and ready to run, as if the client had connected to the servers listening socket. When the client eventually sends requests to the compositor, the wl_client argument to the request handler will be the wl_client returned from this function.

  The other end of the socket can be passed to wl_display_connect_to_fd() on the client side or used with the WAYLAND_SOCKET environment variable on the client side.

  Listeners added with wl_display_add_client_created_listener() will be notified by this function after the client is fully constructed.

  On failure this function sets errno accordingly and returns NULL.

  On success, the new client object takes the ownership of the file descriptor. On failure, the ownership of the socket endpoint file descriptor is unchanged, it is the responsibility of the caller to perform cleanup, e.g. call close().

wl_display_create - Create Wayland display object.

      struct wl_display * wl_display_create(void)

  Returns:
    The Wayland display object. Null if failed to create

  This creates the wl_display object.

wl_display_destroy - Destroy Wayland display object.

      void wl_display_destroy(struct wl_display *display)

  display
    The Wayland display object which should be destroyed.

  This function emits the wl_display destroy signal, releases all the sockets added to this display, free's all the globals associated with this display, free's memory of additional shared memory formats and destroy the display object.

  See also: wl_display_add_destroy_listener

wl_display_set_global_filter - Set a filter function for global objects.

      void wl_display_set_global_filter(struct wl_display *display, wl_display_global_filter_func_t filter, void *data)

  display
    The Wayland display object.
  filter
    The global filter function.
  data
    User data to be associated with the global filter.

  Set a filter for the wl_display to advertise or hide global objects to clients. The set filter will be used during wl_global advertisement to determine whether a global object should be advertised to a given client, and during wl_global binding to determine whether a given client should be allowed to bind to a global.

  Clients that try to bind to a global that was filtered out will have an error raised.

  Setting the filter NULL will result in all globals being advertised to all clients. The default is no filter.

  The filter should be installed before any client connects and should always take the same decision given a client and a global. Not doing so will result in inconsistent filtering and broken wl_registry event sequences.

wl_display_get_serial - Get the current serial number.

      uint32_t wl_display_get_serial(const struct wl_display *display)

  display
    The display object

  This function returns the most recent serial number, but does not increment it.

wl_display_next_serial - Get the next serial number.

      uint32_t wl_display_next_serial(struct wl_display *display)

  display
    The display object

  This function increments the display serial number and returns the new value.

wl_display_destroy_clients - Destroy all clients connected to the display.

      void wl_display_destroy_clients(struct wl_display *display)

  display
    The display object

  This function should be called right before wl_display_destroy() to ensure all client resources are closed properly. Destroying a client from within wl_display_destroy_clients() is safe, but creating one will leak resources and raise a warning.

wl_display_set_default_max_buffer_size - Sets the default maximum size for connection buffers of new clients.

      void wl_display_set_default_max_buffer_size(struct wl_display *display, size_t max_buffer_size)

  display
    The display object
  max_buffer_size
    The default maximum size of the connection buffers

  This function sets the default size of the internal connection buffers for new clients. It doesn't change the buffer size for existing wl_client.

  The connection buffer size of an existing wl_client can be adjusted using wl_client_set_max_buffer_size().

  The actual size of the connection buffers is a power of two, the requested max_buffer_size is therefore rounded up to the nearest power of two value.

  The minimum buffer size is 4096.

  See also: wl_client_set_max_buffer_size Since: 1.22.90

wl_display_add_socket_auto - Automatically pick a Wayland display socket for the clients to connect to.

      const char * wl_display_add_socket_auto(struct wl_display *display)

  display
    Wayland display to which the socket should be added.

  Returns:
    The socket name if success. NULL if failed.

  This adds a Unix socket to Wayland display which can be used by clients to connect to Wayland display. The name of the socket is chosen automatically as the first available name in the sequence "wayland-0", "wayland-1", "wayland-2", ..., "wayland-32".

  The string returned by this function is owned by the library and should not be freed.

  See also: wl_display_add_socket

wl_display_add_socket_fd - Add a socket with an existing fd to Wayland display for the clients to connect.

      int wl_display_add_socket_fd(struct wl_display *display, int sock_fd)

  display
    Wayland display to which the socket should be added.
  sock_fd
    The existing socket file descriptor to be used

  Returns:
    0 if success. -1 if failed.

  The existing socket fd must already be created, opened, and locked. The fd must be properly set to CLOEXEC and bound to a socket file with both bind() and listen() already called.

  On success, the socket fd ownership is transferred to libwayland: libwayland will close the socket when the display is destroyed.

wl_display_add_socket - Add a socket to Wayland display for the clients to connect.

      int wl_display_add_socket(struct wl_display *display, const char *name)

  display
    Wayland display to which the socket should be added.
  name
    Name of the Unix socket.

  Returns:
    0 if success. -1 if failed.

  This adds a Unix socket to Wayland display which can be used by clients to connect to Wayland display.

  If NULL is passed as name, then it would look for WAYLAND_DISPLAY env variable for the socket name. If WAYLAND_DISPLAY is not set, then default wayland-0 is used.

  If the socket name is a relative path, the Unix socket will be created in the directory pointed to by environment variable XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is invalid or not set, then this function fails and returns -1.

  If the socket name is an absolute path, then it is used as-is for the the Unix socket.

  The length of the computed socket path must not exceed the maximum length of a Unix socket path. The function also fails if the user does not have write permission in the directory or if the path is already in use.

wl_display_add_protocol_logger - Adds a new protocol logger.

      struct wl_protocol_logger * wl_display_add_protocol_logger(struct wl_display *display, wl_protocol_logger_func_t func, void *user_data)

  When a new protocol message arrives or is sent from the server all the protocol logger functions will be called, carrying the user_data pointer, the type of the message (request or event) and the actual message. The lifetime of the messages passed to the logger function ends when they return so the messages cannot be stored and accessed later.

  errno is set on error.

  display
    The display object
  func
    The function to call to log a new protocol message
  user_data
    The user data pointer to pass to func

  Returns:
    The protocol logger object on success, NULL on failure.

  See also: wl_protocol_logger_destroy

wl_display_add_shm_format - Add support for a wl_shm pixel format.

      uint32_t * wl_display_add_shm_format(struct wl_display *display, uint32_t format)

  display
    The display object
  format
    The wl_shm pixel format to advertise

  Returns:
    A pointer to the wl_shm format that was added to the list or NULL if adding it to the list failed.

  Add the specified wl_shm format to the list of formats the wl_shm object advertises when a client binds to it. Adding a format to the list means that clients will know that the compositor supports this format and may use it for creating wl_shm buffers. The compositor must be able to handle the pixel format when a client requests it.

  The compositor by default supports WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888.

wl_display_get_client_list - Get the list of currently connected clients.

      struct wl_list * wl_display_get_client_list(struct wl_display *display)

  display
    The display object

  This function returns a pointer to the list of clients currently connected to the display. You can iterate on the list by using the wl_client_for_each macro. The returned value is valid for the lifetime of the display. You must not modify the returned list, but only access it.

  See also: wl_client_for_each() See also: wl_client_get_link() See also: wl_client_from_link()

## wl_event_loop - An event loop context.

Usually you create an event loop context, add sources to it, and call wl_event_loop_dispatch() in a loop to process events.

See also: wl_event_source

wl_event_loop_create - Create a new event loop context.

      struct wl_event_loop * wl_event_loop_create(void)

  Returns:
    A new event loop context object.

  This creates a new event loop context. Initially this context is empty. Event sources need to be explicitly added to it.

  Normally the event loop is run by calling wl_event_loop_dispatch() in a loop until the program terminates. Alternatively, an event loop can be embedded in another event loop by its file descriptor, see wl_event_loop_get_fd().

wl_event_loop_destroy - Destroy an event loop context.

      void wl_event_loop_destroy(struct wl_event_loop *loop)

  loop
    The event loop to be destroyed.

  This emits the event loop destroy signal, closes the event loop file descriptor, and frees loop.

  If the event loop has existing sources, those cannot be safely removed afterwards. Therefore one must call wl_event_source_remove() on all event sources before destroying the event loop context.

wl_event_loop_dispatch_idle - Dispatch the idle sources.

      void wl_event_loop_dispatch_idle(struct wl_event_loop *loop)

  loop
    The event loop whose idle sources are dispatched.

  See also: wl_event_loop_add_idle()

wl_event_loop_dispatch - Wait for events and dispatch them.

      int wl_event_loop_dispatch(struct wl_event_loop *loop, int timeout)

  loop
    The event loop whose sources to wait for.
  timeout
    The polling timeout in milliseconds.

  Returns:
    0 for success, -1 for polling (or timer update) error.

  All the associated event sources are polled. This function blocks until any event source delivers an event (idle sources excluded), or the timeout expires. A timeout of -1 disables the timeout, causing the function to block indefinitely. A timeout of zero causes the poll to always return immediately.

  All idle sources are dispatched before blocking. An idle source is destroyed when it is dispatched. After blocking, all other ready sources are dispatched. Then, idle sources are dispatched again, in case the dispatched events created idle sources. Finally, all sources marked with wl_event_source_check() are dispatched in a loop until their dispatch functions all return zero.

wl_event_loop_get_fd - Get the event loop file descriptor.

      int wl_event_loop_get_fd(struct wl_event_loop *loop)

  loop
    The event loop context.

  Returns:
    The aggregate file descriptor.

  This function returns the aggregate file descriptor, that represents all the event sources (idle sources excluded) associated with the given event loop context. When any event source makes an event available, it will be reflected in the aggregate file descriptor.

  When the aggregate file descriptor delivers an event, one can call wl_event_loop_dispatch() on the event loop context to dispatch all the available events.

wl_event_loop_add_destroy_listener - Register a destroy listener for an event loop context.

      void wl_event_loop_add_destroy_listener(struct wl_event_loop *loop, struct wl_listener *listener)

  loop
    The event loop context whose destruction to listen for.
  listener
    The listener with the callback to be called.

  See also: wl_listener

wl_event_loop_get_destroy_listener - Get the listener struct for the specified callback.

      struct wl_listener * wl_event_loop_get_destroy_listener(struct wl_event_loop *loop, wl_notify_func_t notify)

  loop
    The event loop context to inspect.
  notify
    The destroy callback to find.

  Returns:
    The wl_listener registered to the event loop context with the given callback pointer.

## wl_event_source - An abstract event source.

This is the generic type for fd, timer, signal, and idle sources. Functions that operate on specific source types must not be used with a different type, even if the function signature allows it.

wl_event_loop_fd_func_t - File descriptor dispatch function type.

      typedef int(* wl_event_loop_fd_func_t) (int fd, uint32_t mask, void *data))(int fd, uint32_t mask, void *data)

  Functions of this type are used as callbacks for file descriptor events.

  fd
    The file descriptor delivering the event.
  mask
    Describes the kind of the event as a bitwise-or of: WL_EVENT_READABLE, WL_EVENT_WRITABLE, WL_EVENT_HANGUP, WL_EVENT_ERROR.
  data
    The user data argument of the related wl_event_loop_add_fd() call.

  Returns:
    If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

  See also: wl_event_loop_add_fd()

wl_event_loop_timer_func_t - Timer dispatch function type.

      typedef int(* wl_event_loop_timer_func_t) (void *data))(void *data)

  Functions of this type are used as callbacks for timer expiry.

  data
    The user data argument of the related wl_event_loop_add_timer() call.

  Returns:
    If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

  See also: wl_event_loop_add_timer()

wl_event_loop_signal_func_t - Signal dispatch function type.

      typedef int(* wl_event_loop_signal_func_t) (int signal_number, void *data))(int signal_number, void *data)

  Functions of this type are used as callbacks for (POSIX) signals.

  signal_number
  data
    The user data argument of the related wl_event_loop_add_signal() call.

  Returns:
    If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

  See also: wl_event_loop_add_signal()

wl_event_loop_idle_func_t - Idle task function type.

      typedef void(* wl_event_loop_idle_func_t) (void *data))(void *data)

  Functions of this type are used as callbacks before blocking in wl_event_loop_dispatch().

  data
    The user data argument of the related wl_event_loop_add_idle() call.

  See also: wl_event_loop_add_idle() wl_event_loop_dispatch()

wl_event_loop_add_fd - Create a file descriptor event source.

      struct wl_event_source * wl_event_loop_add_fd(struct wl_event_loop *loop, int fd, uint32_t mask, wl_event_loop_fd_func_t func, void *data)

  loop
    The event loop that will process the new source.
  fd
    The file descriptor to watch.
  mask
    A bitwise-or of which events to watch for: WL_EVENT_READABLE, WL_EVENT_WRITABLE.
  func
    The file descriptor dispatch function.
  data
    User data.

  Returns:
    A new file descriptor event source.

  The given file descriptor is initially watched for the events given in mask. This can be changed as needed with wl_event_source_fd_update().

  If it is possible that program execution causes the file descriptor to be read while leaving the data in a buffer without actually processing it, it may be necessary to register the file descriptor source to be re-checked, see wl_event_source_check(). This will ensure that the dispatch function gets called even if the file descriptor is not readable or writable anymore. This is especially useful with IPC libraries that automatically buffer incoming data, possibly as a side-effect of other operations.

  See also: wl_event_loop_fd_func_t

wl_event_source_fd_update - Update a file descriptor source's event mask.

      int wl_event_source_fd_update(struct wl_event_source *source, uint32_t mask)

  source
    The file descriptor event source to update.
  mask
    The new mask, a bitwise-or of: WL_EVENT_READABLE, WL_EVENT_WRITABLE.

  Returns:
    0 on success, -1 on failure.

  This changes which events, readable and/or writable, cause the dispatch callback to be called on.

  File descriptors are usually writable to begin with, so they do not need to be polled for writable until a write actually fails. When a write fails, the event mask can be changed to poll for readable and writable, delivering a dispatch callback when it is possible to write more. Once all data has been written, the mask can be changed to poll only for readable to avoid busy-looping on dispatch.

  See also: wl_event_loop_add_fd()

wl_event_loop_add_timer - Create a timer event source.

      struct wl_event_source * wl_event_loop_add_timer(struct wl_event_loop *loop, wl_event_loop_timer_func_t func, void *data)

  loop
    The event loop that will process the new source.
  func
    The timer dispatch function.
  data
    User data.

  Returns:
    A new timer event source.

  The timer is initially disarmed. It needs to be armed with a call to wl_event_source_timer_update() before it can trigger a dispatch call.

  See also: wl_event_loop_timer_func_t

wl_event_source_timer_update - Arm or disarm a timer.

      int wl_event_source_timer_update(struct wl_event_source *source, int ms_delay)

  source
    The timer event source to modify.
  ms_delay
    The timeout in milliseconds.

  Returns:
    0 on success, -1 on failure.

  If the timeout is zero, the timer is disarmed.

  If the timeout is non-zero, the timer is set to expire after the given timeout in milliseconds. When the timer expires, the dispatch function set with wl_event_loop_add_timer() is called once from wl_event_loop_dispatch(). If another dispatch is desired after another expiry, wl_event_source_timer_update() needs to be called again.

wl_event_loop_add_signal - Create a POSIX signal event source.

      struct wl_event_source * wl_event_loop_add_signal(struct wl_event_loop *loop, int signal_number, wl_event_loop_signal_func_t func, void *data)

  loop
    The event loop that will process the new source.
  signal_number
    Number of the signal to watch for.
  func
    The signal dispatch function.
  data
    User data.

  Returns:
    A new signal event source.

  This function blocks the normal delivery of the given signal in the calling thread, and creates a "watch" for it. Signal delivery no longer happens asynchronously, but by wl_event_loop_dispatch() calling the dispatch callback function func.

  It is the caller's responsibility to ensure that all other threads have also blocked the signal.

  See also: wl_event_loop_signal_func_t

wl_event_loop_add_idle - Create an idle task.

      struct wl_event_source * wl_event_loop_add_idle(struct wl_event_loop *loop, wl_event_loop_idle_func_t func, void *data)

  loop
    The event loop that will process the new task.
  func
    The idle task dispatch function.
  data
    User data.

  Returns:
    A new idle task (an event source).

  Idle tasks are dispatched before wl_event_loop_dispatch() goes to sleep. See wl_event_loop_dispatch() for more details.

  Idle tasks fire once, and are automatically destroyed right after the callback function has been called.

  An idle task can be cancelled before the callback has been called by wl_event_source_remove(). Calling wl_event_source_remove() after or from within the callback results in undefined behaviour.

  See also: wl_event_loop_idle_func_t

wl_event_source_check - Mark event source to be re-checked.

      void wl_event_source_check(struct wl_event_source *source)

  source
    The event source to be re-checked.

  This function permanently marks the event source to be re-checked after the normal dispatch of sources in wl_event_loop_dispatch(). Re-checking will keep iterating over all such event sources until the dispatch function for them all returns zero.

  Re-checking is used on sources that may become ready to dispatch as a side-effect of dispatching themselves or other event sources, including idle sources. Re-checking ensures all the incoming events have been fully drained before wl_event_loop_dispatch() returns.

wl_event_source_remove - Remove an event source from its event loop.

      int wl_event_source_remove(struct wl_event_source *source)

  source
    The event source to be removed.

  Returns:
    Zero.

  The event source is removed from the event loop it was created for, and is effectively destroyed. This invalidates source . The dispatch function of the source will no longer be called through this source.

## wl_global

wl_global_get_name - Get the name of the global.

      uint32_t wl_global_get_name(const struct wl_global *global, const struct wl_client *client)

  global
    The global object.
  client
    Client for which to look up the global.

  Returns:
    The name of the global, or 0 if the global is not visible to the client.

  Since: 1.22

wl_global_get_version - Get the version of the given global.

      uint32_t wl_global_get_version(const struct wl_global *global)

  global
    The global object.

  Returns:
    The version advertised by the global.

  Since: 1.21

wl_global_get_display - Get the display object for the given global.

      struct wl_display * wl_global_get_display(const struct wl_global *global)

  global
    The global object

  Returns:
    The display object the global is associated with.

  Since: 1.20

## wl_interface - Protocol object interface.

A wl_interface describes the API of a protocol object defined in the Wayland protocol specification. The protocol implementation uses a wl_interface within its marshalling machinery for encoding client requests.

The name of a wl_interface is the name of the corresponding protocol interface, and version represents the version of the interface. The members method_count and event_count represent the number of methods (requests) and events in the respective wl_message members.

For example, consider a protocol interface foo, marked as version 1, with two requests and one event.

    <interface name="foo" version="1">
      <request name="a"></request>
      <request name="b"></request>
      <event name="c"></event>
    </interface>

Given two wl_message arrays foo_requests and foo_events, a wl_interface for foo might be:

    struct wl_interface foo_interface = {
            "foo", 1,
            2, foo_requests,
            1, foo_events
    };

Note: The server side of the protocol may define interface implementation types that incorporate the term interface in their name. Take care to not confuse these server-side structs with a wl_interface variable whose name also ends in interface. For example, while the server may define a type struct wl_foo_interface, the client may define a struct wl_interface wl_foo_interface. See also: wl_message See also: wl_proxy See also: Interfaces See also: Versioning

name - Interface name.

      const char* wl_interface::name

version - Interface version.

      int wl_interface::version

method_count - Number of methods (requests).

      int wl_interface::method_count

methods - Method (request) signatures.

      const struct wl_message* wl_interface::methods

event_count - Number of events.

      int wl_interface::event_count

events - Event signatures.

      const struct wl_message* wl_interface::events

## wl_list - Doubly-linked list.

On its own, an instance of struct wl_list represents the sentinel head of a doubly-linked list, and must be initialized using wl_list_init(). When empty, the list head's next and prev members point to the list head itself, otherwise next references the first element in the list, and prev refers to the last element in the list.

Use the struct wl_list type to represent both the list head and the links between elements within the list. Use wl_list_empty() to determine if the list is empty in O(1).

All elements in the list must be of the same type. The element type must have a struct wl_list member, often named link by convention. Prior to insertion, there is no need to initialize an element's link - invoking wl_list_init() on an individual list element's struct wl_list member is unnecessary if the very next operation is wl_list_insert(). However, a common idiom is to initialize an element's link prior to removal - ensure safety by invoking wl_list_init() before wl_list_remove().

Consider a list reference struct wl_list foo_list, an element type as struct element, and an element's link member as struct wl_list link.

The following code initializes a list and adds three elements to it.

    struct wl_list foo_list;

    struct element {
            int foo;
            struct wl_list link;
    };
    struct element e1, e2, e3;

    wl_list_init(&foo_list);
    wl_list_insert(&foo_list, &e1.link);   // e1 is the first element
    wl_list_insert(&foo_list, &e2.link);   // e2 is now the first element
    wl_list_insert(&e2.link, &e3.link); // insert e3 after e2

The list now looks like [e2, e3, e1].

The wl_list API provides some iterator macros. For example, to iterate a list in ascending order:

    struct element *e;
    wl_list_for_each(e, foo_list, link) {
            do_something_with_element(e);
    }

See the documentation of each iterator for details. See also: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/linux/list.h

prev - Previous list element.

      struct wl_list* wl_list::prev

next - Next list element.

      struct wl_list* wl_list::next

wl_list_init - Initializes the list.

      void wl_list_init(struct wl_list *list)

  list
    List to initialize

wl_list_insert - Inserts an element into the list, after the element represented by list.

      void wl_list_insert(struct wl_list *list, struct wl_list *elm)

  When list is a reference to the list itself (the head), set the containing struct of elm as the first element in the list.

  Note: If elm is already part of a list, inserting it again will lead to list corruption.

  list
    List element after which the new element is inserted
  elm
    Link of the containing struct to insert into the list

wl_list_remove - Removes an element from the list.

      void wl_list_remove(struct wl_list *elm)

  Note: This operation leaves elm in an invalid state.

  elm
    Link of the containing struct to remove from the list

wl_list_length - Determines the length of the list.

      int wl_list_length(const struct wl_list *list)

  Note: This is an O(n) operation.

  list
    List whose length is to be determined

  Returns:
    Number of elements in the list

wl_list_empty - Determines if the list is empty.

      int wl_list_empty(const struct wl_list *list)

  list
    List whose emptiness is to be determined

  Returns:
    1 if empty, or 0 if not empty

wl_list_insert_list - Inserts all of the elements of one list into another, after the element represented by list.

      void wl_list_insert_list(struct wl_list *list, struct wl_list *other)

  Note: This leaves other in an invalid state.

  list
    List element after which the other list elements will be inserted
  other
    List of elements to insert

wl_list_for_each - Iterates over a list.

  This macro expresses a for-each iterator for wl_list. Given a list and wl_list link member name (often named link by convention), this macro assigns each element in the list to pos, which can then be referenced in a trailing code block. For example, given a wl_list of struct message elements:

      struct message {
              char *contents;
              wl_list link;
      };

      struct wl_list *message_list;
      // Assume message_list now "contains" many messages

      struct message *m;
      wl_list_for_each(m, message_list, link) {
              do_something_with_message(m);
      }

  pos
    Cursor that each list element will be assigned to
  head
    Head of the list to iterate over
  member
    Name of the link member within the element struct

wl_list_for_each_safe - Iterates over a list, safe against removal of the list element.

  Note: Only removal of the current element, pos, is safe. Removing any other element during traversal may lead to a loop malfunction. See also: wl_list_for_each()

  pos
    Cursor that each list element will be assigned to
  tmp
    Temporary pointer of the same type as pos
  head
    Head of the list to iterate over
  member
    Name of the link member within the element struct

wl_list_for_each_reverse - Iterates backwards over a list.

  See also: wl_list_for_each()

  pos
    Cursor that each list element will be assigned to
  head
    Head of the list to iterate over
  member
    Name of the link member within the element struct

wl_list_for_each_reverse_safe - Iterates backwards over a list, safe against removal of the list element.

  Note: Only removal of the current element, pos, is safe. Removing any other element during traversal may lead to a loop malfunction. See also: wl_list_for_each()

  pos
    Cursor that each list element will be assigned to
  tmp
    Temporary pointer of the same type as pos
  head
    Head of the list to iterate over
  member
    Name of the link member within the element struct

## wl_listener - A single listener for Wayland signals.

wl_listener provides the means to listen for wl_signal notifications. Many Wayland objects use wl_listener for notification of significant events like object destruction.

Clients should create wl_listener objects manually and can register them as listeners to signals using wl_signal_add(), assuming the signal is directly accessible. For opaque structs like wl_event_loop, adding a listener should be done through provided accessor methods. A listener can only listen to one signal at a time.

    struct wl_listener your_listener;

    your_listener.notify = your_callback_method;

    // Direct access
    wl_signal_add(&some_object->destroy_signal, &your_listener);

    // Accessor access
    wl_event_loop *loop = ...;
    wl_event_loop_add_destroy_listener(loop, &your_listener);

If the listener is part of a larger struct, wl_container_of can be used to retrieve a pointer to it:

    void your_listener(struct wl_listener *listener, void *data)
    {
            struct your_data *data;

            your_data = wl_container_of(listener, data, your_member_name);
    }

If you need to remove a listener from a signal, use wl_list_remove().

    wl_list_remove(&your_listener.link);

See also: wl_signal

link - Part of wl_signal::listener_list.

      struct wl_list wl_listener::link

notify - Callback function pointer.

      wl_notify_func_t wl_listener::notify

## wl_message - 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 See also: wl_interface See also: Wire Format

name - Message name.

      const char* wl_message::name

signature - Message signature.

      const char* wl_message::signature

types - Object argument interfaces.

      const struct wl_interface** wl_message::types

## wl_object - A protocol object.

A wl_object is an opaque struct identifying the protocol object underlying a wl_proxy or wl_resource.

Note: Functions accessing a wl_object are not normally used by client code. Clients should normally use the higher level interface generated by the scanner to interact with compositor objects.

## wl_protocol_logger

wl_protocol_logger_destroy - Destroys a protocol logger.

      void wl_protocol_logger_destroy(struct wl_protocol_logger *logger)

  This function destroys a protocol logger and removes it from the display it was added to with wl_display_add_protocol_logger. The logger object becomes invalid after calling this function.

  See also: wl_display_add_protocol_logger

## wl_protocol_logger_message

## wl_resource

wl_resource_post_error_vargs - Post a protocol error.

      void wl_resource_post_error_vargs(struct wl_resource *resource, uint32_t code, const char *msg, va_list argp)

  resource
    The resource object
  code
    The error code
  msg
    The error message format string
  argp
    The format string argument list

wl_resource_post_error - Post a protocol error.

      void wl_resource_post_error(struct wl_resource *resource, uint32_t code, const char *msg,...)

  resource
    The resource object
  code
    The error code
  msg
    The error message format string
  ...
    The format string arguments

wl_resource_get_class - Retrieve the interface name (class) of a resource object.

      const char * wl_resource_get_class(const struct wl_resource *resource)

  resource
    The resource object

wl_resource_get_interface - Get the interface of a resource object.

      const struct wl_interface * wl_resource_get_interface(struct wl_resource *resource)

  resource
    The resource object

  Returns:
    The interface of the object associated with the resource

  Since: 1.24

wl_resource_create - Create a new resource object.

      struct wl_resource * wl_resource_create(struct wl_client *client, const struct wl_interface *interface, int version, uint32_t id)

  client
    The client owner of the new resource.
  interface
    The interface of the new resource.
  version
    The version of the new resource.
  id
    The id of the new resource. If 0, an available id will be used.

  Listeners added with wl_client_add_resource_created_listener will be notified at the end of this function.

## wl_resource_iterator_context

## wl_shm_buffer - A SHM buffer.

wl_shm_buffer provides a helper for accessing the contents of a wl_buffer resource created via the wl_shm interface.

A wl_shm_buffer becomes invalid as soon as its wl_resource is destroyed.

wl_shm_buffer_get_data - Get a pointer to the memory for the SHM buffer.

      void * wl_shm_buffer_get_data(struct wl_shm_buffer *buffer)

  buffer
    The buffer object

  Returns a pointer which can be used to read the data contained in the given SHM buffer.

  As this buffer is memory-mapped, reading from it may generate SIGBUS signals. This can happen if the client claims that the buffer is larger than it is or if something truncates the underlying file. To prevent this signal from causing the compositor to crash you should call wl_shm_buffer_begin_access() and wl_shm_buffer_end_access() around code that reads from the memory.

wl_shm_buffer_ref - Reference a shm_buffer.

      struct wl_shm_buffer * wl_shm_buffer_ref(struct wl_shm_buffer *buffer)

  buffer
    The buffer object

  Returns a pointer to the buffer and increases the refcount.

  The compositor must remember to call wl_shm_buffer_unref() when it no longer needs the reference to ensure proper destruction of the buffer.

  See also: wl_shm_buffer_unref

wl_shm_buffer_unref - Unreference a shm_buffer.

      void wl_shm_buffer_unref(struct wl_shm_buffer *buffer)

  buffer
    The buffer object

  Drops a reference to a buffer object.

  This is only necessary if the compositor has explicitly taken a reference with wl_shm_buffer_ref(), otherwise the buffer will be automatically destroyed when appropriate.

  See also: wl_shm_buffer_ref

wl_shm_buffer_ref_pool - Get a reference to a shm_buffer's shm_pool.

      struct wl_shm_pool * wl_shm_buffer_ref_pool(struct wl_shm_buffer *buffer)

  buffer
    The buffer object

  Returns a pointer to a buffer's shm_pool and increases the shm_pool refcount.

  The compositor must remember to call wl_shm_pool_unref() when it no longer needs the reference to ensure proper destruction of the pool.

  See also: wl_shm_pool_unref

wl_shm_buffer_begin_access - Mark that the given SHM buffer is about to be accessed.

      void wl_shm_buffer_begin_access(struct wl_shm_buffer *buffer)

  buffer
    The SHM buffer

  An SHM buffer is a memory-mapped file given by the client. According to POSIX, reading from a memory-mapped region that extends off the end of the file will cause a SIGBUS signal to be generated. Normally this would cause the compositor to terminate. In order to make the compositor robust against clients that change the size of the underlying file or lie about its size, you should protect access to the buffer by calling this function before reading from the memory and call wl_shm_buffer_end_access() afterwards. This will install a signal handler for SIGBUS which will prevent the compositor from crashing.

  After calling this function the signal handler will remain installed for the lifetime of the compositor process. Note that this function will not work properly if the compositor is also installing its own handler for SIGBUS.

  If a SIGBUS signal is received for an address within the range of the SHM pool of the given buffer then the client will be sent an error event when wl_shm_buffer_end_access() is called. If the signal is for an address outside that range then the signal handler will reraise the signal which would will likely cause the compositor to terminate.

  It is safe to nest calls to these functions as long as the nested calls are all accessing the same pool. The number of calls to wl_shm_buffer_end_access() must match the number of calls to wl_shm_buffer_begin_access(). These functions are thread-safe and it is allowed to simultaneously access different buffers or the same buffer from multiple threads.

wl_shm_buffer_end_access - Ends the access to a buffer started by wl_shm_buffer_begin_access().

      void wl_shm_buffer_end_access(struct wl_shm_buffer *buffer)

  buffer
    The SHM buffer

  This should be called after wl_shm_buffer_begin_access() once the buffer is no longer being accessed. If a SIGBUS signal was generated in-between these two calls then the resource for the given buffer will be sent an error.

## wl_shm_pool

wl_shm_pool_unref - Unreference a shm_pool.

      void wl_shm_pool_unref(struct wl_shm_pool *pool)

  pool
    The pool object

  Drops a reference to a wl_shm_pool object.

  This is only necessary if the compositor has explicitly taken a reference with wl_shm_buffer_ref_pool(), otherwise the pool will be automatically destroyed when appropriate.

  See also: wl_shm_buffer_ref_pool

## wl_shm_sigbus_data

## wl_signal - A source of a type of observable event.

Signals are recognized points where significant events can be observed. Compositors as well as the server can provide signals. Observers are wl_listener's that are added through wl_signal_add. Signals are emitted using wl_signal_emit, which will invoke all listeners until that listener is removed by wl_list_remove() (or whenever the signal is destroyed).

See also: wl_listener for more information on using wl_signal

wl_signal_emit_mutable - Emits this signal, notifying all registered listeners.

      void wl_signal_emit_mutable(struct wl_signal *signal, void *data)

  A safer version of wl_signal_emit() which can gracefully handle additions and deletions of any signal listener from within listener notification callbacks.

  Listeners deleted during a signal emission and which have not already been notified at the time of deletion are not notified by that emission.

  Listeners added (or readded) during signal emission are ignored by that emission.

  Note that repurposing a listener without explicitly removing it and readding it is not supported and can lead to unexpected behavior.

  signal
    The signal object that will emit the signal
  data
    The data that will be emitted with the signal

  Since: 1.20.90

wl_signal_init - Initialize a new wl_signal for use.

      static void wl_signal_init(struct wl_signal *signal)

  signal
    The signal that will be initialized

wl_signal_add - Add the specified listener to this signal.

      static void wl_signal_add(struct wl_signal *signal, struct wl_listener *listener)

  signal
    The signal that will emit events to the listener
  listener
    The listener to add

wl_signal_get - Gets the listener struct for the specified callback.

      static struct wl_listener * wl_signal_get(struct wl_signal *signal, wl_notify_func_t notify)

  signal
    The signal that contains the specified listener
  notify
    The listener that is the target of this search

  Returns:
    the list item that corresponds to the specified listener, or NULL if none was found

wl_signal_emit - Emits this signal, notifying all registered listeners.

      static void wl_signal_emit(struct wl_signal *signal, void *data)

  signal
    The signal object that will emit the signal
  data
    The data that will be emitted with the signal

## wl_socket

## Functions

wl_client_for_each - Iterate over a list of clients.

wl_display_global_filter_func_t - A filter function for wl_global objects.

      typedef bool(* wl_display_global_filter_func_t) (const struct wl_client *client, const struct wl_global *global, void *data))(const struct wl_client *client, const struct wl_global *global, void *data)

  client
    The client object
  global
    The global object to show or hide
  data
    The user data pointer

  A filter function enables the server to decide which globals to advertise to each client.

  When a wl_global filter is set, the given callback function will be called during wl_global advertisement and binding.

  This function should return true if the global object should be made visible to the client or false otherwise.

wl_client_for_each_resource_iterator_func_t - Callback function type for wl_client_for_each_resource().

      typedef enum wl_iterator_result(* wl_client_for_each_resource_iterator_func_t) (struct wl_resource *resource, void *user_data))(struct wl_resource *resource, void *user_data)

wl_protocol_logger_func_t - Callback function type for wl_display_add_protocol_logger().

      typedef void(* wl_protocol_logger_func_t) (void *user_data, enum wl_protocol_logger_type direction, const struct wl_protocol_logger_message *message))(void *user_data, enum wl_protocol_logger_type direction, const struct wl_protocol_logger_message *message)

wl_event_loop_create

      struct wl_event_loop * wl_event_loop_create(void)

wl_event_loop_destroy

      void wl_event_loop_destroy(struct wl_event_loop *loop)

wl_event_loop_add_fd

      struct wl_event_source * wl_event_loop_add_fd(struct wl_event_loop *loop, int fd, uint32_t mask, wl_event_loop_fd_func_t func, void *data)

wl_event_source_fd_update

      int wl_event_source_fd_update(struct wl_event_source *source, uint32_t mask)

wl_event_loop_add_timer

      struct wl_event_source * wl_event_loop_add_timer(struct wl_event_loop *loop, wl_event_loop_timer_func_t func, void *data)

wl_event_loop_add_signal

      struct wl_event_source * wl_event_loop_add_signal(struct wl_event_loop *loop, int signal_number, wl_event_loop_signal_func_t func, void *data)

wl_event_source_timer_update

      int wl_event_source_timer_update(struct wl_event_source *source, int ms_delay)

wl_event_source_remove

      int wl_event_source_remove(struct wl_event_source *source)

wl_event_source_check

      void wl_event_source_check(struct wl_event_source *source)

wl_event_loop_dispatch

      int wl_event_loop_dispatch(struct wl_event_loop *loop, int timeout)

wl_event_loop_dispatch_idle

      void wl_event_loop_dispatch_idle(struct wl_event_loop *loop)

wl_event_loop_add_idle

      struct wl_event_source * wl_event_loop_add_idle(struct wl_event_loop *loop, wl_event_loop_idle_func_t func, void *data)

wl_event_loop_get_fd

      int wl_event_loop_get_fd(struct wl_event_loop *loop)

wl_event_loop_add_destroy_listener

      void wl_event_loop_add_destroy_listener(struct wl_event_loop *loop, struct wl_listener *listener)

wl_event_loop_get_destroy_listener

      struct wl_listener * wl_event_loop_get_destroy_listener(struct wl_event_loop *loop, wl_notify_func_t notify)

wl_display_create

      struct wl_display * wl_display_create(void)

wl_display_destroy

      void wl_display_destroy(struct wl_display *display)

wl_display_get_event_loop

      struct wl_event_loop * wl_display_get_event_loop(struct wl_display *display)

wl_display_add_socket

      int wl_display_add_socket(struct wl_display *display, const char *name)

wl_display_add_socket_auto

      const char * wl_display_add_socket_auto(struct wl_display *display)

wl_display_add_socket_fd

      int wl_display_add_socket_fd(struct wl_display *display, int sock_fd)

wl_display_terminate

      void wl_display_terminate(struct wl_display *display)

wl_display_run

      void wl_display_run(struct wl_display *display)

wl_display_flush_clients

      void wl_display_flush_clients(struct wl_display *display)

wl_display_destroy_clients

      void wl_display_destroy_clients(struct wl_display *display)

wl_display_set_default_max_buffer_size

      void wl_display_set_default_max_buffer_size(struct wl_display *display, size_t max_buffer_size)

wl_display_get_serial

      uint32_t wl_display_get_serial(const struct wl_display *display)

wl_display_next_serial

      uint32_t wl_display_next_serial(struct wl_display *display)

wl_display_add_destroy_listener

      void wl_display_add_destroy_listener(struct wl_display *display, struct wl_listener *listener)

wl_display_add_client_created_listener - Registers a listener for the client connection signal.

      void wl_display_add_client_created_listener(struct wl_display *display, struct wl_listener *listener)

  When a new client object is created, listener will be notified, carrying a pointer to the new wl_client object.

  wl_client_create wl_display wl_listener

  display
    The display object
  listener
    Signal handler object

wl_display_get_destroy_listener

      struct wl_listener * wl_display_get_destroy_listener(struct wl_display *display, wl_notify_func_t notify)

wl_global_create

      struct wl_global * wl_global_create(struct wl_display *display, const struct wl_interface *interface, int version, void *data, wl_global_bind_func_t bind)

wl_global_remove - Remove the global.

      void wl_global_remove(struct wl_global *global)

  global
    The Wayland global.

  Broadcast a global remove event to all clients without destroying the global. This function can only be called once per global.

  wl_global_destroy() removes the global and immediately destroys it. On the other end, this function only removes the global, allowing clients that have not yet received the global remove event to continue to bind to it.

  This can be used by compositors to mitigate clients being disconnected because a global has been added and removed too quickly. Compositors can call wl_global_remove(), then wait an implementation-defined amount of time, then call wl_global_destroy(). Note that the destruction of a global is still racy, since clients have no way to acknowledge that they received the remove event.

  Since: 1.17.90

wl_global_destroy

      void wl_global_destroy(struct wl_global *global)

wl_display_set_global_filter

      void wl_display_set_global_filter(struct wl_display *display, wl_display_global_filter_func_t filter, void *data)

wl_global_get_interface

      const struct wl_interface * wl_global_get_interface(const struct wl_global *global)

wl_global_get_name

      uint32_t wl_global_get_name(const struct wl_global *global, const struct wl_client *client)

wl_global_get_version

      uint32_t wl_global_get_version(const struct wl_global *global)

wl_global_get_display

      struct wl_display * wl_global_get_display(const struct wl_global *global)

wl_global_get_user_data

      void * wl_global_get_user_data(const struct wl_global *global)

wl_global_set_user_data - Set the global's user data.

      void wl_global_set_user_data(struct wl_global *global, void *data)

  global
    The global object
  data
    The user data pointer

  Since: 1.17.90

wl_client_create

      struct wl_client * wl_client_create(struct wl_display *display, int fd)

wl_display_get_client_list

      struct wl_list * wl_display_get_client_list(struct wl_display *display)

wl_client_get_link

      struct wl_list * wl_client_get_link(struct wl_client *client)

wl_client_from_link

      struct wl_client * wl_client_from_link(struct wl_list *link)

wl_client_destroy

      void wl_client_destroy(struct wl_client *client)

wl_client_flush

      void wl_client_flush(struct wl_client *client)

wl_client_get_credentials

      void wl_client_get_credentials(const struct wl_client *client, pid_t *pid, uid_t *uid, gid_t *gid)

wl_client_get_fd

      int wl_client_get_fd(struct wl_client *client)

wl_client_add_destroy_listener

      void wl_client_add_destroy_listener(struct wl_client *client, struct wl_listener *listener)

wl_client_get_destroy_listener

      struct wl_listener * wl_client_get_destroy_listener(struct wl_client *client, wl_notify_func_t notify)

wl_client_add_destroy_late_listener

      void wl_client_add_destroy_late_listener(struct wl_client *client, struct wl_listener *listener)

wl_client_get_destroy_late_listener

      struct wl_listener * wl_client_get_destroy_late_listener(struct wl_client *client, wl_notify_func_t notify)

wl_client_get_object

      struct wl_resource * wl_client_get_object(struct wl_client *client, uint32_t id)

wl_client_post_no_memory

      void wl_client_post_no_memory(struct wl_client *client)

wl_client_post_implementation_error

      void wl_client_post_implementation_error(struct wl_client *client, const char *msg,...)

wl_client_add_resource_created_listener

      void wl_client_add_resource_created_listener(struct wl_client *client, struct wl_listener *listener)

wl_client_for_each_resource

      void wl_client_for_each_resource(struct wl_client *client, wl_client_for_each_resource_iterator_func_t iterator, void *user_data)

wl_client_set_user_data

      void wl_client_set_user_data(struct wl_client *client, void *data, wl_user_data_destroy_func_t dtor)

wl_client_get_user_data

      void * wl_client_get_user_data(struct wl_client *client)

wl_client_set_max_buffer_size

      void wl_client_set_max_buffer_size(struct wl_client *client, size_t max_buffer_size)

wl_signal_emit_mutable

      void wl_signal_emit_mutable(struct wl_signal *signal, void *data)

wl_resource_post_event

      void wl_resource_post_event(struct wl_resource *resource, uint32_t opcode,...)

wl_resource_post_event_array

      void wl_resource_post_event_array(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)

wl_resource_queue_event

      void wl_resource_queue_event(struct wl_resource *resource, uint32_t opcode,...)

wl_resource_queue_event_array

      void wl_resource_queue_event_array(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)

wl_resource_post_error_vargs

      void wl_resource_post_error_vargs(struct wl_resource *resource, uint32_t code, const char *msg, va_list argp)

wl_resource_post_error

      void wl_resource_post_error(struct wl_resource *resource, uint32_t code, const char *msg,...)

wl_resource_post_no_memory

      void wl_resource_post_no_memory(struct wl_resource *resource)

wl_client_get_display

      struct wl_display * wl_client_get_display(struct wl_client *client)

wl_resource_create

      struct wl_resource * wl_resource_create(struct wl_client *client, const struct wl_interface *interface, int version, uint32_t id)

wl_resource_set_implementation

      void wl_resource_set_implementation(struct wl_resource *resource, const void *implementation, void *data, wl_resource_destroy_func_t destroy)

wl_resource_set_dispatcher

      void wl_resource_set_dispatcher(struct wl_resource *resource, wl_dispatcher_func_t dispatcher, const void *implementation, void *data, wl_resource_destroy_func_t destroy)

wl_resource_destroy

      void wl_resource_destroy(struct wl_resource *resource)

wl_resource_get_id

      uint32_t wl_resource_get_id(const struct wl_resource *resource)

wl_resource_get_link

      struct wl_list * wl_resource_get_link(struct wl_resource *resource)

wl_resource_from_link

      struct wl_resource * wl_resource_from_link(struct wl_list *resource)

wl_resource_find_for_client

      struct wl_resource * wl_resource_find_for_client(struct wl_list *list, struct wl_client *client)

wl_resource_get_client

      struct wl_client * wl_resource_get_client(struct wl_resource *resource)

wl_resource_set_user_data

      void wl_resource_set_user_data(struct wl_resource *resource, void *data)

wl_resource_get_user_data

      void * wl_resource_get_user_data(struct wl_resource *resource)

wl_resource_get_version

      int wl_resource_get_version(const struct wl_resource *resource)

wl_resource_set_destructor

      void wl_resource_set_destructor(struct wl_resource *resource, wl_resource_destroy_func_t destroy)

wl_resource_instance_of

      int wl_resource_instance_of(struct wl_resource *resource, const struct wl_interface *interface, const void *implementation)

wl_resource_get_class

      const char * wl_resource_get_class(const struct wl_resource *resource)

wl_resource_get_interface

      const struct wl_interface * wl_resource_get_interface(struct wl_resource *resource)

wl_resource_add_destroy_listener

      void wl_resource_add_destroy_listener(struct wl_resource *resource, struct wl_listener *listener)

wl_resource_get_destroy_listener

      struct wl_listener * wl_resource_get_destroy_listener(struct wl_resource *resource, wl_notify_func_t notify)

wl_shm_buffer_get

      struct wl_shm_buffer * wl_shm_buffer_get(struct wl_resource *resource)

wl_shm_buffer_begin_access

      void wl_shm_buffer_begin_access(struct wl_shm_buffer *buffer)

wl_shm_buffer_end_access

      void wl_shm_buffer_end_access(struct wl_shm_buffer *buffer)

wl_shm_buffer_get_data

      void * wl_shm_buffer_get_data(struct wl_shm_buffer *buffer)

wl_shm_buffer_get_stride

      int32_t wl_shm_buffer_get_stride(const struct wl_shm_buffer *buffer)

wl_shm_buffer_get_format

      uint32_t wl_shm_buffer_get_format(const struct wl_shm_buffer *buffer)

wl_shm_buffer_get_width

      int32_t wl_shm_buffer_get_width(const struct wl_shm_buffer *buffer)

wl_shm_buffer_get_height

      int32_t wl_shm_buffer_get_height(const struct wl_shm_buffer *buffer)

wl_shm_buffer_ref

      struct wl_shm_buffer * wl_shm_buffer_ref(struct wl_shm_buffer *buffer)

wl_shm_buffer_unref

      void wl_shm_buffer_unref(struct wl_shm_buffer *buffer)

wl_shm_buffer_ref_pool

      struct wl_shm_pool * wl_shm_buffer_ref_pool(struct wl_shm_buffer *buffer)

wl_shm_pool_unref

      void wl_shm_pool_unref(struct wl_shm_pool *pool)

wl_display_init_shm

      int wl_display_init_shm(struct wl_display *display)

wl_display_add_shm_format

      uint32_t * wl_display_add_shm_format(struct wl_display *display, uint32_t format)

wl_shm_buffer_create

      WL_DEPRECATED struct wl_shm_buffer * wl_shm_buffer_create(struct wl_client *client, uint32_t id, int32_t width, int32_t height, int32_t stride, uint32_t format)

wl_log_set_handler_server

      void wl_log_set_handler_server(wl_log_func_t handler)

wl_display_add_protocol_logger

      struct wl_protocol_logger * wl_display_add_protocol_logger(struct wl_display *display, wl_protocol_logger_func_t, void *user_data)

wl_protocol_logger_destroy

      void wl_protocol_logger_destroy(struct wl_protocol_logger *logger)

wl_resource_post_event_array

      void wl_resource_post_event_array(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)

wl_resource_post_event

      void wl_resource_post_event(struct wl_resource *resource, uint32_t opcode,...)

wl_resource_queue_event_array

      void wl_resource_queue_event_array(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)

wl_resource_queue_event

      void wl_resource_queue_event(struct wl_resource *resource, uint32_t opcode,...)

wl_client_post_no_memory

      void wl_client_post_no_memory(struct wl_client *client)

wl_resource_post_no_memory

      void wl_resource_post_no_memory(struct wl_resource *resource)

wl_resource_destroy

      void wl_resource_destroy(struct wl_resource *resource)

wl_resource_get_id

      uint32_t wl_resource_get_id(const struct wl_resource *resource)

wl_resource_get_link

      struct wl_list * wl_resource_get_link(struct wl_resource *resource)

wl_resource_from_link

      struct wl_resource * wl_resource_from_link(struct wl_list *link)

wl_resource_find_for_client

      struct wl_resource * wl_resource_find_for_client(struct wl_list *list, struct wl_client *client)

wl_resource_get_client

      struct wl_client * wl_resource_get_client(struct wl_resource *resource)

wl_resource_set_user_data

      void wl_resource_set_user_data(struct wl_resource *resource, void *data)

wl_resource_get_user_data

      void * wl_resource_get_user_data(struct wl_resource *resource)

wl_resource_get_version

      int wl_resource_get_version(const struct wl_resource *resource)

wl_resource_set_destructor

      void wl_resource_set_destructor(struct wl_resource *resource, wl_resource_destroy_func_t destroy)

wl_resource_instance_of

      int wl_resource_instance_of(struct wl_resource *resource, const struct wl_interface *interface, const void *implementation)

wl_resource_add_destroy_listener

      void wl_resource_add_destroy_listener(struct wl_resource *resource, struct wl_listener *listener)

wl_resource_get_destroy_listener

      struct wl_listener * wl_resource_get_destroy_listener(struct wl_resource *resource, wl_notify_func_t notify)

wl_client_get_destroy_listener

      struct wl_listener * wl_client_get_destroy_listener(struct wl_client *client, wl_notify_func_t notify)

wl_client_get_destroy_late_listener

      struct wl_listener * wl_client_get_destroy_late_listener(struct wl_client *client, wl_notify_func_t notify)

wl_client_destroy

      void wl_client_destroy(struct wl_client *client)

wl_global_create

      struct wl_global * wl_global_create(struct wl_display *display, const struct wl_interface *interface, int version, void *data, wl_global_bind_func_t bind)

wl_global_remove - Remove the global.

      void wl_global_remove(struct wl_global *global)

  global
    The Wayland global.

  Broadcast a global remove event to all clients without destroying the global. This function can only be called once per global.

  wl_global_destroy() removes the global and immediately destroys it. On the other end, this function only removes the global, allowing clients that have not yet received the global remove event to continue to bind to it.

  This can be used by compositors to mitigate clients being disconnected because a global has been added and removed too quickly. Compositors can call wl_global_remove(), then wait an implementation-defined amount of time, then call wl_global_destroy(). Note that the destruction of a global is still racy, since clients have no way to acknowledge that they received the remove event.

  Since: 1.17.90

wl_global_destroy

      void wl_global_destroy(struct wl_global *global)

wl_global_get_interface

      const struct wl_interface * wl_global_get_interface(const struct wl_global *global)

wl_global_get_user_data

      void * wl_global_get_user_data(const struct wl_global *global)

wl_global_set_user_data - Set the global's user data.

      void wl_global_set_user_data(struct wl_global *global, void *data)

  global
    The global object
  data
    The user data pointer

  Since: 1.17.90

wl_display_get_event_loop

      struct wl_event_loop * wl_display_get_event_loop(struct wl_display *display)

wl_display_terminate

      void wl_display_terminate(struct wl_display *display)

wl_display_run

      void wl_display_run(struct wl_display *display)

wl_display_flush_clients

      void wl_display_flush_clients(struct wl_display *display)

wl_display_add_destroy_listener

      void wl_display_add_destroy_listener(struct wl_display *display, struct wl_listener *listener)

wl_display_add_client_created_listener - Registers a listener for the client connection signal.

      void wl_display_add_client_created_listener(struct wl_display *display, struct wl_listener *listener)

  When a new client object is created, listener will be notified, carrying a pointer to the new wl_client object.

  wl_client_create wl_display wl_listener

  display
    The display object
  listener
    Signal handler object

wl_display_get_destroy_listener

      struct wl_listener * wl_display_get_destroy_listener(struct wl_display *display, wl_notify_func_t notify)

wl_resource_set_implementation

      void wl_resource_set_implementation(struct wl_resource *resource, const void *implementation, void *data, wl_resource_destroy_func_t destroy)

wl_resource_set_dispatcher

      void wl_resource_set_dispatcher(struct wl_resource *resource, wl_dispatcher_func_t dispatcher, const void *implementation, void *data, wl_resource_destroy_func_t destroy)

wl_log_set_handler_server

      void wl_log_set_handler_server(wl_log_func_t handler)

wl_client_add_resource

      WL_DEPRECATED uint32_t wl_client_add_resource(struct wl_client *client, struct wl_resource *resource)

wl_client_add_object

      WL_DEPRECATED struct wl_resource * wl_client_add_object(struct wl_client *client, const struct wl_interface *interface, const void *implementation, uint32_t id, void *data)

wl_client_new_object

      WL_DEPRECATED struct wl_resource * wl_client_new_object(struct wl_client *client, const struct wl_interface *interface, const void *implementation, void *data)

wl_display_add_global

      WL_DEPRECATED struct wl_global * wl_display_add_global(struct wl_display *display, const struct wl_interface *interface, void *data, wl_global_bind_func_t bind)

wl_display_remove_global

      WL_DEPRECATED void wl_display_remove_global(struct wl_display *display, struct wl_global *global)

wl_display_init_shm

      int wl_display_init_shm(struct wl_display *display)

wl_shm_buffer_get

      struct wl_shm_buffer * wl_shm_buffer_get(struct wl_resource *resource)

wl_shm_buffer_get_stride

      int32_t wl_shm_buffer_get_stride(const struct wl_shm_buffer *buffer)

wl_shm_buffer_get_format

      uint32_t wl_shm_buffer_get_format(const struct wl_shm_buffer *buffer)

wl_shm_buffer_get_width

      int32_t wl_shm_buffer_get_width(const struct wl_shm_buffer *buffer)

wl_shm_buffer_get_height

      int32_t wl_shm_buffer_get_height(const struct wl_shm_buffer *buffer)

WL_EXPORT - Visibility attribute.

WL_DEPRECATED - Deprecated attribute.

WL_PRINTF - Printf-style argument attribute.

  x
    Ordinality of the format string argument
  y
    Ordinality of the argument to check against the format string

  See also: https://gcc.gnu.org/onlinedocs/gcc-3.2.1/gcc/Function-Attributes.html

WL_MAX_MESSAGE_SIZE - The maximum size of a protocol message.

  If a message size exceeds this value, the connection will be dropped. Servers will send an invalid_method error before disconnecting.

wl_container_of - Retrieves a pointer to a containing struct, given a member name.

  This macro allows "conversion" from a pointer to a member to its containing struct. This is useful if you have a contained item like a wl_list, wl_listener, or wl_signal, provided via a callback or other means, and would like to retrieve the struct that contains it.

  To demonstrate, the following example retrieves a pointer to example_container given only its destroy_listener member:

      struct example_container {
              struct wl_listener destroy_listener;
              // other members...
      };

      void example_container_destroy(struct wl_listener *listener, void *data)
      {
              struct example_container *ctr;

              ctr = wl_container_of(listener, ctr, destroy_listener);
              // destroy ctr...
      }

  Note: sample need not be a valid pointer. A null or uninitialised pointer is sufficient.

  ptr
    Valid pointer to the contained member
  sample
    Pointer to a struct whose type contains ptr
  member
    Named location of ptr within the sample type

  Returns:
    The container for the specified pointer

wl_iterator_result - Return value of an iterator function.

  See also: wl_client_for_each_resource_iterator_func_t See also: wl_client_for_each_resource

wl_fixed_t - Fixed-point number.

      typedef int32_t wl_fixed_t

  A wl_fixed_t is a 24.8 signed fixed-point number with a sign bit, 23 bits of integer precision and 8 bits of decimal precision. Consider wl_fixed_t as an opaque struct with methods that facilitate conversion to and from double and int types.

wl_dispatcher_func_t - Dispatcher function type alias.

      typedef int(* wl_dispatcher_func_t) (const void *user_data, void *target, uint32_t opcode, const struct wl_message *msg, union wl_argument *args))(const void *user_data, void *target, uint32_t opcode, const struct wl_message *msg, union wl_argument *args)

  A dispatcher is a function that handles the emitting of callbacks in client code. For programs directly using the C library, this is done by using libffi to call function pointers. When binding to languages other than C, dispatchers provide a way to abstract the function calling process to be friendlier to other function calling systems.

  A dispatcher takes five arguments: The first is the dispatcher-specific implementation associated with the target object. The second is the object upon which the callback is being invoked (either wl_proxy or wl_resource). The third and fourth arguments are the opcode and the wl_message corresponding to the callback. The final argument is an array of arguments received from the other process via the wire protocol.

  user_data
    Dispatcher-specific implementation data
  target
    Callback invocation target (wl_proxy or wl_resource)
  opcode
    Callback opcode
  msg
    Callback message signature
  args
    Array of received arguments

  Returns:
    0 on success, or -1 on failure

wl_log_func_t - Log function type alias.

      typedef void(* wl_log_func_t) (const char *fmt, va_list args))(const char *fmt, va_list args)

  The C implementation of the Wayland protocol abstracts the details of logging. Users may customize the logging behavior, with a function conforming to the wl_log_func_t type, via wl_log_set_handler_client and wl_log_set_handler_server.

  A wl_log_func_t must conform to the expectations of vprintf, and expects two arguments: a string to write and a corresponding variable argument list. While the string to write may contain format specifiers and use values in the variable argument list, the behavior of any wl_log_func_t depends on the implementation.

  Note: Take care to not confuse this with wl_protocol_logger_func_t, which is a specific server-side logger for requests and events.

  fmt
    String to write to the log, containing optional format specifiers
  args
    Variable argument list

  See also: wl_log_set_handler_client See also: wl_log_set_handler_server

wl_fixed_to_double - Converts a fixed-point number to a floating-point number.

      static double wl_fixed_to_double(wl_fixed_t f)

  f
    Fixed-point number to convert

  Returns:
    Floating-point representation of the fixed-point argument

wl_fixed_from_double - Converts a floating-point number to a fixed-point number.

      static wl_fixed_t wl_fixed_from_double(double d)

  d
    Floating-point number to convert

  Returns:
    Fixed-point representation of the floating-point argument

wl_fixed_to_int - Converts a fixed-point number to an integer.

      static int wl_fixed_to_int(wl_fixed_t f)

  f
    Fixed-point number to convert

  Returns:
    Integer component of the fixed-point argument

wl_fixed_from_int - Converts an integer to a fixed-point number.

      static wl_fixed_t wl_fixed_from_int(int i)

  i
    Integer to convert

  Returns:
    Fixed-point representation of the integer argument

Prev |  |
Appendix B. Client API | Home |