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