From 2962f5449d1c083ec4106773cb4739fc68b0b509 Mon Sep 17 00:00:00 2001 From: Tony Crisci Date: Wed, 17 Apr 2019 06:22:14 -0400 Subject: [PATCH] document the type system --- README.md | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index caa49b0..517720d 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ dbus.setBigIntCompat(true); You can get a proxy object for a name on the bus with the `bus.getProxyObject()` function, passing the name and the path. The proxy object contains introspection data about the object including a list of nodes and interfaces. You can get an interface with the `object.getInterface()` function passing the name of the interface. -The interface object has methods you can call that correspond to the methods in the introspection data. Pass normal JavaScript objects to the parameters of the function and they will automatically be converted into the advertized DBus type. However, you must use the `Variant` class to represent DBus variants. +The interface object has methods you can call that correspond to the methods in the introspection data. Pass normal JavaScript objects to the parameters of the function and they will automatically be converted into the advertised DBus type. However, you must use the `Variant` class to represent DBus variants. Methods will similarly return JavaScript objects converted from the advertised DBus type, with the `Variant` class used to represent returned variants. If the method returns multiple values, they will be returned within an array. @@ -210,6 +210,44 @@ bus.on('message', (msg) => { For a complete example of how to use the low-level interface to send messages, see the `dbus-next-send.js` script in the `bin` directory. +## The Type System + +Values that are sent or received over the message bus always have an associated signature that specifies the types of those values. For the high-level client and service, these signatures are specified in XML data which is advertised in a [standard DBus interface](https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format). The high-level client dynamically creates classes based on this introspection data with methods and signals with arguments based on the type signature. The high-level service does the inverse by introspecting the class to create the introspection XML data which is advertised on the bus for clients. + +Each code in the signature is mapped to a JavaScript type as shown in the table below. + +| Name | Code | JS Type | Notes | +|-------------|------|---------|--------------------------------------------------------------------| +| BYTE | y | number | | +| BOOLEAN | b | boolean | | +| INT16 | n | number | | +| UINT16 | q | number | | +| INT32 | i | number | | +| UINT32 | u | number | | +| INT64 | x | BigInt | Use `dbus.setBigIntCompat(true)` to use `JSBI` | +| UINT64 | t | BigInt | Use `dbus.setBigIntCompat(true)` to use `JSBI` | +| DOUBLE | d | number | | +| STRING | s | string | | +| OBJECT_PATH | o | string | Must be a valid object path | +| SIGNATURE | g | string | Must be a valid signature | +| ARRAY | a | Array | Must be followed by a complete type which specifies the child type | +| STRUCT | ( | Array | Types in the JS Array must match the types between the parens | +| VARIANT | v | Variant | This class is provided by the library. | +| DICT_ENTRY | { | Object | Must be included in an array type to be an object. | + +The types `a`, `(`, `v`, and `{` are container types that hold other values. Examples of container types and JavaScript examples are in the table below. + +| Signature | Example | Notes | +|-----------|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| `(su)` | `[ 'foo', 5 ]` | Each element in the array must match the corresponding type of the struct member. | +| `as` | `[ 'foo', 'bar' ]` | The child type comes immediately after the `a`. The array can have any number of elements, but they all must match the child type. | +| `a{su}` | `{ 'foo': 5 }` | An "array of dict entries" is represented by an Object. The type after `{` is the key type and the type before the `}` is the value type. | +| `ay` | `Buffer.from([0x62, 0x75, 0x66])` | Special case: an array of bytes is represented by a Node `Buffer`. | +| `v` | `new Variant('s', 'hello')` | Signature must be a single type. Value may be a container type. | +| `(asv)` | `[ ['foo'], new Variant('s', 'bar') ]` | Containers may be nested. | + +For more information on the DBus type system, see [the specification](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system). + ## Contributing Contributions are welcome. Development happens on [Github](https://github.com/acrisci/node-dbus-next).