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
       نوشته شده است.


dbus-glib 0.114                   8 Oct 2018              dbus-binding-tool(1)