GDBUS(1) دستورهای کاربری GDBUS(1)

gdbus - ابزاری برای کار با اشیاء D-Bus

gdbus introspect [--system | --session | --address address] --dest bus_name --object-path /path/to/object [--xml] [--recurse] [--only-properties]
gdbus monitor [--system | --session | --address address] --dest bus_name [--object-path /path/to/object]
gdbus call [--system | --session | --address address] --dest bus_name --object-path /path/to/object --method org.project.InterfaceName.MethodName [--timeout seconds | --interactive] [ARG…]
gdbus emit [--system | --session | --address address] --object-path /path/to/object --signal org.project.InterfaceName.SignalName [--dest unique_bus_name] [ARG…]
gdbus wait [--system | --session | --address address] --activate bus_name [--timeout seconds] bus_name
gdbus help

دستور gdbus ابزاری ساده برای کار با اشیاء D-Bus است.

introspect

رابط‌ها و مقادیر ویژگی‌های یک شیء دوردست را چاپ می‌کند. برای کارکرد این قابلیت، مالک شیء باید رابط org.freedesktop.DBus.Introspectable را پیاده‌سازی کرده باشد. اگر از گزینه --xml استفاده شود، پرونده XML بازگردانده‌شده از درون‌نگری (introspection) چاپ می‌شود؛ در غیر این صورت، نمای بازشده و مرتب‌شدهٔ آن نمایش داده می‌شود. از گزینه --recurse می‌توان برای درون‌نگری فرزندان شیء (و فرزندان آن‌ها و به همین ترتیب) استفاده کرد و گزینه --only-properties می‌تواند برای نمایش تنها رابط‌های دارای ویژگی به کار رود.

monitor

یک یا تمام اشیاء تحت مالکیت دارندهٔ bus_name را پایش می‌کند.

call

یک متد را روی یک شیء دوردست فراخوانی می‌کند. هر آرگومان ارسالی به متد باید به صورت یک GVariant سریال‌سازی‌شده مشخص شود، مگر این‌که رشته‌ها نیازی به نقل‌قول‌های صریح نداشته باشند. مقادیر بازگشتی به عنوان مقادیر GVariant سریال‌سازی‌شده چاپ می‌شوند.

emit

یک سیگنال ارسال می‌کند. هر آرگومان ارسالی در سیگنال باید به صورت یک GVariant سریال‌سازی‌شده مشخص شود، مگر این‌که رشته‌ها نیازی به نقل‌قول‌های صریح نداشته باشند.

wait

تا زمانی که bus_name توسط فرایندی در گذرگاه تصاحب شود، منتظر می‌ماند. اگر --activate مشخص شده باشد، آن نام گذرگاه ابتدا به طور خودکار راه‌اندازی می‌شود. این نام ممکن است همان نام گذرگاه مورد انتظار باشد یا نامی متفاوت.

help

پیام راهنما را چاپ کرده و خارج می‌شود.

دستور gdbus به همراه یک اسکریپت تکمیل خودکار بش (bash completion) عرضه می‌شود تا دستورها، مقصدها، نام‌های گذرگاه، مسیرهای شیء و نام‌های رابط و متد را تکمیل کند.

این مثال نحوهٔ درون‌نگری یک شیء را نشان می‌دهد — توجه داشته باشید که مقدار هر ویژگی نمایش داده می‌شود:

$ gdbus introspect --system \
        --dest org.freedesktop.NetworkManager \
        --object-path /org/freedesktop/NetworkManager/Devices/0
node /org/freedesktop/NetworkManager/Devices/0 {
  interface org.freedesktop.DBus.Introspectable {
    methods:
      Introspect(out s data);
  };
  interface org.freedesktop.DBus.Properties {
    methods:
      Get(in  s interface,
          in  s propname,
          out v value);
      Set(in  s interface,
          in  s propname,
          in  v value);
      GetAll(in  s interface,
             out a{sv} props);
  };
  interface org.freedesktop.NetworkManager.Device.Wired {
    signals:
      PropertiesChanged(a{sv} arg_0);
    properties:
      readonly b Carrier = false;
      readonly u Speed = 0;
      readonly s HwAddress = '00:1D:72:88:BE:97';
  };
  interface org.freedesktop.NetworkManager.Device {
    methods:
      Disconnect();
    signals:
      StateChanged(u arg_0,
                   u arg_1,
                   u arg_2);
    properties:
      readonly u DeviceType = 1;
      readonly b Managed = true;
      readwrite o Ip6Config = '/';
      readwrite o Dhcp4Config = '/';
      readwrite o Ip4Config = '/';
      readonly u State = 2;
      readwrite u Ip4Address = 0;
      readonly u Capabilities = 3;
      readonly s Driver = 'e1000e';
      readwrite s Interface = 'eth0';
      readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
  };
};

گزینه‌های --recurse و --only-properties هنگامی که قصد بازبینی تمامی اشیاء متعلق به یک فرایند خاص را دارید مفید هستند:

$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse  --only-properties
node / {
  node /org {
    node /org/freedesktop {
      node /org/freedesktop/UPower {
        interface org.freedesktop.UPower {
          properties:
            readonly b IsDocked = true;
            readonly b LidForceSleep = false;
            readonly b LidIsPresent = false;
            readonly b LidIsClosed = false;
            readonly b OnLowBattery = false;
            readonly b OnBattery = false;
            readonly b CanHibernate = true;
            readonly b CanSuspend = true;
            readonly s DaemonVersion = '0.9.10';
        };
        node /org/freedesktop/UPower/Policy {
        };
        node /org/freedesktop/UPower/Wakeups {
          interface org.freedesktop.UPower.Wakeups {
            properties:
              readonly b HasCapability = true;
          };
        };
      };
    };
  };
};

به همین ترتیب، از دستور introspect می‌توان برای آگاهی از جزئیات متد Notify استفاده کرد:

[…]
  interface org.freedesktop.Notifications {
    methods:
      GetServerInformation(out s return_name,
                           out s return_vendor,
                           out s return_version,
                           out s return_spec_version);
      GetCapabilities(out as return_caps);
      CloseNotification(in  u id);
      Notify(in  s app_name,
             in  u id,
             in  s icon,
             in  s summary,
             in  s body,
             in  as actions,
             in  a{sv} hints,
             in  i timeout,
             out u return_id);
  };
[…]

با داشتن این اطلاعات، استفاده از دستور call برای نمایش یک اعلان به سادگی امکان‌پذیر است:

$ gdbus call --session \
             --dest org.freedesktop.Notifications \
             --object-path /org/freedesktop/Notifications \
             --method org.freedesktop.Notifications.Notify \
             my_app_name \
             42 \
             gtk-dialog-info \
             "The Summary" \
             "Here’s the body of the notification" \
             [] \
             {} \
             5000
(uint32 12,)

فراخوانی یک متد با آرگومان دستگیره فایل (file handle):

$ gdbus call --session \
             --dest org.example.foo \
             --object-path /org/example/foo \
             --method SendFDs \
             1 \
             10 \
             10<file.foo

پایش تمامی اشیاء روی یک سرویس:

$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
The name org.freedesktop.ConsoleKit is owned by :1.15
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)

پایش یک شیء مشخص روی یک سرویس:

$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
The name org.freedesktop.NetworkManager is owned by :1.5
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5c>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5e>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)

ارسال یک سیگنال:

$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"

ارسال یک سیگنال به فرایندی مشخص:

$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42

انتظار برای تصاحب یک نام شناخته‌شده روی گذرگاه؛ این دستور سرویس را به طور خودکار راه‌اندازی نخواهد کرد:

$ gdbus wait --session org.bar.SomeName

راه‌اندازی خودکار و سپس انتظار برای تصاحب یک نام شناخته‌شده روی گذرگاه:

$ gdbus wait --session --activate org.bar.SomeName

راه‌اندازی خودکار یک سرویس دیگر و سپس انتظار برای تصاحب یک نام شناخته‌شده روی گذرگاه. این حالت در شرایطی که SomeName مستقیماً قابل فعال‌سازی نیست مفید است:

$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName

انتظار برای یک نام شناخته‌شده و انصراف پس از ۳۰ ثانیه. به صورت پیش‌فرض، مهلت زمانی غیرفعال است؛ یا می‌توان --timeout را برابر با 0 تنظیم کرد تا غیرفعال شود:

$ gdbus wait --session --timeout 30 org.bar.SomeName

لطفاً گزارش باگ‌ها را به سامانه پیگیری اشکالات توزیع یا سامانه پیگیری اشکالات بالادست ارسال کنید: https://gitlab.gnome.org/GNOME/glib/issues/new

dbus-send(1) <man:dbus-send(1)>

مه ۲۰۲۵ glib2