X-Git-Url: http://git.demorecorder.com/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=src%2Fxcb.h;h=23fe74e9fe47df6fc8cf7917e88adb463fdd2f3f;hb=a187ae85729ec56e46ed0a0453458db18ab731eb;hp=eaab47f2d5d5a0dadf910f26dd0b8d8b729aaf13;hpb=9e10819a678970928c9f9a1fffb4ba00f5ac7c57;p=free-sw%2Fxcb%2Flibxcb diff --git a/src/xcb.h b/src/xcb.h index eaab47f..23fe74e 100644 --- a/src/xcb.h +++ b/src/xcb.h @@ -35,7 +35,11 @@ #include #endif +#ifndef _WIN32 #include +#else +#include "xcb_windefs.h" +#endif #include @@ -47,6 +51,8 @@ extern "C" { * @file xcb.h */ +#define XCB_PACKED __attribute__((__packed__)) + /** * @defgroup XCB_Core_API XCB Core API * @brief Core API of the XCB library. @@ -65,6 +71,27 @@ extern "C" { /** 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 */ @@ -112,9 +139,29 @@ typedef struct { uint8_t pad0; /**< Padding */ uint16_t sequence; /**< Sequence number */ uint32_t pad[7]; /**< Padding */ - uint32_t full_sequence; + uint32_t full_sequence; /**< full sequence */ } xcb_generic_event_t; +/** + * @brief GE event + * + * 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 */ + uint8_t pad0; /**< Padding */ + uint16_t sequence; /**< Sequence number */ + uint32_t length; + uint16_t event_type; + uint16_t pad1; + uint32_t pad[5]; /**< Padding */ + uint32_t full_sequence; /**< full sequence */ +} xcb_ge_event_t; + /** * @brief Generic error. * @@ -124,8 +171,12 @@ typedef struct { uint8_t response_type; /**< Type of the response */ uint8_t error_code; /**< Error code */ uint16_t sequence; /**< Sequence number */ - uint32_t pad[7]; /**< Padding */ - uint32_t full_sequence; + uint32_t resource_id; /** < Resource ID for requests with side effects only */ + uint16_t minor_code; /** < Minor opcode of the failed request */ + uint8_t major_code; /** < Major opcode of the failed request */ + uint8_t pad0; + uint32_t pad[5]; /**< Padding */ + uint32_t full_sequence; /**< full sequence */ } xcb_generic_error_t; /** @@ -183,8 +234,7 @@ typedef struct xcb_auth_info_t { int xcb_flush(xcb_connection_t *c); /** - * @brief Returns the maximum request length field from the connection - * setup data. + * @brief Returns the maximum request length that this server accepts. * @param c: The connection to the X server. * @return The maximum request length field. * @@ -200,6 +250,25 @@ int xcb_flush(xcb_connection_t *c); */ uint32_t xcb_get_maximum_request_length(xcb_connection_t *c); +/** + * @brief Prefetch the maximum request length without blocking. + * @param c: The connection to the X server. + * + * Without blocking, does as much work as possible toward computing + * the maximum request length accepted by the X server. + * + * Invoking this function may cause a call to xcb_big_requests_enable, + * but will not block waiting for the reply. + * xcb_get_maximum_request_length will return the prefetched data + * after possibly blocking while the reply is retrieved. + * + * Note that in order for this function to be fully non-blocking, the + * application must previously have called + * xcb_prefetch_extension_data(c, &xcb_big_requests_id) and the reply + * must have already arrived. + */ +void xcb_prefetch_maximum_request_length(xcb_connection_t *c); + /* xcb_in.c */ @@ -217,8 +286,6 @@ xcb_generic_event_t *xcb_wait_for_event(xcb_connection_t *c); /** * @brief Returns the next event or error from the server. * @param c: The connection to the X server. - * @param error: A pointer to an int to be filled in with the I/O - * error status of the operation. * @return The next event from the server. * * Returns the next event or error from the server, if one is @@ -229,6 +296,54 @@ xcb_generic_event_t *xcb_wait_for_event(xcb_connection_t *c); */ xcb_generic_event_t *xcb_poll_for_event(xcb_connection_t *c); +/** + * @brief Returns the next event without reading from the connection. + * @param c: The connection to the X server. + * @return The next already queued event from the server. + * + * 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. + * + * 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_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. * @param c: The connection to the X server. @@ -247,13 +362,24 @@ xcb_generic_event_t *xcb_poll_for_event(xcb_connection_t *c); */ xcb_generic_error_t *xcb_request_check(xcb_connection_t *c, xcb_void_cookie_t cookie); - -/* xcb_ext.c */ - /** - * @typedef typedef struct xcb_extension_t xcb_extension_t + * @brief Discards the reply for a request. + * @param c: The connection to the X server. + * @param sequence: The request sequence number from a cookie. + * + * Discards the reply for a request. Additionally, any error generated + * by the request is also discarded (unless it was an _unchecked request + * and the error has already arrived). + * + * This function will not block even if the reply is not yet available. + * + * Note that the sequence really does have to come from an xcb cookie; + * this function is not designed to operate on socket-handoff replies. */ -typedef struct xcb_extension_t xcb_extension_t; /**< Opaque structure used as key for xcb_get_extension_data_t. */ +void xcb_discard_reply(xcb_connection_t *c, unsigned int sequence); + + +/* xcb_ext.c */ /** * @brief Caches reply information from QueryExtension requests. @@ -271,7 +397,7 @@ typedef struct xcb_extension_t xcb_extension_t; /**< Opaque structure used as k * 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 @@ -307,7 +433,7 @@ void xcb_prefetch_extension_data(xcb_connection_t *c, xcb_extension_t *ext); * * 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. @@ -322,15 +448,20 @@ int xcb_get_file_descriptor(xcb_connection_t *c); /** * @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. - * - * @todo Other functions should document the conditions in - * which they shut down the connection. + * xcb_connection_t have no effect, but memory will not be freed until + * xcb_disconnect() is called on the xcb_connection_t. + * + * @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); @@ -345,6 +476,11 @@ 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); @@ -353,7 +489,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); @@ -362,10 +498,10 @@ void xcb_disconnect(xcb_connection_t *c); /** * @brief Parses a display string name in the form documented by X(7x). - * @param displayname: The name of the display. - * @param hostp: A pointer to a malloc'd copy of the hostname. - * @param displayp: A pointer to the display number. - * @param screenp: A pointer to the screen number. + * @param name: The name of the display. + * @param host: A pointer to a malloc'd copy of the hostname. + * @param display: A pointer to the display number. + * @param screen: A pointer to the screen number. * @return 0 on failure, non 0 otherwise. * * Parses the display string name @p display_name in the form @@ -390,26 +526,44 @@ int xcb_parse_display(const char *name, char **host, int *display, int *screen); * 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); /** * @brief Connects to the X server, using an authorization information. - * @param displayname: The name of the display. + * @param display: The name of the display. * @param auth: The authorization information. - * @param screenp: A pointer to a preferred screen number. + * @param screen: A pointer to a preferred screen number. * @return A newly allocated xcb_connection_t structure. * * Connects to the X server specified by @p displayname, using the * 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); /* xcb_xid.c */ +/** + * @brief Allocates an XID for a new object. + * @param c: The connection. + * @return A newly allocated XID. + * + * Allocates an XID for a new object. Typically used just prior to + * various object creation functions, such as xcb_create_window. + */ uint32_t xcb_generate_id(xcb_connection_t *c);