1/*
2 * Copyright (C) 2001-2004 Bart Massey and Jamey Sharp.
3 * All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
19 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 *
22 * Except as contained in this notice, the names of the authors or their
23 * institutions shall not be used in advertising or otherwise to promote the
24 * sale, use or other dealings in this Software without prior written
25 * authorization from the authors.
26 */
27
28#ifndef __XCBEXT_H
29#define __XCBEXT_H
30
31#include "xcb.h"
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37/* xcb_ext.c */
38
39struct xcb_extension_t {
40 const char *name;
41 int global_id;
42};
43
44
45/* xcb_out.c */
46
47typedef struct {
48 size_t count;
49 xcb_extension_t *ext;
50 uint8_t opcode;
51 uint8_t isvoid;
52} xcb_protocol_request_t;
53
54enum xcb_send_request_flags_t {
55 XCB_REQUEST_CHECKED = 1 << 0,
56 XCB_REQUEST_RAW = 1 << 1,
57 XCB_REQUEST_DISCARD_REPLY = 1 << 2,
58 XCB_REQUEST_REPLY_FDS = 1 << 3
59};
60
61/**
62 * @brief Send a request to the server.
63 * @param c The connection to the X server.
64 * @param flags A combination of flags from the xcb_send_request_flags_t enumeration.
65 * @param vector Data to send; must have two iovecs before start for internal use.
66 * @param request Information about the request to be sent.
67 * @return The request's sequence number on success, 0 otherwise.
68 *
69 * This function sends a new request to the X server. The data of the request is
70 * given as an array of @c iovecs in the @p vector argument. The length of that
71 * array and the necessary management information are given in the @p request
72 * argument.
73 *
74 * When this function returns, the request might or might not be sent already.
75 * Use xcb_flush() to make sure that it really was sent.
76 *
77 * Please note that this function is not the preferred way for sending requests.
78 * It's better to use the generated wrapper functions.
79 *
80 * Please note that xcb might use index -1 and -2 of the @p vector array internally,
81 * so they must be valid!
82 */
83unsigned int xcb_send_request(xcb_connection_t *c, int flags, struct iovec *vector, const xcb_protocol_request_t *request);
84
85/**
86 * @brief Send a request to the server.
87 * @param c The connection to the X server.
88 * @param flags A combination of flags from the xcb_send_request_flags_t enumeration.
89 * @param vector Data to send; must have two iovecs before start for internal use.
90 * @param request Information about the request to be sent.
91 * @param num_fds Number of additional file descriptors to send to the server
92 * @param fds Additional file descriptors that should be send to the server.
93 * @return The request's sequence number on success, 0 otherwise.
94 *
95 * This function sends a new request to the X server. The data of the request is
96 * given as an array of @c iovecs in the @p vector argument. The length of that
97 * array and the necessary management information are given in the @p request
98 * argument.
99 *
100 * If @p num_fds is non-zero, @p fds points to an array of file descriptors that
101 * will be sent to the X server along with this request. After this function
102 * returns, all file descriptors sent are owned by xcb and will be closed
103 * eventually.
104 *
105 * When this function returns, the request might or might not be sent already.
106 * Use xcb_flush() to make sure that it really was sent.
107 *
108 * Please note that this function is not the preferred way for sending requests.
109 *
110 * Please note that xcb might use index -1 and -2 of the @p vector array internally,
111 * so they must be valid!
112 */
113unsigned int xcb_send_request_with_fds(xcb_connection_t *c, int flags, struct iovec *vector,
114 const xcb_protocol_request_t *request, unsigned int num_fds, int *fds);
115
116/**
117 * @brief Send a request to the server, with 64-bit sequence number returned.
118 * @param c The connection to the X server.
119 * @param flags A combination of flags from the xcb_send_request_flags_t enumeration.
120 * @param vector Data to send; must have two iovecs before start for internal use.
121 * @param request Information about the request to be sent.
122 * @return The request's sequence number on success, 0 otherwise.
123 *
124 * This function sends a new request to the X server. The data of the request is
125 * given as an array of @c iovecs in the @p vector argument. The length of that
126 * array and the necessary management information are given in the @p request
127 * argument.
128 *
129 * When this function returns, the request might or might not be sent already.
130 * Use xcb_flush() to make sure that it really was sent.
131 *
132 * Please note that this function is not the preferred way for sending requests.
133 * It's better to use the generated wrapper functions.
134 *
135 * Please note that xcb might use index -1 and -2 of the @p vector array internally,
136 * so they must be valid!
137 */
138uint64_t xcb_send_request64(xcb_connection_t *c, int flags, struct iovec *vector, const xcb_protocol_request_t *request);
139
140/**
141 * @brief Send a request to the server, with 64-bit sequence number returned.
142 * @param c The connection to the X server.
143 * @param flags A combination of flags from the xcb_send_request_flags_t enumeration.
144 * @param vector Data to send; must have two iovecs before start for internal use.
145 * @param request Information about the request to be sent.
146 * @param num_fds Number of additional file descriptors to send to the server
147 * @param fds Additional file descriptors that should be send to the server.
148 * @return The request's sequence number on success, 0 otherwise.
149 *
150 * This function sends a new request to the X server. The data of the request is
151 * given as an array of @c iovecs in the @p vector argument. The length of that
152 * array and the necessary management information are given in the @p request
153 * argument.
154 *
155 * If @p num_fds is non-zero, @p fds points to an array of file descriptors that
156 * will be sent to the X server along with this request. After this function
157 * returns, all file descriptors sent are owned by xcb and will be closed
158 * eventually.
159 *
160 * When this function returns, the request might or might not be sent already.
161 * Use xcb_flush() to make sure that it really was sent.
162 *
163 * Please note that this function is not the preferred way for sending requests.
164 * It's better to use the generated wrapper functions.
165 *
166 * Please note that xcb might use index -1 and -2 of the @p vector array internally,
167 * so they must be valid!
168 */
169uint64_t xcb_send_request_with_fds64(xcb_connection_t *c, int flags, struct iovec *vector,
170 const xcb_protocol_request_t *request, unsigned int num_fds, int *fds);
171
172/**
173 * @brief Send a file descriptor to the server in the next call to xcb_send_request.
174 * @param c The connection to the X server.
175 * @param fd The file descriptor to send.
176 *
177 * After this function returns, the file descriptor given is owned by xcb and
178 * will be closed eventually.
179 *
180 * @deprecated This function cannot be used in a thread-safe way. Two threads
181 * that run xcb_send_fd(); xcb_send_request(); could mix up their file
182 * descriptors. Instead, xcb_send_request_with_fds() should be used.
183 */
184void xcb_send_fd(xcb_connection_t *c, int fd);
185
186/**
187 * @brief Take over the write side of the socket
188 * @param c The connection to the X server.
189 * @param return_socket Callback function that will be called when xcb wants
190 * to use the socket again.
191 * @param closure Argument to the callback function.
192 * @param flags A combination of flags from the xcb_send_request_flags_t enumeration.
193 * @param sent Location to the sequence number of the last sequence request.
194 * Must not be NULL.
195 * @return 1 on success, else 0.
196 *
197 * xcb_take_socket allows external code to ask XCB for permission to
198 * take over the write side of the socket and send raw data with
199 * xcb_writev. xcb_take_socket provides the sequence number of the last
200 * request XCB sent. The caller of xcb_take_socket must supply a
201 * callback which XCB can call when it wants the write side of the
202 * socket back to make a request. This callback synchronizes with the
203 * external socket owner and flushes any output queues if appropriate.
204 * If you are sending requests which won't cause a reply, please note the
205 * comment for xcb_writev which explains some sequence number wrap issues.
206 *
207 * All replies that are generated while the socket is owned externally have
208 * @p flags applied to them. For example, use XCB_REQUEST_CHECK if you don't
209 * want errors to go to xcb's normal error handling, but instead having to be
210 * picked up via xcb_wait_for_reply(), xcb_poll_for_reply() or
211 * xcb_request_check().
212 */
213int xcb_take_socket(xcb_connection_t *c, void (*return_socket)(void *closure), void *closure, int flags, uint64_t *sent);
214
215/**
216 * @brief Send raw data to the X server.
217 * @param c The connection to the X server.
218 * @param vector Array of data to be sent.
219 * @param count Number of entries in @p vector.
220 * @param requests Number of requests that are being sent.
221 * @return 1 on success, else 0.
222 *
223 * You must own the write-side of the socket (you've called
224 * xcb_take_socket, and haven't returned from return_socket yet) to call
225 * xcb_writev. Also, the iovec must have at least 1 byte of data in it.
226 * You have to make sure that xcb can detect sequence number wraps correctly.
227 * This means that the first request you send after xcb_take_socket must cause a
228 * reply (e.g. just insert a GetInputFocus request). After every (1 << 16) - 1
229 * requests without a reply, you have to insert a request which will cause a
230 * reply. You can again use GetInputFocus for this. You do not have to wait for
231 * any of the GetInputFocus replies, but can instead handle them via
232 * xcb_discard_reply().
233 */
234int xcb_writev(xcb_connection_t *c, struct iovec *vector, int count, uint64_t requests);
235
236
237/* xcb_in.c */
238
239/**
240 * @brief Wait for the reply of a given request.
241 * @param c The connection to the X server.
242 * @param request Sequence number of the request as returned by xcb_send_request().
243 * @param e Location to store errors in, or NULL. Ignored for unchecked requests.
244 *
245 * Returns the reply to the given request or returns null in the event of
246 * errors. Blocks until the reply or error for the request arrives, or an I/O
247 * error occurs.
248 */
249void *xcb_wait_for_reply(xcb_connection_t *c, unsigned int request, xcb_generic_error_t **e);
250
251/**
252 * @brief Wait for the reply of a given request, with 64-bit sequence number
253 * @param c The connection to the X server.
254 * @param request 64-bit sequence number of the request as returned by xcb_send_request64().
255 * @param e Location to store errors in, or NULL. Ignored for unchecked requests.
256 *
257 * Returns the reply to the given request or returns null in the event of
258 * errors. Blocks until the reply or error for the request arrives, or an I/O
259 * error occurs.
260 *
261 * Unlike its xcb_wait_for_reply() counterpart, the given sequence number is not
262 * automatically "widened" to 64-bit.
263 */
264void *xcb_wait_for_reply64(xcb_connection_t *c, uint64_t request, xcb_generic_error_t **e);
265
266/**
267 * @brief Poll for the reply of a given request.
268 * @param c The connection to the X server.
269 * @param request Sequence number of the request as returned by xcb_send_request().
270 * @param reply Location to store the reply in, must not be NULL.
271 * @param error Location to store errors in, or NULL. Ignored for unchecked requests.
272 * @return 1 when the reply to the request was returned, else 0.
273 *
274 * Checks if the reply to the given request already received. Does not block.
275 */
276int xcb_poll_for_reply(xcb_connection_t *c, unsigned int request, void **reply, xcb_generic_error_t **error);
277
278/**
279 * @brief Poll for the reply of a given request, with 64-bit sequence number.
280 * @param c The connection to the X server.
281 * @param request 64-bit sequence number of the request as returned by xcb_send_request().
282 * @param reply Location to store the reply in, must not be NULL.
283 * @param error Location to store errors in, or NULL. Ignored for unchecked requests.
284 * @return 1 when the reply to the request was returned, else 0.
285 *
286 * Checks if the reply to the given request already received. Does not block.
287 *
288 * Unlike its xcb_poll_for_reply() counterpart, the given sequence number is not
289 * automatically "widened" to 64-bit.
290 */
291int xcb_poll_for_reply64(xcb_connection_t *c, uint64_t request, void **reply, xcb_generic_error_t **error);
292
293/**
294 * @brief Don't use this, only needed by the generated code.
295 * @param c The connection to the X server.
296 * @param reply A reply that was received from the server
297 * @param replylen The size of the reply.
298 * @return Pointer to the location where received file descriptors are stored.
299 */
300int *xcb_get_reply_fds(xcb_connection_t *c, void *reply, size_t replylen);
301
302
303/* xcb_util.c */
304
305/**
306 * @param mask The mask to check
307 * @return The number of set bits in the mask
308 */
309int xcb_popcount(uint32_t mask);
310
311/**
312 * @param list The base of an array
313 * @param len The length of the array
314 * @return The sum of all entries in the array.
315 */
316int xcb_sumof(uint8_t *list, int len);
317
318#ifdef __cplusplus
319}
320#endif
321
322#endif
323

source code of include/xcb/xcbext.h