'\" te
.TH dbus-binding-tool 1 "8 Oct 2018" "dbus-glib 0.114" "User Commands"
.SH "نام (NAME)"
dbus-binding-tool \- ابزار ایجاد انقیادهای زبان C برای dbus-glib\&.
.SH "خلاصه دستور (SYNOPSIS)"
.PP
\fBdbus-binding-tool\fR [-\fB-force\fR] [-\fB-help\fR] [-\fB-ignore-unsupported\fR] [-\fB-mode=\fIpretty|glib-client|glib-server\fR\fR] [-\fB-output=\fIfile\fR\fR] [-\fB-prefix=\fIsymbol-prefix\fR\fR] [-\fB-version\fR] [\fB\fIfile\fR\fR\&...]
.SH "توضیحات (DESCRIPTION)"
.PP
دستور \fBdbus-binding-tool\fR برای نمایان‌سازی یک GObject از طریق D\-Bus، با استفاده
از انقیاد منسوخ‌شده‌ی \fBdbus-glib\fR برای GLib به کار می‌رود\&. ابزار
\fBdbus-binding-tool\fR به عنوان ورودی از یک فایل XML درون‌نگری (Introspection) D\-Bus
استفاده می‌کند\&. در خروجی، انقیادهای سمت کلاینت یا سمت سرور تولید می‌شوند\&.
این خروجی یک فایل سرآیند (header) است که استفاده از یک شیء D\-Bus راه دور را آسان می‌سازد\&.
خروجی به خروجی استاندارد یا به نام فایلی که با آرگومان -\fB-output\fR مشخص شده ارسال می‌شود\&.
.SH "توضیحات تکمیلی (EXTENDED DESCRIPTION)"
.SS ""
.PP
متن زیر نمونه‌ای از یک فایل XML درون‌نگری D\-Bus است که شیئی با یک متد به نام ManyArgs را شرح می‌دهد:
.PP
.nf
<?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>
.fi
.PP
ابزار \fBdbus-binding-tool\fR از یادداشت‌ها (annotations) در قالب XML برای کنترل بیشتر بر
نحوه تولید انقیادها پشتیبانی می‌کند\&.
.SS "انقیادهای سمت کلاینت (client-side bindings)"
.PP
هنگام ساخت انقیادهای سمت کلاینت، آرگومان -\fB-mode=glib-client\fR
استفاده می‌شود\&. انقیادهای سمت کلاینت از یادداشت
"org\&.freedesktop\&.DBus\&.Glib\&.NoReply" پشتیبانی می‌کنند\&. این یادداشت
درون برچسب <method> مشخص می‌شود تا نشان دهد کلاینت منتظر پاسخی
برای فراخوانی متد نیست، بنابراین پاسخی نباید ارسال شود\&. این کار اغلب
برای سرعت بخشیدن به فراخوانی‌های مکرر متد در مواقعی که هیچ آرگومان "out"
وجود ندارد استفاده می‌شود، و ندانستن اینکه متد با موفقیت انجام شده یا خیر مصالحه‌ای
قابل‌قبول برای نصف کردن ترافیک گذرگاه (bus) است\&. برای مثال:
.PP
.nf
<method name "FooMethod">
  [\&.\&.\&.]
  <annotation name="org\&.freedesktop\&.DBus\&.GLib\&.NoReply" value="yes"/>
  [\&.\&.\&.]
</method>
.fi
.SS "انقیادهای سمت سرور (server-side bindings)"
.PP
هنگام ساخت انقیادهای سمت سرور، آرگومان -\fB-mode=glib-server\fR
استفاده می‌شود\&. همچنین هنگام ساخت انقیادهای سمت سرور باید از آرگومان -\fB-prefix\fR
استفاده شود تا توابع موجود در خروجی تولیدشده با مقدار مشخص‌شده پیشوندگذاری
شوند\&. انقیادهای سمت سرور از یادداشت‌های زیر پشتیبانی می‌کنند:
.PP
"org\&.freedesktop\&.DBus\&.GLib\&.CSymbol"
.PP
این یادداشت برای مشخص کردن نام نمادهای C برای انواع مختلف
(رابط، متد و غیره) در صورتی که با نام تولیدشده توسط D\-Bus متفاوت باشد، استفاده می‌شود\&. 
.PP
.PP
.nf
<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>
.fi
.PP
"org\&.freedesktop\&.DBus\&.GLib\&.Async"
.PP
این یادداشت، پیاده‌سازی متد را به عنوان یک تابع ناهمگام (asynchronous) علامت‌گذاری می‌کند
که فوراً پاسخی برنمی‌گرداند، بلکه پاسخ را در زمان دیگری برای تکمیل فراخوانی ارسال
خواهد کرد\&. این ویژگی برای پیاده‌سازی سرویس‌های غیرمسدودکننده (non-blocking) که در آن‌ها
فراخوانی متدها ممکن است زمان‌بر باشد، به کار می‌رود\&.
.PP
هنگامی که یک متد ناهمگام است، پیش‌نمونه (prototype) تابع متفاوت خواهد بود\&. ضروری است
که تابع از قواعد زیر پیروی کند:
.sp
.in +2
\(bu
.mk
.in +3
.rt
تابع باید مقداری از نوع gboolean برگرداند؛ TRUE در صورت موفقیت،
و در غیر این صورت FALSE\&.
.in -3
\(bu
.mk
.in +3
.rt
پارامتر اول، اشاره‌گری به نمونه‌ای از شیء است\&.
.in -3
\(bu
.mk
.in +3
.rt
پس از اشاره‌گر نمونه شیء، مقادیر ورودی متد قرار می‌گیرند\&.
.in -3
\(bu
.mk
.in +3
.rt
پارامتر نهایی باید از نوع (* DBusGMethodInvocation) باشد\&. این پارامتر
هنگام ارسال پیام پاسخ به کلاینت، از طریق فراخوانی
dbus_g_method_return یا dbus_g_method_return_error استفاده می‌شود\&.
.in -3
.in -2
.PP
برای مثال:
.PP
.nf
<method name "FooMethod">
  [\&.\&.\&.]
  <annotation name="org\&.freedesktop\&.DBus\&.GLib\&.Async" value="yes"/>
  [\&.\&.\&.]
</method>
.fi
.PP
"org\&.freedesktop\&.DBus\&.GLib\&.Const"
.PP
این صفت فقط می‌تواند روی گره‌های <arg> از نوع "out" اعمال شود و
مشخص می‌کند که پارامتر هنگام بازگردانده شدن کپی نمی‌شود\&. برای مثال،
این کار یک آرگومان 's' را از (** char) به (** const char) تبدیل می‌کند و منجر به
عدم آزادسازی آرگومان توسط D\-Bus پس از ارسال پیام می‌شود\&. برای مثال:
.PP
.nf
  <arg type="u" name="x" direction="out">
    <annotation name="org\&.freedesktop\&.DBus\&.GLib\&.Const" value=""/>
  </arg>
.fi
.PP
"org\&.freedesktop\&.DBus\&.GLib\&.ReturnVal"
.PP
این صفت فقط می‌تواند روی گره‌های <arg> از نوع "out" اعمال شود و
امضای مورد انتظار تابع را تغییر می‌دهد\&. در حال حاضر می‌تواند روی دو مقدار تنظیم شود:
"" یا "error"\&. آرگومانی که با این صفت علامت‌گذاری شده، از طریق
آرگومان اشاره‌گر برگردانده نمی‌شود، بلکه توسط مقدار بازگشتی تابع بازگردانده می‌شود\&. اگر
مقدار صفت رشته خالی باشد، آرگومان (* GError) نیز حذف می‌شود و در نتیجه
روش استانداردی برای بازگرداندن مقدار خطا وجود نخواهد داشت\&. این ویژگی برای
اتصال به کدهای موجود بسیار مفید است، زیرا تطبیق با APIهای موجود را ممکن می‌سازد\&. اگر
مقدار صفت "error" باشد، آخرین آرگومان طبق معمول یک (* GError)
خواهد بود\&. برای مثال:
.PP
.nf
  <arg type="u" name="x" direction="out">
    <annotation name="org\&.freedesktop\&.DBus\&.GLib\&.ReturnVal" value=""/>
  </arg>
.fi
.SH "گزینه‌ها (OPTIONS)"
.PP
گزینه‌های زیر پشتیبانی می‌شوند:
.sp
.ne 2
.mk
\fB-\fB-force\fR\fR
.sp .6
.in +4
بازنویسی فایل خروجی در صورتی که از قبل وجود داشته باشد و برچسب زمانی آن تازه‌تر از
فایل‌های منبع باشد\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fB-\fB-help\fR\fR
.sp .6
.in +4
نمایش اطلاعات نحوه استفاده\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fB-\fB-ignore-unsupported\fR\fR
.sp .6
.in +4
در صورت تنظیم، امضاهای پشتیبانی‌نشده برای پارامترهای <method> نادیده
گرفته می‌شوند\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fB-\fB-mode=\fIpretty|glib-client|glib-server\fR\fR\fR
.sp .6
.in +4
اگر مقدار "glib-client" باشد، انقیادهای سمت کلاینت تولید می‌شوند\&.
اگر مقدار "glib-server" باشد، انقیادهای سمت سرور تولید می‌شوند\&.
اگر مقدار "pretty" باشد، خروجی در قالبی خواناتر برای انسان
خواهد بود\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fB-\fB-output=\fIfile\fR\fR\fR
.sp .6
.in +4
مشخص کردن \fIfile\fR خروجی\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fB-\fB-prefix=\fIsymbol-prefix\fR\fR\fR
.sp .6
.in +4
توابع در خروجی تولیدشده، پیشوندی با مقدار
\fIsymbol-prefix\fR دریافت می‌کنند\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fB-\fB-version\fR\fR
.sp .6
.in +4
نمایش شماره نسخه دستور \fBdbus-binding-tool\fR\&.
.sp
.sp 1
.in -4
.SH "عملوندها (OPERANDS)"
.PP
عملوندهای زیر پشتیبانی می‌شوند:
.sp
.ne 2
.mk
\fB\fB\fIfile\fR\fR\fR
.in +16n
.rt
فهرستی از یک یا چند فایل XML ورودی درون‌نگری D\-Bus جهت گنجانده شدن در
خروجی تولیدشده\&.
.sp
.sp 1
.in -16n
.SH "فایل‌ها (FILES)"
.PP
فایل‌های زیر توسط این برنامه استفاده می‌شوند:
.sp
.ne 2
.mk
\fB\fB${exec_prefix}/bin/dbus-binding-tool\fR \fR
.in +32n
.rt
فایل اجرایی برنامه D\-Bus Binding Tool\&.
.sp
.sp 1
.in -32n
.SH "همچنین ببینید (SEE ALSO)"
.PP
\fBgdbus-codegen\fR(1),
\fBdbus-cleanup-sockets\fR(1),
\fBdbus-daemon\fR(1),
\fBdbus-monitor\fR(1),
\fBdbus-send\fR(1),
\fBdbus-uuidgen\fR(1)
.SH "نکات (NOTES)"
.PP
ابزار \fBdbus-binding-tool\fR بخشی از \fBdbus-glib\fR است که یک انقیاد منسوخ‌شده‌ی
D-Bus برای GLib به شمار می‌رود.
.PP
کتابخانه dbus-glib حداقل نگهداری و وصله‌های امنیتی را به منظور استفاده پروژه‌هایی
مانند Telepathy و NetworkManager که هنوز به آن متکی هستند دریافت می‌کند، اما
نباید در پروژه‌های جدید استفاده شود (و پروژه‌های فعلی نیز باید تلاش کنند
از آن مهاجرت کنند). لطفاً از GDBus استفاده کنید که از نسخه 2.26 بخشی از GLib است.
.PP
دستور \fBgdbus-codegen\fR(1) جایگزین GDBus برای \fBdbus-binding-tool\fR است.
.SH "نویسندگان (AUTHORS)"
.PP
صفحه راهنما توسط Brian Cameron، شرکت Sun Microsystems Inc\&.، سال 2009 نوشته شده است\&.
\" created by instant / solbook-to-man, Thu 26 Feb 2009, 19:15