xcb-dl

此 Rust 包包含 libxcb、libxcb-xinput 等的绑定。符号在运行时动态加载，不支持编译时链接。

开发

此包中的几乎所有代码都是使用 generate.py Python 脚本自动生成的。运行 generate-all 重新生成所有代码。

generate.py 使用来自 xcbproto 项目的 xml 文件作为输入。为了一致性，这些文件被纳入 xcbproto 目录。当前版本为 1.14.1。

该 Python 脚本是 libxcb 源代码中 c_client.py 脚本的严重修改版本。

许可证

X11

lib.rs:

此包包含 libxcb、libxcb-xinput 等的绑定。符号在运行时动态加载；不支持编译时链接。

功能

默认情况下，仅提供 libxcb 的绑定。启用相应命名的功能以启用 libxcb-xinput 等的绑定。

处理缺失的符号

符号在访问时才会被惰性加载。如果失败，我们将 panic。启用 has_symbol 功能以更优雅地处理缺失的符号。这启用了返回符号是否可以加载的 has_X 形式的方法。

let lib = xcb_dl::Xcb::load().unwrap();
if !lib.has_xcb_total_written() {
    eprintln!("Cannot monitor total number of bytes written.");
}

构建结构体

此包的未来的版本可能会向结构体添加新字段或删除填充字段。这不会被视为破坏性更改。使用 Default::default() 构建对象以确保您的代码保持有效

let format = xcb_dl::ffi::xcb_format_t {
    depth: 0,
    bits_per_pixel: 0,
    scanline_pad: 0,
    ..Default::default()
};

语义文档

这个crate几乎没有任何语义文档。X核心协议和扩展的文档可以在freedesktop和x.org找到。不自动从协议生成的libxcb函数的文档可以在libxcb仓库中找到。检查src/xcb.h和src/xcbext.h。

libxcb架构

本节简要概述了libxcb中自动生成的函数。有关更多详细信息，请参阅libxcb文档。

本节中的术语不是官方libxcb术语。

libxcb向X服务器发送请求并接收来自X服务器的消息。有三种类型的消息

• 值回复：对请求的响应中发送的成功消息。
• 错误回复：对请求的错误响应。
• 事件：如按键按下的事件。

发送请求的代码可以通过调用xcb_discard_reply指定自动丢弃回复。

libxcb维护两个用于接收消息的队列

• 事件队列：包含可以通过xcb_poll_for_event等获取的消息。
• 回复队列：包含只能由发送请求的代码检索的消息。

事件始终放入事件队列。

值回复放入回复队列，除非它们被丢弃。

每个请求有两个变体

• 已检查：错误回复放入回复队列，除非它们被丢弃。
• 未检查：错误回复放入事件队列，除非它们被丢弃。

有两种类型的请求

• 空请求：这些不会生成值回复，但可以生成错误回复。
• 值请求：这些可以生成值回复或错误回复。

空请求的默认变体是未检查。对于此类请求，libxcb提供后缀为_checked的函数，该函数使用已检查变体。

值请求的默认变体是已检查。对于此类请求，libxcb提供后缀为_unchecked的函数，该函数使用未检查变体。

放入回复队列的消息必须由用户检索。否则，它们将永远不会被丢弃。

对于空请求，可以通过调用xcb_request_check检索错误回复。

对于每个值请求，libxcb提供一个后缀为_reply的函数，该函数可用于检索值或错误回复。

内存管理

libxcb永远不会获取传递给它的内存的所有权。

返回消息的函数将消息的所有权传递给调用者。这些消息可以使用libc::free来释放。

非均匀请求

某些请求包含可变大小的数据以及可能非均匀的数组。为了简化创建此类请求，libxcb提供了后缀为_aux的辅助函数。这些函数接受固定大小的参数，并在内部创建序列化的请求。

非均匀回复

某些回复包含可变大小的数据以及可能非均匀的数组。

libxcb的数据结构不包含此类数据的字段。相反，libxcb提供了访问器函数来检索这些字段的指针。

如果字段是非均匀数组，则这些访问器函数返回迭代器。可以通过调用相应命名的_next函数来将这些迭代器中的指针向前移动。

如果字段是均匀数组，则libxcb提供了返回数组中元素数量的_length函数。

在某些情况下，这些访问器函数返回 *mut c_void。在这些情况下，libxcb 通常提供一个 _unpack 函数，用于将数据反序列化到结构体中。