Expose the low-level api

fixes #20

Author: Tony Crisci

README.md

@@ -169,6 +169,47 @@ To emit a signal, just call the method marked with the `signal` decorator and th
 
 If you have an interface xml description, which can be gotten from the `org.freedesktop.DBus.Introspect` method on an exported interface, you can generate dbus-next JavaScript classes from the xml file with the `bin/generate-interfaces.js` utility.
 
+## The Low-Level Interface
+
+The low-level interface can be used to interact with messages directly. Create new messages with the `Message` class to be sent on the bus as method calls, signals, method returns, or errors. Method calls can be called with the `call()` method of the `MessageBus` to await a reply and `send()` can be use for messages that don't expect a reply.
+
+```js
+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(message);
+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);
+});
+```
+
+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.
+
 ## Contributing
 
 Contributions are welcome. Development happens on [Github](https://github.com/acrisci/node-dbus-next).

bin/dbus-next-send.js

@@ -128,7 +128,7 @@ let message = new Message({
 });
 
 if (type === MESSAGE_TYPE_METHOD_CALL) {
-  bus._call(message)
+  bus.call(message)
     .then((reply) => {
       console.log(JSON.stringify(reply, null, 2));
       process.exit(0);
@@ -138,6 +138,6 @@ if (type === MESSAGE_TYPE_METHOD_CALL) {
       process.exit(1);
     });
 } else {
-  bus._send(message);
+  bus.send(message);
   process.exit(0);
 }

lib/bus.js

@@ -24,9 +24,13 @@ let { Interface } = require('./service/interface');
  * created with `dbus.sessionBus()` or `dbus.systemBus()` methods of the
  * dbus-next module.
  *
- * The `MessageBus` is an `EventEmitter` which may receive an `error` event
- * with the underlying connection error as the argument. After receiving an
- * `error` event, the `MessageBus` may be disconnected.
+ * The `MessageBus` is an `EventEmitter` which emits the following events:
+ * * `error` - The underlying connection to the bus has errored.  After
+ * receiving an `error` event, the `MessageBus` may be disconnected.
+ * * `connected` - The bus is connected and ready to send and receive messages.
+ * Before this event, messages are buffered.
+ * * `message` - The bus has received a message. Called with the {@link
+ * Message} that was received. This is part of the low-level api.
  *
  * @example
  * const dbus = require('dbus-next');
@@ -103,7 +107,7 @@ class MessageBus extends EventEmitter {
         }
 
         if (!handled) {
-          this._send(Message.newError(msg,
+          this.send(Message.newError(msg,
             'org.freedesktop.DBus.Error.UnknownMethod',
             `Method '${msg.member}' on interface '${msg.interface || '(none)'}' does not exist`));
         }
@@ -116,7 +120,7 @@ class MessageBus extends EventEmitter {
         this.emit('message', msg);
         handleMessage(msg);
       } catch (e) {
-        this._send(Message.newError(msg, 'com.github.dbus_next.Error', `The DBus library encountered an error.\n${e.stack}`));
+        this.send(Message.newError(msg, 'com.github.dbus_next.Error', `The DBus library encountered an error.\n${e.stack}`));
       }
     });
 
@@ -132,7 +136,7 @@ class MessageBus extends EventEmitter {
       member: 'Hello'
     });
 
-    this._call(helloMessage)
+    this.call(helloMessage)
       .then((msg) => {
         this.name = msg.body[0];
         // TODO document this signal
@@ -145,9 +149,9 @@ class MessageBus extends EventEmitter {
   }
 
   /**
-   * Get a `ProxyObject` on the bus for the given name and path for interacting
+   * Get a {@link ProxyObject} on the bus for the given name and path for interacting
    * with a service as a client. The proxy object contains a list of the
-   * `ProxyInterface`s exported at the name and object path as well as a list
+   * [`ProxyInterface`s]{@link ProxyInterface} exported at the name and object path as well as a list
    * of `node`s.
    *
    * @param name {string} - the well-known name on the bus.
@@ -187,7 +191,7 @@ class MessageBus extends EventEmitter {
         signature: 'su',
         body: [name, flags]
       });
-      this._call(requestNameMessage)
+      this.call(requestNameMessage)
         .then((msg) => {
           let result = msg.body[0];
           if (result === constants.DBUS_REQUEST_NAME_REPLY_EXISTS) {
@@ -215,33 +219,81 @@ class MessageBus extends EventEmitter {
     this._connection.stream.end();
   }
 
-  _newSerial() {
+  /**
+   * Get a new serial for this bus. These can be used to set the {@link
+   * Message#serial} member to send the message on this bus.
+   *
+   * @returns {int} - A new serial for this bus.
+   */
+  newSerial() {
     return this._serial++;
   }
 
-  _addMethodHandler(fn) {
+  /**
+   * A function to call when a message of type {@link
+   * MESSAGE_TYPE_METHOD_RETURN} is received. User handlers are run before
+   * default handlers.
+   *
+   * @callback methodHandler
+   * @param {Message} msg - The message to handle.
+   * @returns {boolean} Return `true` if the message is handled and no further
+   * handlers will run.
+   */
+
+  /**
+   * Add a user method return handler. Remove the handler with {@link
+   * MessageBus#removeMethodHandler}
+   *
+   * @param {methodHandler} - A function to handle a {@link Message} of type
+   * {@link MESSAGE_TYPE_METHOD_RETURN}. Takes the `Message` as the first
+    * argument. Return `true` if the method is handled and no further handlers
+    * will run.
+   */
+  addMethodHandler(fn) {
     this._methodHandlers.push(fn);
   }
 
-  _removeMethodHandler(fn) {
+  /**
+   * Remove a user method return handler that was previously added with {@link
+   * MessageBus#addMethodHandler}.
+   *
+   * @param {methodHandler} - A function that was previously added as a method handler with {@link 
+   */
+  removeMethodHandler(fn) {
     for (let i = 0; i < this._methodHandlers.length; ++i) {
       if (this._methodHandlers[i] === fn) {
         this._methodHandlers.splice(i, 1);
       }
     }
   }
 
-  _call(msg) {
+  /**
+   * Send a {@link Message} of type {@link MESSAGE_TYPE_METHOD_CALL} to the bus
+   * and wait for the reply.
+   *
+   * @example
+   * let message = new Message({
+   *   destination: 'org.freedesktop.DBus',
+   *   path: '/org/freedesktop/DBus',
+   *   interface: 'org.freedesktop.DBus',
+   *   member: 'ListNames'
+   * });
+   * let reply = await bus.call(message);
+   *
+   * @param {Message} msg - The message to send. Must be a METHOD_CALL.
+   * @returns {Promise} reply - A `Promise` that resolves to the `Message`
+   * which is a reply to the call.
+   */
+  call(msg) {
     return new Promise((resolve, reject) => {
-      // TODO: if the NO_REPLY_EXPECTED flag is set, resolve immediately after sending the message.
       if (!(msg instanceof Message)) {
         throw new Error('The call() method takes a Message class as the first argument.');
       }
       if (msg.type !== constants.messageType.METHOD_CALL) {
         throw new Error('Only messages of type METHOD_CALL can expect a call reply.');
       }
       if (msg.serial === null || msg._sent) {
-        msg.serial = this._newSerial();
+        msg.serial = this.newSerial();
       }
       msg._sent = true;
       if (msg.flags & constants.flags.noReplyExpected) {
@@ -260,12 +312,23 @@ class MessageBus extends EventEmitter {
     });
   };
 
-  _send(msg) {
+  /**
+   * Send a {@link Message} on the bus that does not expect a reply.
+   *
+   * @example
+   * let message = Message.newSignal('/org/test/path/,
+   *                                 'org.test.interface',
+   *                                 'SomeSignal');
+   * bus.send(message);
+   *
+   * @param {Message} msg - The message to send.
+   */
+  send(msg) {
     if (!(msg instanceof Message)) {
       throw new Error('The send() method takes a Message class as the first argument.');
     }
     if (msg.serial === null || msg._sent) {
-      msg.serial = this._newSerial();
+      msg.serial = this.newSerial();
     }
     this._connection.message(msg);
   }
@@ -279,7 +342,7 @@ class MessageBus extends EventEmitter {
       signature: 's',
       body: [match]
     });
-    return this._call(msg);
+    return this.call(msg);
   };
 };
 

lib/client/proxy-object.js

@@ -142,7 +142,7 @@ class ProxyObject {
         body: []
       });
 
-      this.bus._call(introspectMessage)
+      this.bus.call(introspectMessage)
         .then((msg) => {
           let xml = msg.body[0];
           this._parser.parseString(xml, (err, data) => {
@@ -172,7 +172,7 @@ class ProxyObject {
         body: args
       });
 
-      this.bus._call(methodCallMessage)
+      this.bus.call(methodCallMessage)
         .then((msg) => {
           let outSignatureTree = parseSignature(outSignature);
           if (outSignatureTree.length === 0) {