Support for browser usage via WebSocket connections, in addition to Node.js
Support for skipping handshake authentication (as used by Frida)
Support for connecting via non-socket streams (as used by Frida's WebSocket API)
Type definitions included (and likely converting entirely to TypeScript in future)
Modernization:
- Automated testing via GitHub Actions
- Promises everywhere
- Dropping support for engines before Node v16 (ES2022)
- Replaced xml2js with fast-xml-parser (faster, smaller, better browser compat)
Simplification:
- Dropped bin scripts
- Dropped various unused files
- Dropped examples
Improved error handling:
- Throws an explicit error when sending a message to a closed stream, instead of silently never responding
- Turn D-Bus error responses into proper error instances where possible (rather than throwing arrays of strings)

Installation

npm install @httptoolkit/dbus-native

Usage

Short example using desktop notifications service

const dbus = require('@httptoolkit/dbus-native');
const sessionBus = dbus.sessionBus();
sessionBus.getService('org.freedesktop.Notifications').getInterface(
    '/org/freedesktop/Notifications',
    'org.freedesktop.Notifications', function(err, notifications) {

    // dbus signals are EventEmitter events
    notifications.on('ActionInvoked', function() {
        console.log('ActionInvoked', arguments);
    });
    notifications.on('NotificationClosed', function() {
        console.log('NotificationClosed', arguments);
    });
    notifications.Notify('exampl', 0, '', 'summary 3', 'new message text', ['xxx yyy', 'test2', 'test3', 'test4'], [],  5, function(err, id) {
       //setTimeout(function() { n.CloseNotification(id, console.log); }, 4000);
    });
});

API

Low level messaging: bus connection

connection = dbus.createClient(options)

options:

socket - unix socket path
port - TCP port
host - TCP host
busAddress - encoded bus address. Default is DBUS_SESSION_BUS_ADDRESS environment variable. See http://dbus.freedesktop.org/doc/dbus-specification.html#addresses
authMethods - array of authentication methods, which are attempted in the order provided (default:['EXTERNAL', 'DBUS_COOKIE_SHA1', 'ANONYMOUS'])
ayBuffer - boolean (default:true): if true 'ay' dbus fields are returned as buffers
ReturnLongjs - boolean (default:false): if true 64 bit dbus fields (x/t) are read out as Long.js objects, otherwise they are converted to numbers (which should be good up to 53 bits)
( TODO: add/document option to use adress from X11 session )

connection has only one method, message(msg)

message fields:

type - methodCall, methodReturn, error or signal
path - object path
interface
destination
sender
member
serial
signature
body
errorName
replySerial

connection signals:

connect - emitted after successful authentication
message
error

example:

const dbus = require('@httptoolkit/dbus-native');
const conn = dbus.createConnection();
conn.message({
    path:'/org/freedesktop/DBus',
    destination: 'org.freedesktop.DBus',
    'interface': 'org.freedesktop.DBus',
    member: 'Hello',
    type: dbus.messageType.methodCall
});
conn.on('message', function(msg) { console.log(msg); });

Note on INT64 'x' and UINT64 't'

Long.js is used for 64 Bit support. https://github.com/dcodeIO/long.js The following javascript types can be marshalled into 64 bit dbus fields:

typeof 'number' up to 53bits
typeof 'string' (consisting of decimal digits with no separators or '0x' prefixed hexadecimal) up to full 64bit range
Long.js objects (or object with compatible properties)

By default 64 bit dbus fields are unmarshalled into a 'number' (with precision loss beyond 53 bits). Use {ReturnLongjs:true} option to return the actual Long.js object and preserve the entire 64 bits.

Keywords

FAQs

What is @httptoolkit/dbus-native?

Is @httptoolkit/dbus-native well maintained?

Last updated on 14 May 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@httptoolkit/dbus-native