Client API
==========

Client Introduction
-------------------

The open-source reference implementation of Wayland protocol is split in two C
libraries, libwayland-client and :ref:`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 :type:`wl_display` object is created and manages each open
connection to a server. At least one :type:`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 :type:`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 :type:`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 :func:`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
:ref:`Wayland protocol specification`. For instance the C header file generated
from the xml defines the following inline function to transmit the
:func:`wl_surface_attach` message:

.. code-block:: c

   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 :type:`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 :func:`wl_surface_enter` event
defines this pointer in the :type:`wl_surface_listener` object:

.. code-block:: c 

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

.. c:autodoc:: src/wayland-client-core.h src/wayland-client.c
   :compat: javadoc-liberal