Client API¶

Client Introduction¶

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

A client uses libwayland-client to communicate with one or more wayland servers. A wl_display object is created and manages each open connection to a server. At least one wl_event_queue object is created for each wl_display, this holds events as they are received from the server until they can be processed. Multi-threading is supported by creating an additional wl_event_queue for each additional thread, each object can have it’s events placed in a particular queue, so potentially a different thread could be made to handle the events for each object created.

Though some convenience functions are provided, libwayland-client is designed to allow the calling code to wait for events, so that different polling mechanisms can be used. A file descriptor is provided, when it becomes ready for reading the calling code can ask libwayland-client to read the available events from it into the wl_event_queue objects.

The library only provides low-level access to the wayland objects. Each object created by the client is represented by a wl_proxy object that this library creates. This includes the id that is actually communicated over the socket to the server, a void* data pointer that is intended to point at a client’s representation of the object, and a pointer to a static wl_interface object, which is generated from the xml and identifies the object’s class and can be used for introspection into the messages and events.

Messages are sent by calling wl_proxy_marshal(). This will write a message to the socket, by using the message id and the wl_interface to identify the types of each argument and convert them into stream format. Most software will call type-safe wrappers generated from the xml description of the Wayland protocol specification. For instance the C header file generated from the xml defines the following inline function to transmit the wl_surface_attach() message:

static inline void
wl_surface_attach(struct wl_surface *wl_surface, struct wl_buffer *buffer, int32_t x, int32_t y)
{
  wl_proxy_marshal((struct wl_proxy *) wl_surface, WL_SURFACE_ATTACH, buffer, x, y);
}

Events (messages from the server) are handled by calling a “dispatcher” callback the client stores in the wl_proxy for each event. A language binding for a string-based interpreter, such as CPython, might have a dispatcher that uses the event name from the wl_interface to identify the function to call. The default dispatcher uses the message id number to index an array of functions pointers, called a wl_listener, and the wl_interface to convert data from the stream into arguments to the function. The C header file generated from the xml defines a per-class structure that forces the function pointers to be of the correct type, for instance the wl_surface_enter() event defines this pointer in the wl_surface_listener object:

struct wl_surface_listener {
  void (*enter)(void *data, struct wl_surface *, struct wl_output *);
  ...
}

struct wl_proxy¶

Class:	wl_proxy

Represents a protocol object on the client side.

A wl_proxy acts as a client side proxy to an object existing in the compositor. The proxy is responsible for converting requests made by the clients with @ref wl_proxy_marshal() into Wayland’s wire format. Events coming from the compositor are also handled by the proxy, which will in turn call the handler set with @ref wl_proxy_add_listener().

Note:	With the exception of function @ref wl_proxy_set_queue(), functions

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

struct wl_display¶

Class:	wl_display

Represents a connection to the compositor and acts as a proxy to the wl_display singleton object.

A wl_display object represents a client connection to a Wayland compositor. It is created with either @ref wl_display_connect() or

Ref:	wl_display_connect_to_fd(). A connection is terminated using
Ref:	wl_display_disconnect().

A wl_display is also used as the @ref wl_proxy for the wl_display singleton object on the compositor side.

A wl_display object handles all the data sent from and to the compositor. When a @ref wl_proxy marshals a request, it will write its wire representation to the display’s write buffer. The data is sent to the compositor when the client calls @ref wl_display_flush().

Incoming data is handled in two steps: queueing and dispatching. In the queue step, the data coming from the display fd is interpreted and added to a queue. On the dispatch step, the handler for the incoming event set by the client on the corresponding @ref wl_proxy is called.

A wl_display has at least one event queue, called the <em>default queue</em>. Clients can create additional event queues with @ref wl_display_create_queue() and assign @ref wl_proxy’s to it. Events occurring in a particular proxy are always queued in its assigned queue. A client can ensure that a certain assumption, such as holding a lock or running from a given thread, is true when a proxy event handler is called by assigning that proxy to an event queue and making sure that this queue is only dispatched when the assumption holds.

The default queue is dispatched by calling @ref wl_display_dispatch(). This will dispatch any events queued on the default queue and attempt to read from the display fd if it’s empty. Events read are then queued on the appropriate queues according to the proxy assignment.

A user created queue is dispatched with @ref wl_display_dispatch_queue(). This function behaves exactly the same as wl_display_dispatch() but it dispatches given queue instead of the default queue.

A real world example of event queue usage is Mesa’s implementation of eglSwapBuffers() for the Wayland platform. This function might need to block until a frame callback is received, but dispatching the default queue could cause an event handler on the client to start drawing again. This problem is solved using another event queue, so that only the events handled by the EGL code are dispatched during the block.

This creates a problem where a thread dispatches a non-default queue, reading all the data from the display fd. If the application would call @em poll(2) after that it would block, even though there might be events queued on the default queue. Those events should be dispatched with @ref wl_display_dispatch_pending() or @ref wl_display_dispatch_queue_pending() before flushing and blocking.

struct wl_event_queue¶

Class:	wl_event_queue

A queue for @ref wl_proxy object events.

Event queues allows the events on a display to be handled in a thread-safe manner. See @ref wl_display for details.

enum wl_proxy_flag¶: @cond

int debug_client¶: @endcond

void display_wakeup_threads(struct wl_display * display)¶

This helper function wakes up all threads that are waiting for display->reader_cond (i. e. when reading is done, canceled, or an error occurred)

NOTE: must be called with display->mutex locked

void display_fatal_error(struct wl_display * display, int error)¶

This function is called for local errors (no memory, server hung up)

Param:	display
Parameters:	error – error value (EINVAL, EFAULT, …)
Note:	this function is called with display mutex locked

void display_protocol_error(struct wl_display * display, uint32_t code, uint32_t id, const struct wl_interface * intf)¶

This function is called for error events and indicates that in some object an error occurred. The difference between this function and display_fatal_error() is that this one handles errors that will come by wire, whereas display_fatal_error() is called for local errors.

Param:	display
Parameters:	code – error code id – id of the object that generated the error intf – protocol interface

void wl_event_queue_destroy(struct wl_event_queue * queue)¶

Destroy an event queue

Parameters:	queue – The event queue to be destroyed

Destroy the given event queue. Any pending event on that queue is discarded.

The @ref wl_display object used to create the queue should not be destroyed until all event queues created with it are destroyed with this function.

Memberof:	wl_event_queue

struct wl_event_queue * wl_display_create_queue(struct wl_display * display)¶

Create a new event queue for this display

Parameters:	display – The display context object
Returns:	A new event queue associated with this display or NULL on

failure.

Memberof:	wl_display

struct wl_proxy * wl_proxy_create(struct wl_proxy * factory, const struct wl_interface * interface)¶

Create a proxy object with a given interface

Parameters:	factory – Factory proxy object interface – Interface the proxy object should use
Returns:	A newly allocated proxy object or NULL on failure

This function creates a new proxy object with the supplied interface. The proxy object will have an id assigned from the client id space. The id should be created on the compositor side by sending an appropriate request with @ref wl_proxy_marshal().

The proxy will inherit the display and event queue of the factory object.

Note:	This should not normally be used by non-generated code.
Sa:	wl_display, wl_event_queue, wl_proxy_marshal()
Memberof:	wl_proxy

void wl_proxy_destroy(struct wl_proxy * proxy)¶

Destroy a proxy object

Parameters:	proxy – The proxy to be destroyed
C:	proxy must not be a proxy wrapper.
Memberof:	wl_proxy

int wl_proxy_add_listener(struct wl_proxy * proxy, void (**)(void) implementation, void * data)¶

Set a proxy’s listener

Parameters:	proxy – The proxy object implementation – The listener to be added to proxy data – User data to be associated with the proxy
Returns:	0 on success or -1 on failure

Set proxy’s listener to @c implementation and its user data to

C:	data. If a listener has already been set, this function

fails and nothing is changed.

C:	implementation is a vector of function pointers. For an opcode
C:	n, @c implementation[n] should point to the handler of c n for

the given object.

C:	proxy must not be a proxy wrapper.
Memberof:	wl_proxy

const void * wl_proxy_get_listener(struct wl_proxy * proxy)¶

Get a proxy’s listener

Parameters:	proxy – The proxy object
Returns:	The address of the proxy’s listener or NULL if no listener is set

Gets the address to the proxy’s listener; which is the listener set with

Ref:	wl_proxy_add_listener.

This function is useful in clients with multiple listeners on the same interface to allow the identification of which code to execute.

Memberof:	wl_proxy

int wl_proxy_add_dispatcher(struct wl_proxy * proxy, wl_dispatcher_func_t dispatcher, const void * implementation, void * data)¶

Set a proxy’s listener (with dispatcher)

Parameters:	proxy – The proxy object dispatcher – The dispatcher to be used for this proxy implementation – The dispatcher-specific listener implementation data – User data to be associated with the proxy
Returns:	0 on success or -1 on failure

Set proxy’s listener to use @c dispatcher_func as its dispatcher and @c dispatcher_data as its dispatcher-specific implementation and its user data to @c data. If a listener has already been set, this function fails and nothing is changed.

The exact details of dispatcher_data depend on the dispatcher used. This function is intended to be used by language bindings, not user code.

C:	proxy must not be a proxy wrapper.
Memberof:	wl_proxy

struct wl_proxy * wl_proxy_marshal_array_constructor(struct wl_proxy * proxy, uint32_t opcode, union wl_argument * args, const struct wl_interface * interface)¶

Prepare a request to be sent to the compositor

Parameters:	proxy – The proxy object opcode – Opcode of the request to be sent args – Extra arguments for the given request interface – The interface to use for the new proxy

This function translates a request given an opcode, an interface and a wl_argument array to the wire format and writes it to the connection buffer.

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will inherit their version from their parent.

Note:	This is intended to be used by language bindings and not in

non-generated code.

Sa:	wl_proxy_marshal()
Memberof:	wl_proxy

struct wl_proxy * wl_proxy_marshal_array_constructor_versioned(struct wl_proxy * proxy, uint32_t opcode, union wl_argument * args, const struct wl_interface * interface, uint32_t version)¶

Prepare a request to be sent to the compositor

Parameters:	proxy – The proxy object opcode – Opcode of the request to be sent args – Extra arguments for the given request interface – The interface to use for the new proxy version – The protocol object version for the new proxy

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer. This version takes an array of the union type wl_argument.

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified.

Note:	This is intended to be used by language bindings and not in

non-generated code.

Sa:	wl_proxy_marshal()
Memberof:	wl_proxy

void wl_proxy_marshal(struct wl_proxy * proxy, uint32_t opcode, ...)¶

Prepare a request to be sent to the compositor

Parameters:	proxy – The proxy object opcode – Opcode of the request to be sent ... – Extra arguments for the given request

This function is similar to wl_proxy_marshal_constructor(), except it doesn’t create proxies for new-id arguments.

Note:	This should not normally be used by non-generated code.
Sa:	wl_proxy_create()
Memberof:	wl_proxy

struct wl_proxy * wl_proxy_marshal_constructor(struct wl_proxy * proxy, uint32_t opcode, const struct wl_interface * interface, ...)¶

Prepare a request to be sent to the compositor

Parameters:	proxy – The proxy object opcode – Opcode of the request to be sent interface – The interface to use for the new proxy ... – Extra arguments for the given request
Returns:	A new wl_proxy for the new_id argument or NULL on error

This function translates a request given an opcode, an interface and extra arguments to the wire format and writes it to the connection buffer. The types of the extra arguments must correspond to the argument types of the method associated with the opcode in the interface.

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will inherit their version from their parent.

Note:	This should not normally be used by non-generated code.
Memberof:	wl_proxy

struct wl_proxy * wl_proxy_marshal_constructor_versioned(struct wl_proxy * proxy, uint32_t opcode, const struct wl_interface * interface, uint32_t version, ...)¶

Prepare a request to be sent to the compositor

Parameters:	proxy – The proxy object opcode – Opcode of the request to be sent interface – The interface to use for the new proxy version – The protocol object version of the new proxy ... – Extra arguments for the given request
Returns:	A new wl_proxy for the new_id argument or NULL on error

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer.

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified.

Note:	This should not normally be used by non-generated code.
Memberof:	wl_proxy

void wl_proxy_marshal_array(struct wl_proxy * proxy, uint32_t opcode, union wl_argument * args)¶

Prepare a request to be sent to the compositor

Parameters:	proxy – The proxy object opcode – Opcode of the request to be sent args – Extra arguments for the given request

This function is similar to wl_proxy_marshal_array_constructor(), except it doesn’t create proxies for new-id arguments.

Note:	This is intended to be used by language bindings and not in

non-generated code.

Sa:	wl_proxy_marshal()
Memberof:	wl_proxy

struct wl_display * wl_display_connect_to_fd(int fd)¶

Connect to Wayland display on an already open fd

Parameters:	fd – The fd to use for the connection
Returns:	A @ref wl_display object or c 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.

Memberof:	wl_display

struct wl_display * wl_display_connect(const char * name)¶

Connect to a Wayland display

Parameters:	name – Name of the Wayland display to connect to
Returns:	A @ref wl_display object or c NULL on failure

Connect to the Wayland display named @c name. If @c name is c NULL, its value will be replaced with the WAYLAND_DISPLAY environment variable if it is set, otherwise display “wayland-0” will be used.

If @c 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 @c name is @c 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 @c name held an absolute path. Support for absolute paths in @c name and WAYLAND_DISPLAY is present since Wayland version 1.15.

Memberof:	wl_display

void wl_display_disconnect(struct wl_display * display)¶

Close a connection to a Wayland display

Parameters:	display – The display context object

Close the connection to @c display and free all resources associated with it.

Memberof:	wl_display

int wl_display_get_fd(struct wl_display * display)¶

Get a display context’s file descriptor

Parameters:	display – 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.

Memberof:	wl_display

int wl_display_roundtrip_queue(struct wl_display * display, struct wl_event_queue * queue)¶

Block until all pending request are processed by the server

Parameters:	display – 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.

Sa:	wl_display_roundtrip()
Memberof:	wl_display

int wl_display_roundtrip(struct wl_display * display)¶

Block until all pending request are processed by the server

Parameters:	display – 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.

Memberof:	wl_display

int wl_display_read_events(struct wl_display * display)¶

Read events from display file descriptor

Parameters:	display – 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().

Sa:	wl_display_prepare_read(), wl_display_cancel_read(),

wl_display_dispatch_pending(), wl_display_dispatch()

Memberof:	wl_display

int wl_display_prepare_read_queue(struct wl_display * display, struct wl_event_queue * queue)¶

Prepare to read events from the display’s file descriptor to a queue

Parameters:	display – 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.

Sa:	wl_display_cancel_read(), wl_display_read_events(),

wl_display_prepare_read()

Memberof:	wl_display

int wl_display_prepare_read(struct wl_display * display)¶

Prepare to read events from the display’s file descriptor

Parameters:	display – 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.

Sa:	wl_display_prepare_read_queue
Memberof:	wl_display

void wl_display_cancel_read(struct wl_display * display)¶

Cancel read intention on display’s fd

Parameters:	display – 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.

Sa:	wl_display_prepare_read(), wl_display_read_events()
Memberof:	wl_display

int wl_display_dispatch_queue(struct wl_display * display, struct wl_event_queue * queue)¶

Dispatch events in an event queue

Parameters:	display – 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.

Sa:	wl_display_dispatch(), wl_display_dispatch_pending(),

wl_display_dispatch_queue_pending(), wl_display_prepare_read_queue()

Memberof:	wl_display

int wl_display_dispatch_queue_pending(struct wl_display * display, struct wl_event_queue * queue)¶

Dispatch pending events in an event queue

Parameters:	display – 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.

Memberof:	wl_display
Since:	1.0.2

int wl_display_dispatch(struct wl_display * display)¶

Process incoming events

Parameters:	display – 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 @ref wl_display_dispatch_pending().

Sa:	wl_display_dispatch_pending(), wl_display_dispatch_queue(),

wl_display_read_events()

Memberof:	wl_display

int wl_display_dispatch_pending(struct wl_display * display)¶

Dispatch default queue events without reading from the display fd

Parameters:	display – 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.

Sa:	wl_display_dispatch(), wl_display_dispatch_queue(),

wl_display_flush()

Memberof:	wl_display

int wl_display_get_error(struct wl_display * display)¶

Retrieve the last error that occurred on a display

Parameters:	display – The display context object
Returns:	The last error that occurred on @c 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 @b fatal. If this function returns non-zero the display

can no longer be used.

Memberof:	wl_display

uint32_t wl_display_get_protocol_error(struct wl_display * display, const struct wl_interface ** interface, uint32_t * id)¶

Retrieves the information about a protocol error:

Parameters:	display – 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);

}

…

Memberof:	wl_display

int wl_display_flush(struct wl_display * display)¶

Send all buffered requests on the display to the server

Parameters:	display – 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.

Memberof:	wl_display

void wl_proxy_set_user_data(struct wl_proxy * proxy, void * user_data)¶

Set the user data associated with a proxy

Parameters:	proxy – The proxy object user_data – The data to be associated with proxy

Set the user data associated with @c proxy. When events for this proxy are received, @c user_data will be supplied to its listener.

Memberof:	wl_proxy

void * wl_proxy_get_user_data(struct wl_proxy * proxy)¶

Get the user data associated with a proxy

Parameters:	proxy – The proxy object
Returns:	The user data associated with proxy
Memberof:	wl_proxy

uint32_t wl_proxy_get_version(struct wl_proxy * proxy)¶

Get the protocol object version of a proxy object

Parameters:	proxy – The proxy object
Returns:	The protocol object version of the proxy or 0

Gets the protocol object version of a proxy object, or 0 if the proxy was created with unversioned API.

A returned value of 0 means that no version information is available, so the caller must make safe assumptions about the object’s real version.

wl_display’s version will always return 0.

Memberof:	wl_proxy

uint32_t wl_proxy_get_id(struct wl_proxy * proxy)¶

Get the id of a proxy object

Parameters:	proxy – The proxy object
Returns:	The id the object associated with the proxy
Memberof:	wl_proxy

const char * wl_proxy_get_class(struct wl_proxy * proxy)¶

Get the interface name (class) of a proxy object

Parameters:	proxy – The proxy object
Returns:	The interface name of the object associated with the proxy
Memberof:	wl_proxy

void wl_proxy_set_queue(struct wl_proxy * proxy, struct wl_event_queue * queue)¶

Assign a proxy to an event queue

Parameters:	proxy – The proxy object queue – The event queue that will handle this proxy or NULL

Assign proxy to event queue. Events coming from @c proxy will be queued in @c queue from now. If queue is NULL, then the display’s default queue is set to the proxy.

Note:	By default, the queue set in proxy is the one inherited from parent.
Sa:	wl_display_dispatch_queue()
Memberof:	wl_proxy

void * wl_proxy_create_wrapper(void * proxy)¶

Create a proxy wrapper for making queue assignments thread-safe

Parameters:	proxy – The proxy object to be wrapped
Returns:	A proxy wrapper for the given proxy or NULL on failure

A proxy wrapper is type of ‘struct wl_proxy’ instance that can be used when sending requests instead of using the original proxy. A proxy wrapper does not have an implementation or dispatcher, and events received on the object is still emitted on the original proxy. Trying to set an implementation or dispatcher will have no effect but result in a warning being logged.

Setting the proxy queue of the proxy wrapper will make new objects created using the proxy wrapper use the set proxy queue. Even though there is no implementation nor dispatcher, the proxy queue can be changed. This will affect the default queue of new objects created by requests sent via the proxy wrapper.

A proxy wrapper can only be destroyed using wl_proxy_wrapper_destroy().

A proxy wrapper must be destroyed before the proxy it was created from.

If a user reads and dispatches events on more than one thread, it is necessary to use a proxy wrapper when sending requests on objects when the intention is that a newly created proxy is to use a proxy queue different from the proxy the request was sent on, as creating the new proxy and then setting the queue is not thread safe.

For example, a module that runs using its own proxy queue that needs to do display roundtrip must wrap the wl_display proxy object before sending the wl_display.sync request. For example:

struct wl_event_queue *queue = ...;
struct wl_display *wrapped_display;
struct wl_callback *callback;

wrapped_display = wl_proxy_create_wrapper(display);
wl_proxy_set_queue((struct wl_proxy *) wrapped_display, queue);
callback = wl_display_sync(wrapped_display);
wl_proxy_wrapper_destroy(wrapped_display);
wl_callback_add_listener(callback, ...);

Memberof:	wl_proxy

void wl_proxy_wrapper_destroy(void * proxy_wrapper)¶

Destroy a proxy wrapper

Parameters:	proxy_wrapper – The proxy wrapper to be destroyed
Memberof:	wl_proxy