gdbus-codegen - クラウドでオンライン

プログラム：

NAME

gdbus-codegen - D-Bus コードとドキュメントのジェネレーター

SYNOPSIS

gdbus コード生成 [-h, - 助けて] [--インターフェースプレフィックス org.プロジェクト.プレフィックス]
[--C コードを生成する アウトファイル] [--c-名前空間 あなたのプロジェクト]
[--c-generate-オブジェクトマネージャー] [--generate-docbook アウトファイル]
[--xml ファイル FILE] [-注釈を付ける ELEMENT キー VALUE]... ファイル [ファイル...]

DESCRIPTION

gdbus コード生成 XNUMX つ以上の D-Bus のコードやドキュメントを生成するために使用されます。
インターフェース。 ツールは次のように読み取ります Dバス 内観 XML[1] ファイルを作成し、出力ファイルを生成します。
このツールは現在、C コードの生成をサポートしています ( --C コードを生成する) および Docbook XML (経由)
--generate-docbook).

生成 C CODE

C コードを生成するとき、各 D-Bus インターフェイスに対して #GInterface 派生型が生成されます。
さらに、生成された型ごとに、 FooBar、インスタンス化可能な XNUMX つの具体的な型、
FooBarProxy & FooBarスケルトン、前記インターフェースを実装するものも生成される。 前者
#GDBusProxy から派生し、クライアント側での使用を目的としていますが、後者は
#GDBusInterfaceSkeleton タイプから派生し、簡単にエクスポートできるようにします。
#GDBusConnection は、直接または #GDBusObjectManagerServer インスタンス経由で行われます。

生成された各 C 型の名前は、D-Bus インターフェイス名から次の文字を取り除いたものから派生します。
で与えられたプレフィックス --インターフェースプレフィックス ドットと頭文字を削除したもの
大文字。 たとえば、D-Bus インターフェイス com.acme.Coyote の場合、使用される名前は次のとおりです。
コムアクメコヨーテ。 D-Bus インターフェース org.project.Bar.Frobnicator の場合 --インターフェースプレフィックス
org.project.、使用される名前は BarFrobnicator です。

メソッド、シグナル、プロパティの場合、指定しない場合、名前はデフォルトで次の名前になります。
メソッド、信号、またはプロパティ。

名前には、キャメルケース形式と小文字形式の XNUMX つの形式が使用されます。 キャメルケース
#GType と構造体名には形式が使用され、関数では小文字の形式が使用されます
名前。 小文字形式は、キャメルケースから小文字に変換することによって計算され、
単語の境界にアンダースコアを挿入します (特定のヒューリスティックを使用)。

org.gtk.GDBus.C.Name アノテーションまたは --c-名前空間 オプション
アンダースコアが含まれています (アンダースコアと呼ばれることもあります) アグリーケース)、キャメルケース名が導出されます。
すべてのアンダースコアを削除することによって、小文字の名前が派生します。
弦。 これは、略語が使用される状況によっては便利です。 たとえば、次の場合
注釈は、インターフェイス net.MyCorp.MyApp.iSCSITarget で値とともに使用されます。
iSCSI_Target キャメルケース形式は iSCSITarget ですが、小文字形式は iscsi_target です。
注釈が値 Eject_The_iPod を持つメソッド EjectTheiPod で使用されている場合、
小文字の形式は eject_the_ipod です。

生成 ドックブック マニュアル

生成された各 Docbook XML ファイル ( --generate-docbook 詳細はオプション）
参照エントリ[2] D-Bus インターフェイスについて説明した記事。

OPTIONS

次のオプションがサポートされています。

-h, - 助けて
ヘルプを表示して終了します。

--xml ファイル FILE
D-Bus イントロスペクション XML ファイル。

--インターフェースプレフィックス org.プロジェクト.プレフィックス。
のタイプ名を計算するときに、すべての D-Bus インターフェイス名から削除するプレフィックス。
C バインディングと Docbook いわば 属性を使用する。[3]。

--generate-docbook アウトファイル
各 D-Bus インターフェイスの Docbook ドキュメントを生成し、
OUTFILES-NAME.xml ここで、NAME はインターフェイス名のプレースホルダーです。例:
net.Corp.FooBar など。

--C コードを生成する アウトファイル
すべての D-Bus インターフェイスの C コードを生成し、それを OUTFILES.c および OUTFILES.h に配置します。

--c-名前空間 あなたのプロジェクト
生成された C コードに使用する名前空間。 これは入ることが予想されます キャメルケース[4]または
アグリーケース （上記を参照）。

--c-generate-オブジェクトマネージャー
このオプションが渡された場合、適切な #GDBusObject、#GDBusObjectProxy、
#GDBusObjectSkeleton サブクラスと #GDBusObjectManagerClient サブクラスが生成されます。

-注釈を付ける ELEMENT キー VALUE
指定された XML ファイルに D-Bus アノテーションを挿入するために使用されます。 と一緒に使用できます
インターフェイス、メソッド、シグナル、プロパティ、および引数を次の方法で追加します。

gdbus-codegen --c-namespace MyApp \
--generate-c-code myapp で生成された \
--annotate "org.project.InterfaceName" \
org.gtk.GDBus.C.Name 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 文字列を使用できます。 キー & VALUE.

サポートされている D-バス 注釈

次の D-Bus アノテーションがサポートされています。 gdbus コード生成:

org.freedesktop.DBus.非推奨
どれでも使用できます、 、 そして指定する要素
その値が true の場合、その要素は非推奨であることを示します。 この注釈は次のとおりであることに注意してください。
で定義された Dバス 仕様[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.Name
どれでも使用できます、 、 そして指定する要素
C コードを生成するときに使用する名前。 値は次のとおりであると予想されます キャメルケース[4]または
アグリーケース （上記を参照）。

org.gtk.GDBus.C.ForceGVariant
空ではない文字列に設定すると、自然な文字列の代わりに #GVariant インスタンスが使用されます。
Cタイプ。 この注釈はどのようなものでも使用できます。 そして要素。

org.gtk.GDBus.C.UnixFD
空ではない文字列に設定すると、生成されたコードには交換するパラメータが含まれます。
#GUnixFDList タイプを使用したファイル記述子。 この注釈は以下で使用できます
要素。

org.gtk.GDBus.DocString アノテーションを使用するより簡単な代替方法として、パーサーは
によって使用される gdbus コード生成 XML コメントを次のような方法で解析します。 gtk-doc[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 イントロスペクション XML について考えてみましょう。


















If gdbus コード生成 このファイルでは次のように使用されます。

gdbus-codegen --generate-c-code myapp で生成された\
--c-namespace MyApp \
--interface-prefix net.corp.MyApp。 \
net.Corp.MyApp.Frobber.xml

myapp-generated.[ch] という XNUMX つのファイルが生成されます。 ファイルは要約を提供します
#GTypeInterface から派生した型が呼び出されます MyAppFrobber XNUMX つのインスタンス化可能な型と同様に、
同じ名前ですが接尾辞が プロキシ & スケルトン。 生成されたファイルには、大まかに次の内容が含まれます
以下の施設：

/* 生成された XNUMX つの型の GType マクロ */
#define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
#define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
#define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())

typedef struct _MyAppFrobber MyAppFrobber; /* ダミーの typedef */

typedef構造体
{
GTypeInterfaceparent_iface;

/* ::notification シグナルのシグナル ハンドラー */
void (*通知) (MyAppFrobber *プロキシ、
GVariant *icon_blob、
ジントの高さ、
const gchar* const *messages);

/* ::handle-hello-world シグナルのシグナル ハンドラー */
gboolean (*handle_hello_world) (MyAppFrobber *プロキシ,
GDBusMethodInvocation *呼び出し、
const gchar *挨拶);
MyAppFrobberIface;

/* HelloWorld() を非同期的に呼び出します */
ボイド
my_app_frobber_call_hello_world (MyAppFrobber *プロキシ,
const gchar *こんにちは。
Gキャンセル可能 ※キャンセル可能、
GAsyncReadyCallback コールバック、
gpointer user_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *プロキシ,
gchar **out_response、
GAsyncResult *res、
Gエラー **エラー);

/* HelloWorld() を同期的に呼び出します。 スレッドの呼び出しをブロックします。 */
gboolean
my_app_frobber_call_hello_world_sync (MyAppFrobber *プロキシ,
const gchar *こんにちは。
gchar **out_response、
Gキャンセル可能 ※キャンセル可能、
Gエラー **エラー);

/* HelloWorld() メソッド呼び出しの処理を完了します */
ボイド
my_app_frobber_complete_hello_world (MyAppFrobber *オブジェクト,
GDBusMethodInvocation *呼び出し、
const gchar *応答);

/* ::notification シグナルを送信します / Notice() D-Bus シグナル */
ボイド
my_app_frobber_emit_notification (MyAppFrobber *オブジェクト,
GVariant *icon_blob、
ジントの高さ、
const gchar* const *messages);

/* :verbose GObject プロパティ / Verbose D-Bus プロパティを取得します。
* ブロッキング I/O は行いません。
*/
gboolean my_app_frobber_get_verbose (MyAppFrobber *object);

/* :verbose GObject プロパティ / Verbose D-Bus プロパティを設定します。
* ブロッキング I/O は行いません。
*/
void my_app_frobber_set_verbose (MyAppFrobber *オブジェクト,
gboolean 値);

/* インターフェース情報を取得します */
GDBusInterfaceInfo *my_app_frobber_interface_info (void);

/* 新しいスケルトン オブジェクトを作成し、エクスポートできるようにします */
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 *オブジェクトパス,
Gキャンセル可能 ※キャンセル可能、
GAsyncReadyCallback コールバック、
gpointer user_data);
マイアプリフロッバー *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
Gエラー **エラー);
マイアプリフロッバー *
my_app_frobber_proxy_new_sync (GDBusConnection *接続、
GDBusProxyFlags フラグ、
const gchar *名前、
const gchar *オブジェクトパス,
Gキャンセル可能 ※キャンセル可能、
Gエラー **エラー);

したがって、すべての D-Bus メソッドに対して、メソッドを呼び出すための XNUMX つの C 関数が存在します。
着信呼び出しを処理するための #GObject シグナルと、通話を完了するための XNUMX つの C 関数
電話の着信。 すべての D-Bus 信号に対して、XNUMX つの #GObject 信号と XNUMX つの C 関数があります。
それを発するのです。 D-Bus プロパティごとに、XNUMX つの C 関数が生成されます (セッターが XNUMX つ、セッターが XNUMX つ、
getter) と XNUMX つの #GObject プロパティ。 次の表は生成された施設をまとめたものです
そしてそれらが適用される場合:

┌─────────────┬─────────────┬─ ───────────────┐
││ クライアント │ サーバー │
§───────────┼─────────────┼─ ───────────────┤
│種類 │ 用途 MyAppFrobberProxy │ 実装する任意の型 │
│ │ │ MyAppFrobber │
│ │ │ インターフェース │
§───────────┼─────────────┼─ ───────────────┤
│方法 │ 使用方法 m_a_f_hello_world() │ 経由で受け取る │
│ │ 電話をかける。 │ ハンドル_hello_world() │
│ │ │ シグナルハンドラー。 完了 │
│ │ │ との通話 │
│││ m_a_f_complete_hello_world() │
§───────────┼─────────────┼─ ───────────────┤
│信号 │ 接続する │ 使用する │
││ ：：通知 Gオブジェクト │ m_a_f_emit_notification() から│
│ │ 信号。 │ 信号を発します。 │
§───────────┼─────────────┼─ ───────────────┤
│プロパティ（読み方）│用途 m_a_f_get_verbose() │ #GObject を実装する │
│ │ または :冗長。 │ get_property（） vfunc。 │
§───────────┼─────────────┼─ ───────────────┤
│特性（書き込み）│用途 m_a_f_set_verbose() │ #GObject を実装する │
│ │ または :冗長。 │ set_property() vfunc。 │
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ───────────────┘

クライアント側 使用
生成されたプロキシ タイプは、生成されたコンストラクターで使用できます。

MyAppFrobber *プロキシ;
Gエラー *エラー;

エラー = 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, /* Gキャンセル可能* */
＆エラー）;
/* プロキシを使用して処理を行います */
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:Verbose GObject プロパティのいずれかを使用する D-Bus プロパティ
:冗長 または my_app_get_verbose() & my_app_set_verbose() メソッド。 標準を使用する
#GObject::notify シグナルでプロパティの変更をリッスンします。

すべてのプロパティへのアクセスは #GDBusProxy のプロパティ キャッシュを介して行われるため、I/O は行われないことに注意してください。
プロパティを読み取るとき。 また、プロパティを設定すると、
org.freedesktop.DBus.Properties.Set[8] リモート オブジェクトで呼び出されるメソッド。 これ
ただし、呼び出しは非同期であるため、プロパティの設定はブロックされません。 さらに変更点は、
遅延しており、エラーチェックは不可能です。

サーバ側 使用
生成された MyAppFrobber インターフェイスは、簡単に実装できるように設計されています。
#GObject サブクラス。 たとえば、処理するには こんにちは世界（） メソッド呼び出し、vfunc を設定する
for handle_hello_hello_world() セクションに MyAppFrobberIface 構造。 同様に、
net.Corp.MyApp.Frobber:Verbose プロパティがオーバーライドする :冗長 #GObject プロパティ
サブクラス。 信号を発信するには、次のように使用します。 my_app_emit_signal() または g_signal_emit_by_name()。

多くの場合、サブクラス化する代わりに、生成された MyAppFrobberSkeleton
サブクラス。 受信メソッド呼び出しを処理するには、次を使用します。 g_signal_connect() ：：ハンドル-*
#GObject をオーバーライドする代わりにシグナルを送信します。 get_property（） & set_property() vfuncs、
g_object_get() と g_object_set() または生成されたプロパティのゲッターとセッター (
生成されたクラスには内部プロパティ バッグ実装があります)。

静的gboolean
on_handle_hello_world (MyAppFrobber *インターフェース、
GDBusMethodInvocation *呼び出し、
const gchar *こんにちは。
gpointer user_data)
{
if (g_strcmp0 (挨拶、「ブー」) != 0)
{
gchar *応答;
response = g_strdup_printf (「単語! `%s' と言ったね。」、挨拶);
my_app_complete_hello_world (インターフェイス、呼び出し、応答);
g_free (応答);
}
ほかに
{
g_dbus_method_invocation_return_error (呼び出し、
MY_APP_エラー、
MY_APP_ERROR_NO_WHINING、
"やあ、%s、泣き言は言わないよ!",
g_dbus_method_invocation_get_sender (呼び出し));
}
TRUEを返します。
}

[...]

インターフェース = my_app_frobber_skeleton_new();
my_app_frobber_set_verbose (インターフェース、TRUE);

g_signal_connect (インターフェース、
"ハンドル-hello-world",
G_CALLBACK (on_handle_hello_world)、
some_user_data);

[...]

エラー = NULL;
if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (インターフェイス),
接続、
"/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'、および 'd'))、文字列
(type-strings 's'、'ay'、'o'、および 'g') および文字列の配列 (type-strings 'as'、'ao'、および
'aay') は自然型にマッピングされます (例: #gboolean、#gdouble、#gint、gchar*、gchar**)
等々。 他のすべては #GVariant 型にマップされます。

この自動マッピングは、注釈を使用してオフにできます。
org.gtk.GDBus.C.ForceGVariant - 使用された場合、代わりに #GVariant が常に交換されます。
対応するネイティブ C 型。 この注釈は、を使用するときに使用すると便利かもしれません。
NUL バイトが埋め込まれている可能性のあるデータのバイト文字列 (タイプ文字列 'ay')。

安定性 保証

生成された 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-doc[5]/ Gオブジェクト
内観[9] コメント/注釈。 レイアウトや内容は変更になる場合がございます
将来的なものであるため、SECTION の使用などについては保証されません。

D-Bus インターフェース用に生成された Docbook は変更される予定はありませんが、保証はありません
この時点で与えられます。

生成されたコードはリビジョンにチェックインしないでください。
また、分散ソース アーカイブにも含めるべきではありません。

onworks.net サービスを使用してオンラインで gdbus-codegen を使用する