gdbus-codegen - Online di Cloud

PROGRAM:

NAMA

gdbus-codegen - pembuat kode dan dokumentasi D-Bus

RINGKASAN

gdbus-codegen [-h, --membantu] [--interface-awalan org.proyek.Awalan]
[--hasilkan-kode-c OUTFILE] [--c-ruang nama Proyek Anda]
[--c-generate-object-manager] [--menghasilkan-docbook OUTFILE]
[--xml-file FILE] [--membubuhi keterangan ELEMEN KUNCI NILAI]... FILE [FILE...]

DESKRIPSI

gdbus-codegen digunakan untuk menghasilkan kode dan/atau dokumentasi untuk satu atau lebih D-Bus
antarmuka. Alat itu berbunyi D bis Introspeksi XML[1] file dan menghasilkan file output.
Alat saat ini mendukung pembuatan kode C (melalui --hasilkan-kode-c) dan Docbook XML (melalui
--menghasilkan-docbook).

MENGHASILKAN C KODE

Saat membuat kode C, tipe turunan #GInterface dibuat untuk setiap antarmuka D-Bus.
Selain itu, untuk setiap jenis yang dihasilkan, FooBar, dua jenis beton instan,
Proksi FooBar dan Kerangka FooBar, mengimplementasikan antarmuka tersebut juga dihasilkan. Mantan
berasal dari #GDBusProxy dan dimaksudkan untuk digunakan di sisi klien sedangkan yang terakhir adalah
berasal dari tipe #GDBusInterfaceSkeleton yang membuatnya mudah untuk diekspor di
#GDBusConnection baik secara langsung atau melalui instance #GDBusObjectManagerServer.

Nama setiap tipe C yang dihasilkan berasal dari nama antarmuka D-Bus yang dilucuti dengan
awalan yang diberikan dengan --interface-awalan dan dengan menghilangkan titik dan karakter awal
dikapitalisasi. Misalnya, untuk antarmuka D-Bus com.acme.Coyote nama yang digunakan adalah
ComAcmeCoyote. Untuk antarmuka D-Bus org.project.Bar.Frobnicator dengan --interface-awalan
org.project., nama yang digunakan adalah BarFrobnicator.

Untuk metode, sinyal, dan properti, jika tidak ditentukan, nama defaultnya adalah nama
metode, sinyal atau properti.

Dua bentuk nama yang digunakan - bentuk CamelCase dan bentuk huruf kecil. Kasus Unta
form digunakan untuk #GType dan nama struct, sedangkan bentuk huruf kecil digunakan dalam fungsi
nama. Bentuk huruf kecil dihitung dengan mengonversi dari CamelCase ke huruf kecil dan
menyisipkan garis bawah pada batas kata (menggunakan heuristik tertentu).

Jika nilai yang diberikan oleh anotasi org.gtk.GDBus.C.Name atau --c-ruang nama Option
berisi garis bawah (kadang-kadang disebut Jelek_Kasus), maka nama kotak unta diturunkan
dengan menghapus semua garis bawah, dan nama huruf kecil diturunkan dengan huruf kecil
rangkaian. Ini berguna dalam beberapa situasi di mana singkatan digunakan. Misalnya, jika
anotasi digunakan pada antarmuka net.MyCorp.MyApp.iSCSITarget dengan nilai
iSCSI_Target bentuk CamelCase adalah iSCSITarget sedangkan bentuk huruf kecil adalah iscsi_target.
Jika anotasi digunakan pada metode EjectTheiPod dengan nilai Eject_The_iPod,
bentuk huruf kecil adalah eject_the_ipod.

MENGHASILKAN BUKU DOC DOKUMENTASI

Setiap file XML Docbook yang dihasilkan (lihat: --menghasilkan-docbook opsi untuk detail) adalah a
Entri Ref[2] artikel yang menjelaskan antarmuka D-Bus.

PILIHAN

Opsi berikut didukung:

-h, --membantu
Tunjukkan bantuan dan keluar.

--xml-file FILE
File XML introspeksi D-Bus.

--interface-awalan org.proyek.Awalan.
Awalan untuk menghapus semua nama antarmuka D-Bus saat menghitung nama jenis untuk
C mengikat dan Docbook agak atribut[3].

--menghasilkan-docbook OUTFILE
Hasilkan Dokumentasi Docbook untuk setiap antarmuka D-Bus dan masukkan ke dalam
OUTFILES-NAME.xml di mana NAME adalah tempat untuk nama antarmuka, mis
net.Corp.FooBar dan seterusnya.

--hasilkan-kode-c OUTFILE
Hasilkan kode C untuk semua antarmuka D-Bus dan letakkan di OUTFILES.c dan OUTFILES.h.

--c-ruang nama Proyek Anda
Namespace yang akan digunakan untuk kode C yang dihasilkan. Hal ini diharapkan dalam UntaKasus[4] atau
Jelek_Kasus (Lihat di atas).

--c-generate-object-manager
Jika opsi ini dilewati, cocokkan #GDBusObject, #GDBusObjectProxy,
Subkelas #GDBusObjectSkeleton dan #GDBusObjectManagerClient dihasilkan.

--membubuhi keterangan ELEMEN KUNCI NILAI
Digunakan untuk menyuntikkan anotasi D-Bus ke dalam file XML yang diberikan. Ini dapat digunakan dengan
antarmuka, metode, sinyal, properti, dan argumen dengan cara berikut:

gdbus-codegen --c-namespace Aplikasi Saya \
--generate-c-code yang dihasilkan aplikasi saya \
--annotate "org.project.InterfaceName" \
org.gtk.GDBus.C.Name MyFrobnicator \
--annotate "org.project.InterfaceName:Property" \
kelelawar \
--annotate "org.project.InterfaceName.Method()" \
org.freedesktop.DBus.Usang benar \
--annotate "org.project.InterfaceName.Method()[arg_name]" \
ular mendesis \
--annotate "org.project.InterfaceName::Signal" \
kucing mengeong \
--annotate "org.project.InterfaceName::Signal[arg_name]" \
kotoran anjing \
aplikasi-dbus-interfaces.xml
Setiap string UTF-8 dapat digunakan untuk KUNCI dan NILAI.

DIDUKUNG D-BUS ANOTASI

Anotasi D-Bus berikut didukung oleh gdbus-codegen:

org.freedesktop.DBus.Usang
Dapat digunakan di mana saja , , dan elemen untuk menentukan
bahwa elemen tersebut tidak digunakan lagi jika nilainya benar. Perhatikan bahwa anotasi ini adalah
didefinisikan dalam D bis spesifikasi[1] dan hanya dapat mengasumsikan nilai benar dan salah.
Secara khusus, Anda tidak dapat menentukan versi di mana elemen tersebut tidak digunakan lagi
pesan penghentian yang bermanfaat. Informasi tersebut harus ditambahkan ke elemen
dokumentasi sebagai gantinya.

Saat membuat kode C, anotasi ini digunakan untuk menambahkan #G_GNUC_DEPRECATED ke yang dihasilkan
fungsi untuk elemen

Saat membuat Docbook XML, peringatan penghentian akan muncul di sepanjang dokumentasi
untuk elemennya.

org.gtk.GDBus.Sejak
Dapat digunakan di mana saja , , dan elemen untuk menentukan
versi (string bentuk bebas apa pun tetapi dibandingkan menggunakan fungsi pengurutan yang sadar versi)
elemen muncul di

Saat membuat kode C, bidang ini digunakan untuk memastikan urutan penunjuk fungsi untuk
melestarikan ABI/API, lihat bagian yang disebut “JAMINAN STABILITAS”.

Saat membuat Docbook XML, nilai tag ini muncul di dokumentasi.

org.gtk.GDBus.DocString
String dengan konten Docbook untuk dokumentasi. Anotasi ini dapat digunakan pada
, , , dan elemen.

org.gtk.GDBus.DocString.Short
String dengan konten Docbook untuk dokumentasi singkat/singkat. Anotasi ini hanya bisa
digunakan pada elemen.

org.gtk.GDBus.C.Name
Dapat digunakan di mana saja , , dan elemen untuk menentukan
nama yang akan digunakan saat membuat kode C. Nilainya diharapkan dalam UntaKasus[4] atau
Jelek_Kasus (Lihat di atas).

org.gtk.GDBus.C.ForceGVariant
Jika disetel ke string yang tidak kosong, instance #GVariant akan digunakan sebagai ganti natural
tipe C. Anotasi ini dapat digunakan pada semua dan elemen.

org.gtk.GDBus.C.UnixFD
Jika disetel ke string yang tidak kosong, kode yang dihasilkan akan menyertakan parameter untuk ditukar
deskriptor file menggunakan tipe #GUnixFDList. Anotasi ini dapat digunakan pada
elemen.

Sebagai alternatif yang lebih mudah untuk menggunakan anotasi org.gtk.GDBus.DocString, perhatikan bahwa parser
digunakan oleh gdbus-codegen mem-parsing komentar XML dengan cara yang mirip dengan gtk-doc[dua]:

Perhatikan bahwa @since dapat digunakan dalam bit dokumentasi sebaris (mis. untuk antarmuka,
metode, sinyal, dan properti) untuk menyetel anotasi org.gtk.GDBus. Since. Untuk
org.gtk.GDBus.DocString anotasi (dan komentar sebaris), perhatikan bahwa substring dari formulir
#net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal dan
#net.Corp.InlineDocs:BazProperty semuanya diperluas ke tautan ke antarmuka masing-masing,
metode, sinyal dan properti. Selain itu, substring yang dimulai dengan karakter @ dan % adalah
diterjemahkan sebagai parameter[6] dan konstan[7] masing-masing.

Jika keduanya XML berkomentar dan org.gtk.GDBus.DocString atau org.gtk.GDBus.DocString.Short
anotasi hadir, yang terakhir menang.

CONTOH

Perhatikan XML Introspeksi D-Bus berikut.


















If gdbus-codegen digunakan pada file ini seperti ini:

gdbus-codegen --generate-c-code myapp-generated\
--c-namespace Aplikasi Saya \
--antarmuka-awalan net.corp.MyApp. \
net.Corp.MyApp.Frobber.xml

dua file bernama myapp-generated.[ch] dihasilkan. File memberikan abstrak
#GTypeInterface -tipe turunan yang disebut Aplikasi SayaFrobber serta dua tipe instan dengan
nama yang sama tetapi diakhiri dengan wakil dan Kerangka. File yang dihasilkan, kira-kira, berisi
fasilitas berikut:

/* Makro GType untuk tiga tipe yang dihasilkan */
#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 tiruan */

struktur typedef
{
GTypeInterface parent_iface;

/* Pengendali sinyal untuk ::sinyal notifikasi */
batal (*notifikasi) (MyAppFrobber *proksi,
GVarian *icon_blob,
tinggi gint,
const gchar* const *pesan);

/* Pengatur sinyal untuk ::handle-hello-world signal */
gboolean (*handle_hello_world) (MyAppFrobber *proksi,
GDBusMethodInvocation *doa,
const gchar *salam);
} Aplikasi SayaFrobberIface;

/* Secara tidak sinkron memanggil HelloWorld() */
membatalkan
my_app_frobber_call_hello_world (MyAppFrobber *proksi,
const gchar *salam,
GCancellable *dapat dibatalkan,
GAsyncReadyCallback panggilan balik,
gpointer pengguna_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *proksi,
gchar **keluar_respons,
GAsyncHasil *res,
GERror **kesalahan);

/* Secara sinkron memanggil HelloWorld(). Memblokir utas panggilan. */
gboolean
my_app_frobber_call_hello_world_sync (MyAppFrobber *proksi,
const gchar *salam,
gchar **keluar_respons,
GCancellable *dapat dibatalkan,
GERror **kesalahan);

/* Menyelesaikan penanganan pemanggilan metode HelloWorld() */
membatalkan
my_app_frobber_complete_hello_world (objek MyAppFrobber *,
GDBusMethodInvocation *doa,
const gchar *respon);

/* Memancarkan :: sinyal notifikasi / Notification() sinyal D-Bus */
membatalkan
my_app_frobber_emit_notification (objek MyAppFrobber *,
GVarian *icon_blob,
tinggi gint,
const gchar* const *pesan);

/* Mendapatkan properti :verbose GObject / properti Verbose D-Bus.
* Tidak memblokir I/O.
*/
gboolean my_app_frobber_get_verbose (objek MyAppFrobber *);

/* Menyetel properti :verbose GObject / properti Verbose D-Bus.
* Tidak memblokir I/O.
*/
batalkan my_app_frobber_set_verbose (objek MyAppFrobber *,
nilai gboolean);

/* Mendapatkan info antarmuka */
GDBusInterfaceInfo *my_app_frobber_interface_info (tidak berlaku);

/* Membuat objek kerangka baru, siap untuk diekspor */
MyAppFrobber *my_app_frobber_skeleton_new (tidak berlaku);

/* Konstruktor proxy sisi klien.
*
* Selain itu, _new_for_bus(), _new_for_bus_finish() dan
* _new_for_bus_sync() konstruktor proxy juga dibuat.
*/
membatalkan
my_app_frobber_proxy_new (Koneksi GDBus *koneksi,
Bendera GDBusProxyFlags,
const gchar *nama,
const gchar * jalur_objek,
GCancellable *dapat dibatalkan,
GAsyncReadyCallback panggilan balik,
gpointer pengguna_data);
Aplikasi SayaFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
GERror **kesalahan);
Aplikasi SayaFrobber *
my_app_frobber_proxy_new_sync (Koneksi GDBus *koneksi,
Bendera GDBusProxyFlags,
const gchar *nama,
const gchar * jalur_objek,
GCancellable *dapat dibatalkan,
GERror **kesalahan);

Jadi, untuk setiap metode D-Bus, akan ada tiga fungsi C untuk memanggil metode, satu
Sinyal #GObject untuk menangani panggilan masuk dan satu fungsi C untuk menyelesaikan sebuah
panggilan masuk. Untuk setiap sinyal D-Bus, ada satu sinyal #GObject dan satu fungsi C untuk
memancarkannya. Untuk setiap properti D-Bus, dua fungsi C dihasilkan (satu setter, satu
pengambil) dan satu properti #GObject. Tabel berikut merangkum fasilitas yang dihasilkan
dan di mana mereka berlaku:

┌─────────────────────┬─────────────────────────┬─ ─────────────────────────────┐
│ │. Pelanggan │ Server │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
Jenis Gunakan Proxy AplikasiFrobber Saya Semua jenis mengimplementasikan
itu Aplikasi SayaFrobber │
antarmuka
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
Metode Gunakan m_a_f_halo_dunia() Terima melalui
untuk menelepon. │ menangani_halo_dunia() │
penangan sinyal. Lengkap
│ panggilan dengan
│ │ │. m_a_f_lengkap_halo_dunia() │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
Sinyal Hubungkan ke Gunakan
│ │. ::pemberitahuan GOobjek m_a_f_emit_notification() untuk
sinyal. memancarkan sinyal. │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
Properti (Membaca) Penggunaan m_a_f_get_verbose() Implementasikan #GObject
atau : bertele-tele. │. dapatkan_properti() fungsi │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
Properti (tulisan) Gunakan m_a_f_set_verbose() Implementasikan #GObject
atau : bertele-tele. │. set_properti() fungsi │
└─────────────────────┴─────────────────────────┴─ ─────────────────────────────┘

Sisi klien pemakaian
Anda dapat menggunakan jenis proxy yang dihasilkan dengan konstruktor yang dihasilkan:

MyAppFrobber *proksi;
Gror * kesalahan;

kesalahan = NULL;
proksi = my_app_frobber_proxy_new_for_bus_sync (
G_BUS_TYPE_SESSION,
G_DBUS_PROXY_FLAGS_NONE,
"net.Corp.MyApp", /* nama bus */
"/net/Corp/MyApp/SomeFrobber", /* objek */
NULL, /* GDapat dibatalkan* */
&kesalahan);
/* melakukan sesuatu dengan proxy */
g_object_unref (proksi);

Alih-alih menggunakan fasilitas #GDBusProxy generik, seseorang dapat menggunakan metode yang dihasilkan
seperti my_app_frobber_call_hello_world() untuk meminta
net.Corp.MyApp.Frobber.HelloWorld() Metode D-Bus, sambungkan ke ::pemberitahuan
Sinyal GObject untuk menerima net.Corp.MyApp.Frobber::Pemberitahuan Sinyal D-Bus dan dapatkan/set
itu net.Corp.MyApp.Frobber: Verbose Properti D-Bus menggunakan properti GObject
: bertele-tele atau itu aplikasi_saya_get_verbose() dan aplikasi_saya_set_verbose() metode. Gunakan standar
#GObject::notify signal untuk mendengarkan perubahan properti.

Perhatikan bahwa semua akses properti melalui cache properti #GDBusProxy jadi tidak ada I/O yang pernah dilakukan
saat membaca properti. Perhatikan juga bahwa menyetel properti akan menyebabkan
org.freedesktop.DBus.Properti.Set[8] metode yang akan dipanggil pada objek jarak jauh. Ini
panggilan, bagaimanapun, tidak sinkron sehingga pengaturan properti tidak akan memblokir. Selanjutnya, perubahannya adalah
tertunda dan tidak ada pemeriksaan kesalahan yang mungkin dilakukan.

Sisi server pemakaian
Yang dihasilkan Aplikasi SayaFrobber antarmuka dirancang sehingga mudah untuk diimplementasikan dalam a
Subkelas #GObject. Misalnya, untuk menangani Halo Dunia() pemanggilan metode, atur vfunc
untuk handle_hello_hello_world() dalam Aplikasi SayaFrobberIface struktur. Demikian pula, untuk menangani
net.Corp.MyApp.Frobber: Verbose properti menimpa : bertele-tele #GObject properti dari
subkelas. Untuk memancarkan sinyal, gunakan mis aplikasi_saya_memancarkan_sinyal() atau g_signal_emit_by_name().

Alih-alih mensubklasifikasikan, seringkali lebih mudah menggunakan yang dihasilkan Kerangka AplikasiFrobber Saya
subkelas. Untuk menangani panggilan metode masuk, gunakan g_sinyal_koneksi() pada pengatur terkenal. Pengatur ini menawarkan bantuan hukum kepada traderapabila trader berselisih dengan broker yang terdaftar dengan mereka. ::menangani-*
sinyal dan bukannya menimpa #GObject 's dapatkan_properti() dan set_properti() vfungsi,
gunakan g_object_get() dan g_object_set() atau getter dan setter properti yang dihasilkan (the
kelas yang dihasilkan memiliki implementasi tas properti internal).

gboolean statis
on_handle_hello_world (Antarmuka MyAppFrobber *,
GDBusMethodInvocation *doa,
const gchar *salam,
gpointer data_pengguna)
{
if (g_strcmp0 (salam, "Boo") != 0)
{
gchar *tanggapan;
response = g_strdup_printf("Word! Anda mengatakan `%s'.", salam);
my_app_complete_hello_world (antarmuka, doa, respons);
g_free (tanggapan);
}
lain
{
g_dbus_method_invocation_return_error (doa,
SAYA_APP_ERROR,
SAYA_APP_ERROR_NO_WHINING,
"Hei, %s, tidak akan ada rengekan!",
g_dbus_method_invocation_get_sender (doa));
}
mengembalikan TRUE;
}

[...]

antarmuka = ​​my_app_frobber_skeleton_new();
my_app_frobber_set_verbose (antarmuka, BENAR);

g_signal_connect (antarmuka,
"tangani-halo-dunia",
G_CALLBACK (di_handle_hello_world),
beberapa_data_pengguna);

[...]

kesalahan = NULL;
jika (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (antarmuka),
koneksi,
"/path/of/dbus_object",
&kesalahan))
{
/* menangani kesalahan */
}

Untuk memfasilitasi perubahan atom (beberapa properti berubah pada saat yang sama),
#GObject::notify sinyal diantrekan saat diterima. Antrian terkuras dalam keadaan idle
handler (yang dipanggil dari loop utama utas-default dari utas tempat
kerangka objek dibangun) dan akan menyebabkan emisi dari
org.freedesktop.DBus.Properties::PropertiesChanged[8] sinyal dengan semua properti yang
telah berubah. Gunakan g_dbus_interface_skeleton_flush() atau g_dbus_object_skeleton_flush() untuk
segera kosongkan antrian. Gunakan g_object_freeze_notify() dan g_object_thaw_notify() untuk
perubahan atom jika pada utas yang berbeda.

C JENIS PEMETAAN

Jenis skalar (tipe-string 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' dan 'd') ), string
(type-string 's', 'ay', 'o' dan 'g') dan array string (type-string 'as', 'ao' dan
'aay') dipetakan ke tipe alami, misalnya #gboolean, #gdouble, #gint, gchar*, gchar**
dan seterusnya. Segala sesuatu yang lain dipetakan ke tipe #GVariant.

Pemetaan otomatis ini dapat dimatikan dengan menggunakan anotasi
org.gtk.GDBus.C.ForceGVariant - jika digunakan maka #GVariant selalu ditukar, bukan
tipe C asli yang sesuai. Anotasi ini mungkin nyaman digunakan saat menggunakan
bytestrings (type-string 'ay') untuk data yang dapat menyematkan NUL byte.

STABILITAS JAMINAN

Fungsi C yang dihasilkan dijamin tidak akan mengubah ABI-nya yaitu, jika suatu metode,
sinyal atau properti tidak mengubah tanda tangannya dalam XML introspeksi, C . yang dihasilkan
fungsi juga tidak akan mengubah C ABI-nya. ABI dari instance dan kelas yang dihasilkan
struktur akan dipertahankan juga.

ABI dari #GType s yang dihasilkan hanya akan dipertahankan jika org.gtk.GDBus. Since
anotasi digunakan dengan bijaksana — ini karena VTable untuk #GInterface bergantung pada
fungsi pointer untuk penangan sinyal. Khususnya, jika metode D-Bus, properti atau
sinyal atau ditambahkan ke antarmuka D-Bus, maka ABI dari tipe #GInterface yang dihasilkan adalah
dipertahankan jika, dan hanya jika, setiap metode yang ditambahkan, sinyal properti dianotasi dengan mereka
org.gtk.GDBus.Sejak anotasi menggunakan nomor versi yang lebih besar dari versi sebelumnya.

Kode C yang dihasilkan saat ini kebetulan dianotasi dengan gtk-doc[5] / objek GO
Introspeksi[9] komentar / anotasi. Tata letak dan konten dapat berubah di
masa depan jadi tidak ada jaminan tentang misalnya penggunaan BAGIAN dll diberikan.

Meskipun antarmuka Docbook untuk D-Bus yang dihasilkan tidak diharapkan berubah, tidak ada jaminan
diberikan pada titik ini.

Penting untuk dicatat bahwa kode yang dihasilkan tidak boleh diperiksa ke dalam revisi
sistem kontrol, juga tidak boleh dimasukkan dalam arsip sumber terdistribusi.

Gunakan gdbus-codegen online menggunakan layanan onworks.net