# 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.

```gizlang
import * as Dbus from "gizlang/dbus";
```

## Types

### `Value`

```gizlang
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`: `string`
- `number`: `i64`
- `real`: `f64`
- `text`: `string`
- `items`: `Vec<gizlang_dbus.Value>`
- `data`: `bytes`

### `Message`

```gizlang
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`: `i64`
- `flags`: `i64`
- `serial`: `i64`
- `replySerial`: `i64`
- `path`: `string`
- `interface_`: `string`
- `member`: `string`
- `errorName`: `string`
- `destination`: `string`
- `sender`: `string`
- `signature`: `string`
- `body`: `Vec<gizlang_dbus.Value>`

### `Bus`

```gizlang
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.Stream`
- `name`: `string`
- `serial`: `i64`
- `waiting`: `Vec<gizlang_dbus.Message>`

## Functions

### `byte`

```gizlang
function byte(n: i64): Value
```

The byte (y) of the low 8 bits of N.

Effects: fail.

### `boolean`

```gizlang
function boolean(b: bool): Value
```

The boolean (b) B.

### `int16`

```gizlang
function int16(n: i64): Value
```

The 16-bit signed integer (n) N.

### `uint16`

```gizlang
function uint16(n: i64): Value
```

The 16-bit unsigned integer (q) of the low 16 bits of N.

Effects: fail.

### `int32`

```gizlang
function int32(n: i64): Value
```

The 32-bit signed integer (i) N.

### `uint32`

```gizlang
function uint32(n: i64): Value
```

The 32-bit unsigned integer (u) of the low 32 bits of N.

Effects: fail.

### `int64`

```gizlang
function int64(n: i64): Value
```

The 64-bit signed integer (x) N.

### `uint64`

```gizlang
function uint64(n: i64): Value
```

The 64-bit unsigned integer (t) with the bits of N.

### `double`

```gizlang
function double(x: f64): Value
```

The double (d) X.

### `text`

```gizlang
function text(value: string): Value
```

The string (s) VALUE.

### `objectPath`

```gizlang
function objectPath(path: string): Value
```

The object path (o) PATH.

### `typeSignature`

```gizlang
function typeSignature(value: string): Value
```

The signature (g) VALUE.

### `array`

```gizlang
function array(element: string, items: Vec<Value>): Value
```

An array of ELEMENT, the signature of each of its ITEMS; the bytes of a byte array go to its DATA.

Effects: fail, alloc.

### `byteArray`

```gizlang
function byteArray(data: bytes): Value
```

The byte array (ay) of DATA.

### `struct`

```gizlang
function struct(items: Vec<Value>): Value
```

The struct of ITEMS, in order.

Effects: fail, alloc.

### `variant`

```gizlang
function variant(value: Value): Value
```

The variant (v) that holds VALUE.

Effects: fail, alloc.

### `dict`

```gizlang
function dict(key: string, value: string, keys: Vec<Value>, values: Vec<Value>): Value
```

A dict a{KV}: the entries of KEYS and VALUES in order, VALUE the signature of every value.

Effects: fail, alloc.

### `lookup`

```gizlang
function lookup(dict: Value, key: string): Value | undefined
```

The value of KEY in the dict DICT (a{s...}, its values variants unwrapped), or undefined.

Effects: fail.

### `marshal`

```gizlang
function marshal(out: mut bytes, value: Value): void
```

VALUE appended to OUT, whose length is the offset its alignment counts from (the message's start).

Effects: fail, alloc.

### `typeEnd`

```gizlang
function typeEnd(signature: string, at: i64): i64
```

The end of the single complete type that starts at AT in SIGNATURE.

Effects: fail, alloc.

### `types`

```gizlang
function types(signature: string): Vec<string>
```

The complete types of SIGNATURE, in order.

Effects: fail, alloc.

### `unmarshalAll`

```gizlang
function unmarshalAll(data: bytes, at: i64, signature: string): Vec<Value> throws string
```

The values of SIGNATURE in DATA from AT (alignment counts from DATA's start).

Effects: fail, alloc.

### `call`

```gizlang
function call(destination: string, path: string, interface_: string, member: string, body: Vec<Value>): Message
```

A method call of MEMBER of INTERFACE on PATH of DESTINATION, with BODY.

### `signal`

```gizlang
function signal(path: string, interface_: string, member: string, body: Vec<Value>): Message
```

The signal MEMBER of INTERFACE from PATH, with BODY.

### `reply`

```gizlang
function reply(to: Message, body: Vec<Value>): Message
```

The return of the call TO, with BODY.

### `error`

```gizlang
function error(to: Message, name: string, said: string): Message
```

The error NAME of the call TO, saying SAID.

Effects: fail, alloc.

### `encode`

```gizlang
function encode(message: Message, serial: i64): bytes
```

The bytes of MESSAGE with SERIAL.

Effects: fail, alloc.

### `length`

```gizlang
function length(head: bytes): i64
```

The bytes of a whole message from its first 16 (HEAD): its length.

Effects: fail.

### `decode`

```gizlang
function decode(data: bytes): Message throws string
```

The message in DATA, whole.

Effects: fail, alloc.

### `socketPath`

```gizlang
function socketPath(address: string): string
```

The path of a unix:path= ADDRESS (the first of its ;-separated addresses that is one), or "".

Effects: fail, alloc.

### `connect`

```gizlang
function connect(address: string): Bus throws string
```

A 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`

```gizlang
function Bus.send(self: mut Bus, message: Message): i64 throws string
```

Sends MESSAGE; its serial.

Effects: fail, read, io, alloc.

### `Bus.request`

```gizlang
function Bus.request(self: mut Bus, message: Message): Message throws string
```

Sends 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`

```gizlang
function Bus.next(self: mut Bus): Message throws string
```

The 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`

```gizlang
function Bus.own(self: mut Bus, name: string): bool throws string
```

Owns the well-known NAME on the bus, replacing nothing; whether it is this connection's now.

Effects: fail, read, io, alloc.

### `Bus.listen`

```gizlang
function Bus.listen(self: mut Bus, rule: string): void throws string
```

Listens to the messages that the match RULE selects (`type='signal',interface_='...'`).

Effects: fail, read, io, alloc.

### `Bus.dispose`

```gizlang
function Bus.dispose(self: Bus): void
```

Closes the connection to the bus.

Effects: fail, io, alloc.

## Constants

### `METHOD_CALL`

```gizlang
const METHOD_CALL = 1
```

The message kind of a method call.

### `METHOD_RETURN`

```gizlang
const METHOD_RETURN = 2
```

The message kind of a method return.

### `ERROR`

```gizlang
const ERROR = 3
```

The message kind of an error reply.

### `SIGNAL`

```gizlang
const SIGNAL = 4
```

The message kind of a signal.

### `NO_REPLY`

```gizlang
const NO_REPLY = 1
```

A message expects no reply.

