Provided by: libwayland-doc_1.21.0-1_all bug

NAME

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

SYNOPSIS

       #include <wayland-client-core.h>

   Public Member Functions
       struct wl_client * wl_client_create (struct wl_display *display, int fd)
       struct wl_display * wl_display_create (void)
       void wl_display_destroy (struct wl_display *display)
       void wl_display_set_global_filter (struct wl_display *display,
           wl_display_global_filter_func_t filter, void *data)
       uint32_t wl_display_get_serial (struct wl_display *display)
       uint32_t wl_display_next_serial (struct wl_display *display)
       void wl_display_destroy_clients (struct wl_display *display)
       int wl_display_add_socket_fd (struct wl_display *display, int sock_fd)
       int wl_display_add_socket (struct wl_display *display, const char *name)
       struct wl_protocol_logger * wl_display_add_protocol_logger (struct wl_display *display,
           wl_protocol_logger_func_t func, void *user_data)
       uint32_t * wl_display_add_shm_format (struct wl_display *display, uint32_t format)
       struct wl_list * wl_display_get_client_list (struct wl_display *display)
       struct wl_event_queue * wl_display_create_queue (struct wl_display *display)
       struct wl_display * wl_display_connect_to_fd (int fd)
       struct wl_display * wl_display_connect (const char *name)
       void wl_display_disconnect (struct wl_display *display)
       int wl_display_get_fd (struct wl_display *display)
       int wl_display_roundtrip_queue (struct wl_display *display, struct wl_event_queue *queue)
       int wl_display_roundtrip (struct wl_display *display)
       int wl_display_read_events (struct wl_display *display)
       int wl_display_prepare_read_queue (struct wl_display *display, struct wl_event_queue
           *queue)
       int wl_display_prepare_read (struct wl_display *display)
       void wl_display_cancel_read (struct wl_display *display)
       int wl_display_dispatch_queue (struct wl_display *display, struct wl_event_queue *queue)
       int wl_display_dispatch_queue_pending (struct wl_display *display, struct wl_event_queue
           *queue)
       int wl_display_dispatch (struct wl_display *display)
       int wl_display_dispatch_pending (struct wl_display *display)
       int wl_display_get_error (struct wl_display *display)
       uint32_t wl_display_get_protocol_error (struct wl_display *display, const struct
           wl_interface **interface, uint32_t *id)
       int wl_display_flush (struct wl_display *display)

   Data Fields
       struct wl_event_loop * loop
       int run
       uint32_t id
       uint32_t serial
       struct wl_list registry_resource_list
       struct wl_list global_list
       struct wl_list socket_list
       struct wl_list client_list
       struct wl_list protocol_loggers
       struct wl_priv_signal destroy_signal
       struct wl_priv_signal create_client_signal
       struct wl_array additional_shm_formats
       wl_display_global_filter_func_t global_filter
       void * global_filter_data
       int terminate_efd
       struct wl_event_source * term_source

Detailed Description

       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 wl_display_connect() or wl_display_connect_to_fd(). A connection is terminated
       using wl_display_disconnect().

       A wl_display is also used as the 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 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 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 wl_proxy is
       called.

       A wl_display has at least one event queue, called the default queue. Clients can create
       additional event queues with wl_display_create_queue() and assign 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 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 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 poll(2) after that it would block, even
       though there might be events queued on the default queue. Those events should be
       dispatched with wl_display_dispatch_pending() or wl_display_dispatch_queue_pending()
       before flushing and blocking.

Member Function Documentation

   struct wl_client * wl_client_create (struct wl_display * display, int fd)
       Create a client for the given file descriptor

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

   struct wl_protocol_logger * wl_display_add_protocol_logger (struct wl_display * display,
       wl_protocol_logger_func_t func, 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.

       Parameters
           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

   uint32_t * wl_display_add_shm_format (struct wl_display * display, uint32_t format)
       Add support for a wl_shm pixel format

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

   int wl_display_add_socket (struct wl_display * display, const char * name)
       Add a socket to Wayland display for the clients to connect.

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

       Returns
           0 if success. -1 if failed.

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

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

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

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

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

   int wl_display_add_socket_fd (struct wl_display * display, int sock_fd)
       Add a socket with an existing fd to Wayland display for the clients to connect.

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

   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.

       See also
           wl_display_prepare_read(), wl_display_read_events()

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

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

   struct wl_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.

   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.

   void wl_display_destroy (struct wl_display * display)
       Destroy Wayland display object.

       Parameters
           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

   void wl_display_destroy_clients (struct wl_display * display)
       Destroy all clients connected to the display

       Parameters
           display The display object

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

   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 display and free all resources associated with it.

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

       See also
           wl_display_dispatch_pending(), wl_display_dispatch_queue(), wl_display_read_events()

   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.

       See also
           wl_display_dispatch(), wl_display_dispatch_queue(), wl_display_flush()

   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.

       See also
           wl_display_dispatch(), wl_display_dispatch_pending(),
           wl_display_dispatch_queue_pending(), wl_display_prepare_read_queue()

   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.

       Since
           1.0.2

   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.

   struct wl_list * wl_display_get_client_list (struct wl_display * display)
       Get the list of currently connected clients

       Parameters
           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()

           wl_client_get_link()

           wl_client_from_link()

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

   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.

   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);
       }

       ...

   uint32_t wl_display_get_serial (struct wl_display * display)
       Get the current serial number

       Parameters
           display The display object

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

   uint32_t wl_display_next_serial (struct wl_display * display)
       Get the next serial number

       Parameters
           display The display object

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

   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.

       See also
           wl_display_prepare_read_queue

   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.

       See also
           wl_display_cancel_read(), wl_display_read_events(), wl_display_prepare_read()

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

       See also
           wl_display_prepare_read(), wl_display_cancel_read(), wl_display_dispatch_pending(),
           wl_display_dispatch()

   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.

   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.

       See also
           wl_display_roundtrip()

   void wl_display_set_global_filter (struct wl_display * display,
       wl_display_global_filter_func_t filter, void * data)
       Set a filter function for global objects

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

       Returns
           None.

       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.

Field Documentation

   struct wl_array wl_display::additional_shm_formats
   struct wl_list wl_display::client_list
   struct wl_priv_signal wl_display::create_client_signal
   struct wl_priv_signal wl_display::destroy_signal
   wl_display_global_filter_func_t wl_display::global_filter
   void* wl_display::global_filter_data
   struct wl_list wl_display::global_list
   uint32_t wl_display::id
   struct wl_event_loop* wl_display::loop
   struct wl_list wl_display::protocol_loggers
   struct wl_list wl_display::registry_resource_list
   int wl_display::run
   uint32_t wl_display::serial
   struct wl_list wl_display::socket_list
   struct wl_event_source* wl_display::term_source
   int wl_display::terminate_efd

Author

       Generated automatically by Doxygen for Wayland from the source code.