نام (NAME)

dbus-send - ارسال پیام به گذرگاه پیام D-Bus

خلاصه دستور (SYNOPSIS)

dbus-send [--system | --session | --bus=آدرس | --peer=آدرس] [--dest=نام_مقصد] [--print-reply[=literal]] [--reply-timeout=میلیثانیه] [--type=نوع_پیام] مسیر_شیء رابط.پیام [محتوا...]

توضیحات (DESCRIPTION)

دستور dbus-send برای ارسال پیام به یک گذرگاه پیام D-Bus استفاده میشود. برای اطلاعات بیشتر در مورد تصویر کلی به https://www.freedesktop.org/wiki/Software/dbus مراجعه کنید.

دو گذرگاه پیام شناخته‌شده وجود دارند: گذرگاه پیام سراسری سیستم (که در بسیاری از سیستم‌ها به عنوان سرویس "messagebus" نصب شده است) و گذرگاه پیام نشست ورود به ازای هر کاربر (که با هر بار ورود کاربر راه‌اندازی می‌شود). گزینه‌های --system و --session دستور dbus-send را هدایت می‌کنند تا پیام‌ها را به ترتیب به گذرگاه سیستم یا گذرگاه نشست ارسال کند. در صورتی که هیچ‌یک مشخص نشود، dbus-send پیام را به گذرگاه نشست ارسال خواهد کرد.

تقریباً در تمام موارد استفاده از dbus-send، باید آرگومان --dest مشخص شود که نام اتصال مقصد در گذرگاه برای دریافت پیام است. اگر --dest مشخص نشود، مقصدی تعیین نخواهد شد.

مسیر شیء (object path) و نام پیام ارسالی همواره باید مشخص شوند. آرگومان‌های بعدی، در صورت وجود، محتوای پیام (آرگومان‌های پیام) خواهند بود. این مقادیر به صورت نوع‌های مشخص‌شده تعیین می‌شوند و ممکن است شامل ظرف‌ها (آرایه‌ها، دیکشنری‌ها و مقادیر چندریختی یا variantها) باشند، همان‌طور که در ادامه شرح داده شده است:

<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

توضیح ظرف‌ها (Containers):

array: آرایه‌ای از مقادیر هم‌نوع (مانند array:string:"عنصر نخست","عنصر دوم").
dict: دیکشنری یا نگاشت کلید-مقدار (مانند dict:string:int32:"یک",1,"دو",2).
variant: یک مقدار چندریختی که می‌تواند هر نوع داده معتبری را دربرگیرد (مانند variant:int32:-8).

توضیح انواع داده (Data Types):

string: رشته متنی (مانند string:"متن آزمایشی").
int16 ، uint16: عدد صحیح ۱۶ بیتی علامت‌دار و بدون علامت.
int32 ، uint32: عدد صحیح ۳۲ بیتی علامت‌دار و بدون علامت.
int64 ، uint64: عدد صحیح ۶۴ بیتی علامت‌دار و بدون علامت.
double: عدد ممیز شناور با دقت مضاعف (مانند double:65.32).
byte: یک بایت (۸ بیتی).
boolean: مقدار بولی منطقی (true یا false).
objpath: مسیر شیء معتبر در D-Bus (مانند objpath:/org/freedesktop/sample/object/name).

سامانه D-Bus از انواع داده‌های بیشتری نسبت به این موارد پشتیبانی می‌کند، اما در حال حاضر dbus-send از آن‌ها پشتیبانی نمی‌نماید. همچنین dbus-send استفاده از ظرف‌های خالی یا ظرف‌های تو در تو (مانند آرایه‌ای از variantها) را مجاز نمی‌داند.

در ادامه یک نمونه از نحوه فراخوانی آورده شده است:

dbus-send --dest=org.freedesktop.ExampleName               \
          /org/freedesktop/sample/object/name              \
          org.freedesktop.ExampleInterface.ExampleMethod   \
          int32:47 string:'hello world' double:65.32       \
          array:string:"1st item","next item","last item"  \
          dict:string:int32:"one",1,"two",2,"three",3      \
          variant:int32:-8                                 \
          objpath:/org/freedesktop/sample/object/name

توجه داشته باشید که رابط (interface) توسط یک نقطه از متد یا سیگنال جدا می‌شود، اگرچه در پروتکل واقعی D-Bus، رابط و عضو رابط دو فیلد مستقل هستند.

گزینه‌ها (OPTIONS)

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

--dest=نام_مقصد: مشخص کردن نام اتصالی که پیام را دریافت می‌کند.
--print-reply: مسدودسازی تا زمان دریافت پاسخ پیام ارسال‌شده، و چاپ هر پاسخ دریافتی در قالبی خوانا برای انسان. همچنین این گزینه به این معنی است که نوع پیام (--type=) به صورت خودکار method_call در نظر گرفته می‌شود.
--print-reply=literal: مسدودسازی تا زمان دریافت پاسخ پیام ارسال‌شده، و چاپ مستقیم بدنه پاسخ. اگر پاسخ یک مسیر شیء یا رشته باشد، به صورت تحت‌اللفظی بدون هیچ‌گونه علامت‌گذاری، نویسه‌های گریز (escape) و غیره چاپ می‌شود.
--reply-timeout=میلیثانیه: انتظار برای دریافت پاسخ حداکثر تا سقف میلیثانیه (به میلی‌ثانیه). مقدار پیش‌فرض به پیاده‌سازی وابسته است و معمولاً ۲۵ ثانیه است.
--system: ارسال پیام به گذرگاه پیام سیستم (System Bus).
--session: ارسال پیام به گذرگاه پیام نشست (Session Bus). (این گزینه پیش‌فرض است.)
--bus=آدرس: ثبت در گذرگاه پیام موجود در آدرس، که معمولاً یک dbus-daemon است.
--peer=آدرس: ارسال مستقیم پیام به یک کارساز D-Bus خارج از گذرگاه پیام در آدرس. در این حالت dbus-send متد Hello را فراخوانی نخواهد کرد.
--sender=نام: درخواست مالکیت نام پیش از ارسال پیام. این نام به هنگام اتمام کار و خروج dbus-send آزاد خواهد شد.
--type=نوع_پیام: مشخص کردن نوع پیام به صورت method_call یا signal (پیش‌فرض signal است).

وضعیت خروج (EXIT STATUS)

وضعیت خروج ۰ نشان‌دهنده موفقیت است. مقدار وضعیت خروج غیرصفر نشان‌دهنده هرگونه خطا است، از جمله پارامترهای نامعتبر، عدم موفقیت در برقراری اتصال به --bus یا --peer، خطا در دریافت مالکیت نام فرستنده (--sender)، اتمام مهلت زمانی (timeout) در انتظار برای پاسخ به یک فراخوانی متد، یا دریافت خطا به عنوان پاسخ فراخوانی متد.

نویسنده (AUTHOR)

ابزار dbus-send توسط Philip Blundell نوشته شده است.

گزارش اشکالات (BUGS)

لطفاً گزارش اشکالات را به لیست پستی D-Bus یا سامانه ردیابی باگ ارسال نمایید، نشانی: https://www.freedesktop.org/wiki/Software/dbus

همچنین ببینید (SEE ALSO)

dbus-daemon(1)، dbus-monitor(1)، dbus-launch(1)