diff options
Diffstat (limited to 'include/xcb')
| -rw-r--r-- | include/xcb/xcb.h | 5 | ||||
| -rw-r--r-- | include/xcb/xcbext.h | 107 |
2 files changed, 105 insertions, 7 deletions
diff --git a/include/xcb/xcb.h b/include/xcb/xcb.h index 18704c3f2..ec5cd3301 100644 --- a/include/xcb/xcb.h +++ b/include/xcb/xcb.h @@ -324,7 +324,7 @@ typedef struct xcb_special_event xcb_special_event_t; */ xcb_generic_event_t *xcb_poll_for_special_event(xcb_connection_t *c, xcb_special_event_t *se); - + /** * @brief Returns the next event from a special queue, blocking until one arrives */ @@ -335,7 +335,6 @@ xcb_generic_event_t *xcb_wait_for_special_event(xcb_connection_t *c, */ typedef struct xcb_extension_t xcb_extension_t; /**< Opaque structure used as key for xcb_get_extension_data_t. */ - /** * @brief Listen for a special event */ @@ -489,7 +488,7 @@ xcb_connection_t *xcb_connect_to_fd(int fd, xcb_auth_info_t *auth_info); * @param c: The connection. * * Closes the file descriptor and frees all memory associated with the - * connection @c c. + * connection @c c. If @p c is @c NULL, nothing is done. */ void xcb_disconnect(xcb_connection_t *c); diff --git a/include/xcb/xcbext.h b/include/xcb/xcbext.h index 20ec1c37a..7587513d7 100644 --- a/include/xcb/xcbext.h +++ b/include/xcb/xcbext.h @@ -58,11 +58,56 @@ enum xcb_send_request_flags_t { XCB_REQUEST_REPLY_FDS = 1 << 3 }; +/** + * @brief Send a request to the server. + * @param c: The connection to the X server. + * @param flags: A combination of flags from the xcb_send_request_flags_t enumeration. + * @param vector: Data to send; must have two iovecs before start for internal use. + * @param request: Information about the request to be sent. + * @return The request's sequence number on success, 0 otherwise. + * + * This function sends a new request to the X server. The data of the request is + * given as an array of @c iovecs in the @p vector argument. The length of that + * array and the neccessary management information are given in the @p request + * argument. + * + * When this function returns, the request might or might not be sent already. + * Use xcb_flush() to make sure that it really was sent. + * + * Please note that this function is not the prefered way for sending requests. + * It's better to use the generated wrapper functions. + * + * Please note that xcb might use index -1 and -2 of the @p vector array internally, + * so they must be valid! + */ unsigned int xcb_send_request(xcb_connection_t *c, int flags, struct iovec *vector, const xcb_protocol_request_t *request); +/** + * @brief Send a file descriptor to the server in the next call to xcb_send_request. + * @param c: The connection to the X server. + * @param fd: The file descriptor to send. + * + * After this function returns, the file descriptor given is owned by xcb and + * will be closed eventually. + * + * FIXME: How the heck is this supposed to work in a thread-safe way? There is a + * race between two threads doing xcb_send_fd(); xcb_send_request(); at the same + * time. + */ void xcb_send_fd(xcb_connection_t *c, int fd); -/* xcb_take_socket allows external code to ask XCB for permission to +/** + * @brief Take over the write side of the socket + * @param c: The connection to the X server. + * @param return_socket: Callback function that will be called when xcb wants + * to use the socket again. + * @param closure: Argument to the callback function. + * @param flags: A combination of flags from the xcb_send_request_flags_t enumeration. + * @param sent: Location to the sequence number of the last sequence request. + * Must not be NULL. + * @return 1 on success, else 0. + * + * xcb_take_socket allows external code to ask XCB for permission to * take over the write side of the socket and send raw data with * xcb_writev. xcb_take_socket provides the sequence number of the last * request XCB sent. The caller of xcb_take_socket must supply a @@ -71,10 +116,24 @@ void xcb_send_fd(xcb_connection_t *c, int fd); * external socket owner and flushes any output queues if appropriate. * If you are sending requests which won't cause a reply, please note the * comment for xcb_writev which explains some sequence number wrap issues. - * */ + * + * All replies that are generated while the socket is owned externally have + * @p flags applied to them. For example, use XCB_REQUEST_CHECK if you don't + * want errors to go to xcb's normal error handling, but instead having to be + * picked up via xcb_wait_for_reply(), xcb_poll_for_reply() or + * xcb_request_check(). + */ int xcb_take_socket(xcb_connection_t *c, void (*return_socket)(void *closure), void *closure, int flags, uint64_t *sent); -/* You must own the write-side of the socket (you've called +/** + * @brief Send raw data to the X server. + * @param c: The connection to the X server. + * @param vector: Array of data to be sent. + * @param count: Number of entries in @p vector. + * @param requests: Number of requests that are being sent. + * @return 1 on success, else 0. + * + * You must own the write-side of the socket (you've called * xcb_take_socket, and haven't returned from return_socket yet) to call * xcb_writev. Also, the iovec must have at least 1 byte of data in it. * You have to make sure that xcb can detect sequence number wraps correctly. @@ -83,20 +142,60 @@ int xcb_take_socket(xcb_connection_t *c, void (*return_socket)(void *closure), v * requests without a reply, you have to insert a request which will cause a * reply. You can again use GetInputFocus for this. You do not have to wait for * any of the GetInputFocus replies, but can instead handle them via - * xcb_discard_reply(). */ + * xcb_discard_reply(). + */ int xcb_writev(xcb_connection_t *c, struct iovec *vector, int count, uint64_t requests); /* xcb_in.c */ +/** + * @brief Wait for the reply of a given request. + * @param c: The connection to the X server. + * @param request: Sequence number of the request as returned by xcb_send_request(). + * @param e: Location to store errors in, or NULL. Ignored for unchecked requests. + * + * Returns the reply to the given request or returns null in the event of + * errors. Blocks until the reply or error for the request arrives, or an I/O + * error occurs. + */ void *xcb_wait_for_reply(xcb_connection_t *c, unsigned int request, xcb_generic_error_t **e); + +/** + * @brief Poll for the reply of a given request. + * @param c: The connection to the X server. + * @param request: Sequence number of the request as returned by xcb_send_request(). + * @param reply: Location to store the reply in, must not be NULL. + * @param e: Location to store errors in, or NULL. Ignored for unchecked requests. + * @return 1 when the reply to the request was returned, else 0. + * + * Checks if the reply to the given request already received. Does not block. + */ int xcb_poll_for_reply(xcb_connection_t *c, unsigned int request, void **reply, xcb_generic_error_t **error); + +/** + * @brief Don't use this, only needed by the generated code. + * @param c: The connection to the X server. + * @param reply: A reply that was received from the server + * @param replylen: The size of the reply. + * @return Pointer to the location where received file descriptors are stored. + */ int *xcb_get_reply_fds(xcb_connection_t *c, void *reply, size_t replylen); /* xcb_util.c */ +/** + * @param mask: The mask to check + * @return The number of set bits in the mask + */ int xcb_popcount(uint32_t mask); + +/** + * @param list: The base of an array + * @param len: The length of the array + * @return The sum of all entries in the array. + */ int xcb_sumof(uint8_t *list, int len); #ifdef __cplusplus |