dbus-binding-tool(1) User Commands dbus-binding-tool(1)

dbus-binding-tool - ابزار ایجاد انقیادهای زبان C برای dbus-glib.

dbus-binding-tool [--force] [--help] [--ignore-unsupported] [--mode=pretty|glib-client|glib-server] [--output=file] [--prefix=symbol-prefix] [--version] [file...]

دستور dbus-binding-tool برای نمایان‌سازی یک GObject از طریق D-Bus، با استفاده از انقیاد منسوخ‌شده‌ی dbus-glib برای GLib به کار می‌رود. ابزار dbus-binding-tool به عنوان ورودی از یک فایل XML درون‌نگری (Introspection) D-Bus استفاده می‌کند. در خروجی، انقیادهای سمت کلاینت یا سمت سرور تولید می‌شوند. این خروجی یک فایل سرآیند (header) است که استفاده از یک شیء D-Bus راه دور را آسان می‌سازد. خروجی به خروجی استاندارد یا به نام فایلی که با آرگومان --output مشخص شده ارسال می‌شود.

متن زیر نمونه‌ای از یک فایل 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 برای کنترل بیشتر بر نحوه تولید انقیادها پشتیبانی می‌کند.

هنگام ساخت انقیادهای سمت کلاینت، آرگومان --mode=glib-client استفاده می‌شود. انقیادهای سمت کلاینت از یادداشت "org.freedesktop.DBus.Glib.NoReply" پشتیبانی می‌کنند. این یادداشت درون برچسب <method> مشخص می‌شود تا نشان دهد کلاینت منتظر پاسخی برای فراخوانی متد نیست، بنابراین پاسخی نباید ارسال شود. این کار اغلب برای سرعت بخشیدن به فراخوانی‌های مکرر متد در مواقعی که هیچ آرگومان "out" وجود ندارد استفاده می‌شود، و ندانستن اینکه متد با موفقیت انجام شده یا خیر مصالحه‌ای قابل‌قبول برای نصف کردن ترافیک گذرگاه (bus) است. برای مثال:

<method name "FooMethod">
  [...]
  <annotation name="org.freedesktop.DBus.GLib.NoReply" value="yes"/>
  [...]
</method>

هنگام ساخت انقیادهای سمت سرور، آرگومان --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>

گزینه‌های زیر پشتیبانی می‌شوند:

--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.


عملوندهای زیر پشتیبانی می‌شوند:

file
فهرستی از یک یا چند فایل XML ورودی درون‌نگری D-Bus جهت گنجانده شدن در خروجی تولیدشده.


فایل‌های زیر توسط این برنامه استفاده می‌شوند:

${exec_prefix}/bin/dbus-binding-tool
فایل اجرایی برنامه D-Bus Binding Tool.


gdbus-codegen(1), dbus-cleanup-sockets(1), dbus-daemon(1), dbus-monitor(1), dbus-send(1), dbus-uuidgen(1)

ابزار dbus-binding-tool بخشی از dbus-glib است که یک انقیاد منسوخ‌شده‌ی D-Bus برای GLib به شمار می‌رود.

کتابخانه dbus-glib حداقل نگهداری و وصله‌های امنیتی را به منظور استفاده پروژه‌هایی مانند Telepathy و NetworkManager که هنوز به آن متکی هستند دریافت می‌کند، اما نباید در پروژه‌های جدید استفاده شود (و پروژه‌های فعلی نیز باید تلاش کنند از آن مهاجرت کنند). لطفاً از GDBus استفاده کنید که از نسخه 2.26 بخشی از GLib است.

دستور gdbus-codegen(1) جایگزین GDBus برای dbus-binding-tool است.

صفحه راهنما توسط Brian Cameron، شرکت Sun Microsystems Inc.، سال 2009 نوشته شده است.

8 Oct 2018 dbus-glib 0.114