structwl_client*wl_client_create(structwl_display*display,intfd)
Create a client for the given file descriptor
Parametersdisplay 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().
structwl_protocol_logger*wl_display_add_protocol_logger(structwl_display*display,wl_protocol_logger_func_tfunc,void*user_data)
Adds a new protocol logger.
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.
Parametersdisplay The display object
func The function to call to log a new protocol message
user_data The user data pointer to pass to funcReturns
The protol logger object on success, NULL on failure.
Seealsowl_protocol_logger_destroyuint32_t*wl_display_add_shm_format(structwl_display*display,uint32_tformat)
Add support for a wl_shm pixel format
Parametersdisplay 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.
intwl_display_add_socket(structwl_display*display,constchar*name)
Add a socket to Wayland display for the clients to connect.
Parametersdisplay 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.
intwl_display_add_socket_fd(structwl_display*display,intsock_fd)
Add a socket with an existing fd to Wayland display for the clients to connect.
Parametersdisplay 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.
voidwl_display_cancel_read(structwl_display*display)
Cancel read intention on display's fd
Parametersdisplay The display context object
After a thread successfully called wl_display_prepare_read() it must either call wl_display_read_events()
or wl_display_cancel_read(). If the threads do not follow this rule it will lead to deadlock.
Seealsowl_display_prepare_read(), wl_display_read_events()structwl_display*wl_display_connect(constchar*name)
Connect to a Wayland display
Parametersname Name of the Wayland display to connect to
Returns
A wl_display object or NULL on failure
Connect to the Wayland display named name. If name is NULL, its value will be replaced with the
WAYLAND_DISPLAY environment variable if it is set, otherwise display 'wayland-0' will be used.
If WAYLAND_SOCKET is set, it's interpreted as a file descriptor number referring to an already opened
socket. In this case, the socket is used as-is and name is ignored.
If name is a relative path, then the socket is opened relative to the XDG_RUNTIME_DIR directory.
If name is an absolute path, then that path is used as-is for the location of the socket at which the
Wayland server is listening; no qualification inside XDG_RUNTIME_DIR is attempted.
If name is NULL and the WAYLAND_DISPLAY environment variable is set to an absolute pathname, then that
pathname is used as-is for the socket in the same manner as if name held an absolute path. Support for
absolute paths in name and WAYLAND_DISPLAY is present since Wayland version 1.15.
structwl_display*wl_display_connect_to_fd(intfd)
Connect to Wayland display on an already open fd
Parametersfd The fd to use for the connection
Returns
A wl_display object or NULL on failure
The wl_display takes ownership of the fd and will close it when the display is destroyed. The fd will
also be closed in case of failure.
structwl_display*wl_display_create(void)
Create Wayland display object.
Returns
The Wayland display object. Null if failed to create
This creates the wl_display object.
structwl_event_queue*wl_display_create_queue(structwl_display*display)
Create a new event queue for this display
Parametersdisplay The display context object
Returns
A new event queue associated with this display or NULL on failure.
structwl_event_queue*wl_display_create_queue_with_name(structwl_display*display,constchar*name)
Create a new event queue for this display and give it a name
Parametersdisplay The display context object
name A human readable queue name
Returns
A new event queue associated with this display or NULL on failure.
voidwl_display_destroy(structwl_display*display)
Destroy Wayland display object.
Parametersdisplay 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.
Seealsowl_display_add_destroy_listenervoidwl_display_destroy_clients(structwl_display*display)
Destroy all clients connected to the display
Parametersdisplay 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.
voidwl_display_disconnect(structwl_display*display)
Close a connection to a Wayland display
Parametersdisplay The display context object
Close the connection to display. The wl_proxy and wl_event_queue objects need to be manually destroyed by
the caller before disconnecting.
intwl_display_dispatch(structwl_display*display)
Process incoming events
Parametersdisplay The display context object
Returns
The number of dispatched events on success or -1 on failure
Dispatch events on the default event queue.
If the default event queue is empty, this function blocks until there are events to be read from the
display fd. Events are read and queued on the appropriate event queues. Finally, events on the default
event queue are dispatched. On failure -1 is returned and errno set appropriately.
In a multi threaded environment, do not manually wait using poll() (or equivalent) before calling this
function, as doing so might cause a dead lock. If external reliance on poll() (or equivalent) is
required, see wl_display_prepare_read_queue() of how to do so.
This function is thread safe as long as it dispatches the right queue on the right thread. It is also
compatible with the multi thread event reading preparation API (see wl_display_prepare_read_queue()), and
uses the equivalent functionality internally. It is not allowed to call this function while the thread is
being prepared for reading events, and doing so will cause a dead lock.
Note
It is not possible to check if there are events on the queue or not. For dispatching default queue
events without blocking, see wl_display_dispatch_pending().
Seealsowl_display_dispatch_pending(), wl_display_dispatch_queue(), wl_display_read_events()intwl_display_dispatch_pending(structwl_display*display)
Dispatch default queue events without reading from the display fd
Parametersdisplay The display context object
Returns
The number of dispatched events or -1 on failure
This function dispatches events on the main event queue. It does not attempt to read the display fd and
simply returns zero if the main queue is empty, i.e., it doesn't block.
Seealsowl_display_dispatch(), wl_display_dispatch_queue(), wl_display_flush()intwl_display_dispatch_queue(structwl_display*display,structwl_event_queue*queue)
Dispatch events in an event queue
Parametersdisplay The display context object
queue The event queue to dispatch
Returns
The number of dispatched events on success or -1 on failure
Dispatch events on the given event queue.
If the given event queue is empty, this function blocks until there are events to be read from the
display fd. Events are read and queued on the appropriate event queues. Finally, events on given event
queue are dispatched. On failure -1 is returned and errno set appropriately.
In a multi threaded environment, do not manually wait using poll() (or equivalent) before calling this
function, as doing so might cause a dead lock. If external reliance on poll() (or equivalent) is
required, see wl_display_prepare_read_queue() of how to do so.
This function is thread safe as long as it dispatches the right queue on the right thread. It is also
compatible with the multi thread event reading preparation API (see wl_display_prepare_read_queue()), and
uses the equivalent functionality internally. It is not allowed to call this function while the thread is
being prepared for reading events, and doing so will cause a dead lock.
It can be used as a helper function to ease the procedure of reading and dispatching events.
Note
Since Wayland 1.5 the display has an extra queue for its own events (i. e. delete_id). This queue is
dispatched always, no matter what queue we passed as an argument to this function. That means that
this function can return non-0 value even when it haven't dispatched any event for the given queue.
Seealsowl_display_dispatch(), wl_display_dispatch_pending(), wl_display_dispatch_queue_pending(),
wl_display_prepare_read_queue()intwl_display_dispatch_queue_pending(structwl_display*display,structwl_event_queue*queue)
Dispatch pending events in an event queue
Parametersdisplay The display context object
queue The event queue to dispatch
Returns
The number of dispatched events on success or -1 on failure
Dispatch all incoming events for objects assigned to the given event queue. On failure -1 is returned and
errno set appropriately. If there are no events queued, this function returns immediately.
Since
1.0.2
intwl_display_flush(structwl_display*display)
Send all buffered requests on the display to the server
Parametersdisplay The display context object
Returns
The number of bytes sent on success or -1 on failure
Send all buffered data on the client side to the server. Clients should always call this function before
blocking on input from the display fd. On success, the number of bytes sent to the server is returned. On
failure, this function returns -1 and errno is set appropriately.
wl_display_flush() never blocks. It will write as much data as possible, but if all data could not be
written, errno will be set to EAGAIN and -1 returned. In that case, use poll on the display file
descriptor to wait for it to become writable again.
structwl_list*wl_display_get_client_list(structwl_display*display)
Get the list of currently connected clients
Parametersdisplay 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.
Seealsowl_client_for_each()wl_client_get_link()wl_client_from_link()intwl_display_get_error(structwl_display*display)
Retrieve the last error that occurred on a display
Parametersdisplay The display context object
Returns
The last error that occurred on display or 0 if no error occurred
Return the last error that occurred on the display. This may be an error sent by the server or caused by
the local client.
Note
Errors are fatal. If this function returns non-zero the display can no longer be used.
intwl_display_get_fd(structwl_display*display)
Get a display context's file descriptor
Parametersdisplay The display context object
Returns
Display object file descriptor
Return the file descriptor associated with a display so it can be integrated into the client's main loop.
uint32_twl_display_get_protocol_error(structwl_display*display,conststructwl_interface**interface,uint32_t*id)
Retrieves the information about a protocol error:
Parametersdisplay The Wayland display
interface if not NULL, stores the interface where the error occurred, or NULL, if unknown.
id if not NULL, stores the object id that generated the error, or 0, if the object id is unknown.
There's no guarantee the object is still valid; the client must know if it deleted the object.
Returns
The error code as defined in the interface specification.
int err = wl_display_get_error(display);
if (err == EPROTO) {
code = wl_display_get_protocol_error(display, &interface, &id);
handle_error(code, interface, id);
}
...
uint32_twl_display_get_serial(structwl_display*display)
Get the current serial number
Parametersdisplay The display object
This function returns the most recent serial number, but does not increment it.
uint32_twl_display_next_serial(structwl_display*display)
Get the next serial number
Parametersdisplay The display object
This function increments the display serial number and returns the new value.
intwl_display_prepare_read(structwl_display*display)
Prepare to read events from the display's file descriptor
Parametersdisplay The display context object
Returns
0 on success or -1 if event queue was not empty
This function does the same thing as wl_display_prepare_read_queue() with the default queue passed as the
queue.
Seealsowl_display_prepare_read_queueintwl_display_prepare_read_queue(structwl_display*display,structwl_event_queue*queue)
Prepare to read events from the display's file descriptor to a queue
Parametersdisplay The display context object
queue The event queue to use
Returns
0 on success or -1 if event queue was not empty
This function (or wl_display_prepare_read()) must be called before reading from the file descriptor using
wl_display_read_events(). Calling wl_display_prepare_read_queue() announces the calling thread's
intention to read and ensures that until the thread is ready to read and calls wl_display_read_events(),
no other thread will read from the file descriptor. This only succeeds if the event queue is empty, and
if not -1 is returned and errno set to EAGAIN.
If a thread successfully calls wl_display_prepare_read_queue(), it must either call
wl_display_read_events() when it's ready or cancel the read intention by calling
wl_display_cancel_read().
Use this function before polling on the display fd or integrate the fd into a toolkit event loop in a
race-free way. A correct usage would be (with most error checking left out):
while (wl_display_prepare_read_queue(display, queue) != 0)
wl_display_dispatch_queue_pending(display, queue);
wl_display_flush(display);
ret = poll(fds, nfds, -1);
if (has_error(ret))
wl_display_cancel_read(display);
else
wl_display_read_events(display);
wl_display_dispatch_queue_pending(display, queue);
Here we call wl_display_prepare_read_queue(), which ensures that between returning from that call and
eventually calling wl_display_read_events(), no other thread will read from the fd and queue events in
our queue. If the call to wl_display_prepare_read_queue() fails, we dispatch the pending events and try
again until we're successful.
The wl_display_prepare_read_queue() function doesn't acquire exclusive access to the display's fd. It
only registers that the thread calling this function has intention to read from fd. When all registered
readers call wl_display_read_events(), only one (at random) eventually reads and queues the events and
the others are sleeping meanwhile. This way we avoid races and still can read from more threads.
Seealsowl_display_cancel_read(), wl_display_read_events(), wl_display_prepare_read()intwl_display_read_events(structwl_display*display)
Read events from display file descriptor
Parametersdisplay The display context object
Returns
0 on success or -1 on error. In case of error errno will be set accordingly
Calling this function will result in data available on the display file descriptor being read and read
events will be queued on their corresponding event queues.
Before calling this function, depending on what thread it is to be called from,
wl_display_prepare_read_queue() or wl_display_prepare_read() needs to be called. See
wl_display_prepare_read_queue() for more details.
When being called at a point where other threads have been prepared to read (using
wl_display_prepare_read_queue() or wl_display_prepare_read()) this function will sleep until all other
prepared threads have either been cancelled (using wl_display_cancel_read()) or them self entered this
function. The last thread that calls this function will then read and queue events on their corresponding
event queues, and finally wake up all other wl_display_read_events() calls causing them to return.
If a thread cancels a read preparation when all other threads that have prepared to read has either
called wl_display_cancel_read() or wl_display_read_events(), all reader threads will return without
having read any data.
To dispatch events that may have been queued, call wl_display_dispatch_pending() or
wl_display_dispatch_queue_pending().
Seealsowl_display_prepare_read(), wl_display_cancel_read(), wl_display_dispatch_pending(),
wl_display_dispatch()intwl_display_roundtrip(structwl_display*display)
Block until all pending request are processed by the server
Parametersdisplay The display context object
Returns
The number of dispatched events on success or -1 on failure
This function blocks until the server has processed all currently issued requests by sending a request to
the display server and waiting for a reply before returning.
This function uses wl_display_dispatch_queue() internally. It is not allowed to call this function while
the thread is being prepared for reading events, and doing so will cause a dead lock.
Note
This function may dispatch other events being received on the default queue.
intwl_display_roundtrip_queue(structwl_display*display,structwl_event_queue*queue)
Block until all pending request are processed by the server
Parametersdisplay The display context object
queue The queue on which to run the roundtrip
Returns
The number of dispatched events on success or -1 on failure
This function blocks until the server has processed all currently issued requests by sending a request to
the display server and waiting for a reply before returning.
This function uses wl_display_dispatch_queue() internally. It is not allowed to call this function while
the thread is being prepared for reading events, and doing so will cause a dead lock.
Note
This function may dispatch other events being received on the given queue.
Seealsowl_display_roundtrip()voidwl_display_set_default_max_buffer_size(structwl_display*display,size_tmax_buffer_size)
Sets the default maximum size for connection buffers of new clients
Parametersdisplay 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.
Seealsowl_client_set_max_buffer_sizeSince
1.22.90
voidwl_display_set_global_filter(structwl_display*display,wl_display_global_filter_func_tfilter,void*data)
Set a filter function for global objects
Parametersdisplay 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.
voidwl_display_set_max_buffer_size(structwl_display*display,size_tmax_buffer_size)
Adjust the maximum size of the client connection buffers
Parametersdisplay The display context object
max_buffer_size The maximum size of the connection buffers
Client buffers are unbounded by default. This function sets a limit to the size of the connection
buffers.
A value of 0 for max_buffer_size requests the buffers to be unbounded.
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.
Since
1.22.90
Install Now
PNG Icons
