<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
  <!ENTITY doxygen SYSTEM "ClientAPI.xml">
%BOOK_ENTITIES;
]>
<appendix id="sect-Library-Client">
  <title>Client API</title>
  <section><title>Introduction</title>
  <para>
    The open-source reference implementation of Wayland protocol is
    split in two C libraries, libwayland-client and <link
    linkend="sect-Library-Server">libwayland-server</link>. Their main
    responsibility is to handle the Inter-process communication
    (<emphasis>IPC</emphasis>) with each other, therefore guaranteeing
    the protocol objects marshaling and messages synchronization.
  </para>
  <para>
    A client uses libwayland-client to communicate with one or more
    wayland servers. A <link
    linkend="Client-classwl__display">wl_display</link> object is
    created and manages each open connection to a server. At least one
    <link linkend="Client-classwl__event__queue">wl_event_queue</link>
    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.
  </para>
  <para>
    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.
  </para>
  <para>
    The library only provides low-level access to the wayland objects.
    Each object created by the client is represented by a <link
    linkend="Client-classwl__proxy">wl_proxy</link> 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 <link
    linkend="Client-structwl__interface">wl_interface</link> object,
    which is generated from the xml and identifies the object's class
    and can be used for introspection into the messages and events.
  </para>
  <para>
    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 <link
    linkend="appe-Wayland-Protocol">Wayland protocols</link>. For
    instance the C header file generated from the xml defines the
    following inline function to transmit the <link
    linkend="protocol-spec-wl_surface-request-attach">wl_surface::attach</link>
    message:
  </para>
  <programlisting>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);
}</programlisting>
  <para>
    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 <link
    linkend="protocol-spec-wl_surface-event-enter">wl_surface::enter</link>
    event defines this pointer in the wl_surface_listener object:
  </para>
  <programlisting>struct wl_surface_listener {
  void (*enter)(void *data, struct wl_surface *, struct wl_output *);
  ...
}</programlisting>
  <para>
  </para>
  </section>
  &doxygen;
</appendix>