Appendix C. Server API

Table of Contents

Introduction
wl_argument - A union representing all of the basic data types that can be passed along the wayland wire format.
wl_array
wl_buffer
wl_client
wl_display
wl_global
wl_interface
wl_list - doubly-linked list
wl_listener - A single listener for Wayland signals.
wl_message
wl_object
wl_protocol_logger
wl_protocol_logger_message
wl_resource
wl_resource_iterator_context
wl_shm_buffer
wl_shm_pool
wl_shm_sigbus_data
wl_signal - A source of a type of observable event.
wl_socket
Functions

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 equvalent 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 - A union representing all of the basic data types that can be passed along the wayland wire format.

This union represents all of the basic data types that can be passed in the wayland wire format. It is used by dispatchers and runtime-friendly versions of the event and request marshaling functions.

wl_array

wl_buffer

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(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.

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_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_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.

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.

Returns:
None.

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_get_serial - Get the current serial number.
uint32_t wl_display_get_serial(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_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.

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.

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

The length of socket path, i.e., the path set in XDG_RUNTIME_DIR and the socket name, must not exceed the maximum length of a Unix socket path. The function also fails if the user do not have write permission in the XDG_RUNTIME_DIR path or if the socket name 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 protol 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_global

wl_interface

wl_list - doubly-linked list

The list head is of "struct wl_list" type, and must be initialized using wl_list_init(). All entries in the list must be of the same type. The item type must have a "struct wl_list" member. This member will be initialized by wl_list_insert(). There is no need to call wl_list_init() on the individual item. To query if the list is empty in O(1), use wl_list_empty().

Let's call the list reference "struct wl_list foo_list", the item type as "item_t", and the item member as "struct wl_list link".

The following code will initialize a list:

struct wl_list foo_list;

struct item_t {
        int foo;
        struct wl_list link;
};
struct item_t item1, item2, item3;

wl_list_init(&foo_list);
wl_list_insert(&foo_list, &item1.link); // Pushes item1 at the head
wl_list_insert(&foo_list, &item2.link); // Pushes item2 at the head
wl_list_insert(&item2.link, &item3.link);       // Pushes item3 after item2

The list now looks like [item2, item3, item1]

Iterate the list in ascending order:

item_t *item;
wl_list_for_each(item, foo_list, link) {
        Do_something_with_item(item);
}

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

wl_message

wl_object

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_get_class - Retrieve the interface name (class) of a resource object.
const char * wl_resource_get_class(struct wl_resource *resource)
resource
The resource object

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

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_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 buffer. 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_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_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_get_serial
uint32_t wl_display_get_serial(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_destroy
void wl_global_destroy(struct wl_global *global)
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(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_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_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_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
void wl_resource_post_error(struct wl_resource *resource, uint32_t code, const char *msg,...) WL_PRINTF(3
wl_resource_post_no_memory
void 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(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(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(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(struct wl_shm_buffer *buffer)
wl_shm_buffer_get_format
uint32_t wl_shm_buffer_get_format(struct wl_shm_buffer *buffer)
wl_shm_buffer_get_width
int32_t wl_shm_buffer_get_width(struct wl_shm_buffer *buffer)
wl_shm_buffer_get_height
int32_t wl_shm_buffer_get_height(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
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_DEPRECATED
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_resource_post_error
void wl_resource_post_error(struct wl_resource *resource, uint32_t code, const char *msg,...)
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(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(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_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_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_destroy
void wl_global_destroy(struct wl_global *global)
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_socket_auto
const char* wl_display_add_socket_auto(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
uint32_t wl_client_add_resource(struct wl_client *client, struct wl_resource *resource) WL_DEPRECATED
wl_client_add_object
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_DEPRECATED
wl_client_new_object
struct wl_resource* wl_client_new_object(struct wl_client *client, const struct wl_interface *interface, const void *implementation, void *data) WL_DEPRECATED
wl_display_add_global
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_DEPRECATED
wl_display_remove_global
void wl_display_remove_global(struct wl_display *display, struct wl_global *global) WL_DEPRECATED
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(struct wl_shm_buffer *buffer)
wl_shm_buffer_get_format
uint32_t wl_shm_buffer_get_format(struct wl_shm_buffer *buffer)
wl_shm_buffer_get_width
int32_t wl_shm_buffer_get_width(struct wl_shm_buffer *buffer)
wl_shm_buffer_get_height
int32_t wl_shm_buffer_get_height(struct wl_shm_buffer *buffer)
wl_list_init
void wl_list_init(struct wl_list *list)
wl_list_insert
void wl_list_insert(struct wl_list *list, struct wl_list *elm)
wl_list_remove
void wl_list_remove(struct wl_list *elm)
wl_list_length
int wl_list_length(const struct wl_list *list)
wl_list_empty
int wl_list_empty(const struct wl_list *list)
wl_list_insert_list
void wl_list_insert_list(struct wl_list *list, struct wl_list *other)
wl_array_init
void wl_array_init(struct wl_array *array)
wl_array_release
void wl_array_release(struct wl_array *array)
wl_array_add
void* wl_array_add(struct wl_array *array, size_t size)
wl_array_copy
int wl_array_copy(struct wl_array *array, struct wl_array *source)
wl_container_of - Retrieves a pointer to the containing struct of a given member item.

This macro allows conversion from a pointer to a item 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...
}

ptr
A valid pointer to the contained item.
sample
A pointer to the type of content that the list item stores. Sample does not need be a valid pointer; a null or an uninitialised pointer will suffice.
member
The named location of ptr within the sample type.

Returns:
The container for the specified pointer.

wl_iterator_result - This enum represents the return value of an iterator function.
wl_dispatcher_func_t - A function pointer type for a dispatcher.
typedef int(* wl_dispatcher_func_t) (const void *, void *, uint32_t, const struct wl_message *, union wl_argument *))(const void *, void *, uint32_t, const struct wl_message *, union wl_argument *)

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 data associated with the target object. The second is the object on which the callback is being invoked (either wl_proxy or wl_resource). The third and fourth arguments are the opcode the wl_message structure corresponding to the callback being emitted. The final argument is an array of arguments received from the other process via the wire protocol.

wl_list_init
void wl_list_init(struct wl_list *list)
wl_list_insert
void wl_list_insert(struct wl_list *list, struct wl_list *elm)
wl_list_remove
void wl_list_remove(struct wl_list *elm)
wl_list_length
int wl_list_length(const struct wl_list *list)
wl_list_empty
int wl_list_empty(const struct wl_list *list)
wl_list_insert_list
void wl_list_insert_list(struct wl_list *list, struct wl_list *other)
wl_array_init
void wl_array_init(struct wl_array *array)
wl_array_release
void wl_array_release(struct wl_array *array)
wl_array_add
void* wl_array_add(struct wl_array *array, size_t size)
wl_array_copy
int wl_array_copy(struct wl_array *array, struct wl_array *source)