gdbus-codegen - 云端在线

程序：

您的姓名

gdbus-codegen - D-Bus 代码和文档生成器

概要

gdbus-代码生成器 [-h, - 帮帮我[--接口前缀 org.project.前缀]
[--generate-c-代码 档案[--c-命名空间 你的项目]
[--c-生成对象管理器[--生成文档书 档案]
[--xml-文件 文件[- 注释 ELEMENT KEY VALUE]...文件 [文件...]

商品描述

gdbus-代码生成器 用于为一个或多个 D-Bus 生成代码和/或文档
接口。 该工具读取 公交车 内省 XML[1] 文件并生成输出文件。
该工具目前支持生成 C 代码（通过 --generate-c-代码) 和 Docbook XML (通过
--生成文档书).

生成 C 守则

生成 C 代码时，会为每个 D-Bus 接口生成一个 #GInterface 派生类型。
此外，对于每个生成的类型， 富吧，两个具体的实例化类型，
FooBar代理 和 FooBar骨架，还生成了实现所述接口。 前者
派生自 #GDBusProxy 并用于客户端，而后者是
派生自 #GDBusInterfaceSkeleton 类型，可以轻松导出到
#GDBusConnection 直接或通过 #GDBusObjectManagerServer 实例。

每个生成的 C 类型的名称都来自于去掉了 D-Bus 接口名称
给定的前缀 --接口前缀 并删除点和初始字符
大写。 例如，对于 D-Bus 接口 com.acme.Coyote，使用的名称是
ComAcmeCoyote。 对于 D-Bus 接口 org.project.Bar.Frobnicator 与 --接口前缀
org.project.，使用的名称是 BarFrobnicator。

对于方法、信号和属性，如果未指定，则名称默认为
方法、信号或属性。

使用了两种形式的名称 - CamelCase 形式和小写形式。 骆驼案
form 用于#GType 和结构名称，而小写形式用于函数
名称。 小写形式是通过将 CamelCase 转换为小写和
在单词边界处插入下划线（使用某些启发式方法）。

如果 org.gtk.GDBus.C.Name 注释或 --c-命名空间 选项
包含下划线（有时称为 丑陋的案例)，则导出驼峰命名法
通过删除所有下划线，小写名称是通过小写
细绳。 这在某些使用缩写的情况下很有用。 例如，如果
注释用于接口 net.MyCorp.MyApp.iSCSITarget 和值
iSCSI_Target CamelCase 形式是 iSCSITarget 而小写形式是 iscsi_target。
如果在 EjectTheiPod 方法上使用了值为 Eject_The_iPod 的注解，则
小写形式是eject_the_ipod。

生成 行书 文档

每个生成的 Docbook XML 文件（请参阅 --生成文档书 详细信息选项）是一个
参考条目[2] 描述 D-Bus 接口的文章。

配置

支持以下选项：

-h, - 帮帮我
显示帮助并退出。

--xml-文件 文件
D-Bus 自省 XML 文件。

--接口前缀 org.project.Prefix。
在计算类型名称时从所有 D-Bus 接口名称中剥离的前缀
C 绑定和 Docbook 排序 属性[3]。

--生成文档书 档案
为每个D-Bus接口生成Docbook Documentation并放入
OUTFILES-NAME.xml 其中 NAME 是接口名称的占位符，例如
net.Corp.FooBar 等。

--generate-c-代码 档案
为所有 D-Bus 接口生成 C 代码并将其放入 OUTFILES.c 和 OUTFILES.h。

--c-命名空间 你的项目
用于生成的 C 代码的命名空间。 这预计将在 骆驼套[4]或
丑陋的案例 （往上看）。

--c-生成对象管理器
如果通过此选项，则适合#GDBusObject、#GDBusObjectProxy、
生成#GDBusObjectSkeleton 和#GDBusObjectManagerClient 子类。

- 注释 ELEMENT KEY VALUE
用于将 D-Bus 注释注入给定的 XML 文件。 它可以与
接口、方法、信号、属性和参数如下：

gdbus-codegen --c-命名空间 MyApp \
--generate-c-code myapp-generate \
--annotate "org.project.InterfaceName" \
org.gtk.GDBus.C.名称 MyFrobnicator \
--annotate "org.project.InterfaceName:Property" \
棒棒\
--annotate "org.project.InterfaceName.Method()" \
org.freedesktop.DBus.Deprecated true \
--annotate "org.project.InterfaceName.Method()[arg_name]" \
蛇嘶嘶\
--annotate "org.project.InterfaceName::Signal" \
猫喵\
--annotate "org.project.InterfaceName::Signal[arg_name]" \
狗窝\
myapp-dbus-interfaces.xml
任何 UTF-8 字符串都可以用于 KEY 和 VALUE.

支持的 总线 注释

支持以下 D-Bus 注释 gdbus-代码生成器:

org.freedesktop.DBus.已弃用
可用于任何, , 和要指定的元素
如果该元素的值为 true，则该元素将被弃用。 注意这个注解是
定义在 公交车 规范[1] 并且只能假设值 true 和 false。
特别是，您不能指定元素被弃用的版本，也不能指定
任何有用的弃用消息。 应将此类信息添加到元素中
文档代替。

生成 C 代码时，该注解用于在生成时添加#G_GNUC_DEPRECATED
元素的函数。

生成 Docbook XML 时，文档中会出现弃用警告
为元素。

org.gtk.GDBus.Since
可用于任何, , 和要指定的元素
版本（任何自由形式的字符串，但使用版本感知排序功能进行比较）
元素出现在。

生成 C 代码时，此字段用于确保函数指针顺序
保留 ABI/API，请参阅“稳定性保证”部分。

生成Docbook XML 时，此标记的值会出现在文档中。

org.gtk.GDBus.DocString
包含文档的 Docbook 内容的字符串。 此注解可用于
, , , 和元素。

org.gtk.GDBus.DocString.Short
包含用于简短/简短文档的 Docbook 内容的字符串。 这个注解只能
用于元素。

org.gtk.GDBus.C.名称
可用于任何, , 和要指定的元素
生成 C 代码时使用的名称。 该值预计在 骆驼套[4]或
丑陋的案例 （往上看）。

org.gtk.GDBus.C.ForceGVariant
如果设置为非空字符串，将使用 #GVariant 实例而不是自然的
C型。 此注释可用于任何和元素。

org.gtk.GDBus.C.UnixFD
如果设置为非空字符串，则生成的代码将包含要交换的参数
使用 #GUnixFDList 类型的文件描述符。 此注解可用于
元素。

作为使用 org.gtk.GDBus.DocString 注释的更简单的替代方法，请注意解析器
用于 gdbus-代码生成器 以类似于的方式解析 XML 注释 gtk 文档[5]：

请注意，@since 可用于任何内联文档位（例如，用于接口、
方法、信号和属性）来设置 org.gtk.GDBus.Since 注释。 为了
org.gtk.GDBus.DocString 注释（和内联注释），注意表单的子字符串
#net.Corp.Bar、net.Corp.Bar.FooMethod()、#net.Corp.Bar::BarSignal 和
#net.Corp.InlineDocs:BazProperty 都扩展为指向相应界面的链接，
方法、信号和属性。 此外，以@ 和 % 字符开头的子字符串是
呈现为 参数[6]和 常数[7] 分别。

如果 XML 注释和 org.gtk.GDBus.DocString 或 org.gtk.GDBus.DocString.Short
存在注释，后者获胜。

例

考虑以下 D-Bus Introspection XML。


















If gdbus-代码生成器 用于此文件，如下所示：

gdbus-codegen --generate-c-code myapp-generate \
--c-命名空间 MyApp \
--interface-prefix net.corp.MyApp。 \
net.Corp.MyApp.Frobber.xml

生成了两个名为 myapp-generated.[ch] 的文件。 这些文件提供了一个摘要
#GTypeInterface - 派生类型调用 我的AppFrobber 以及两种可实例化的类型
同名但后缀 代理 和 骨架. 生成的文件大致包含
以下设施：

/* 三种生成类型的 GType 宏 */
#define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
#define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_骨骼_get_type ())
#define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())

typedef struct _MyAppFrobber MyAppFrobber; /* 虚拟类型定义 */

typedef结构
{
GTypeInterfaceparent_iface；

/* ::notification 信号的信号处理程序 */
无效（*通知）（MyAppFrobber *代理，
GVariant *icon_blob，
金币高度，
常量 gchar* 常量 *消息);

/* ::handle-hello-world 信号的信号处理程序 */
gboolean (*handle_hello_world) (MyAppFrobber *proxy,
GDBusMethodInvocation *调用，
const gchar *问候）；
我的AppFrobberIface;

/* 异步调用 HelloWorld() */
无效
my_app_frobber_call_hello_world（MyAppFrobber *代理，
const gchar *问候，
G可取消 *可取消，
GAsyncReadyCallback 回调，
gpointer 用户数据）；
布尔值
my_app_frobber_call_hello_world_finish（MyAppFrobber *代理，
gchar **out_response，
GAsyncResult *res,
GError **错误);

/* 同步调用HelloWorld()。 阻塞调用线程。 */
布尔值
my_app_frobber_call_hello_world_sync（MyAppFrobber *代理，
const gchar *问候，
gchar **out_response，
G可取消 *可取消，
GError **错误);

/* 完成对 HelloWorld() 方法调用的处理 */
无效
my_app_frobber_complete_hello_world（MyAppFrobber *对象，
GDBusMethodInvocation *调用，
const gchar *响应);

/* 发出 ::notification 信号 / Notification() D-Bus 信号 */
无效
my_app_frobber_emit_notification（MyAppFrobber *对象，
GVariant *icon_blob，
金币高度，
常量 gchar* 常量 *消息);

/* 获取 :verbose GObject 属性/详细 D-Bus 属性。
* 不阻塞 I/O。
*/
gboolean my_app_frobber_get_verbose (MyAppFrobber *object);

/* 设置 :verbose GObject 属性/详细 D-Bus 属性。
* 不阻塞 I/O。
*/
无效 my_app_frobber_set_verbose (MyAppFrobber *object,
布尔值）；

/* 获取接口信息 */
GDBusInterfaceInfo *my_app_frobber_interface_info（无效）；

/* 创建一个新的骨架对象，准备导出 */
MyAppFrobber *my_app_frobber_skeleton_new（无效）；

/* 客户端代理构造函数。
*
* 此外，_new_for_bus()、_new_for_bus_finish() 和
* _new_for_bus_sync() 代理构造函数也被生成。
*/
无效
my_app_frobber_proxy_new（GDBusConnection *连接，
GDBusProxyFlags 标志，
const gchar *名称，
const gchar *object_path,
G可取消 *可取消，
GAsyncReadyCallback 回调，
gpointer 用户数据）；
我的应用程序Frobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
GError **错误);
我的应用程序Frobber *
my_app_frobber_proxy_new_sync（GDBusConnection *连接，
GDBusProxyFlags 标志，
const gchar *名称，
const gchar *object_path,
G可取消 *可取消，
GError **错误);

因此，对于每个 D-Bus 方法，都会有三个 C 函数来调用该方法，一个
#GObject 信号用于处理传入呼叫和一个 C 函数用于完成
来电。 对于每个 D-Bus 信号，有一个 #GObject 信号和一个 C 函数，用于
发射它。 对于每个 D-Bus 属性，都会生成两个 C 函数（一个 setter，一个
getter) 和一个 #GObject 属性。 下表总结了生成的设施
以及它们适用的地方：

┌────────────────────────┬───────────────────────────┬─ ────────────────────────────────┐
│ │ 客户 │ 服务器 │
├──────────────────────┼─────────────────────────┼── ────────────────────────────────┤
│种类│用途 MyAppFrobber代理 │ 任何类型的实现 │
│ │ │ 我的AppFrobber │
│ │ │ 界面│
├──────────────────────┼─────────────────────────┼── ────────────────────────────────┤
│方法│使用 m_a_f_hello_world() │ 通过 │ 接收
│ │ 来电话。 │ 句柄_hello_world() │
│ │ │ 信号处理程序。 完成│
│ │ │ 电话与 │
│ │ │ m_a_f_complete_hello_world() │
├──────────────────────┼─────────────────────────┼── ────────────────────────────────┤
│信号 │ 连接 │ 使用 │
│ │ ：：通知 图形对象│ m_a_f_emit_notification() 至│
│ │ 信号。 │ 发出信号。 │
├──────────────────────┼─────────────────────────┼── ────────────────────────────────┤
│属性（阅读）│使用 m_a_f_get_verbose() │ 实现#GObject 的 │
│ │ 或 :详细。 │ 获取属性（） 虚拟功能。 │
├──────────────────────┼─────────────────────────┼── ────────────────────────────────┤
│属性（书写）│使用 m_a_f_set_verbose() │ 实现#GObject 的 │
│ │ 或 :详细。 │ 设置属性（） 虚拟功能。 │
└──────────────────────┴─────────────────────────┴─ ────────────────────────────────┘

客户端 用法
您可以将生成的代理类型与生成的构造函数一起使用：

MyAppFrobber *代理；
GError *错误；

错误 = NULL;
代理 = my_app_frobber_proxy_new_for_bus_sync (
G_BUS_TYPE_SESSION，
G_DBUS_PROXY_FLAGS_NONE，
"net.Corp.MyApp", /* 总线名称 */
"/net/Corp/MyApp/SomeFrobber", /* 对象 */
NULL, /* GCancellable* */
＆错误）;
/* 用代理做事 */
g_object_unref（代理）；

可以使用生成的方法，而不是使用通用的 #GDBusProxy 设施
如 my_app_frobber_call_hello_world() 调用
net.Corp.MyApp.Frobber.HelloWorld() D-Bus 方法，连接到 ：：通知
接收 GObject 信号 net.Corp.MyApp.Frobber::通知 D-Bus 信号和获取/设置
这些因素包括原料奶的可用性以及达到必要粉末质量水平所需的工艺。 net.Corp.MyApp.Frobber：详细 使用 GObject 属性的 D-Bus 属性
:详细 或者 my_app_get_verbose() 和 my_app_set_verbose() 方法。 使用标准
#GObject::notify 信号以侦听属性更改。

请注意，所有属性访问都是通过 #GDBusProxy 的属性缓存进行的，因此不会进行任何 I/O
读取属性时。 另请注意，设置属性会导致
org.freedesktop.DBus.Properties.Set[8] 要在远程对象上调用的方法。 这个
但是，调用是异步的，因此设置属性不会阻塞。 此外，变化是
延迟并且不可能进行错误检查。

服务器端 用法
产生的 我的AppFrobber 接口被设计成很容易在一个
#GObject 子类。 例如，处理 你好，世界（） 方法调用，设置 vfunc
HPMC胶囊 句柄_hello_hello_world() ，在 MyAppFrobberIface 结构体。 类似地，处理
net.Corp.MyApp.Frobber：详细 属性覆盖 :详细 #GObject 属性来自
子类。 要发出信号，请使用例如 my_app_emit_signal() 或 g_signal_emit_by_name()。

与子类化相比，使用生成的通常更容易 MyAppFrobber骨架
子类。 要处理传入的方法调用，请使用 g_signal_connect() 与 ：：处理-*
信号而不是覆盖 #GObject 的 获取属性（） 和 设置属性（） 虚拟函数，
使用 g_object_get() 和 g_object_set() 或生成的属性 getter 和 setter（
生成的类有一个内部属性包实现）。

静态布尔值
on_handle_hello_world（MyAppFrobber *接口，
GDBusMethodInvocation *调用，
const gchar *问候，
gpointer 用户数据）
{
如果（g_strcmp0（问候语，“嘘”）！= 0）
{
gchar *响应；
response = g_strdup_printf("Word！你说的是'%s'。"，问候语);
my_app_complete_hello_world（接口、调用、响应）；
g_free（响应）；
}
其他
{
g_dbus_method_invocation_return_error（调用，
MY_APP_ERROR，
MY_APP_ERROR_NO_WHINING，
“嘿，%s，不会有抱怨的！”,
g_dbus_method_invocation_get_sender（调用））；
}
返回TRUE;
}

[...]

interface = my_app_frobber_skeleton_new();
my_app_frobber_set_verbose（接口，真）；

g_signal_connect（接口，
“处理你好世界”，
G_CALLBACK(on_handle_hello_world),
一些用户数据）；

[...]

错误 = NULL;
如果 (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
连接，
"/path/of/dbus_object",
＆错误））
{
/* 处理错误 */
}

为了促进原子更改集（同时更改多个属性），
#GObject::notify 信号在收到时排队。 队列在空闲时排空
处理程序（从线程的线程默认主循环调用，其中
骨架对象被构造）并将导致排放
org.freedesktop.DBus.Properties::PropertiesChanged[8] 具有所有特性的信号
已经变化。 使用 g_dbus_interface_skeleton_flush() 或 g_dbus_object_skeleton_flush() 来
立即清空队列。 使用 g_object_freeze_notify() 和 g_object_thaw_notify() 为
如果在不同的线程上，则原子变更集。

C 型 MAPPING

标量类型（类型字符串 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' and 'd') ），字符串
（类型字符串 's'、'ay'、'o' 和 'g'）和字符串数组（类型字符串 'as'、'ao' 和
'aay') 映射到自然类型，例如 #gboolean、#gdouble、#gint、gchar*、gchar**
等等。 其他所有内容都映射到 #GVariant 类型。

可以使用注释关闭此自动映射
org.gtk.GDBus.C.ForceGVariant - 如果使用，则始终交换 #GVariant 而不是
相应的原生 C 类型。 这个注解在使用的时候可能方便
bytestrings (type-string 'ay') 用于可能嵌入 NUL 字节的数据。

稳定性 担保

生成的 C 函数保证不会改变它们的 ABI，也就是说，如果一个方法，
信号或属性在自省 XML 中不会改变其签名，生成的 C
函数也不会改变它的 C ABI。 生成的实例和类的 ABI
结构也将被保留。

生成的 #GType 的 ABI 将仅在 org.gtk.GDBus.Since
明智地使用注释——这是因为 #GInterface 的 VTable 依赖于
信号处理程序的函数指针。 具体来说，如果 D-Bus 方法、属性或
信号或添加到 D-Bus 接口，则生成的 #GInterface 类型的 ABI 是
当且仅当每个添加的方法、属性信号都用它们进行注释时保留
org.gtk.GDBus.Since 注释使用比以前版本更大的版本号。

生成的 C 代码当前恰好被注释为 gtk 文档[5]/ 图形对象
内省[9] 评论/注释。 布局和内容可能会在
未来，因此不提供关于例如 SECTION 使用等的保证。

虽然为 D-Bus 接口生成的 Docbook 预计不会改变，但不能保证
此时给出。

需要注意的是，不应将生成的代码签入修订版
控制系统，也不应该包含在分布式源档案中。

使用 onworks.net 服务在线使用 gdbus-codegen