gizlang/dbus
the D-Bus wire protocol (the D-Bus Specification): values and messages marshalled little-endian, and a connection to a bus at its address (unix:path=PATH) with SASL EXTERNAL, its Hello, the names a program owns, method calls with their returns or errors, and signals. A desktop serves the freedesktop interfaces on its session bus (a notification server, a portal); a program on Linux reaches systemd or NetworkManager on the system bus.
import * as Dbus from "gizlang/dbus";Types
Value
type Value = { signature: string; number: i64; real: f64; text: string; items: Vec<Value>; data: bytes; }A value of a D-Bus type: its complete SIGNATURE and its contents. A number (y b n q i u x t h) is NUMBER, its bits for t; a double is REAL; a string, object path or signature is TEXT; the items of an array, a struct or a dict entry, and the one value of a variant, are ITEMS; the bytes of a byte array (ay) are DATA, whole.
signature:stringnumber:i64real:f64text:stringitems:Vec<gizlang_dbus.Value>data:bytes
Message
type Message = { kind: i64; flags: i64; serial: i64; replySerial: i64; path: string; interface_: string; member: string; errorName: string; destination: string; sender: string; signature: string; body: Vec<Value>; }A message: its kind (METHOD_CALL, METHOD_RETURN, ERROR or SIGNAL), flags, serial, and its header fields; its body is the values of SIGNATURE.
kind:i64flags:i64serial:i64replySerial:i64path:stringinterface_:stringmember:stringerrorName:stringdestination:stringsender:stringsignature:stringbody:Vec<gizlang_dbus.Value>
Bus
type Bus = { stream: Stream; name: string; serial: i64; waiting: Vec<Message>; }A connection to a bus: its stream, its unique name, its last serial, and the messages read while a call waited.
stream:gizlang_system.Streamname:stringserial:i64waiting:Vec<gizlang_dbus.Message>
Functions
byte
function byte(n: i64): ValueThe byte (y) of the low 8 bits of N.
Effects: fail.
boolean
function boolean(b: bool): ValueThe boolean (b) B.
int16
function int16(n: i64): ValueThe 16-bit signed integer (n) N.
uint16
function uint16(n: i64): ValueThe 16-bit unsigned integer (q) of the low 16 bits of N.
Effects: fail.
int32
function int32(n: i64): ValueThe 32-bit signed integer (i) N.
uint32
function uint32(n: i64): ValueThe 32-bit unsigned integer (u) of the low 32 bits of N.
Effects: fail.
int64
function int64(n: i64): ValueThe 64-bit signed integer (x) N.
uint64
function uint64(n: i64): ValueThe 64-bit unsigned integer (t) with the bits of N.
double
function double(x: f64): ValueThe double (d) X.
text
function text(value: string): ValueThe string (s) VALUE.
objectPath
function objectPath(path: string): ValueThe object path (o) PATH.
typeSignature
function typeSignature(value: string): ValueThe signature (g) VALUE.
array
function array(element: string, items: Vec<Value>): ValueAn array of ELEMENT, the signature of each of its ITEMS; the bytes of a byte array go to its DATA.
Effects: fail, alloc.
byteArray
function byteArray(data: bytes): ValueThe byte array (ay) of DATA.
struct
function struct(items: Vec<Value>): ValueThe struct of ITEMS, in order.
Effects: fail, alloc.
variant
function variant(value: Value): ValueThe variant (v) that holds VALUE.
Effects: fail, alloc.
dict
function dict(key: string, value: string, keys: Vec<Value>, values: Vec<Value>): ValueA dict a{KV}: the entries of KEYS and VALUES in order, VALUE the signature of every value.
Effects: fail, alloc.
lookup
function lookup(dict: Value, key: string): Value | undefinedThe value of KEY in the dict DICT (a{s...}, its values variants unwrapped), or undefined.
Effects: fail.
marshal
function marshal(out: mut bytes, value: Value): voidVALUE appended to OUT, whose length is the offset its alignment counts from (the message's start).
Effects: fail, alloc.
typeEnd
function typeEnd(signature: string, at: i64): i64The end of the single complete type that starts at AT in SIGNATURE.
Effects: fail, alloc.
types
function types(signature: string): Vec<string>The complete types of SIGNATURE, in order.
Effects: fail, alloc.
unmarshalAll
function unmarshalAll(data: bytes, at: i64, signature: string): Vec<Value> throws stringThe values of SIGNATURE in DATA from AT (alignment counts from DATA's start).
Effects: fail, alloc.
call
function call(destination: string, path: string, interface_: string, member: string, body: Vec<Value>): MessageA method call of MEMBER of INTERFACE on PATH of DESTINATION, with BODY.
signal
function signal(path: string, interface_: string, member: string, body: Vec<Value>): MessageThe signal MEMBER of INTERFACE from PATH, with BODY.
reply
function reply(to: Message, body: Vec<Value>): MessageThe return of the call TO, with BODY.
error
function error(to: Message, name: string, said: string): MessageThe error NAME of the call TO, saying SAID.
Effects: fail, alloc.
encode
function encode(message: Message, serial: i64): bytesThe bytes of MESSAGE with SERIAL.
Effects: fail, alloc.
length
function length(head: bytes): i64The bytes of a whole message from its first 16 (HEAD): its length.
Effects: fail.
decode
function decode(data: bytes): Message throws stringThe message in DATA, whole.
Effects: fail, alloc.
socketPath
function socketPath(address: string): stringThe path of a unix:path= ADDRESS (the first of its ;-separated addresses that is one), or "".
Effects: fail, alloc.
connect
function connect(address: string): Bus throws stringA connection to the bus at ADDRESS, authenticated as this process's user (EXTERNAL, which the bus reads from the socket) and named by the bus (Hello).
Effects: fail, read, io, alloc.
Methods
Bus.send
function Bus.send(self: mut Bus, message: Message): i64 throws stringSends MESSAGE; its serial.
Effects: fail, read, io, alloc.
Bus.request
function Bus.request(self: mut Bus, message: Message): Message throws stringSends the call MESSAGE and waits for its return; an error reply throws its name and text. Calls and signals that come
meanwhile wait for next.
Effects: fail, read, io, alloc.
Bus.next
function Bus.next(self: mut Bus): Message throws stringThe next message for this connection: a call to serve, a signal it listens to, or a reply nothing waits for.
Effects: fail, read, io, alloc.
Bus.own
function Bus.own(self: mut Bus, name: string): bool throws stringOwns the well-known NAME on the bus, replacing nothing; whether it is this connection's now.
Effects: fail, read, io, alloc.
Bus.listen
function Bus.listen(self: mut Bus, rule: string): void throws stringListens to the messages that the match RULE selects (type='signal',interface_='...').
Effects: fail, read, io, alloc.
Bus.dispose
function Bus.dispose(self: Bus): voidCloses the connection to the bus.
Effects: fail, io, alloc.
Constants
METHOD_CALL
const METHOD_CALL = 1The message kind of a method call.
METHOD_RETURN
const METHOD_RETURN = 2The message kind of a method return.
ERROR
const ERROR = 3The message kind of an error reply.
SIGNAL
const SIGNAL = 4The message kind of a signal.
NO_REPLY
const NO_REPLY = 1A message expects no reply.