* @file xcb.h
*/
+#define XCB_PACKED __attribute__((__packed__))
+
/**
* @defgroup XCB_Core_API XCB Core API
* @brief Core API of the XCB library.
/** X_TCP_PORT + display number = server port for TCP transport */
#define X_TCP_PORT 6000
+/** xcb connection errors because of socket, pipe and other stream errors. */
+#define XCB_CONN_ERROR 1
+
+/** xcb connection shutdown because of extension not supported */
+#define XCB_CONN_CLOSED_EXT_NOTSUPPORTED 2
+
+/** malloc(), calloc() and realloc() error upon failure, for eg ENOMEM */
+#define XCB_CONN_CLOSED_MEM_INSUFFICIENT 3
+
+/** Connection closed, exceeding request length that server accepts. */
+#define XCB_CONN_CLOSED_REQ_LEN_EXCEED 4
+
+/** Connection closed, error during parsing display string. */
+#define XCB_CONN_CLOSED_PARSE_ERR 5
+
+/** Connection closed because the server does not have a screen matching the display. */
+#define XCB_CONN_CLOSED_INVALID_SCREEN 6
+
+/** Connection closed because some FD passing operation failed */
+#define XCB_CONN_CLOSED_FDPASSING_FAILED 7
+
#define XCB_TYPE_PAD(T,I) (-(I) & (sizeof(T) > 4 ? 3 : sizeof(T) - 1))
/* Opaque structures */
*
* An event as sent by the XGE extension. The length field specifies the
* number of 4-byte blocks trailing the struct.
+ *
+ * @deprecated Since some fields in this struct have unfortunate names, it is
+ * recommended to use xcb_ge_generic_event_t instead.
*/
typedef struct {
uint8_t response_type; /**< Type of the response */
/**
* @brief Returns the next event or error from the server.
* @param c: The connection to the X server.
- * error status of the operation.
* @return The next event from the server.
*
* Returns the next event or error from the server, if one is
xcb_generic_event_t *xcb_poll_for_event(xcb_connection_t *c);
/**
- * @brief Returns the next event or error that precedes the given request.
+ * @brief Returns the next event without reading from the connection.
* @param c: The connection to the X server.
- * @param request: The limiting sequence number.
- * @return The next event from the server.
+ * @return The next already queued event from the server.
*
- * Returns the next event or error with a sequence number less than or
- * equal to the given sequence number, or returns NULL if no such event can
- * ever arrive. Blocks until either a suitable event or error arrive, or a
- * response arrives that proves no such event is coming, or an I/O error
- * occurs.
+ * This is a version of xcb_poll_for_event that only examines the
+ * event queue for new events. The function doesn't try to read new
+ * events from the connection if no queued events are found.
*
- * After processing a request, the X server sends responses in a specific
- * order. First come any events that the request generated, then any
- * replies for the request, then the error response if there is one. After
- * that, the server may spontaneously send more events with the same
- * sequence number, which are not related to that request.
- *
- * This function will always return events from the pre-reply phase of the
- * specified request. It may also return events from the unrelated
- * post-reply stream, as long as they have the same sequence number.
- *
- * This function is useful for callers that need to process responses in
- * wire-order.
- *
- * Implementation note: You cannot currently use this function to ensure
- * that you process responses in exactly wire-order, because depending on
- * the sequence of calls you make and the timing of server responses,
- * post-reply events with the same sequence number may be returned as part
- * of the pre-reply event stream, even though they were separated by a
- * reply or error. In practice this kind of error is unlikely to matter,
- * but it may be fixed in the future.
+ * This function is useful for callers that know in advance that all
+ * interesting events have already been read from the connection. For
+ * example, callers might use xcb_wait_for_reply and be interested
+ * only of events that preceded a specific reply.
+ */
+xcb_generic_event_t *xcb_poll_for_queued_event(xcb_connection_t *c);
+
+typedef struct xcb_special_event xcb_special_event_t;
+
+/**
+ * @brief Returns the next event from a special queue
+ */
+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
+ */
+xcb_generic_event_t *xcb_wait_for_special_event(xcb_connection_t *c,
+ xcb_special_event_t *se);
+/**
+ * @typedef typedef struct xcb_extension_t xcb_extension_t
+ */
+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
*/
-xcb_generic_event_t *xcb_wait_for_event_until(xcb_connection_t *c, unsigned int request);
+xcb_special_event_t *xcb_register_for_special_xge(xcb_connection_t *c,
+ xcb_extension_t *ext,
+ uint32_t eid,
+ uint32_t *stamp);
+
+/**
+ * @brief Stop listening for a special event
+ */
+void xcb_unregister_for_special_event(xcb_connection_t *c,
+ xcb_special_event_t *se);
/**
* @brief Return the error for a request, or NULL if none can ever arrive.
/* xcb_ext.c */
-/**
- * @typedef typedef struct xcb_extension_t xcb_extension_t
- */
-typedef struct xcb_extension_t xcb_extension_t; /**< Opaque structure used as key for xcb_get_extension_data_t. */
-
/**
* @brief Caches reply information from QueryExtension requests.
* @param c: The connection.
* The result must not be freed. This storage is managed by the cache
* itself.
*/
-const xcb_query_extension_reply_t *xcb_get_extension_data(xcb_connection_t *c, xcb_extension_t *ext);
+const struct xcb_query_extension_reply_t *xcb_get_extension_data(xcb_connection_t *c, xcb_extension_t *ext);
/**
* @brief Prefetch of extension data into the extension cache
*
* The result must not be freed.
*/
-const xcb_setup_t *xcb_get_setup(xcb_connection_t *c);
+const struct xcb_setup_t *xcb_get_setup(xcb_connection_t *c);
/**
* @brief Access the file descriptor of the connection.
/**
* @brief Test whether the connection has shut down due to a fatal error.
* @param c: The connection.
- * @return 1 if the connection is in an error state; 0 otherwise.
+ * @return > 0 if the connection is in an error state; 0 otherwise.
*
* Some errors that occur in the context of an xcb_connection_t
* are unrecoverable. When such an error occurs, the
* connection is shut down and further operations on the
- * xcb_connection_t have no effect.
+ * xcb_connection_t have no effect, but memory will not be freed until
+ * xcb_disconnect() is called on the xcb_connection_t.
*
- * @todo Other functions should document the conditions in
- * which they shut down the connection.
+ * @return XCB_CONN_ERROR, because of socket errors, pipe errors or other stream errors.
+ * @return XCB_CONN_CLOSED_EXT_NOTSUPPORTED, when extension not supported.
+ * @return XCB_CONN_CLOSED_MEM_INSUFFICIENT, when memory not available.
+ * @return XCB_CONN_CLOSED_REQ_LEN_EXCEED, exceeding request length that server accepts.
+ * @return XCB_CONN_CLOSED_PARSE_ERR, error during parsing display string.
+ * @return XCB_CONN_CLOSED_INVALID_SCREEN, because the server does not have a screen matching the display.
*/
int xcb_connection_has_error(xcb_connection_t *c);
* bidirectionally connected to an X server. If the connection
* should be unauthenticated, @p auth_info must be @c
* NULL.
+ *
+ * Always returns a non-NULL pointer to a xcb_connection_t, even on failure.
+ * Callers need to use xcb_connection_has_error() to check for failure.
+ * When finished, use xcb_disconnect() to close the connection and free
+ * the structure.
*/
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);
* variable. If a particular screen on that server is preferred, the
* int pointed to by @p screenp (if not @c NULL) will be set to that
* screen; otherwise the screen will be set to 0.
+ *
+ * Always returns a non-NULL pointer to a xcb_connection_t, even on failure.
+ * Callers need to use xcb_connection_has_error() to check for failure.
+ * When finished, use xcb_disconnect() to close the connection and free
+ * the structure.
*/
xcb_connection_t *xcb_connect(const char *displayname, int *screenp);
* authorization @p auth. If a particular screen on that server is
* preferred, the int pointed to by @p screenp (if not @c NULL) will
* be set to that screen; otherwise @p screenp will be set to 0.
+ *
+ * Always returns a non-NULL pointer to a xcb_connection_t, even on failure.
+ * Callers need to use xcb_connection_has_error() to check for failure.
+ * When finished, use xcb_disconnect() to close the connection and free
+ * the structure.
*/
xcb_connection_t *xcb_connect_to_display_with_auth_info(const char *display, xcb_auth_info_t *auth, int *screen);
projects / free-sw / xcb / libxcb / blobdiff