gdbus-codegen - Online nel cloud

PROGRAMMA:

NOME

gdbus-codegen - Generatore di codice e documentazione D-Bus

SINOSSI

codegen gdbus [-h, --Aiuto] [--prefisso-interfaccia org.project.Prefisso]
[--genera-c-code OUTFILE] [--c-spazio dei nomi Il tuo progetto]
[--c-genera-object-manager] [--genera-docbook OUTFILE]
[--file-xml RISORSE] [--annotare ELEMENT KEY VALORE]... FILE [FILE...]

DESCRIZIONE

codegen gdbus viene utilizzato per generare codice e/o documentazione per uno o più D-Bus
interfacce. Lo strumento legge autobus D Introspezione XML[1] file e genera file di output.
Lo strumento attualmente supporta la generazione di codice C (tramite --genera-c-code) e Docbook XML (tramite
--genera-docbook).

GENERARE C CODICE

Quando si genera codice C, viene generato un tipo derivato da #GInterface per ogni interfaccia D-Bus.
Inoltre, per ogni tipo generato, FooBar, due tipi concreti istanziabili,
FooBar Proxy e FooBarScheletro, implementando detta interfaccia vengono anche generate. L'ex
è derivato da #GDBusProxy e destinato all'uso lato client mentre quest'ultimo è
derivato dal tipo #GDBusInterfaceSkeleton che semplifica l'esportazione su a
#GDBusConnection direttamente o tramite un'istanza #GDBusObjectManagerServer.

Il nome di ogni tipo C generato è derivato dal nome dell'interfaccia D-Bus spogliato con
il prefisso dato con --prefisso-interfaccia e con i punti rimossi e i caratteri iniziali
in maiuscolo. Ad esempio, per l'interfaccia D-Bus com.acme.Coyote il nome utilizzato è
ComAcmeCoyote. Per l'interfaccia D-Bus org.project.Bar.Frobnicator con --prefisso-interfaccia
org.project., il nome utilizzato è BarFrobnicator.

Per metodi, segnali e proprietà, se non specificato, il nome predefinito è il nome di
il metodo, il segnale o la proprietà.

Vengono utilizzate due forme del nome: la forma CamelCase e la forma minuscola. Il caso del cammello
form viene utilizzato per #GType e nome struct, mentre il form minuscolo viene utilizzato in function
nomi. La forma minuscola viene calcolata convertendo da CamelCase a minuscolo e
inserendo caratteri di sottolineatura ai confini delle parole (usando determinate euristiche).

Se il valore fornito dall'annotazione org.gtk.GDBus.C.Name o dal --c-spazio dei nomi opzione
contiene un trattino basso (a volte chiamato Brutto_Caso), quindi viene derivato il nome della custodia del cammello
rimuovendo tutti i trattini bassi e il nome in minuscolo viene derivato dal minuscolo di
corda. Ciò è utile in alcune situazioni in cui vengono utilizzate abbreviazioni. Ad esempio, se
l'annotazione viene utilizzata sull'interfaccia net.MyCorp.MyApp.iSCSITarget con il valore
iSCSI_Target la forma CamelCase è iSCSITarget mentre la forma minuscola è iscsi_target.
Se l'annotazione viene utilizzata sul metodo EjectTheiPod con il valore Eject_The_iPod, il
la forma minuscola è eject_the_ipod.

GENERARE DOCBOOK DOCUMENTAZIONE

Ogni file XML Docbook generato (vedi il --genera-docbook opzione per i dettagli) è a
RifEntry[2] articolo che descrive l'interfaccia D-Bus.

VERSIONI

Sono supportate le seguenti opzioni:

-h, --Aiuto
Mostra aiuto ed esci.

--file-xml RISORSE
Il file XML di introspezione D-Bus.

--prefisso-interfaccia org.project.Prefisso.
Un prefisso da eliminare da tutti i nomi delle interfacce D-Bus quando si calcola il nome del tipo per il
Rilegatura C e Docbook sorta attributo[3].

--genera-docbook OUTFILE
Genera documentazione Docbook per ogni interfaccia D-Bus e inseriscila
OUTFILES-NAME.xml dove NAME è un segnaposto per il nome dell'interfaccia, ad es
net.Corp.FooBar e così via.

--genera-c-code OUTFILE
Genera codice C per tutte le interfacce D-Bus e inseriscilo in OUTFILES.c e OUTFILES.h.

--c-spazio dei nomi Il tuo progetto
Lo spazio dei nomi da utilizzare per il codice C generato. Questo dovrebbe essere in Camel Case[4] o
Brutto_Caso (vedi sopra).

--c-genera-object-manager
Se questa opzione viene passata, #GDBusObject adatto, #GDBusObjectProxy,
Vengono generate le sottoclassi #GDBusObjectSkeleton e #GDBusObjectManagerClient.

--annotare ELEMENT KEY VALORE
Utilizzato per inserire annotazioni D-Bus nei file XML forniti. Può essere utilizzato con
interfacce, metodi, segnali, proprietà e argomenti nel modo seguente:

gdbus-codegen --c-namespace MiaApp
--generate-c-code generato da miaapp
--annotate "org.project.InterfaceName"
org.gtk.GDBus.C.Nome MyFrobnicator
--annotate "org.project.InterfaceName:Property"
mazza da bar
--annotate "org.project.InterfaceName.Method()"
org.freedesktop.DBus.Deprecated vero
--annotate "org.project.InterfaceName.Method()[arg_name]"
sibilo di serpente
--annotate "org.project.InterfaceName::Signal"
gatto miagola
--annotate "org.project.InterfaceName::Signal[nome_arg]"
schifo di cane
myapp-dbus-interfaces.xml
Qualsiasi stringa UTF-8 può essere utilizzata per KEY e VALORE.

SUPPORTATI D-BUS ANNOTAZIONI

Le seguenti annotazioni D-Bus sono supportate da codegen gdbus:

org.freedesktop.DBus.Deprecato
Può essere utilizzato su qualsiasi , , e elemento da specificare
che l'elemento è deprecato se il suo valore è vero. Nota che questa annotazione è
definito in autobus D specificazione[1] e può assumere solo i valori vero e falso.
In particolare, non è possibile specificare la versione in cui l'elemento è stato deprecato né
qualsiasi messaggio di disapprovazione utile. Tali informazioni dovrebbero essere aggiunte all'elemento
documentazione invece.

Quando si genera codice C, questa annotazione viene utilizzata per aggiungere #G_GNUC_DEPRECATED a generato
funzioni per l'elemento.

Quando si genera Docbook XML, verrà visualizzato un avviso di deprecazione lungo la documentazione
per l'elemento.

org.gtk.GDBus.Da
Può essere utilizzato su qualsiasi , , e elemento da specificare
la versione (qualsiasi stringa in formato libero ma confrontata utilizzando una funzione di ordinamento compatibile con la versione)
l'elemento è apparso in.

Quando si genera il codice C, questo campo viene utilizzato per garantire l'ordine del puntatore alla funzione per
preservando ABI/API, vedere la sezione denominata “GARANZIE DI STABILITA'”.

Quando si genera Docbook XML, il valore di questo tag viene visualizzato nella documentazione.

org.gtk.GDBus.DocString
Una stringa con contenuto Docbook per la documentazione. Questa annotazione può essere utilizzata su
, , , e elementi.

org.gtk.GDBus.DocString.Short
Una stringa con contenuto Docbook per documentazione breve/breve. Questa annotazione può solo
essere utilizzato su elementi.

org.gtk.GDBus.C.Nome
Può essere utilizzato su qualsiasi , , e elemento da specificare
il nome da utilizzare durante la generazione del codice C. Il valore dovrebbe essere in Camel Case[4] o
Brutto_Caso (vedi sopra).

org.gtk.GDBus.C.ForceGVariant
Se impostato su una stringa non vuota, verrà utilizzata un'istanza #GVariant al posto del naturale
tipo C. Questa annotazione può essere utilizzata su qualsiasi e elemento.

org.gtk.GDBus.C.UnixFD
Se impostato su una stringa non vuota, il codice generato includerà i parametri da scambiare
descrittori di file utilizzando il tipo #GUnixFDList. Questa annotazione può essere utilizzata su
elementi.

Come alternativa più semplice all'utilizzo dell'annotazione org.gtk.GDBus.DocString, si noti che il parser
utilizzato da codegen gdbus analizza i commenti XML in modo simile a gtk-doc[5]:

Nota che @since può essere utilizzato in qualsiasi bit di documentazione in linea (ad esempio per interfacce,
metodi, segnali e proprietà) per impostare l'annotazione org.gtk.GDBus.Since. Per il
org.gtk.GDBus.DocString annotazione (e commenti in linea), notare che le sottostringhe del modulo
#net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal e
#net.Corp.InlineDocs:BazProperty sono tutti espansi per i collegamenti alla rispettiva interfaccia,
metodo, segnale e proprietà. Inoltre, le sottostringhe che iniziano con i caratteri @ e % sono
reso come parametro[6] e costante[7] rispettivamente.

Se entrambi i commenti XML e org.gtk.GDBus.DocString o org.gtk.GDBus.DocString.Short
le annotazioni sono presenti, quest'ultimo vince.

ESEMPIO

Considera il seguente XML di introspezione D-Bus.


















If codegen gdbus è usato su questo file in questo modo:

gdbus-codegen --generate-c-code myapp-generated
--c-spazio dei nomi MiaApp
--interface-prefix net.corp.MyApp.
net.Corp.MyApp.Frobber.xml

vengono generati due file chiamati myapp-generated.[ch]. I file forniscono un abstract
#GTypeInterface -tipo derivato chiamato MyAppFrobber così come due tipi istanziabili con
lo stesso nome ma con suffisso delega e Scheletro. Il file generato, grosso modo, contiene
le seguenti strutture:

/* Macro GType per i tre tipi generati */
#define MY_APP_TYPE_FROBBER (mia_app_frobber_get_type ())
#define MY_APP_TYPE_FROBBER_SKELETON (mia_app_frobber_skeleton_get_type ())
#define MY_APP_TYPE_FROBBER_PROXY (mia_app_frobber_proxy_get_type ())

typedef struct _MyAppFrobber MyAppFrobber; /* typedef fittizio */

struttura typedef
{
GTypeInterface parent_iface;

/* Gestore del segnale per il ::segnale di notifica */
void (*notifica) (MyAppFrobber *proxy,
Gvariant *icon_blob,
altezza gin,
const gchar* const *messaggi);

/* Gestore del segnale per il segnale ::handle-hello-world */
gboolean (*handle_hello_world) (MyAppFrobber *proxy,
GDBusMethodInvocation *invocazione,
const gchar *saluto);
} MiaAppFrobberIface;

/* Chiama in modo asincrono HelloWorld() */
nulla
my_app_frobber_call_hello_world (MyAppFrobber *proxy,
const gchar *saluto,
GCancellabile *cancellabile,
GAsyncReadyCallback richiamata,
gpointer dati_utente);
gbooleano
my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
gchar **out_risposta,
GAsyncResult *res,
GError **errore);

/* Chiama in modo sincrono HelloWorld(). Blocca la chiamata al thread. */
gbooleano
my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
const gchar *saluto,
gchar **out_risposta,
GCancellabile *cancellabile,
GError **errore);

/* Completa la gestione della chiamata al metodo HelloWorld() */
nulla
my_app_frobber_complete_hello_world (MyAppFrobber *oggetto,
GDBusMethodInvocation *invocazione,
const gchar *risposta);

/* Emette il ::segnale di notifica / Notification() segnale D-Bus */
nulla
my_app_frobber_emit_notification (MyAppFrobber *oggetto,
Gvariant *icon_blob,
altezza gin,
const gchar* const *messaggi);

/* Ottiene la proprietà :verbose GObject / Verbose D-Bus proprietà.
* Non blocca I/O.
*/
gboolean my_app_frobber_get_verbose (MyAppFrobber *oggetto);

/* Imposta la proprietà :verbose GObject / Verbose D-Bus proprietà.
* Non blocca I/O.
*/
void my_app_frobber_set_verbose (MyAppFrobber *oggetto,
valore gbooleano);

/* Ottiene le informazioni sull'interfaccia */
GDBusInterfaceInfo *my_app_frobber_interface_info (vuoto);

/* Crea un nuovo oggetto scheletro, pronto per essere esportato */
MyAppFrobber *my_app_frobber_skeleton_new (vuoto);

/* Costruttori proxy lato client.
*
* Inoltre, _new_for_bus(), _new_for_bus_finish() e
* Vengono generati anche i costruttori proxy _new_for_bus_sync().
*/
nulla
my_app_frobber_proxy_new (GDBusConnection *connessione,
flag GDBusProxyFlags,
const gchar *nome,
const gchar *percorso_oggetto,
GCancellabile *cancellabile,
GAsyncReadyCallback richiamata,
gpointer dati_utente);
MyAppFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
GError **errore);
MyAppFrobber *
my_app_frobber_proxy_new_sync (GDBusConnection *connessione,
flag GDBusProxyFlags,
const gchar *nome,
const gchar *percorso_oggetto,
GCancellabile *cancellabile,
GError **errore);

Quindi, per ogni metodo D-Bus, ci saranno tre funzioni C per chiamare il metodo, una
#GSegnale oggetto per la gestione di una chiamata in arrivo e una funzione C per il completamento di un
chiamata in arrivo. Per ogni segnale D-Bus, c'è un segnale #GObject e una funzione C per
emettendolo. Per ogni proprietà D-Bus vengono generate due funzioni C (un setter, uno
getter) e una proprietà #GObject. La tabella seguente riassume le strutture generate
e dove sono applicabili:

? ?
│ │ . │ server │
? ?
Tipi │ Utilizzo MyAppFrobberProxy │ Qualsiasi tipo di implementazione │
│ │ │ il MyAppFrobber │
│ │ │ interfaccia │
? ?
│Metodi │ Utilizzo m_a_f_ciao_mondo() │ Ricevi tramite il │
│ │ per chiamare. ? handle_ciao_mondo() │
│ │ │ gestore del segnale. Completo
│ │ │ la chiamata con │
│ │ │ m_a_f_complete_ciao_mondo() │
? ?
│Segnali │ Collegati a │ Usa │
│ │ ::notifica GObject m_a_f_emit_notification() a
│ segnale. emette un segnale. ?
? ?
Proprietà (Lettura) │ Utilizzo m_a_f_get_verbose() Implementa #GObject
│ │ o :verboso. ? get_proprietà() vfunc. ?
? ?
Proprietà (scrittura) │ Utilizzo m_a_f_set_verbose() Implementa #GObject
│ │ o :verboso. ? set_proprietà() vfunc. ?
? ?

Dalla parte del cliente uso
Puoi utilizzare il tipo di proxy generato con i costruttori generati:

MyAppFrobber *proxy;
GError *errore;

errore = NULL;
proxy = my_app_frobber_proxy_new_for_bus_sync (
G_BUS_TIPO_SESSIONE,
G_DBUS_PROXY_FLAGS_NONE,
"net.Corp.MyApp", /* nome bus */
"/net/Corp/MyApp/SomeFrobber", /* oggetto */
NULL, /* GCancellabile* */
&errore);
/* fai cose con il proxy */
g_oggetto_unref (proxy);

Invece di usare le funzioni generiche #GDBusProxy, si possono usare i metodi generati
ad esempio my_app_frobber_call_hello_world() per invocare il
net.Corp.MyApp.Frobber.HelloWorld() Metodo D-Bus, connettersi al ::notifica
GSegnale oggetto per ricevere il net.Corp.MyApp.Frobber::Notifiche Segnale D-Bus e get/set
, il net.Corp.MyApp.Frobber: Verbose Proprietà D-Bus utilizzando la proprietà GObject
:verboso oppure mia_app_get_verbose() e la mia_app_set_verbose() metodi. Usa lo standard
#GObject::segnala di notifica per ascoltare i cambiamenti di proprietà.

Nota che tutto l'accesso alle proprietà avviene tramite la cache delle proprietà di #GDBusProxy, quindi non viene mai eseguito alcun I/O
durante la lettura delle proprietà. Si noti inoltre che l'impostazione di una proprietà causerà il
org.freedesktop.DBus.Properties.Set[8] metodo da chiamare sull'oggetto remoto. Questo
la chiamata, tuttavia, è asincrona, quindi l'impostazione di una proprietà non si bloccherà. Inoltre, il cambiamento è
ritardato e non è possibile controllare gli errori.

Lato server uso
Il generato MyAppFrobber l'interfaccia è progettata in modo che sia facile da implementare in a
Sottoclasse #GObject. Ad esempio, per gestire Ciao mondo() invocazioni del metodo, impostare il vfunc
da handle_ciao_ciao_mondo() nella MyAppFrobberIface struttura. Allo stesso modo, per gestire il
net.Corp.MyApp.Frobber: Verbose la proprietà sovrascrive il :verboso #GObject proprietà da
sottoclasse. Per emettere un segnale, utilizzare ad es mia_app_emit_signal() o g_signal_emit_by_name().

Invece di sottoclassi, è spesso più facile usare il generato MyAppFrobberScheletro
sottoclasse. Per gestire le chiamate al metodo in entrata, usa g_segnale_connessione() con la ::maneggiare-*
segnali e invece di sovrascrivere #GObject 's get_proprietà() e set_proprietà() vfunzioni,
usa g_object_get() e g_object_set() o i getter e setter di proprietà generati (il
la classe generata ha un'implementazione interna del sacchetto delle proprietà).

gbooleano statico
on_handle_hello_world (MyAppFrobber *interfaccia,
GDBusMethodInvocation *invocazione,
const gchar *saluto,
gpointer dati_utente)
{
if (g_strcmp0 (saluto, "Boo") != 0)
{
gchar *risposta;
response = g_strdup_printf ("Parola! Hai detto `%s'.", saluto);
my_app_complete_hello_world (interfaccia, invocazione, risposta);
g_free (risposta);
}
altro
{
g_dbus_method_invocation_return_error (invocazione,
MIA_APP_ERRORE,
MY_APP_ERROR_NO_WHINE,
"Ehi, %s, non ci saranno pianti!",
g_dbus_method_invocation_get_sender (invocazione));
}
restituisce VERO;
}

[...]

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

g_signal_connect (interfaccia,
"gestire-ciao-mondo",
G_CALLBACK (su_handle_hello_world),
alcuni_dati_utente);

[...]

errore = NULL;
if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interfaccia),
connessione,
"/percorso/di/dbus_object",
&errore))
{
/* gestisce l'errore */
}

Per facilitare i changeset atomici (più proprietà cambiano contemporaneamente),
#GObject::i segnali di notifica vengono accodati quando vengono ricevuti. La coda viene drenata in un inattivo
handler (che viene chiamato dal ciclo principale thread-default del thread in cui il
oggetto scheletro è stato costruito) e causerà emissioni del
org.freedesktop.DBus.Properties::PropertiesChanged[8] segnale con tutte le proprietà che
è cambiato. Usa g_dbus_interface_skeleton_flush() o g_dbus_object_skeleton_flush() per
svuota subito la coda. Usa g_object_freeze_notify() e g_object_thaw_notify() per
changeset atomici se su un thread diverso.

C TIPO MAPPATURA

Tipi scalari (stringhe di tipo "b", "y", "n", "q", "i", "u", "x", "t" e "d")), stringhe
(stringhe di tipo 's', 'ay', 'o' e 'g') e array di stringhe (stringhe di tipo 'as', 'ao' e
'aay') sono mappati ai tipi naturali, ad esempio #gboolean, #gdouble, #gint, gchar*, gchar**
e così via. Tutto il resto è mappato al tipo #GVariant.

Questa mappatura automatica può essere disattivata utilizzando l'annotazione
org.gtk.GDBus.C.ForceGVariant - se usato, viene sempre scambiato un #GVariant invece di
il corrispondente tipo C nativo. Questa annotazione può essere comoda da usare quando si utilizza
stringhe di byte (stringa di tipo 'ay') per i dati che potrebbero avere byte NUL incorporati.

STABILITA ' GARANZIE

Le funzioni C generate sono garantite per non modificare il loro ABI ovvero, se un metodo,
segnale o proprietà non cambia la sua firma nell'XML di introspezione, il C . generato
le funzioni non cambieranno nemmeno il suo C ABI. L'ABI dell'istanza e della classe generate
anche le strutture saranno preservate.

L'ABI dei #GType generati sarà preservato solo se org.gtk.GDBus.Since
l'annotazione è usata con giudizio — questo perché VTable per #GInterface si basa su
puntatori alle funzioni per i gestori di segnale. In particolare, se un metodo D-Bus, proprietà o
segnale o viene aggiunto a un'interfaccia D-Bus, quindi ABI del tipo #GInterface generato è
conservato se, e solo se, ogni metodo aggiunto, segnale di proprietà è annotato con essi
org.gtk.GDBus.Since annotazione che utilizza un numero di versione maggiore rispetto alle versioni precedenti.

Il codice C generato attualmente sembra essere annotato con gtk-doc[5] / GOggetto
Introspezione[9] commenti/annotazioni. Il layout e i contenuti potrebbero cambiare nel
futuro, quindi non viene fornita alcuna garanzia sull'utilizzo della SEZIONE ecc.

Sebbene le interfacce Docbook per D-Bus generate non dovrebbero cambiare, nessuna garanzia
sono dati a questo punto.

È importante notare che il codice generato non deve essere verificato nella revisione
sistemi di controllo, né dovrebbe essere incluso in archivi di sorgenti distribuiti.

Usa gdbus-codegen online utilizzando i servizi onworks.net