gdbus-codegen - En ligne dans le Cloud

PROGRAMME:

Nom

gdbus-codegen - Générateur de code et de documentation D-Bus

SYNOPSIS

gdbus-codegen [-h, --Aidez-moi] [--interface-préfixe org.project.Préfixe]
[--generate-c-code SORTIES] [--c-espace de noms Votre projet]
[--c-generate-object-manager] [--generate-docbook SORTIES]
[--xml-fichiers DOSSIER] [--annoter ELEMENT clé - KEY VALEURE]... FICHIER [FICHIER...]

DESCRIPTION

gdbus-codegen est utilisé pour générer du code et/ou de la documentation pour un ou plusieurs D-Bus
interfaces. L'outil lit Autobus D Introspection XML[1] et génère des fichiers de sortie.
L'outil prend actuellement en charge la génération de code C (via --generate-c-code) et Docbook XML (via
--generate-docbook).

GÉNÉRATEUR C CODE

Lors de la génération du code C, un type dérivé de #GInterface est généré pour chaque interface D-Bus.
De plus, pour chaque type généré, FooBar, deux types concrets instanciables,
FooBarProxy et FooBarSquelette, implémentant ladite interface sont également générés. L'ancien
est dérivé de #GDBusProxy et destiné à être utilisé côté client tandis que ce dernier est
dérivé du type #GDBusInterfaceSkeleton facilitant l'export sur un
#GDBusConnection soit directement, soit via une instance #GDBusObjectManagerServer.

Le nom de chaque type C généré est dérivé du nom de l'interface D-Bus dépouillé de
le préfixe donné avec --interface-préfixe et avec les points supprimés et les caractères initiaux
en majuscule. Par exemple, pour l'interface D-Bus com.acme.Coyote le nom utilisé est
ComAcmeCoyote. Pour l'interface D-Bus org.project.Bar.Frobnicator avec --interface-préfixe
org.project., le nom utilisé est BarFrobnicator.

Pour les méthodes, signaux et propriétés, s'il n'est pas spécifié, le nom par défaut est le nom de
la méthode, le signal ou la propriété.

Deux formes du nom sont utilisées - la forme CamelCase et la forme minuscule. Le CamelCase
form est utilisé pour le #GType et le nom de la structure, tandis que la forme minuscule est utilisée dans la fonction
noms. La forme minuscule est calculée en convertissant de CamelCase en minuscule et
insérer des traits de soulignement aux limites des mots (en utilisant certaines heuristiques).

Si la valeur donnée par l'annotation org.gtk.GDBus.C.Name ou le --c-espace de noms option
contient un trait de soulignement (parfois appelé Laid_Case), alors le nom de cas de chameau est dérivé
en supprimant tous les traits de soulignement, et le nom en minuscule est dérivé en mettant en minuscule le
chaîne de caractères. Ceci est utile dans certaines situations où des abréviations sont utilisées. Par exemple, si
l'annotation est utilisée sur l'interface net.MyCorp.MyApp.iSCSITarget avec la valeur
iSCSI_Target la forme CamelCase est iSCSITarget tandis que la forme minuscule est iscsi_target.
Si l'annotation est utilisée sur la méthode EjectTheiPod avec la valeur Eject_The_iPod, le
la forme minuscule est eject_the_ipod.

GÉNÉRATEUR DOCBOOK DOCUMENTATION

Chaque fichier XML Docbook généré (voir le --generate-docbook option pour plus de détails) est un
RéfEntrée[2] article décrivant l'interface D-Bus.

OPTIONS

Les options suivantes sont prises en charge :

-h, --Aidez-moi
Afficher l'aide et quitter.

--xml-fichiers DOSSIER
Le fichier XML d'introspection D-Bus.

--interface-préfixe org.project.Préfixe.
Un préfixe à supprimer de tous les noms d'interface D-Bus lors du calcul du nom de type du
La reliure C et le Docbook sort attribuer[3].

--generate-docbook SORTIES
Générez la documentation Docbook pour chaque interface D-Bus et mettez-la dans
OUTFILES-NAME.xml où NAME est un espace réservé pour le nom de l'interface, par exemple
net.Corp.FooBar et ainsi de suite.

--generate-c-code SORTIES
Générez du code C pour toutes les interfaces D-Bus et placez-le dans OUTFILES.c et OUTFILES.h.

--c-espace de noms Votre projet
L'espace de noms à utiliser pour le code C généré. Cela devrait être en Affaire de chameau[4] ou
Laid_Case (voir au dessus).

--c-generate-object-manager
Si cette option est passée, #GDBusObject, #GDBusObjectProxy,
Les sous-classes #GDBusObjectSkeleton et #GDBusObjectManagerClient sont générées.

--annoter ELEMENT clé - KEY VALEURE
Utilisé pour injecter des annotations D-Bus dans les fichiers XML donnés. Il peut être utilisé avec
interfaces, méthodes, signaux, propriétés et arguments de la manière suivante :

gdbus-codegen --c-namespace MonApp
--generate-c-code généré par mon application
--annoter "org.project.InterfaceName"
org.gtk.GDBus.C.Name MyFrobnicator
--annoter "org.project.InterfaceName:Property"
batte de barre
--annoter "org.project.InterfaceName.Method()"
org.freedesktop.DBus.Obsolète vrai
--annoter "org.project.InterfaceName.Method()[arg_name]"
sifflement de serpent
--annoter "org.project.InterfaceName :: Signal"
chat miaou
--annotate "org.project.InterfaceName::Signal[arg_name]"
wuff de chien
monapp-dbus-interfaces.xml
Toute chaîne UTF-8 peut être utilisée pour clé - KEY et VALEURE.

PRISE EN CHARGE D-BUS ANNOTATION

Les annotations D-Bus suivantes sont prises en charge par gdbus-codegen:

org.freedesktop.DBus.Obsolète
Peut être utilisé sur n'importe quel , , et élément à préciser
que l'élément est déconseillé si sa valeur est true. Notez que cette annotation est
défini dans le Autobus D spécification[1] et ne peut assumer que les valeurs true et false.
En particulier, vous ne pouvez pas spécifier la version dans laquelle l'élément a été déprécié ni
tout message d'obsolescence utile. Ces informations doivent être ajoutées à l'élément
documentation à la place.

Lors de la génération de code C, cette annotation est utilisée pour ajouter #G_GNUC_DEPRECATED à généré
fonctions pour l'élément.

Lors de la génération de Docbook XML, un avertissement de dépréciation apparaîtra le long de la documentation
pour l'élément.

org.gtk.GDBus.Depuis
Peut être utilisé sur n'importe quel , , et élément à préciser
la version (toute chaîne de forme libre mais comparée à l'aide d'une fonction de tri basée sur la version)
l'élément est apparu dans.

Lors de la génération du code C, ce champ est utilisé pour assurer l'ordre du pointeur de fonction pour
préservant ABI/API, voir la section intitulée « GARANTIES DE STABILITÉ ».

Lors de la génération de Docbook XML, la valeur de cette balise apparaît dans la documentation.

org.gtk.GDBus.DocString
Une chaîne avec du contenu Docbook pour la documentation. Cette annotation peut être utilisée sur
, , , et éléments.

org.gtk.GDBus.DocString.Short
Une chaîne avec du contenu Docbook pour une documentation courte/brève. Cette annotation ne peut
être utilisé sur éléments.

org.gtk.GDBus.C.Name
Peut être utilisé sur n'importe quel , , et élément à préciser
le nom à utiliser lors de la génération du code C. La valeur devrait être en Affaire de chameau[4] ou
Laid_Case (voir au dessus).

org.gtk.GDBus.C.ForceGVariant
Si défini sur une chaîne non vide, une instance #GVariant sera utilisée à la place du naturel
type C. Cette annotation peut être utilisée sur n'importe quel et élément.

org.gtk.GDBus.C.UnixFD
S'il est défini sur une chaîne non vide, le code généré inclura des paramètres à échanger
descripteurs de fichiers utilisant le type #GUnixFDList. Cette annotation peut être utilisée sur
éléments.

Comme alternative plus simple à l'utilisation de l'annotation org.gtk.GDBus.DocString, notez que l'analyseur
utilisé par gdbus-codegen analyse les commentaires XML d'une manière similaire à gtk-doc[5]:

Notez que @since peut être utilisé dans n'importe quel bit de documentation en ligne (par exemple pour les interfaces,
méthodes, signaux et propriétés) pour définir l'annotation org.gtk.GDBus.Since. Pour le
org.gtk.GDBus.DocString (et commentaires en ligne), notez que les sous-chaînes du formulaire
#net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal et
#net.Corp.InlineDocs:BazProperty sont tous étendus aux liens vers l'interface respective,
méthode, signal et propriété. De plus, les sous-chaînes commençant par les caractères @ et % sont
rendu comme paramètre[6] et constant[7] respectivement.

Si les commentaires XML et org.gtk.GDBus.DocString ou org.gtk.GDBus.DocString.Short
les annotations sont présentes, ce dernier l'emporte.

EXEMPLE

Considérez le code XML d'introspection D-Bus suivant.


















If gdbus-codegen est utilisé sur ce fichier comme ceci :

gdbus-codegen --generate-c-code généré par mon application
--c-espace de noms MonApp
--interface-prefix net.corp.MyApp.
net.Corp.MyApp.Frobber.xml

deux fichiers appelés myapp-generated.[ch] sont générés. Les fichiers fournissent un résumé
#GTypeInterface -type dérivé appelé MonAppFrobber ainsi que deux types instanciables avec
le même nom mais suffixé par procuration et Squelette. Le fichier généré, grosso modo, contient
les installations suivantes:

/* Macros GType pour les trois types générés */
#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 factice */

structure typedef
{
GTypeInterface parent_iface ;

/* Gestionnaire de signal pour le ::signal de notification */
void (*notification) (MyAppFrobber *proxy,
Gvariant *icon_blob,
hauteur de coton,
const gchar* const *messages);

/* Gestionnaire de signal pour le signal ::handle-hello-world */
gboolean (*handle_hello_world) (MyAppFrobber *proxy,
GDBusMethodInvocation *invocation,
const gchar *salutation);
} MonAppFrobberIface;

/* Appelle de manière asynchrone HelloWorld() */
annuler
my_app_frobber_call_hello_world (MyAppFrobber * proxy,
const gchar *salut,
GAnnulable *annulable,
Rappel GAsyncReadyCallback,
gpointeur user_data);
gbooléen
my_app_frobber_call_hello_world_finish (MyAppFrobber * proxy,
gchar **out_response,
Résultat GAsync *res,
GError **erreur);

/* Appelle de manière synchrone HelloWorld(). Bloque le fil d'appel. */
gbooléen
my_app_frobber_call_hello_world_sync (MyAppFrobber * proxy,
const gchar *salut,
gchar **out_response,
GAnnulable *annulable,
GError **erreur);

/* Termine la gestion de l'appel de la méthode HelloWorld() */
annuler
my_app_frobber_complete_hello_world (MyAppFrobber *objet,
GDBusMethodInvocation *invocation,
const gchar *réponse);

/* Émet le ::signal de notification / Notification() Signal D-Bus */
annuler
my_app_frobber_emit_notification (MyAppFrobber *objet,
Gvariant *icon_blob,
hauteur de coton,
const gchar* const *messages);

/* Obtient la propriété :verbose GObject / la propriété Verbose D-Bus.
* Ne bloque pas les E/S.
*/
gboolean my_app_frobber_get_verbose (MyAppFrobber *objet);

/* Définit la propriété :verbose GObject / la propriété Verbose D-Bus.
* Ne bloque pas les E/S.
*/
void my_app_frobber_set_verbose (MyAppFrobber *objet,
valeur gbooléenne);

/* Récupère les informations de l'interface */
GDBusInterfaceInfo *my_app_frobber_interface_info (void);

/* Crée un nouvel objet squelette, prêt à être exporté */
MyAppFrobber *my_app_frobber_skeleton_new (void) ;

/* Constructeurs de proxy côté client.
*
* De plus, _new_for_bus(), _new_for_bus_finish() et
* Les constructeurs de proxy _new_for_bus_sync() sont également générés.
*/
annuler
my_app_frobber_proxy_new (GDBusConnection *connexion,
les drapeaux GDBusProxyFlags,
const gchar *nom,
const gchar * chemin_objet,
GAnnulable *annulable,
Rappel GAsyncReadyCallback,
gpointeur user_data);
MonAppFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
GError **erreur);
MonAppFrobber *
my_app_frobber_proxy_new_sync (GDBusConnection *connexion,
les drapeaux GDBusProxyFlags,
const gchar *nom,
const gchar * chemin_objet,
GAnnulable *annulable,
GError **erreur);

Ainsi, pour chaque méthode D-Bus, il y aura trois fonctions C pour appeler la méthode, une
#GObject signal pour gérer un appel entrant et une fonction C pour terminer un
appel entrant. Pour chaque signal D-Bus, il y a un signal #GObject et une fonction C pour
l'émettre. Pour chaque propriété D-Bus, deux fonctions C sont générées (un setter, un
getter) et une propriété #GObject. Le tableau suivant résume les installations générées
et le cas échéant :

?? ??
│ Projet │ Server │
?? ??
Types │ Utilisation MonAppFrobberProxy │ Tout type de mise en œuvre │
│ │ le MonAppFrobber │
│ │ interface │
?? ??
Méthodes │ Utilisation m_a_f_hello_world() Recevez via le │
│ appeler. ?? handle_hello_world() │
│ │ gestionnaire de signal. Terminé │
│ │ l'appel avec │
│ │ m_a_f_complete_hello_world() │
?? ??
Signaux │ Se connecter au │ Utiliser │
│ ::notification GObjet │ m_a_f_emit_notification() à
│ signal. émettre un signal. ??
?? ??
Propriétés (Lecture) │ Utilisation m_a_f_get_verbose() Implémenter #GObject's │
│ ou :verbeux. ?? obtenir_propriété() vfunc. ??
?? ??
│Propriétés (écriture) │ Utilisation m_a_f_set_verbose() Implémenter #GObject's │
│ ou :verbeux. ?? set_property() vfunc. ??
?? ??

Côté client usage
Vous pouvez utiliser le type de proxy généré avec les constructeurs générés :

MonAppFrobber * proxy ;
GError *erreur;

erreur = NULL ;
proxy = my_app_frobber_proxy_new_for_bus_sync (
G_BUS_TYPE_SESSION,
G_DBUS_PROXY_FLAGS_NONE,
"net.Corp.MyApp", /* nom du bus */
"/net/Corp/MyApp/SomeFrobber", /* objet */
NULL, /* GAnnulable* */
&Erreur);
/* faire des trucs avec proxy */
g_object_unref (proxy);

Au lieu d'utiliser les installations génériques #GDBusProxy, on peut utiliser les méthodes générées
tel que mon_app_frobber_call_hello_world() pour invoquer le
net.Corp.MyApp.Frobber.HelloWorld() Méthode D-Bus, connectez-vous au ::notification
Signal GObject pour recevoir le net.Corp.MyApp.Frobber::Notification Signal D-Bus et get/set
le net.Corp.MyApp.Frobber : verbeux Propriété D-Bus utilisant soit la propriété GObject
:verbeux ou la mon_app_get_verbose() et mon_app_set_verbose() méthodes. Utiliser la norme
#GObject::notify signal pour écouter les changements de propriété.

Notez que tous les accès aux propriétés se font via le cache des propriétés de #GDBusProxy, donc aucune E/S n'est jamais effectuée
lors de la lecture des propriétés. Notez également que la définition d'une propriété entraînera le
org.freedesktop.DBus.Properties.Set[8] à appeler sur l'objet distant. Cette
l'appel, cependant, est asynchrone, donc la définition d'une propriété ne bloquera pas. De plus, le changement est
retardé et aucune vérification d'erreur n'est possible.

Du côté serveur usage
Le généré MonAppFrobber l'interface est conçue de sorte qu'il est facile de l'implémenter dans un
#GObject sous-classe. Par exemple, pour gérer Bonjour le monde() appels de méthode, définissez le vfunc
pour handle_hello_hello_world() dans le MonAppFrobberIface structure. De même, pour gérer le
net.Corp.MyApp.Frobber : verbeux la propriété remplace le :verbeux #GObject propriété de la
sous-classe. Pour émettre un signal, utilisez par exemple mon_app_emit_signal() ou g_signal_emit_by_name().

Au lieu de sous-classer, il est souvent plus facile d'utiliser le MyAppFrobberSquelette
sous-classe. Pour gérer les appels de méthode entrants, utilisez g_signal_connect() grâce à la fonction ::manipuler-*
signaux et au lieu de remplacer les #GObject obtenir_propriété() et set_property() vfonctions,
utilisez g_object_get() et g_object_set() ou les getters et setters de propriétés générés (le
la classe générée a une implémentation de sac de propriétés interne).

gboolean statique
on_handle_hello_world (interface MyAppFrobber *,
GDBusMethodInvocation *invocation,
const gchar *salut,
gpointeur user_data)
{
if (g_strcmp0 (salutation, "Boo") != 0)
{
gchar *réponse ;
réponse = g_strdup_printf ("Word ! Vous avez dit `%s'.", salutation);
my_app_complete_hello_world (interface, invocation, réponse);
g_free (réponse);
}
d'autre
{
g_dbus_method_invocation_return_error (appel,
MON_APP_ERROR,
MY_APP_ERROR_NO_WHINING,
"Hé, %s, il n'y aura pas de pleurnicherie !",
g_dbus_method_invocation_get_sender (appel));
}
retourne VRAI;
}

[...]

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

g_signal_connect (interface,
"poignée-bonjour-monde",
G_CALLBACK (on_handle_hello_world),
certaines_données_utilisateur );

[...]

erreur = NULL ;
si (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
connexion,
"/chemin/de/dbus_object",
&Erreur))
{
/* gérer l'erreur */
}

Pour faciliter les ensembles de modifications atomiques (plusieurs propriétés changeant en même temps),
#GObject::notify les signaux sont mis en file d'attente lorsqu'ils sont reçus. La file d'attente est drainée dans un ralenti
gestionnaire (appelé à partir de la boucle principale par défaut du thread du thread où le
objet squelette a été construit) et provoquera des émissions du
org.freedesktop.DBus.Properties ::PropertiesChanged[8] signal avec toutes les propriétés qui
ont changé. Utilisez g_dbus_interface_skeleton_flush() ou g_dbus_object_skeleton_flush() pour
videz immédiatement la file d'attente. Utilisez g_object_freeze_notify() et g_object_thaw_notify() pour
ensembles de modifications atomiques si sur un thread différent.

C TYPE CARTOGRAPHIE

Types scalaires (chaînes de type 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' et 'd') ), chaînes
(chaînes de type 's', 'ay', 'o' et 'g') et des tableaux de chaînes (chaînes de type 'as', 'ao' et
'aay') sont mappés aux types naturels, par exemple #gboolean, #gdouble, #gint, gchar*, gchar**
etc. Tout le reste est mappé au type #GVariant.

Ce mappage automatique peut être désactivé en utilisant l'annotation
org.gtk.GDBus.C.ForceGVariant - s'il est utilisé, un #GVariant est toujours échangé au lieu de
le type C natif correspondant. Cette annotation peut être pratique à utiliser lors de l'utilisation
bytestrings (type-string 'ay') pour les données qui pourraient avoir des octets NUL intégrés.

STABILITÉ GARANTIES

Les fonctions C générées sont garanties de ne pas changer leur ABI c'est-à-dire, si une méthode,
le signal ou la propriété ne change pas sa signature dans le XML d'introspection, le C généré
fonctions ne changeront pas non plus son C ABI. L'ABI de l'instance et de la classe générées
Les structures seront également préservées.

L'ABI des #GType générés sera conservée uniquement si le org.gtk.GDBus.Since
l'annotation est utilisée judicieusement — c'est parce que la VTable pour la #GInterface repose sur
pointeurs de fonctions pour les gestionnaires de signaux. Plus précisément, si une méthode, une propriété ou un
signal ou est ajouté à une interface D-Bus, alors l'ABI du type #GInterface généré est
préservé si, et seulement si, chaque méthode ajoutée, le signal de propriété est annoté avec eux
org.gtk.GDBus.Since annotation utilisant un numéro de version supérieur aux versions précédentes.

Le code C généré se trouve actuellement être annoté avec gtk-doc[5] / GObjet
Introspection[9] commentaires/annotations. La mise en page et le contenu peuvent changer dans le
l'avenir, donc aucune garantie sur, par exemple, l'utilisation de la SECTION, etc. n'est donnée.

Alors que le Docbook généré pour les interfaces D-Bus ne devrait pas changer, aucune garantie
sont donnés à ce stade.

Il est important de noter que le code généré ne doit pas être vérifié dans la révision
systèmes de contrôle, ni ne devrait être inclus dans les archives de sources distribuées.

Utilisez gdbus-codegen en ligne en utilisant les services onworks.net