dbus

dbusモジュールは、JSHアプリケーション用のLinux専用D-Bus APIを提供します。 メソッド呼び出し、プロパティの読み書き、イントロスペクション、シグナル購読、名前の所有者の監視に対応しています。

モジュールの読み込み

const dbus = require("dbus");
const conn = new dbus.Connection({ busType: dbus.BusType.Session });

ランタイムのOSがLinux以外の場合、接続の作成は失敗します。

BusType

• dbus.BusType.Session
• dbus.BusType.System

Connection

D-Bus接続オブジェクトです。

作成

new dbus.Connection(options)

オプション

戻り値

• Connection

エラー時の動作：

• busTypeが不正な場合は、例外が発生します。
• プラットフォームがLinux以外の場合は、例外が発生します。

close()

現在のD-Bus接続を閉じます。

構文

conn.close()

戻り値

• undefined

このメソッドは冪等であり、複数回呼び出しても安全です。

object()

指定したdestination/pathにバインドされたObjectProxyを作成します。

構文

conn.object(destination, path)

パラメーター

• destination (string): サービス名（例：org.freedesktop.DBus）
• path (string): オブジェクトパス（例：/org/freedesktop/DBus）

戻り値

• ObjectProxy

call()

D-Busメソッドを呼び出します。

構文

conn.call(request)

パラメーター

• request (object): CallRequest

戻り値

• object: CallResult

エラー時の動作：

• 必須フィールドがない場合は、例外が発生します。
• オブジェクトパスが不正な場合は、例外が発生します。

getProperty()

D-Busプロパティを読み取ります。

構文

conn.getProperty(request)

パラメーター

• request (object): PropertyRequest

戻り値

• object: PropertyResult

setProperty()

D-Busプロパティを書き込みます。

構文

conn.setProperty(request)

パラメーター

• request (object): SetPropertyRequest

戻り値

• undefined

introspect()

オブジェクトのイントロスペクションメタデータを取得します。

構文

conn.introspect(request)

パラメーター

• request (object): IntrospectRequest

戻り値

• object: IntrospectionNode

subscribeSignal()

条件に一致するD-Busシグナルを購読します。

構文

conn.subscribeSignal(request)

パラメーター

• request (object): SignalWatchRequest

戻り値

• Connection (メソッドチェーンに対応)

エラー時の動作：

• すべての一致条件フィールドが空の場合は、missing signal match criteria例外が発生します。

unsubscribeSignal()

登録済みのシグナル購読を解除します。

構文

conn.unsubscribeSignal(request)

パラメーター

• request (object): SignalWatchRequest

戻り値

• Connection (メソッドチェーンに対応)

エラー時の動作：

• 一致する購読がない場合は、例外が発生します。

watchName()

バス名の所有者の変更監視を開始します。

構文

conn.watchName(name)

パラメーター

• name (string): D-Bus well-known name

戻り値

• Connection (メソッドチェーンに対応)

unwatchName()

バス名の所有者の変更監視を停止します。

構文

conn.unwatchName(name)

パラメーター

• name (string): D-Bus well-known name

戻り値

• Connection (メソッドチェーンに対応)

エラー時の動作：

• 実行中の監視がない場合は、name watch not found例外が発生します。

getNameOwner()

バス名の現在の所有者を取得します。

構文

conn.getNameOwner(name)

パラメーター

• name (string): D-Bus well-known name

戻り値

• object: NameOwnerResult

名前に所有者がない場合は、例外をスローせずhasOwner: falseを返します。

イベント

Connectionは、EventEmitterを継承します。

signal

購読したD-Busシグナルを受信するたびに発生します。

conn.on("signal", (sig) => {
    console.println(sig.interface, sig.member, sig.body);
});

name-owner-changed

監視中の名前の所有者が変わると発生します。

conn.on("name-owner-changed", (evt) => {
    console.println(evt.name, evt.oldOwner, evt.newOwner);
});

ObjectProxy

conn.object(destination, path)で作成します。

call()

obj.call(method, ...args)

• 戻り値: CallResultと同じ構造

getProperty() / get()

obj.getProperty(name, interfaceName)
obj.get(name, interfaceName)

• getProperty()は、PropertyResultを返します。
• get()は、プロパティ値だけを返します（result.value）。

setProperty() / set()

obj.setProperty(name, value, interfaceName)
obj.set(name, value, interfaceName)

introspect()

obj.introspect()

• 戻り値: IntrospectionNode

subscribeSignal() / unsubscribeSignal()

obj.subscribeSignal(member, interfaceName)
obj.unsubscribeSignal(member, interfaceName)

destination/pathを自動的に渡す便利なラッパーです。

リクエスト・レスポンスの構造

CallRequest

argsの型指定規則：

• JavaScriptの数値は、呼び出し時に整数型（uint16、int32など）の区別が曖昧になる場合があります。
• 正確なD-Bus型が必要な場合は、引数を"type:value"文字列で渡せます。
• 例： "uint16:123", "int32:-7", "bool:true", "objectpath:/org/freedesktop/DBus"

対応する型（type:value）：

• byte, uint8, uint16, uint32, uint64
• int16, int32, int64
• float32, float64, double
• bool, string
• objectpath, path
• signature

動作に関する注意:

• 型の接頭辞がない文字列は、通常の文字列として渡します。
• 不明な型の接頭辞（例："custom:123"）は変換せず、そのまま文字列として渡します。
• 値の解析が失敗すると、呼び出し時に例外が発生します。

CallResult

PropertyRequest

PropertyResult

SetPropertyRequest

IntrospectRequest

IntrospectionNode

各interfaceには、methods/signals/properties/annotationsが含まれます。

SignalWatchRequest

sender、path、interface、memberのうち、少なくとも1つが必要です。

NameOwnerResult

使用例

1) 基本的なメソッド呼び出し

1
2
3
4
5
6
7
8
9

const dbus = require("dbus");

const conn = new dbus.Connection();
const obj = conn.object("com.plc.manufacture.Service", "/com/plc/device0");

const temp = obj.call("com.plc.manufacture.Interval.GetTemperature");
console.println("temperature:", temp.body[0]);

conn.close();

2) プロパティの読み書き

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const dbus = require("dbus");

const conn = new dbus.Connection();
const dev = conn.object("com.plc.manufacture.Service", "/com/plc/device0");

console.println("mode:", dev.get("Mode", "com.plc.manufacture.Status"));
dev.set("Mode", "MANUAL", "com.plc.manufacture.Status");
console.println("mode:", dev.get("Mode", "com.plc.manufacture.Status"));

conn.close();

3) イントロスペクション

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

const dbus = require("dbus");

const conn = new dbus.Connection();
const obj = conn.object("com.plc.manufacture.Service", "/com/plc/device0");
const node = obj.introspect();

for (const iface of node.interfaces) {
    console.println("iface:", iface.name);
}

conn.close();

4) シグナルの購読

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

const dbus = require("dbus");

const conn = new dbus.Connection();
const obj = conn.object("com.plc.manufacture.Service", "/com/plc/device0");

obj.subscribeSignal("TemperatureChanged", "com.plc.manufacture.Interval");
conn.on("signal", (sig) => {
    if (sig.member !== "TemperatureChanged") {
        return;
    }
    console.println("temperature changed:", sig.body[0]);
});

5) 名前の監視

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const dbus = require("dbus");

const conn = new dbus.Connection();
const name = "com.example.Worker";

const owner = conn.getNameOwner(name);
console.println("has owner:", owner.hasOwner);

conn.watchName(name);
conn.on("name-owner-changed", (evt) => {
    if (evt.name === name) {
        console.println("owner changed:", evt.oldOwner, "->", evt.newOwner);
    }
});

エラー時の動作に関する注意

• conn.close()の後にメソッドを呼び出すと、connection not initialized例外が発生します。
• リクエストオブジェクトの必須フィールドが欠けている場合は、例外が発生します。
• 不正なオブジェクトパスは、例外を発生させます。
• getNameOwner()は、所有者がない場合に{ hasOwner: false }を返します。
• D-Busのランタイムとテストの動作は、Linux専用です。