1*84e872a0SLloyd Pique<?xml version='1.0' encoding='utf-8' ?> 2*84e872a0SLloyd Pique<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ 3*84e872a0SLloyd Pique <!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent"> 4*84e872a0SLloyd Pique <!ENTITY doxygen SYSTEM "ClientAPI.xml"> 5*84e872a0SLloyd Pique%BOOK_ENTITIES; 6*84e872a0SLloyd Pique]> 7*84e872a0SLloyd Pique<appendix id="sect-Library-Client"> 8*84e872a0SLloyd Pique <title>Client API</title> 9*84e872a0SLloyd Pique <section><title>Introduction</title> 10*84e872a0SLloyd Pique <para> 11*84e872a0SLloyd Pique The open-source reference implementation of Wayland protocol is 12*84e872a0SLloyd Pique split in two C libraries, libwayland-client and <link 13*84e872a0SLloyd Pique linkend="sect-Library-Server">libwayland-server</link>. Their main 14*84e872a0SLloyd Pique responsibility is to handle the Inter-process communication 15*84e872a0SLloyd Pique (<emphasis>IPC</emphasis>) with each other, therefore guaranteeing 16*84e872a0SLloyd Pique the protocol objects marshaling and messages synchronization. 17*84e872a0SLloyd Pique </para> 18*84e872a0SLloyd Pique <para> 19*84e872a0SLloyd Pique A client uses libwayland-client to communicate with one or more 20*84e872a0SLloyd Pique wayland servers. A <link 21*84e872a0SLloyd Pique linkend="Client-classwl__display">wl_display</link> object is 22*84e872a0SLloyd Pique created and manages each open connection to a server. At least one 23*84e872a0SLloyd Pique <link linkend="Client-classwl__event__queue">wl_event_queue</link> 24*84e872a0SLloyd Pique object is created for each wl_display, this holds events as they 25*84e872a0SLloyd Pique are received from the server until they can be 26*84e872a0SLloyd Pique processed. Multi-threading is supported by creating an additional 27*84e872a0SLloyd Pique wl_event_queue for each additional thread, each object can have 28*84e872a0SLloyd Pique it's events placed in a particular queue, so potentially a 29*84e872a0SLloyd Pique different thread could be made to handle the events for each 30*84e872a0SLloyd Pique object created. 31*84e872a0SLloyd Pique </para> 32*84e872a0SLloyd Pique <para> 33*84e872a0SLloyd Pique Though some convenience functions are provided, libwayland-client 34*84e872a0SLloyd Pique is designed to allow the calling code to wait for events, so that 35*84e872a0SLloyd Pique different polling mechanisms can be used. A file descriptor is 36*84e872a0SLloyd Pique provided, when it becomes ready for reading the calling code can 37*84e872a0SLloyd Pique ask libwayland-client to read the available events from it into 38*84e872a0SLloyd Pique the wl_event_queue objects. 39*84e872a0SLloyd Pique </para> 40*84e872a0SLloyd Pique <para> 41*84e872a0SLloyd Pique The library only provides low-level access to the wayland objects. 42*84e872a0SLloyd Pique Each object created by the client is represented by a <link 43*84e872a0SLloyd Pique linkend="Client-classwl__proxy">wl_proxy</link> object that this 44*84e872a0SLloyd Pique library creates. This includes the id that is actually 45*84e872a0SLloyd Pique communicated over the socket to the server, a void* data pointer 46*84e872a0SLloyd Pique that is intended to point at a client's representation of the 47*84e872a0SLloyd Pique object, and a pointer to a static <link 48*84e872a0SLloyd Pique linkend="Client-structwl__interface">wl_interface</link> object, 49*84e872a0SLloyd Pique which is generated from the xml and identifies the object's class 50*84e872a0SLloyd Pique and can be used for introspection into the messages and events. 51*84e872a0SLloyd Pique </para> 52*84e872a0SLloyd Pique <para> 53*84e872a0SLloyd Pique Messages are sent by calling wl_proxy_marshal. This will write a 54*84e872a0SLloyd Pique message to the socket, by using the message id and the 55*84e872a0SLloyd Pique wl_interface to identify the types of each argument and convert 56*84e872a0SLloyd Pique them into stream format. Most software will call type-safe 57*84e872a0SLloyd Pique wrappers generated from the xml description of the <link 58*84e872a0SLloyd Pique linkend="appe-Wayland-Protocol">Wayland protocols</link>. For 59*84e872a0SLloyd Pique instance the C header file generated from the xml defines the 60*84e872a0SLloyd Pique following inline function to transmit the <link 61*84e872a0SLloyd Pique linkend="protocol-spec-wl_surface-request-attach">wl_surface::attach</link> 62*84e872a0SLloyd Pique message: 63*84e872a0SLloyd Pique </para> 64*84e872a0SLloyd Pique <programlisting>static inline void 65*84e872a0SLloyd Piquewl_surface_attach(struct wl_surface *wl_surface, struct wl_buffer *buffer, int32_t x, int32_t y) 66*84e872a0SLloyd Pique{ 67*84e872a0SLloyd Pique wl_proxy_marshal((struct wl_proxy *) wl_surface, WL_SURFACE_ATTACH, buffer, x, y); 68*84e872a0SLloyd Pique}</programlisting> 69*84e872a0SLloyd Pique <para> 70*84e872a0SLloyd Pique Events (messages from the server) are handled by calling a 71*84e872a0SLloyd Pique "dispatcher" callback the client stores in the wl_proxy for each 72*84e872a0SLloyd Pique event. A language binding for a string-based interpreter, such as 73*84e872a0SLloyd Pique CPython, might have a dispatcher that uses the event name from the 74*84e872a0SLloyd Pique wl_interface to identify the function to call. The default 75*84e872a0SLloyd Pique dispatcher uses the message id number to index an array of 76*84e872a0SLloyd Pique functions pointers, called a wl_listener, and the wl_interface to 77*84e872a0SLloyd Pique convert data from the stream into arguments to the function. The 78*84e872a0SLloyd Pique C header file generated from the xml defines a per-class structure 79*84e872a0SLloyd Pique that forces the function pointers to be of the correct type, for 80*84e872a0SLloyd Pique instance the <link 81*84e872a0SLloyd Pique linkend="protocol-spec-wl_surface-event-enter">wl_surface::enter</link> 82*84e872a0SLloyd Pique event defines this pointer in the wl_surface_listener object: 83*84e872a0SLloyd Pique </para> 84*84e872a0SLloyd Pique <programlisting>struct wl_surface_listener { 85*84e872a0SLloyd Pique void (*enter)(void *data, struct wl_surface *, struct wl_output *); 86*84e872a0SLloyd Pique ... 87*84e872a0SLloyd Pique}</programlisting> 88*84e872a0SLloyd Pique <para> 89*84e872a0SLloyd Pique </para> 90*84e872a0SLloyd Pique </section> 91*84e872a0SLloyd Pique &doxygen; 92*84e872a0SLloyd Pique</appendix> 93