Warning: That file was not part of the compilation database. It may have many parsing errors.

1/*
2 * Copyright © 2008 Kristian Høgsberg
3 *
4 * Permission to use, copy, modify, distribute, and sell this software and its
5 * documentation for any purpose is hereby granted without fee, provided that
6 * the above copyright notice appear in all copies and that both that copyright
7 * notice and this permission notice appear in supporting documentation, and
8 * that the name of the copyright holders not be used in advertising or
9 * publicity pertaining to distribution of the software without specific,
10 * written prior permission. The copyright holders make no representations
11 * about the suitability of this software for any purpose. It is provided "as
12 * is" without express or implied warranty.
13 *
14 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
15 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
16 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
17 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
18 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
19 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
20 * OF THIS SOFTWARE.
21 */
22
23#ifndef WAYLAND_CLIENT_H
24#define WAYLAND_CLIENT_H
25
26#include "wayland-util.h"
27#include "wayland-version.h"
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33/** \class wl_proxy
34 *
35 * \brief Represents a protocol object on the client side.
36 *
37 * A wl_proxy acts as a client side proxy to an object existing in the
38 * compositor. The proxy is responsible for converting requests made by the
39 * clients with \ref wl_proxy_marshal() into Wayland's wire format. Events
40 * coming from the compositor are also handled by the proxy, which will in
41 * turn call the handler set with \ref wl_proxy_add_listener().
42 *
43 * \note With the exception of function \ref wl_proxy_set_queue(), functions
44 * accessing a \ref wl_proxy are not normally used by client code. Clients
45 * should normally use the higher level interface generated by the scanner to
46 * interact with compositor objects.
47 *
48 */
49struct wl_proxy;
50
51/** \class wl_display
52 *
53 * \brief Represents a connection to the compositor and acts as a proxy to
54 * the wl_display singleton object.
55 *
56 * A \ref wl_display object represents a client connection to a Wayland
57 * compositor. It is created with either \ref wl_display_connect() or
58 * \ref wl_display_connect_to_fd(). A connection is terminated using
59 * \ref wl_display_disconnect().
60 *
61 * A \ref wl_display is also used as the \ref wl_proxy for the \ref wl_display
62 * singleton object on the compositor side.
63 *
64 * A \ref wl_display object handles all the data sent from and to the
65 * compositor. When a \ref wl_proxy marshals a request, it will write its wire
66 * representation to the display's write buffer. The data is sent to the
67 * compositor when the client calls \ref wl_display_flush().
68 *
69 * Incoming data is handled in two steps: queueing and dispatching. In the
70 * queue step, the data coming from the display fd is interpreted and
71 * added to a queue. On the dispatch step, the handler for the incoming
72 * event set by the client on the corresponding \ref wl_proxy is called.
73 *
74 * A \ref wl_display has at least one event queue, called the <em>main
75 * queue</em>. Clients can create additional event queues with \ref
76 * wl_display_create_queue() and assign \ref wl_proxy's to it. Events
77 * occurring in a particular proxy are always queued in its assigned queue.
78 * A client can ensure that a certain assumption, such as holding a lock
79 * or running from a given thread, is true when a proxy event handler is
80 * called by assigning that proxy to an event queue and making sure that
81 * this queue is only dispatched when the assumption holds.
82 *
83 * The main queue is dispatched by calling \ref wl_display_dispatch().
84 * This will dispatch any events queued on the main queue and attempt
85 * to read from the display fd if its empty. Events read are then queued
86 * on the appropriate queues according to the proxy assignment. Calling
87 * that function makes the calling thread the <em>main thread</em>.
88 *
89 * A user created queue is dispatched with \ref wl_display_dispatch_queue().
90 * If there are no events to dispatch this function will block. If this
91 * is called by the main thread, this will attempt to read data from the
92 * display fd and queue any events on the appropriate queues. If calling
93 * from any other thread, the function will block until the main thread
94 * queues an event on the queue being dispatched.
95 *
96 * A real world example of event queue usage is Mesa's implementation of
97 * eglSwapBuffers() for the Wayland platform. This function might need
98 * to block until a frame callback is received, but dispatching the main
99 * queue could cause an event handler on the client to start drawing
100 * again. This problem is solved using another event queue, so that only
101 * the events handled by the EGL code are dispatched during the block.
102 *
103 * This creates a problem where the main thread dispatches a non-main
104 * queue, reading all the data from the display fd. If the application
105 * would call \em poll(2) after that it would block, even though there
106 * might be events queued on the main queue. Those events should be
107 * dispatched with \ref wl_display_dispatch_pending() before
108 * flushing and blocking.
109 */
110struct wl_display;
111
112/** \class wl_event_queue
113 *
114 * \brief A queue for \ref wl_proxy object events.
115 *
116 * Event queues allows the events on a display to be handled in a thread-safe
117 * manner. See \ref wl_display for details.
118 *
119 */
120struct wl_event_queue;
121
122void wl_event_queue_destroy(struct wl_event_queue *queue);
123
124void wl_proxy_marshal(struct wl_proxy *p, uint32_t opcode, ...);
125void wl_proxy_marshal_array(struct wl_proxy *p, uint32_t opcode,
126 union wl_argument *args);
127struct wl_proxy *wl_proxy_create(struct wl_proxy *factory,
128 const struct wl_interface *interface);
129struct wl_proxy *wl_proxy_marshal_constructor(struct wl_proxy *proxy,
130 uint32_t opcode,
131 const struct wl_interface *interface,
132 ...);
133struct wl_proxy *
134wl_proxy_marshal_array_constructor(struct wl_proxy *proxy,
135 uint32_t opcode, union wl_argument *args,
136 const struct wl_interface *interface);
137
138void wl_proxy_destroy(struct wl_proxy *proxy);
139int wl_proxy_add_listener(struct wl_proxy *proxy,
140 void (**implementation)(void), void *data);
141const void *wl_proxy_get_listener(struct wl_proxy *proxy);
142int wl_proxy_add_dispatcher(struct wl_proxy *proxy,
143 wl_dispatcher_func_t dispatcher_func,
144 const void * dispatcher_data, void *data);
145void wl_proxy_set_user_data(struct wl_proxy *proxy, void *user_data);
146void *wl_proxy_get_user_data(struct wl_proxy *proxy);
147uint32_t wl_proxy_get_id(struct wl_proxy *proxy);
148const char *wl_proxy_get_class(struct wl_proxy *proxy);
149void wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue);
150
151#include "wayland-client-protocol.h"
152
153struct wl_display *wl_display_connect(const char *name);
154struct wl_display *wl_display_connect_to_fd(int fd);
155void wl_display_disconnect(struct wl_display *display);
156int wl_display_get_fd(struct wl_display *display);
157int wl_display_dispatch(struct wl_display *display);
158int wl_display_dispatch_queue(struct wl_display *display,
159 struct wl_event_queue *queue);
160int wl_display_dispatch_queue_pending(struct wl_display *display,
161 struct wl_event_queue *queue);
162int wl_display_dispatch_pending(struct wl_display *display);
163int wl_display_get_error(struct wl_display *display);
164
165int wl_display_flush(struct wl_display *display);
166int wl_display_roundtrip(struct wl_display *display);
167struct wl_event_queue *wl_display_create_queue(struct wl_display *display);
168
169int wl_display_prepare_read_queue(struct wl_display *display,
170 struct wl_event_queue *queue);
171int wl_display_prepare_read(struct wl_display *display);
172void wl_display_cancel_read(struct wl_display *display);
173int wl_display_read_events(struct wl_display *display);
174
175void wl_log_set_handler_client(wl_log_func_t handler);
176
177#ifdef __cplusplus
178}
179#endif
180
181#endif
182

Warning: That file was not part of the compilation database. It may have many parsing errors.