gdbus-codegen - Online sa Cloud

PROGRAMA:

NAME

gdbus-codegen - D-Bus code at documentation generator

SINOPSIS

gdbus-codegen [-h, - Tumulong] [--interface-prefix org.project.Pfix]
[--generate-c-code MGA OUTFILES] [--c-namespace IyongProyekto]
[--c-generate-object-manager] [--bumuo-docbook MGA OUTFILES]
[--xml-files FILE] [--itala Elemento KEY VALUE]... FILE [FILE...]

DESCRIPTION

gdbus-codegen ay ginagamit upang bumuo ng code at/o dokumentasyon para sa isa o higit pang D-Bus
mga interface. Nagbabasa ang tool D bus Pagsisiyasat ng sarili XML[1] mga file at bumubuo ng mga output file.
Kasalukuyang sinusuportahan ng tool ang pagbuo ng C code (sa pamamagitan ng --generate-c-code) at Docbook XML (sa pamamagitan ng
--bumuo-docbook).

PAGBUBUO C CODE

Kapag bumubuo ng C code, isang #GInterface -derived type ang bubuo para sa bawat D-Bus interface.
Bukod pa rito, para sa bawat nabuong uri, FooBar, dalawang uri ng kongkretong instantiable,
FooBarProxy at FooBarSkeleton, ang pagpapatupad ng nasabing interface ay nabuo din. Ang dating
ay nagmula sa #GDBusProxy at nilayon para gamitin sa panig ng kliyente habang ang huli ay
nagmula sa uri ng #GDBusInterfaceSkeleton na nagpapadali sa pag-export sa isang
#GDBusConnection alinman nang direkta o sa pamamagitan ng isang halimbawa ng #GDBusObjectManagerServer.

Ang pangalan ng bawat nabuong uri ng C ay hinango sa D-Bus na pangalan ng interface na tinanggalan ng gamit
ang prefix na ibinigay sa --interface-prefix at sa mga tuldok na inalis at inisyal na mga character
naka-capitalize. Halimbawa, para sa D-Bus interface com.acme.Coyote ang ginamit na pangalan ay
ComAcmeCoyote. Para sa D-Bus interface org.project.Bar.Frobnicator na may --interface-prefix
org.project., ang ginamit na pangalan ay BarFrobnicator.

Para sa mga pamamaraan, signal at katangian, kung hindi tinukoy, ang pangalan ay default sa pangalan ng
ang paraan, senyas o ari-arian.

Dalawang anyo ng pangalan ang ginagamit - ang CamelCase form at ang lower-case na form. Ang CamelCase
ginagamit ang form para sa #GType at struct name, habang ginagamit ang lower-case na form sa function
mga pangalan. Ang lower-case na form ay kinakalkula sa pamamagitan ng pag-convert mula sa CamelCase sa lower-case at
paglalagay ng mga salungguhit sa mga hangganan ng salita (gamit ang ilang heuristics).

Kung ang value na ibinigay ng org.gtk.GDBus.C.Name annotation o ang --c-namespace opsyon
naglalaman ng underscore (minsan tinatawag na Pangit_Kaso), pagkatapos ay ang pangalan ng camel-case ay hinango
sa pamamagitan ng pag-alis ng lahat ng underscore, at ang lower-case na pangalan ay hinango sa lower-casing ng
string. Ito ay kapaki-pakinabang sa ilang sitwasyon kung saan ginagamit ang mga pagdadaglat. Halimbawa, kung
ang anotasyon ay ginagamit sa interface net.MyCorp.MyApp.iSCSITarget na may halaga
iSCSI_Target ang CamelCase form ay iSCSITarget habang ang lower-case na form ay iscsi_target.
Kung ang anotasyon ay ginamit sa pamamaraang EjectTheiPod na may halagang Eject_The_iPod, ang
Ang lower-case na form ay eject_the_ipod.

PAGBUBUO DOCBOOK Dokumentasyon

Ang bawat nabuong Docbook XML file (tingnan ang --bumuo-docbook opsyon para sa mga detalye) ay a
RefEntry[2] artikulong naglalarawan sa interface ng D-Bus.

Opsyon

Ang mga sumusunod na opsyon ay sinusuportahan:

-h, - Tumulong
Ipakita ang tulong at lumabas.

--xml-files FILE
Ang D-Bus introspection XML file.

--interface-prefix org.project.Pfix.
Isang prefix na aalisin mula sa lahat ng D-Bus na mga pangalan ng interface kapag kinakalkula ang typename para sa
C binding at ang Docbook sortas katangian[3].

--bumuo-docbook MGA OUTFILES
Bumuo ng Docbook Documentation para sa bawat D-Bus interface at ilagay ito
OUTFILES-NAME.xml kung saan ang NAME ay isang place-holder para sa pangalan ng interface, hal
net.Corp.FooBar at iba pa.

--generate-c-code MGA OUTFILES
Bumuo ng C code para sa lahat ng interface ng D-Bus at ilagay ito sa OUTFILES.c at OUTFILES.h.

--c-namespace IyongProyekto
Ang namespace na gagamitin para sa nabuong C code. Ito ay inaasahang papasok CamelCase[4] o
Pangit_Kaso (tingnan sa itaas).

--c-generate-object-manager
Kung naipasa ang opsyong ito, angkop ang #GDBusObject, #GDBusObjectProxy,
Ang mga subclass ng #GDBusObjectSkeleton at #GDBusObjectManagerClient ay nabuo.

--itala Elemento KEY VALUE
Ginagamit upang mag-inject ng mga anotasyon ng D-Bus sa ibinigay na mga XML file. Maaari itong gamitin kasama ng
mga interface, pamamaraan, signal, katangian at argumento sa sumusunod na paraan:

gdbus-codegen --c-namespace MyApp \
--generate-c-code myapp-generated \
--annotate "org.project.InterfaceName" \
org.gtk.GDBus.C.Name MyFrobnicator \
--annotate "org.project.InterfaceName:Property" \
bar bat \
--annotate "org.project.InterfaceName.Method()" \
org.freedesktop.DBus.Deprecated true \
--annotate "org.project.InterfaceName.Method()[arg_name]" \
sumisitsit ng ahas \
--annotate "org.project.InterfaceName::Signal" \
pusa meow \
--annotate "org.project.InterfaceName::Signal[arg_name]" \
aso tanga \
myapp-dbus-interfaces.xml
Anumang UTF-8 string ay maaaring gamitin para sa KEY at VALUE.

Sinusuportahan D-BUS MGA ANOTASYON

Ang mga sumusunod na D-Bus annotation ay sinusuportahan ng gdbus-codegen:

org.freedesktop.DBus.Hindi na ginagamit
Maaaring gamitin sa anumang , , at elemento upang tukuyin
na ang elemento ay hindi na ginagamit kung ang halaga nito ay totoo. Tandaan na ang anotasyong ito ay
tinukoy sa D bus detalye[1] at maaari lamang ipalagay ang mga halagang totoo at mali.
Sa partikular, hindi mo maaaring tukuyin ang bersyon kung saan hindi na ginagamit ang elemento o
anumang kapaki-pakinabang na mensahe ng pagtigil sa paggamit. Ang nasabing impormasyon ay dapat idagdag sa elemento
dokumentasyon sa halip.

Kapag bumubuo ng C code, ginagamit ang anotasyong ito upang magdagdag ng #G_GNUC_DEPRECATED sa nabuo
mga function para sa elemento.

Kapag bumubuo ng Docbook XML, may lalabas na babala sa paghinto sa paggamit kasama ng dokumentasyon
para sa elemento.

org.gtk.GDBus.Since
Maaaring gamitin sa anumang , , at elemento upang tukuyin
ang bersyon (anumang free-form na string ngunit inihambing gamit ang isang bersyon-aware sort function)
ang elemento ay lumitaw sa.

Kapag bumubuo ng C code, ginagamit ang field na ito upang matiyak ang pagkakasunud-sunod ng pointer ng function para sa
pag-iingat ng ABI/API, tingnan ang seksyong tinatawag na “STABILITY GUARANTEES”.

Kapag bumubuo ng Docbook XML, lumalabas ang halaga ng tag na ito sa dokumentasyon.

org.gtk.GDBus.DocString
Isang string na may nilalaman ng Docbook para sa dokumentasyon. Maaaring gamitin ang anotasyong ito sa
, , , at mga elemento.

org.gtk.GDBus.DocString.Short
Isang string na may nilalamang Docbook para sa maikli/maiksing dokumentasyon. Ang anotasyong ito ay maaari lamang
gamitin sa mga elemento.

org.gtk.GDBus.C.Name
Maaaring gamitin sa anumang , , at elemento upang tukuyin
ang pangalan na gagamitin kapag bumubuo ng C code. Ang halaga ay inaasahang nasa CamelCase[4] o
Pangit_Kaso (tingnan sa itaas).

org.gtk.GDBus.C.ForceGVariant
Kung itatakda sa isang walang laman na string, isang #GVariant instance ang gagamitin sa halip na natural
C uri. Maaaring gamitin ang anotasyong ito sa alinman at elemento.

org.gtk.GDBus.C.UnixFD
Kung itatakda sa isang walang laman na string, ang nabuong code ay magsasama ng mga parameter na ipapalit
mga deskriptor ng file gamit ang uri ng #GUnixFDList. Maaaring gamitin ang anotasyong ito sa
mga elemento.

Bilang isang mas madaling alternatibo sa paggamit ng org.gtk.GDBus.DocString annotation, tandaan na ang parser
ginamit ni gdbus-codegen nag-parse ng mga komento sa XML sa paraang katulad ng gtk-doc[5]:

Tandaan na ang @since ay maaaring gamitin sa anumang inline na dokumentasyong bit (hal para sa mga interface,
pamamaraan, signal, at property) para itakda ang org.gtk.GDBus.Since annotation. Para sa
org.gtk.GDBus.DocString annotation (at inline na mga komento), tandaan na ang mga substring ng form
#net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal at
#net.Corp.InlineDocs:BazProperty ay pinalawak lahat sa mga link sa kani-kanilang interface,
paraan, signal at ari-arian. Bilang karagdagan, ang mga substring na nagsisimula sa @ at % na mga character ay
nai-render bilang parametro[6] at patuloy[7] ayon sa pagkakabanggit.

Kung parehong XML komento at org.gtk.GDBus.DocString o org.gtk.GDBus.DocString.Short
ang mga anotasyon ay naroroon, ang huli ay nanalo.

Halimbawa

Isaalang-alang ang sumusunod na D-Bus Introspection XML.


















If gdbus-codegen ay ginagamit sa file na ito tulad nito:

gdbus-codegen --generate-c-code myapp-generated \
--c-namespace MyApp \
--interface-prefix net.corp.MyApp. \
net.Corp.MyApp.Frobber.xml

dalawang file na tinatawag na myapp-generated.[ch] ay nabuo. Ang mga file ay nagbibigay ng abstract
#GTypeInterface -derived type na tinatawag MyAppFrobber pati na rin ang dalawang instantiable na uri na may
parehong pangalan ngunit may panlapi Kahalili at Balangkas. Ang nabuong file, halos, ay naglalaman ng
ang mga sumusunod na pasilidad:

/* Mga macro ng GType para sa tatlong nabuong uri */
#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; /* Dummy typedef */

typedef struct
{
GTypeInterface parent_iface;

/* Signal handler para sa ::notification signal */
walang bisa (*notification) (MyAppFrobber *proxy,
GVariant *icon_blob,
gint na taas,
const gchar* const *mensahe);

/* Handler ng signal para sa ::handle-hello-world signal */
gboolean (*handle_hello_world) (MyAppFrobber *proxy,
GDBusMethodInvocation *invocation,
const gchar *pagbati);
} MyAppFrobberIface;

/* Asynchronous na tumatawag sa HelloWorld() */
walang bisa
my_app_frobber_call_hello_world (MyAppFrobber *proxy,
const gchar *bati,
Gcancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
gchar **out_response,
GAsyncResult *res,
GError **error);

/* Kasabay na tawag sa HelloWorld(). Bina-block ang thread ng pagtawag. */
gboolean
my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
const gchar *bati,
gchar **out_response,
Gcancellable *cancellable,
GError **error);

/* Nakumpleto ang paghawak sa HelloWorld() method call */
walang bisa
my_app_frobber_complete_hello_world (MyAppFrobber *object,
GDBusMethodInvocation *invocation,
const gchar *tugon);

/* Nagpapalabas ng ::notification signal / Notification() D-Bus signal */
walang bisa
my_app_frobber_emit_notification (MyAppFrobber *object,
GVariant *icon_blob,
gint na taas,
const gchar* const *mensahe);

/* Nakukuha ang :verbose GObject property / Verbose D-Bus property.
* Hindi nakaharang sa I/O.
*/
gboolean my_app_frobber_get_verbose (MyAppFrobber *object);

/* Itinatakda ang :verbose GObject property / Verbose D-Bus property.
* Hindi nakaharang sa I/O.
*/
void my_app_frobber_set_verbose (MyAppFrobber *object,
halaga ng gboolean);

/* Nakukuha ang impormasyon ng interface */
GDBusInterfaceInfo *my_app_frobber_interface_info (walang bisa);

/* Lumilikha ng bagong skeleton object, handa nang i-export */
MyAppFrobber *my_app_frobber_skeleton_new (walang bisa);

/* Mga tagabuo ng proxy sa panig ng kliyente.
*
* Bukod pa rito, _new_for_bus(), _new_for_bus_finish() at
* Ang _new_for_bus_sync() proxy constructors ay nabuo din.
*/
walang bisa
my_app_frobber_proxy_new (GDBusConnection *koneksyon,
Mga flag ng GDBusProxyFlags,
const gchar *pangalan,
const gchar *object_path,
Gcancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
MyAppFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
GError **error);
MyAppFrobber *
my_app_frobber_proxy_new_sync (GDBusConnection *koneksyon,
Mga flag ng GDBusProxyFlags,
const gchar *pangalan,
const gchar *object_path,
Gcancellable *cancellable,
GError **error);

Kaya, para sa bawat paraan ng D-Bus, magkakaroon ng tatlong C function para sa pagtawag sa pamamaraan, isa
#GObject signal para sa paghawak ng isang papasok na tawag at isang C function para sa pagkumpleto ng isang
papasok na tawag. Para sa bawat signal ng D-Bus, mayroong isang #GObject signal at isang C function para sa
nagpapalabas nito. Para sa bawat pag-aari ng D-Bus, dalawang C function ang nabuo (isang setter, isa
getter) at isang #GObject property. Ang sumusunod na talahanayan ay nagbubuod sa mga nabuong pasilidad
at kung saan naaangkop ang mga ito:

┌─────────────────────┬─────────────────────────┬─ ─────────────────────────────┐
│ │ Kliente │ server │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
│Mga Uri │ Gamitin MyAppFrobberProxy │ Anumang uri ng pagpapatupad │
│ │ │ ang MyAppFrobber │
│ │ │ interface │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
│Mga Paraan │ Gamitin m_a_f_hello_world() │ Tumanggap sa pamamagitan ng │
│ │ para tumawag. │ handle_hello_world() │
│ │ │ tagahawak ng signal. Kumpleto │
│ │ │ ang tawag na may │
│ │ │ m_a_f_complete_hello_world() │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
│Mga Signal │ Kumonekta sa │ Gamitin │
│ │ ::notification GObject │ m_a_f_emit_notification() sa │
│ │ signal. │ naglalabas ng signal. │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
│Properties (Pagbasa) │ Gamitin m_a_f_get_verbose() │ Ipatupad ang #GObject's │
│ │ o :verbose. │ get_property() vfunc. │
├─────────────────────┼─────────────────────────┼─ ─────────────────────────────┤
│Properties (pagsulat) │ Gamitin m_a_f_set_verbose() │ Ipatupad ang #GObject's │
│ │ o :verbose. │ set_property() vfunc. │
└─────────────────────┴─────────────────────────┴─ ─────────────────────────────┘

Panig ng kliyente paggamit
Maaari mong gamitin ang nabuong uri ng proxy sa mga nabuong constructor:

MyAppFrobber *proxy;
GError *error;

error = NULL;
proxy = my_app_frobber_proxy_new_for_bus_sync (
G_BUS_TYPE_SESSION,
G_DBUS_PROXY_FLAGS_NONE,
"net.Corp.MyApp", /* pangalan ng bus */
"/net/Corp/MyApp/SomeFrobber", /* object */
NULL, /* GCancellable* */
&error);
/* gumawa ng mga bagay gamit ang proxy */
g_object_unref (proxy);

Sa halip na gamitin ang mga generic na pasilidad ng #GDBusProxy, maaaring gamitin ng isa ang mga nabuong pamamaraan
tulad ng my_app_frobber_call_hello_world() upang tawagan ang
net.Corp.MyApp.Frobber.HelloWorld() Paraan ng D-Bus, kumonekta sa ::notification
GObject signal upang matanggap ang net.Corp.MyApp.Frobber::Notication D-Bus signal at kumuha/itakda
ang net.Corp.MyApp.Frobber:Verbose D-Bus Property gamit ang alinman sa GObject property
:verbose o ang my_app_get_verbose() at my_app_set_verbose() paraan. Gamitin ang pamantayan
#GObject::notify signal para makinig sa mga pagbabago sa property.

Tandaan na ang lahat ng access sa property ay sa pamamagitan ng property cache ng #GDBusProxy kaya walang I/O na nagagawa
kapag nagbabasa ng mga katangian. Tandaan din na ang pagtatakda ng isang property ay magiging sanhi ng
org.freedesktop.DBus.Properties.Set[8] paraan na itatawag sa malayong bagay. Ito
Ang tawag, gayunpaman, ay asynchronous kaya ang pagtatakda ng property ay hindi ma-block. Dagdag pa, ang pagbabago ay
naantala at walang error checking ang posible.

Sa panig ng server paggamit
Ang nabuo MyAppFrobber interface ay dinisenyo upang ito ay madaling ipatupad ito sa isang
#GObject subclass. Halimbawa, upang mahawakan HelloWorld() method invocations, itakda ang vfunc
para handle_hello_hello_world() nasa MyAppFrobberIface istraktura. Katulad, upang mahawakan ang
net.Corp.MyApp.Frobber:Verbose ari-arian override ang :verbose #GObject property mula sa
subclass. Upang maglabas ng signal, gamitin ang hal my_app_emit_signal() o g_signal_emit_by_name().

Sa halip na subclassing, kadalasan ay mas madaling gamitin ang nabuo MyAppFrobberSkeleton
subclass. Upang mahawakan ang mga papasok na paraan ng tawag, gamitin g_signal_connect() sa ::hawakan-*
signal at sa halip na i-override ang #GObject 's get_property() at set_property() vfuncs,
gamitin ang g_object_get() at g_object_set() o ang nabuong property getters at setters (ang
ang nabuong klase ay may panloob na pagpapatupad ng bag ng ari-arian).

static na gboolean
on_handle_hello_world (MyAppFrobber *interface,
GDBusMethodInvocation *invocation,
const gchar *bati,
gpointer user_data)
{
if (g_strcmp0 (pagbati, "Boo") != 0)
{
gchar *tugon;
tugon = g_strdup_printf ("Word! Sabi mo `%s'.", pagbati);
my_app_complete_hello_world (interface, invocation, tugon);
g_free (tugon);
}
iba
{
g_dbus_method_invocation_return_error (invocation,
MY_APP_ERROR,
MY_APP_ERROR_NO_WHINING,
"Hoy, %s, walang reklamo!",
g_dbus_method_invocation_get_sender (invocation));
}
ibalik ang TUNAY;
}

[...]

interface = my_app_frobber_skeleton_new ();
my_app_frobber_set_verbose (interface, TRUE);

g_signal_connect (interface,
"hawakan-hello-world",
G_CALLBACK (on_handle_hello_world),
some_user_data);

[...]

error = NULL;
kung (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
koneksyon,
"/path/of/dbus_object",
&error))
{
/* error sa paghawak */
}

Upang mapadali ang mga pagbabago sa atomic (maramihang mga katangian na nagbabago nang sabay-sabay),
#GObject::notify signal ay nakapila kapag natanggap. Ang pila ay pinatuyo sa isang idle
handler (na tinatawag mula sa thread-default na pangunahing loop ng thread kung saan ang
skeleton object ay ginawa) at magdudulot ng mga paglabas ng
org.freedesktop.DBus.Properties::PropertiesChanged[8] signal kasama ang lahat ng mga katangian na
nagbago. Gamitin ang g_dbus_interface_skeleton_flush() o g_dbus_object_skeleton_flush() upang
bakante agad ang pila. Gamitin ang g_object_freeze_notify() at g_object_thaw_notify() para sa
atomic changesets kung nasa ibang thread.

C TYPE Pagma-map

Mga uri ng scaler (type-strings 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' at 'd') ), mga string
(type-strings 's', 'ay', 'o' at 'g') at arrays ng string (type-strings 'as', 'ao' at
'aay') ay nakamapa sa mga natural na uri, hal #gboolean, #gdouble, #gint, gchar*, gchar**
at iba pa. Lahat ng iba pa ay nakamapa sa uri ng #GVariant.

Maaaring i-off ang awtomatikong pagmamapa na ito sa pamamagitan ng paggamit ng anotasyon
org.gtk.GDBus.C.ForceGVariant - kung ginamit, ang isang #GVariant ay palaging ipinagpapalit sa halip na
ang kaukulang uri ng katutubong C. Maaaring maginhawang gamitin ang anotasyong ito kapag ginagamit
bytestrings (type-string 'ay') para sa data na maaaring naka-embed ng NUL byte.

STABILITY Mga GABAY

Ang mga nabuong C function ay ginagarantiyahan na hindi mababago ang kanilang ABI iyon ay, kung isang paraan,
signal o property ay hindi nagbabago ng lagda nito sa introspection XML, ang nabuong C
hindi rin babaguhin ng mga function ang C ABI nito. Ang ABI ng nabuong instance at klase
ang mga istruktura ay mapangalagaan din.

Ang ABI ng nabuong #GType s ay papanatilihin lamang kung ang org.gtk.GDBus.Since
Ang anotasyon ay maingat na ginagamit — ito ay dahil umaasa ang VTable para sa #GInterface
function na mga pointer para sa mga humahawak ng signal. Sa partikular, kung ang isang D-Bus na paraan, ari-arian o
signal o idinagdag sa isang D-Bus interface, pagkatapos ay ang ABI ng nabuong #GInterface na uri ay
napreserba kung, at kung, ang bawat idinagdag na paraan, ang signal ng property ay may anotasyon sa kanila
org.gtk.GDBus.Since annotation gamit ang mas malaking numero ng bersyon kaysa sa mga nakaraang bersyon.

Ang nabuong C code ay kasalukuyang may anotasyon gtk-doc[5] / GObject
Pagsisiyasat ng sarili[9] komento / anotasyon. Maaaring magbago ang layout at mga nilalaman sa
hinaharap kaya walang mga garantiya tungkol sa eg SECTION paggamit atbp ay ibinigay.

Habang ang nabuong Docbook para sa mga interface ng D-Bus ay hindi inaasahang magbabago, walang mga garantiya
ay ibinigay sa puntong ito.

Mahalagang tandaan na ang nabuong code ay hindi dapat i-check sa rebisyon
control system, at hindi rin ito dapat isama sa mga distributed source archive.

Gumamit ng gdbus-codegen online gamit ang mga serbisyo ng onworks.net