| dbus-binding-tool(1) | User Commands | dbus-binding-tool(1) |
نام (NAME)
dbus-binding-tool - ابزار ایجاد انقیادهای زبان C برای dbus-glib.
خلاصه دستور (SYNOPSIS)
dbus-binding-tool [--force] [--help] [--ignore-unsupported] [--mode=pretty|glib-client|glib-server] [--output=file] [--prefix=symbol-prefix] [--version] [file...]
توضیحات (DESCRIPTION)
دستور dbus-binding-tool برای نمایانسازی یک GObject از طریق D-Bus، با استفاده از انقیاد منسوخشدهی dbus-glib برای GLib به کار میرود. ابزار dbus-binding-tool به عنوان ورودی از یک فایل XML دروننگری (Introspection) D-Bus استفاده میکند. در خروجی، انقیادهای سمت کلاینت یا سمت سرور تولید میشوند. این خروجی یک فایل سرآیند (header) است که استفاده از یک شیء D-Bus راه دور را آسان میسازد. خروجی به خروجی استاندارد یا به نام فایلی که با آرگومان --output مشخص شده ارسال میشود.
توضیحات تکمیلی (EXTENDED DESCRIPTION)
متن زیر نمونهای از یک فایل XML دروننگری D-Bus است که شیئی با یک متد به نام ManyArgs را شرح میدهد:
<?xml version="1.0" encoding="UTF-8" ?>
<node name="/com/example/MyObject">
<interface name="com.example.MyObject">
<method name="ManyArgs">
<arg type="u" name="x" direction="in" />
<arg type="s" name="str" direction="in" />
<arg type="d" name="trouble" direction="in" />
<arg type="d" name="d_ret" direction="out" />
<arg type="s" name="str_ret" direction="out" />
</method>
</interface>
</node>
ابزار dbus-binding-tool از یادداشتها (annotations) در قالب XML برای کنترل بیشتر بر نحوه تولید انقیادها پشتیبانی میکند.
انقیادهای سمت کلاینت (client-side bindings)
هنگام ساخت انقیادهای سمت کلاینت، آرگومان --mode=glib-client استفاده میشود. انقیادهای سمت کلاینت از یادداشت "org.freedesktop.DBus.Glib.NoReply" پشتیبانی میکنند. این یادداشت درون برچسب <method> مشخص میشود تا نشان دهد کلاینت منتظر پاسخی برای فراخوانی متد نیست، بنابراین پاسخی نباید ارسال شود. این کار اغلب برای سرعت بخشیدن به فراخوانیهای مکرر متد در مواقعی که هیچ آرگومان "out" وجود ندارد استفاده میشود، و ندانستن اینکه متد با موفقیت انجام شده یا خیر مصالحهای قابلقبول برای نصف کردن ترافیک گذرگاه (bus) است. برای مثال:
<method name "FooMethod"> [...] <annotation name="org.freedesktop.DBus.GLib.NoReply" value="yes"/> [...] </method>
انقیادهای سمت سرور (server-side bindings)
هنگام ساخت انقیادهای سمت سرور، آرگومان --mode=glib-server استفاده میشود. همچنین هنگام ساخت انقیادهای سمت سرور باید از آرگومان --prefix استفاده شود تا توابع موجود در خروجی تولیدشده با مقدار مشخصشده پیشوندگذاری شوند. انقیادهای سمت سرور از یادداشتهای زیر پشتیبانی میکنند:
"org.freedesktop.DBus.GLib.CSymbol"
این یادداشت برای مشخص کردن نام نمادهای C برای انواع مختلف (رابط، متد و غیره) در صورتی که با نام تولیدشده توسط D-Bus متفاوت باشد، استفاده میشود.
<interface name="com.example.MyObject">
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="my_object"/>
[...]
<method name "ManyArgs">
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="my_object_many_args"/>
[...]
</method>
</interface>
"org.freedesktop.DBus.GLib.Async"
این یادداشت، پیادهسازی متد را به عنوان یک تابع ناهمگام (asynchronous) علامتگذاری میکند که فوراً پاسخی برنمیگرداند، بلکه پاسخ را در زمان دیگری برای تکمیل فراخوانی ارسال خواهد کرد. این ویژگی برای پیادهسازی سرویسهای غیرمسدودکننده (non-blocking) که در آنها فراخوانی متدها ممکن است زمانبر باشد، به کار میرود.
هنگامی که یک متد ناهمگام است، پیشنمونه (prototype) تابع متفاوت خواهد بود. ضروری است که تابع از قواعد زیر پیروی کند:
•
تابع باید
مقداری از
نوع gboolean
برگرداند؛
TRUE در صورت
موفقیت، و
در غیر این
صورت FALSE.
•
پارامتر
اول،
اشارهگری
به
نمونهای
از شیء است.
•
پس از
اشارهگر
نمونه شیء،
مقادیر
ورودی متد
قرار
میگیرند.
•
پارامتر
نهایی باید
از نوع (* DBusGMethodInvocation)
باشد. این
پارامتر
هنگام
ارسال پیام
پاسخ به
کلاینت، از
طریق
فراخوانی
dbus_g_method_return یا dbus_g_method_return_error
استفاده
میشود.
برای مثال:
<method name "FooMethod"> [...] <annotation name="org.freedesktop.DBus.GLib.Async" value="yes"/> [...] </method>
"org.freedesktop.DBus.GLib.Const"
این صفت فقط میتواند روی گرههای <arg> از نوع "out" اعمال شود و مشخص میکند که پارامتر هنگام بازگردانده شدن کپی نمیشود. برای مثال، این کار یک آرگومان 's' را از (** char) به (** const char) تبدیل میکند و منجر به عدم آزادسازی آرگومان توسط D-Bus پس از ارسال پیام میشود. برای مثال:
<arg type="u" name="x" direction="out"> <annotation name="org.freedesktop.DBus.GLib.Const" value=""/> </arg>
"org.freedesktop.DBus.GLib.ReturnVal"
این صفت فقط میتواند روی گرههای <arg> از نوع "out" اعمال شود و امضای مورد انتظار تابع را تغییر میدهد. در حال حاضر میتواند روی دو مقدار تنظیم شود: "" یا "error". آرگومانی که با این صفت علامتگذاری شده، از طریق آرگومان اشارهگر برگردانده نمیشود، بلکه توسط مقدار بازگشتی تابع بازگردانده میشود. اگر مقدار صفت رشته خالی باشد، آرگومان (* GError) نیز حذف میشود و در نتیجه روش استانداردی برای بازگرداندن مقدار خطا وجود نخواهد داشت. این ویژگی برای اتصال به کدهای موجود بسیار مفید است، زیرا تطبیق با APIهای موجود را ممکن میسازد. اگر مقدار صفت "error" باشد، آخرین آرگومان طبق معمول یک (* GError) خواهد بود. برای مثال:
<arg type="u" name="x" direction="out"> <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/> </arg>
گزینهها (OPTIONS)
گزینههای زیر پشتیبانی میشوند:
--force
بازنویسی
فایل خروجی
در صورتی که
از قبل وجود
داشته باشد
و برچسب
زمانی آن
تازهتر از
فایلهای
منبع باشد.
--help
نمایش
اطلاعات
نحوه
استفاده.
--ignore-unsupported
در صورت
تنظیم،
امضاهای
پشتیبانینشده
برای
پارامترهای
<method> نادیده
گرفته
میشوند.
--mode=pretty|glib-client|glib-server
اگر مقدار
"glib-client" باشد،
انقیادهای
سمت کلاینت
تولید
میشوند.
اگر مقدار
"glib-server" باشد،
انقیادهای
سمت سرور
تولید
میشوند.
اگر مقدار
"pretty" باشد،
خروجی در
قالبی
خواناتر
برای انسان
خواهد بود.
--output=file
مشخص کردن file
خروجی.
--prefix=symbol-prefix
توابع در
خروجی
تولیدشده،
پیشوندی با
مقدار symbol-prefix
دریافت
میکنند.
--version
نمایش
شماره نسخه
دستور dbus-binding-tool.
عملوندها (OPERANDS)
عملوندهای زیر پشتیبانی میشوند:
file
فهرستی از
یک یا چند
فایل XML
ورودی
دروننگری
D-Bus جهت
گنجانده
شدن در
خروجی
تولیدشده.
فایلها (FILES)
فایلهای زیر توسط این برنامه استفاده میشوند:
${exec_prefix}/bin/dbus-binding-tool
فایل
اجرایی
برنامه D-Bus Binding Tool.
همچنین ببینید (SEE ALSO)
gdbus-codegen(1), dbus-cleanup-sockets(1), dbus-daemon(1), dbus-monitor(1), dbus-send(1), dbus-uuidgen(1)
نکات (NOTES)
ابزار dbus-binding-tool بخشی از dbus-glib است که یک انقیاد منسوخشدهی D-Bus برای GLib به شمار میرود.
کتابخانه dbus-glib حداقل نگهداری و وصلههای امنیتی را به منظور استفاده پروژههایی مانند Telepathy و NetworkManager که هنوز به آن متکی هستند دریافت میکند، اما نباید در پروژههای جدید استفاده شود (و پروژههای فعلی نیز باید تلاش کنند از آن مهاجرت کنند). لطفاً از GDBus استفاده کنید که از نسخه 2.26 بخشی از GLib است.
دستور gdbus-codegen(1) جایگزین GDBus برای dbus-binding-tool است.
نویسندگان (AUTHORS)
صفحه راهنما توسط Brian Cameron، شرکت Sun Microsystems Inc.، سال 2009 نوشته شده است.
| 8 Oct 2018 | dbus-glib 0.114 |