dbus 下一个

诺德JS的下一个伟大的 DBus 库.

文档

聊天

关于

dbus-next是DBus的全功能高水平库,主要用于将应用程序整合到Linux桌面和移动环境中.

桌面应用程序开发人员可以通过实施通用的DBus标准接口或创建自定义插件接口,使用这个库将其应用程序集成到桌面环境中.

桌面用户可以利用这个库来创建自己的脚本和公用设备来与这些界面互动,以定制他们的桌面环境.

节点相容性

目前,dbus-next针对JavaScript的最新特性. 支持的最早版本是 6.3.0然而,图书馆使用 BigInt 默认的长整数类型 10.8.0。如果需要提前支持版本,请设置 BigInt 兼容模式。 这将配置要使用的库 JSBI (联合履行机构) 作为长类型的多填充.

const dbus = require('dbus-next');
dbus.setBigIntCompat(true);

客户界面

您可以在总线上获得一个名称的代理对象 bus.getProxyObject() 函数,传递名称和路径。 代理对象包含关于对象的内向数据,包括节点和接口列表. 您可以与 object.getInterface() 函数传递接口的名称.

界面对象有您可以调用的方法与内向数据中的方法相对应. 将正常的JavaScript对象传递到函数的参数上,它们会被自动转换为被公示的 DBus 类型. 不过,你必须使用 Variant 类代表 DBus 变体.

方法同样会返回 JavaScript 从已公布的 DBus 类型转换出来的对象, 并带有 Variant 类用于表示返回的变体。 如果方法返回多个值,它们将在数组内返回.

界面对象是一个事件发报器,当信号在总线上被放出时会发出信号的名称. 对回调的参数应当与信号的参数对应.

这是使用代理对象与该代理对象的简单实例 MPRIS (MPRIS) 维基百科中的相关条目 媒体播放器界面.

let dbus = require('dbus-next');
let bus = dbus.sessionBus();
let Variant = dbus.Variant;

// getting an object introspects it on the bus and creates the interfaces
let obj = await bus.getProxyObject('org.mpris.MediaPlayer2.vlc', '/org/mpris/MediaPlayer2');

// the interfaces are the primary way of interacting with objects on the bus
let player = obj.getInterface('org.mpris.MediaPlayer2.Player');
let properties = obj.getInterface('org.freedesktop.DBus.Properties');

// call methods on the interface
await player.Play()

// get properties with the properties interface (this returns a variant)
let volumeVariant = await properties.Get('org.mpris.MediaPlayer2.Player', 'Volume');
console.log('current volume: ' + volumeVariant.value);

// set properties with the properties interface using a variant
await properties.Set('org.mpris.MediaPlayer2.Player', 'Volume', new Variant('d', volumeVariant.value + 0.05));

// listen to signals
properties.on('PropertiesChanged', (iface, changed, invalidated) => {
  for (let prop of Object.keys(changed)) {
    console.log(`property changed: ${prop}`);
  }
});

完整的例子见 MPRIS 客户端 实例,可用于控制命令行上的媒体播放器.

服务接口

你可以用这个 Interface 类以定义界面。 此接口使用拟议 装饰语法 尚未纳入ECMAScript标准,但应当包括一天。 不幸的是,你需要一个 Babel 插件 使这个代码暂时有效.

let dbus = require('dbus-next');
let Variant = dbus.Variant;

let {
  Interface, property, method, signal, DBusError,
  ACCESS_READ, ACCESS_WRITE, ACCESS_READWRITE
} = dbus.interface;

let bus = dbus.sessionBus();

class ExampleInterface extends Interface {
  @property({signature: 's', access: ACCESS_READWRITE})
  SimpleProperty = 'foo';

  _MapProperty = {
    'foo': new Variant('s', 'bar'),
    'bat': new Variant('i', 53)
  };

  @property({signature: 'a{sv}'})
  get MapProperty() {
    return this._MapProperty;
  }

  set MapProperty(value) {
    this._MapProperty = value;

    Interface.emitPropertiesChanged(this, {
      MapProperty: value
    });
  }

  @method({inSignature: 's', outSignature: 's'})
  Echo(what) {
    return what;
  }

  @method({inSignature: 'ss', outSignature: 'vv'})
  ReturnsMultiple(what, what2) {
    return [
      new Variant('s', what),
      new Variant('s', what2)
    ];
  }

  @method({inSignature: '', outSignature: ''})
  ThrowsError() {
    // the error is returned to the client
    throw new DBusError('org.test.iface.Error', 'something went wrong');
  }

  @method({inSignature: '', outSignature: '', noReply: true})
  NoReply() {
    // by setting noReply to true, dbus-next will NOT send a return reply through dbus 
    // after the method is called.
  }

  @signal({signature: 's'})
  HelloWorld(value) {
    return value;
  }

  @signal({signature: 'ss'})
  SignalMultiple(x) {
    return [
      'hello',
      'world'
    ];
  }
}

let example = new ExampleInterface('org.test.iface');

setTimeout(() => {
  // emit the HelloWorld signal by calling the method with the parameters to
  // send to the listeners
  example.HelloWorld('hello');
}, 500);

async function main() {
  // make a request for the name on the bus
  await bus.requestName('org.test.name');
  // export the interface on the path
  bus.export('/org/test/path', example);
}

main().catch((err) => {
  console.log('Error: ' + err);
});

接口扩展 Interface 课。 声明服务方法、属性和信号,由图书馆提供装饰。 您可以选择在总线上请求名称 bus.requestName() 所以客户有 众所周知的名称可以连接。 那就打电话 bus.export() 与路径和界面一起在总线上曝光此界面.

当一个 DBus 客户端在服务器上调用该方法时,方法被称为方法. 属性可以与 org.freedesktop.DBus.Properties 界面,并包含在后演化 xml 中.

要发出信号,请拨打标记为 signal 装饰器和信号会随返回值而出出.

如果您有 xml 接口描述, 可以从 org.freedesktop.DBus.Introspect 在导出接口上,您可以从 xml 文件生成 dbus- next JavaScript 类 bin/generate-interfaces.js 函数.

低级界面

低等界面可用于直接与消息交互. 创建新信件 Message 分类作为方法调用、信号、方法返回或出错发送到总线上。 方法调用与 call() 方法 MessageBus 等待回复 send() 可用于不需要回复的信息.

let dbus = require('dbus-next');
let Message = dbus.Message;

let bus = dbus.sessionBus();

// send a method call to list the names on the bus
let methodCall = new Message({
  destination: 'org.freedesktop.DBus',
  path: '/org/freedesktop/DBus',
  interface: 'org.freedesktop.DBus',
  member: 'ListNames'
});

let reply = await bus.call(methodCall);
console.log('names on the bus: ', reply.body[0]);

// add a custom handler for a particular method
bus.addMethodHandler((msg) => {
  if (msg.path === '/org/test/path' &&
      msg.interface === 'org.test.interface'
      && msg.member === 'SomeMethod') {
    // handle the method by sending a reply
    let someMethodReply = Message.newMethodReturn(msg, 's', ['hello']);
    bus.send(someMethodReply);
    return true;
  }
});

// listen to any messages that are sent to the bus
bus.on('message', (msg) => {
  console.log('got a message: ', msg);
});

关于如何使用低等界面发送信件的完整实例,请参见 dbus-next-send.js 脚本在 bin 目录.

类型系统

通过消息总线发送或接收的值总是有一个相关的签名,指定了这些值的类型. 对于高级客户端和服务,这些签名在XML数据中加以具体说明,在XML数据中公布 标准 DBus 接口. 高端客户端动态创建基于该内测数据的类,其方法和信号基于类型签名. 高端服务通过对班级进行回顾来进行反向,以创建在巴士上为客户公示的反向XML数据.

签名中的每个代码被映射为JavaScript类型,如下表所示.

Unix 文件描述符只在抽象或域(path)套接字上支持. 这是系统和会话总线的默认值 . 当发送文件描述符时,它必须一直打开直到消息被发送. 当收到文件描述器时,应用程序负责关闭.

类型 a, (中文(简体) ), (, (中文(简体) ), v,以及 { 是具有其他值的容器类型。 容器类型和JavaScript实例见下表.

关于DBus 类型系统的更多信息,请参见 规格。 。 。 .

谈判 Unix 文件描述符

支持谈判 Unix 文件描述符( DBus 类型) h),设置 negotiateUnixFd 改为 true 在消息总线构建器选项中。 任意类型的值 h 在发送或接收的信件中,文件本身应当是描述符。 您负责关闭公共汽车发送或接收的文件描述符 .

捐款

欢迎捐款。 发展发生在 吉图布。 。 。 .

类似项目

dbus- next 是一个叉 dbus- 内在 图书馆。 虽然这个库很棒,但它有许多错误,我认为如果不彻底重新设计用户API,它就无法被修复. 另一个库存在 节点-dbus 类似,但也不足以创建全功能的 DBus 服务.

版权

您可以在麻省理工学院许可下使用此代码(参见LICENSE).

2012年,安德烈·西多罗夫

2018年,东尼·克瑞西