gdbus-codegen - онлайн у хмарі

ПРОГРАМА:

ІМ'Я

gdbus-codegen - генератор коду D-Bus і документації

СИНТАКСИС

gdbus-codegen [-h, --допомога] [--інтерфейс-префікс org.project.Prefix]
[--generate-c-код ВИДАННЯ] [--c-простір імен Ваш проект]
[--c-generate-object-manager] [--generate-docbook ВИДАННЯ]
[--xml-файли Фото] [-- анотувати ELEMENT KEY VALUE]... ФАЙЛ [ФАЙЛ...]

ОПИС

gdbus-codegen використовується для генерування коду та/або документації для однієї чи кількох D-Bus
інтерфейси. Інструмент читає D-автобус Інтроспекція XML[1] файлів і створює вихідні файли.
Наразі інструмент підтримує генерацію коду C (через --generate-c-код) і Docbook XML (через
--generate-docbook).

ГЕНЕРУЮЧИЙ C КОД

Під час генерації коду C для кожного інтерфейсу D-Bus генерується тип, отриманий від #GInterface.
Крім того, для кожного згенерованого типу, FooBar, два конкретних миттєвих типи,
FooBarProxy та FooBarSkeleton, що реалізують зазначений інтерфейс також генеруються. Колишній
є похідним від #GDBusProxy і призначений для використання на стороні клієнта, поки останній є
похідний від типу #GDBusInterfaceSkeleton, що полегшує експорт на a
#GDBusConnection безпосередньо або через екземпляр #GDBusObjectManagerServer.

Ім'я кожного згенерованого типу C походить від імені інтерфейсу D-Bus, розділеного з
префікс, поданий с --інтерфейс-префікс з вилученими крапками та початковими символами
з великої літери. Наприклад, для інтерфейсу D-Bus com.acme.Coyote використовується назва
ComAcmeCoyote. Для інтерфейсу D-Bus org.project.Bar.Frobnicator с --інтерфейс-префікс
org.project., використовується назва BarFrobnicator.

Для методів, сигналів і властивостей, якщо не вказано, ім’ям за замовчуванням буде ім’я
метод, сигнал або властивість.

Використовуються дві форми імені - форма CamelCase і форма в нижньому регістрі. Кейс CamelCase
Форма використовується для назви #GType та структури, тоді як форма нижнього регістру використовується у функції
імена. Форма нижнього регістру обчислюється шляхом перетворення з CamelCase у нижній регістр і
вставлення підкреслення на межі слів (з використанням певних евристик).

Якщо значення, задане анотацією org.gtk.GDBus.C.Name або --c-простір імен варіант
містить символ підкреслення (іноді називається Ugly_Case), то виходить назва верблюда
видаляючи всі символи підкреслення, а ім’я в нижньому регістрі одержується за допомогою нижнього регістру
рядок. Це корисно в деяких ситуаціях, коли використовуються скорочення. Наприклад, якщо
анотація використовується в інтерфейсі net.MyCorp.MyApp.iSCSITarget зі значенням
iSCSI_Target форма CamelCase — iSCSItarget, а форма нижнього регістру — iscsi_target.
Якщо анотація використовується для методу EjectTheiPod зі значенням Eject_The_iPod, то
форма нижнього регістру – eject_the_ipod.

ГЕНЕРУЮЧИЙ DOCBOOK ДОКУМЕНТАЦІЯ

Кожен згенерований файл Docbook XML (див --generate-docbook варіант для деталей) є a
RefEntry[2] стаття з описом інтерфейсу D-Bus.

ВАРІАНТИ

Підтримуються такі параметри:

-h, --допомога
Показати довідку та вийти.

--xml-файли Фото
XML-файл інтроспекції D-Bus.

--інтерфейс-префікс org.project.Prefix.
Префікс для видалення з усіх імен інтерфейсу D-Bus під час обчислення назви типу для
C binding і Docbook сорти атрибут[3].

--generate-docbook ВИДАННЯ
Згенеруйте документацію Docbook для кожного інтерфейсу D-Bus і вставте її
OUTFILES-NAME.xml, де NAME є заповнювачем імені інтерфейсу, наприклад
net.Corp.FooBar і так далі.

--generate-c-код ВИДАННЯ
Згенеруйте код C для всіх інтерфейсів D-Bus і помістіть його в OUTFILES.c і OUTFILES.h.

--c-простір імен Ваш проект
Простір імен для згенерованого коду C. Очікується, що це буде в CamelCase[4] або
Ugly_Case (Дивись вище).

--c-generate-object-manager
Якщо цей параметр переданий, підходять #GDBusObject, #GDBusObjectProxy,
Генеруються підкласи #GDBusObjectSkeleton і #GDBusObjectManagerClient.

-- анотувати ELEMENT KEY VALUE
Використовується для введення анотацій D-Bus у надані файли XML. Його можна використовувати з
інтерфейси, методи, сигнали, властивості та аргументи таким чином:

gdbus-codegen --c-простір імен MyApp
--generate-c-код, згенерований 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 KEY та VALUE.

ПІДТРИМАНО D-BUS АНОТАЦІЇ

Наведені нижче анотації D-Bus підтримуються gdbus-codegen:

org.freedesktop.DBus.Не рекомендовано
Можна використовувати на будь-якому , , і елемент для вказівки
що елемент не підтримується, якщо його значення є істинним. Зауважте, що ця анотація є
визначені в D-автобус специфікація[1] і може приймати лише значення true та false.
Зокрема, ви не можете вказати версію, у якій цей елемент застарів
будь-яке корисне повідомлення про припинення підтримки. Таку інформацію слід додати до елемента
натомість документація.

Під час створення коду C ця анотація використовується для додавання #G_GNUC_DEPRECATED до згенерованого
функції для елемента.

Під час створення XML Docbook у документації з’явиться попередження про припинення підтримки
для елемента.

org.gtk.GDBus.Since
Можна використовувати на будь-якому , , і елемент для вказівки
версія (будь-який рядок довільної форми, але порівнюється за допомогою функції сортування з урахуванням версії)
елемент з'явився в.

Під час генерації коду C це поле використовується для забезпечення порядку вказівника функції для
збереження ABI/API, див. розділ «ГАРАНТІЇ СТАБІЛЬНОСТІ».

Під час створення XML Docbook значення цього тегу з’являється в документації.

org.gtk.GDBus.DocString
Рядок із вмістом Docbook для документації. Цю анотацію можна використовувати на
, , , і елементів.

org.gtk.GDBus.DocString.Short
Рядок із вмістом Docbook для короткої/короткої документації. Ця анотація може тільки
використовувати на елементів.

org.gtk.GDBus.C.Name
Можна використовувати на будь-якому , , і елемент для вказівки
ім'я, яке використовуватиметься під час створення коду C. Очікується значення в CamelCase[4] або
Ugly_Case (Дивись вище).

org.gtk.GDBus.C.ForceGVariant
Якщо встановлено не порожній рядок, замість натурального буде використовуватися екземпляр #GVariant
Тип C. Цю анотацію можна використовувати на будь-якому і елемент.

org.gtk.GDBus.C.UnixFD
Якщо встановлено не порожній рядок, згенерований код включатиме параметри для обміну
дескриптори файлів із використанням типу #GUnixFDList. Цю анотацію можна використовувати на
елементи.

Як простішу альтернативу використанню анотації org.gtk.GDBus.DocString, зверніть увагу, що аналізатор
використаний gdbus-codegen аналізує коментарі XML подібно до gtk-doc[два]:

Зауважте, що @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
анотації присутні, останній виграє.

приклад

Розглянемо наступний XML-інтроспекція D-Bus.


















If gdbus-codegen використовується в цьому файлі таким чином:

gdbus-codegen --generate-c-code myapp-generated
--c-простір імен MyApp
--interface-prefix net.corp.MyApp.
net.Corp.MyApp.Frobber.xml

створюється два файли, які називаються myapp-generated.[ch]. Файли містять анотацію
#GTypeInterface -похідний тип називається MyAppFrobber а також два миттєвих типи з
те саме ім'я, але з суфіксом довірена особа та Скелет. Згенерований файл, приблизно, містить
наступні об'єкти:

/* Макроси 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
{
GTypeInterface parent_iface;

/* Обробник сигналу для сигналу::сповіщення */
void (*сповіщення) (MyAppFrobber *проксі,
GVariant *icon_blob,
висота гінта,
const gchar* const *повідомлення);

/* Обробник сигналу для сигналу ::handle-hello-world */
gboolean (*handle_hello_world) (MyAppFrobber *проксі,
GDBusMethodInvocation *виклик,
const gchar *привітання);
} MyAppFrobberIface;

/* Асинхронно викликає HelloWorld() */
анулювати
my_app_frobber_call_hello_world (MyAppFrobber *проксі,
const gchar *привітання,
GCancellable *можна скасувати,
зворотний виклик GAsyncReadyCallback,
gpointer user_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *проксі,
gchar **out_response,
GAsyncResult *res,
GError **помилка);

/* Синхронно викликає HelloWorld(). Блокує потік виклику. */
gboolean
my_app_frobber_call_hello_world_sync (MyAppFrobber *проксі,
const gchar *привітання,
gchar **out_response,
GCancellable *можна скасувати,
GError **помилка);

/* Завершує обробку виклику методу HelloWorld() */
анулювати
my_app_frobber_complete_hello_world (MyAppFrobber *об'єкт,
GDBusMethodInvocation *виклик,
const gchar *відповідь);

/* Видає сигнал::сповіщення / Notification() сигнал D-Bus */
анулювати
my_app_frobber_emit_notification (MyAppFrobber *об'єкт,
GVariant *icon_blob,
висота гінта,
const gchar* const *повідомлення);

/* Отримує властивість :verbose GObject / Властивість Verbose D-Bus.
* Не блокує введення-виведення.
*/
gboolean my_app_frobber_get_verbose (MyAppFrobber *об'єкт);

/* Встановлює властивість :verbose GObject / Властивість Verbose D-Bus.
* Не блокує введення-виведення.
*/
void my_app_frobber_set_verbose (MyAppFrobber *об'єкт,
gboolean значення);

/* Отримує інформацію про інтерфейс */
GDBusInterfaceInfo *my_app_frobber_interface_info (недійсний);

/* Створює новий каркасний об'єкт, готовий до експорту */
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 *path_object,
GCancellable *можна скасувати,
зворотний виклик GAsyncReadyCallback,
gpointer user_data);
MyAppFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
GError **помилка);
MyAppFrobber *
my_app_frobber_proxy_new_sync (GDBusConnection *підключення,
прапори GDBusProxyFlags,
const gchar *ім'я,
const gchar *path_object,
GCancellable *можна скасувати,
GError **помилка);

Таким чином, для кожного методу D-Bus буде три функції C для виклику методу, одна
Сигнал #GObject для обробки вхідного виклику та одна функція C для завершення
Вхідний виклик. Для кожного сигналу D-Bus є один сигнал #GObject і одна функція C
випромінюючи його. Для кожної властивості D-Bus генеруються дві функції C (один установник, один
getter) і одну властивість #GObject. У наступній таблиці підсумовано створені об’єкти
і де вони застосовні:

┌─────────────────────┬─────────────────────────┬─ ──────────────────────────────┐
│ │ Клієнт │ сервер │
├─────────────────────┼─────────────────────────┼─ ──────────────────────────────┤
│Типи │ Використання MyAppFrobberProxy │ Будь-який тип реалізації │
│ │ │ MyAppFrobber │
│ │ │ інтерфейс │
├─────────────────────┼─────────────────────────┼─ ──────────────────────────────┤
│Методи │ Використання m_a_f_hello_world() │ Отримати через │
│ │ дзвонити. │ handle_hello_world() │
│ │ │ обробник сигналів. Завершити │
│ │ │ дзвінок з │
│ │ │ m_a_f_complete_hello_world() │
├─────────────────────┼─────────────────────────┼─ ──────────────────────────────┤
│Сигнали │ Підключіть до │ Використовуйте │
│ │ :: повідомлення GObject │ m_a_f_emit_notification() до │
│ │ сигнал. │ видавати сигнал. │
├─────────────────────┼─────────────────────────┼─ ──────────────────────────────┤
│Властивості (Читання) │ Використання m_a_f_get_verbose() │ Реалізуйте #GObject's │
│ │ або : багатослівний. │ get_property() vfunc. │
├─────────────────────┼─────────────────────────┼─ ──────────────────────────────┤
│Властивості (запис) │ Використ m_a_f_set_verbose() │ Реалізуйте #GObject's │
│ │ або : багатослівний. │ set_property() vfunc. │
└─────────────────────┴─────────────────────────┴─ ──────────────────────────────┘

Клієнтська сторона використання
Ви можете використовувати згенерований тип проксі зі згенерованими конструкторами:

MyAppFrobber *проксі;
GError *помилка;

помилка = 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, /* GCancellable* */
&помилка);
/* робити щось за допомогою проксі */
g_object_unref (проксі);

Замість використання загальних засобів #GDBusProxy можна використовувати згенеровані методи
такий як my_app_frobber_call_hello_world() викликати
net.Corp.MyApp.Frobber.HelloWorld() Метод D-Bus, підключіться до :: повідомлення
GObject сигнал для отримання net.Corp.MyApp.Frobber::Notication Сигнал D-Bus і отримати/налаштувати
net.Corp.MyApp.Frobber: Verbose Властивість D-Bus з використанням властивості GObject
: багатослівний або my_app_get_verbose() та my_app_set_verbose() методи. Використовуйте стандарт
#GObject::notify сигнал прослуховування змін властивостей.

Зауважте, що весь доступ до властивостей здійснюється через кеш властивостей #GDBusProxy, тому ввод-вивод ніколи не виконується
під час читання властивостей. Також зауважте, що встановлення властивості призведе до
org.freedesktop.DBus.Properties.Set[8] метод для виклику віддаленого об'єкта. Це
виклик, однак, є асинхронним, тому налаштування властивості не блокуватиме. Далі, зміна є
затримується, і перевірка помилок неможлива.

На стороні сервера використання
Створене MyAppFrobber Інтерфейс розроблений так, що його легко реалізувати в a
Підклас #GObject. Наприклад, обробляти Привіт Світ() викликів методів, встановіть vfunc
та цінності 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_ERROR,
MY_APP_ERROR_NO_WHINING,
"Гей, %s, не буде скиглити!",
g_dbus_method_invocation_get_sender (виклик));
}
return TRUE;
}

[...]

інтерфейс = my_app_frobber_skeleton_new ();
my_app_frobber_set_verbose (інтерфейс, TRUE);

g_signal_connect (інтерфейс,
"ручка-привіт-світ",
G_CALLBACK (on_handle_hello_world),
деякі_дані_користувача);

[...]

помилка = NULL;
if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (інтерфейс),
з'єднання,
"/path/of/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 TYPE СКАСУВАННЯ

Скалярні типи (рядки типу 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't' і 'd') ), рядки
(рядки типу "s", "ay", "o" і "g") і масиви рядків (рядки типу "as", "ao" і
"aay") зіставляються з природними типами, наприклад #gboolean, #gdouble, #gint, gchar*, gchar**
і так далі. Все інше зіставляється з типом #GVariant.

Це автоматичне відображення можна вимкнути за допомогою анотації
org.gtk.GDBus.C.ForceGVariant - якщо використовується, то завжди замінюється #GVariant замість
відповідний рідний тип C. Цю анотацію може бути зручно використовувати під час використання
рядки байтів (рядок типу 'ay') для даних, у які могли бути вбудовані NUL-байти.

СТАБІЛЬНІСТЬ ГАРАНТІЇ

Згенеровані функції C гарантовано не змінять свій ABI, тобто, якщо метод,
сигнал або властивість не змінюють свій підпис у XML інтроспекції, створеному C
функції також не змінять його C ABI. ABI згенерованого екземпляра та класу
також будуть збережені конструкції.

ABI згенерованих #GType s буде збережено, лише якщо org.gtk.GDBus.Since
анотація використовується розумно — це тому, що VTable для #GInterface покладається на
покажчики функцій для обробників сигналів. Зокрема, якщо метод D-Bus, властивість або
сигнал або додається до інтерфейсу D-Bus, тоді ABI згенерованого типу #GInterface
зберігається тоді і тільки тоді, коли кожен доданий метод, сигнал властивості анотується ними
org.gtk.GDBus.Since анотація з використанням більшого номера версії, ніж попередні версії.

Згенерований код C наразі має анотацію gtk-doc[5] / GObject
Інтроспекція[9] коментарі / анотації. Макет і вміст можуть змінитися в
майбутнє, тому жодних гарантій щодо, наприклад, використання SECTION тощо, не надається.

Хоча згенерований документ Docbook для інтерфейсів D-Bus не зміниться, жодних гарантій
надані на цьому етапі.

Важливо зауважити, що згенерований код не слід перевіряти
системи керування, а також його не слід включати до розподілених архівів джерел.

Використовуйте gdbus-codegen онлайн за допомогою служб onworks.net