.TH "DBUS\-SEND" "1" "سپتامبر ۲۰۲۲" "D-Bus" "دستورهای کاربری"
.SH "نام (NAME)"
dbus-send \- ارسال پیام به گذرگاه پیام D-Bus
.SH "خلاصه دستور (SYNOPSIS)"
.B dbus-send
[\fB\-\-system\fR | \fB\-\-session\fR | \fB\-\-bus=\fIآدرس\fR | \fB\-\-peer=\fIآدرس\fR]
[\fB\-\-dest=\fIنام_مقصد\fR]
[\fB\-\-print-reply\fR[=\fBliteral\fR]]
[\fB\-\-reply-timeout=\fIمیلیثانیه\fR]
[\fB\-\-type=\fIنوع_پیام\fR]
\fIمسیر_شیء\fR
\fIرابط.پیام\fR
[\fIمحتوا\fR...]
.SH "توضیحات (DESCRIPTION)"
دستور \fBdbus-send\fR برای ارسال پیام به یک گذرگاه پیام D-Bus استفاده میشود. برای اطلاعات بیشتر در مورد تصویر کلی به
<https://www.freedesktop.org/wiki/Software/dbus>
مراجعه کنید.
.PP
دو گذرگاه پیام شناخته‌شده وجود دارند: گذرگاه پیام سراسری سیستم (که در بسیاری از سیستم‌ها به عنوان سرویس "messagebus" نصب شده است) و گذرگاه پیام نشست ورود به ازای هر کاربر (که با هر بار ورود کاربر راه‌اندازی می‌شود). گزینه‌های
.B \-\-system
و
.B \-\-session
دستور
.B dbus\-send
را هدایت می‌کنند تا پیام‌ها را به ترتیب به گذرگاه سیستم یا گذرگاه نشست ارسال کند. در صورتی که هیچ‌یک مشخص نشود،
.B dbus\-send
پیام را به گذرگاه نشست ارسال خواهد کرد.
.PP
تقریباً در تمام موارد استفاده از
.BR dbus\-send ،
باید آرگومان
.B \-\-dest
مشخص شود که نام اتصال مقصد در گذرگاه برای دریافت پیام است. اگر
.B \-\-dest
مشخص نشود، مقصدی تعیین نخواهد شد.
.PP
مسیر شیء (object path) و نام پیام ارسالی همواره باید مشخص شوند. آرگومان‌های بعدی، در صورت وجود، محتوای پیام (آرگومان‌های پیام) خواهند بود. این مقادیر به صورت نوع‌های مشخص‌شده تعیین می‌شوند و ممکن است شامل ظرف‌ها (آرایه‌ها، دیکشنری‌ها و مقادیر چندریختی یا variantها) باشند، همان‌طور که در ادامه شرح داده شده است:
.sp
.nf
<contents>   ::= <item> | <container> [ <item> | <container>...]
<item>       ::= <type>:<value>
<container>  ::= <array> | <dict> | <variant>
<array>      ::= array:<type>:<value>[,<value>...]
<dict>       ::= dict:<type>:<type>:<key>,<value>[,<key>,<value>...]
<variant>    ::= variant:<type>:<value>
<type>       ::= string | int16 | uint16 | int32 | uint32 | int64 | uint64 | double | byte | boolean | objpath
.fi
.PP
توضیح ظرف‌ها (Containers):
.TP
.B array
آرایه‌ای از مقادیر هم‌نوع (مانند \fBarray:string:"عنصر نخست","عنصر دوم"\fR).
.TP
.B dict
دیکشنری یا نگاشت کلید-مقدار (مانند \fBdict:string:int32:"یک",1,"دو",2\fR).
.TP
.B variant
یک مقدار چندریختی که می‌تواند هر نوع داده معتبری را دربرگیرد (مانند \fBvariant:int32:\-8\fR).
.PP
توضیح انواع داده (Data Types):
.TP
.B string
رشته متنی (مانند \fBstring:"متن آزمایشی"\fR).
.TP
.B int16 \fR،\fB uint16
عدد صحیح ۱۶ بیتی علامت‌دار و بدون علامت.
.TP
.B int32 \fR،\fB uint32
عدد صحیح ۳۲ بیتی علامت‌دار و بدون علامت.
.TP
.B int64 \fR،\fB uint64
عدد صحیح ۶۴ بیتی علامت‌دار و بدون علامت.
.TP
.B double
عدد ممیز شناور با دقت مضاعف (مانند \fBdouble:65.32\fR).
.TP
.B byte
یک بایت (۸ بیتی).
.TP
.B boolean
مقدار بولی منطقی (\fBtrue\fR یا \fBfalse\fR).
.TP
.B objpath
مسیر شیء معتبر در D-Bus (مانند \fBobjpath:/org/freedesktop/sample/object/name\fR).
.PP
سامانه D\-Bus از انواع داده‌های بیشتری نسبت به این موارد پشتیبانی می‌کند، اما در حال حاضر
.B dbus\-send
از آن‌ها پشتیبانی نمی‌نماید. همچنین
.B dbus\-send
استفاده از ظرف‌های خالی یا ظرف‌های تو در تو (مانند آرایه‌ای از variantها) را مجاز نمی‌داند.
.PP
در ادامه یک نمونه از نحوه فراخوانی آورده شده است:
.sp
.nf
  dbus\-send \-\-dest=org.freedesktop.ExampleName               \e
            /org/freedesktop/sample/object/name              \e
            org.freedesktop.ExampleInterface.ExampleMethod   \e
            int32:47 string:'hello world' double:65.32       \e
            array:string:"1st item","next item","last item"  \e
            dict:string:int32:"one",1,"two",2,"three",3      \e
            variant:int32:\-8                                 \e
            objpath:/org/freedesktop/sample/object/name
.fi
.PP
توجه داشته باشید که رابط (interface) توسط یک نقطه از متد یا سیگنال جدا می‌شود، اگرچه در پروتکل واقعی D-Bus، رابط و عضو رابط دو فیلد مستقل هستند.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر پشتیبانی می‌شوند:
.TP
\fB\-\-dest=\fIنام_مقصد\fR
مشخص کردن نام اتصالی که پیام را دریافت می‌کند.
.TP
.B \-\-print\-reply
مسدودسازی تا زمان دریافت پاسخ پیام ارسال‌شده، و چاپ هر پاسخ دریافتی در قالبی خوانا برای انسان. همچنین این گزینه به این معنی است که نوع پیام (\fB\-\-type=\fR) به صورت خودکار \fBmethod_call\fR در نظر گرفته می‌شود.
.TP
.B \-\-print\-reply=literal
مسدودسازی تا زمان دریافت پاسخ پیام ارسال‌شده، و چاپ مستقیم بدنه پاسخ. اگر پاسخ یک مسیر شیء یا رشته باشد، به صورت تحت‌اللفظی بدون هیچ‌گونه علامت‌گذاری، نویسه‌های گریز (escape) و غیره چاپ می‌شود.
.TP
\fB\-\-reply\-timeout=\fIمیلیثانیه\fR
انتظار برای دریافت پاسخ حداکثر تا سقف
.I میلیثانیه
(به میلی‌ثانیه). مقدار پیش‌فرض به پیاده‌سازی وابسته است و معمولاً ۲۵ ثانیه است.
.TP
.B \-\-system
ارسال پیام به گذرگاه پیام سیستم (System Bus).
.TP
.B \-\-session
ارسال پیام به گذرگاه پیام نشست (Session Bus). (این گزینه پیش‌فرض است.)
.TP
\fB\-\-bus=\fIآدرس\fR
ثبت در گذرگاه پیام موجود در
.IR آدرس ،
که معمولاً یک
.B dbus\-daemon
است.
.TP
\fB\-\-peer=\fIآدرس\fR
ارسال مستقیم پیام به یک کارساز D-Bus خارج از گذرگاه پیام در
.IR آدرس .
در این حالت
.B dbus\-send
متد
.B Hello
را فراخوانی نخواهد کرد.
.TP
\fB\-\-sender=\fIنام\fR
درخواست مالکیت
.I نام
پیش از ارسال پیام. این نام به هنگام اتمام کار و خروج
.B dbus\-send
آزاد خواهد شد.
.TP
\fB\-\-type=\fIنوع_پیام\fR
مشخص کردن نوع پیام به صورت
.B method_call
یا
.B signal
(پیش‌فرض
.B signal
است).
.SH "وضعیت خروج (EXIT STATUS)"
وضعیت خروج ۰ نشان‌دهنده موفقیت است. مقدار وضعیت خروج غیرصفر نشان‌دهنده هرگونه خطا است، از جمله پارامترهای نامعتبر، عدم موفقیت در برقراری اتصال به \fB\-\-bus\fR یا \fB\-\-peer\fR، خطا در دریافت مالکیت نام فرستنده (\fB\-\-sender\fR)، اتمام مهلت زمانی (timeout) در انتظار برای پاسخ به یک فراخوانی متد، یا دریافت خطا به عنوان پاسخ فراخوانی متد.
.SH "نویسنده (AUTHOR)"
ابزار dbus\-send توسط Philip Blundell نوشته شده است.
.SH "گزارش اشکالات (BUGS)"
لطفاً گزارش اشکالات را به لیست پستی D\-Bus یا سامانه ردیابی باگ ارسال نمایید، نشانی:
<https://www.freedesktop.org/wiki/Software/dbus>
.SH "همچنین ببینید (SEE ALSO)"
.BR dbus\-daemon (1)،
.BR dbus\-monitor (1)،
.BR dbus\-launch (1)