Documents

Installation

Installation of D-Bus

First of all, install D-Bus itself w/ packages of your Linux distributions or from a tar ball.

If you are using Debian GNU/Linux (etch or later), following lines will do:

apt-get install libdbus-1-dev

Installation of PHP DBus

You can install PHP DBus extension just like other PHP extensions. PHP DBus is tested w/ 5.2.6, but maybe available w/ 4.x.

$ tar zxvf php-dbus-0.1.0.tgz
$ cd php-dbus-0.1.0
$ phpize
$ ./configure
$ make
$ sudo make install

and then, add a following line to your php.ini:

extension=dbus.so

Tutorial

As far as I know, major usage of D-Bus is to communicate w/ Skype process on Linux, and PHP DBus is only tested w/ it:) So, please note that currently not only all D-Bus fucntions are provided in this module.

Anyway, simple usage of this module is as follows:

1. Creating DBusConnection Object

$dbus = dbus_bus_get($type);

You can set follwing D-Bus connection type:

DBUS_BUS_SESSION
DBUS_BUS_SYSTEM
DBUS_BUS_STARTER

in case you want to communicate w/ Skype process, specifiy DBUS_BUS_SESSION:

$dbus = dbus_bus_get(DBUS_BUS_SESSION);

2. Specify "object path"

Next, tell "object path" and its callback method to DBusConnection object. This enables the object to receive notification from anotehr process. For example, if you want to receive notification from Skype process, add the follwing line in your code:

$dbus->registerObjectPath("/com/Skype/Client", 'my_callback');

of course you can specify an object method via

$dbus->registerObjectPath("/com/Skype/Client", array($this, 'my_callback'));

3-1. Sending messages

Sending D-Bus message is also simple. First, creating DBusMessage object and pass it to DBusConnection::sendWithReplyAndBlock(). A practical example is like this(sending "PROTOCOL" command to Skype process):

$m = new DBusMessage(DBUS_MESSAGE_TYPE_METHOD_CALL);
$m->setDestination("com.Skype.API");
$m->setPath("/com/Skype");
$m->setInterface("com.Skype.API");
$m->setMember("Invoke");
$m->setAutoStart(true);
$m->appendArgs("PROTOCOL 7");

$r = $dbus->sendWithReplyAndBlock($m);
$tmp = $r->getArgs();
// ...

Parameters in the code above (destination("com.Skype.API"), path("/com/Skype") and interface("com.Skype.API")) are described in Skype API Documents.

D-Bus itself provides asynchronous communication but PHP DBus intentionally does not provides it to keep simplicity (at least for a while).

You can specify two message type w/ a first argument of ctor:

DBUS_MESSAGE_TYPE_METHOD_CALL
DBUS_MESSAGE_TYPE_SIGNAL

If you want to know more about message type, please visit D-Bus Specification page

3-2. Receiving messages

You can receive message (which is sent to path you specified via DBusConnection::registerObjectPath()) w/ DBusConnection::poll($timeout).

PHP DBus only provides synchronous method to receive messages (same reason as SendWithReplyAndBlock()...). So the polling code will be like this:

for (;;) {
  try {
    $dbus->poll(86400);
  } catch (Exception $e) {
    print $e;
    continue;
  }   
}

DBusConnection::poll() waits for messages to registered path, and call registered method in case the process finds any message.

notice

Again, PHP DBus currently provides minimum methods to handle Skype API but D-Bus itself provides more functions. Implementing rest of functions is not so hard (it is time consuming but easy, to be honest...), so if you are interested in this module, please fork my github project or give me a message.

Reference

PHP DBus is a simple wrapper of D-Bus API, so please read through API documents and D-Bus Specification.

mixed dbus_bus_get($type)

Creating DBusConnection object.

int $type: bus type(DBUS_BUS_SYSETM | DBUS_BUS_SESSION | DBUS_BUS_STARTER)

return value: DBusConnection object:success false:failure

mixed DBusConnection::sendWithReplyAndBlock($message, $timeout)

Sending a message(synchronous mode).

$message: DBusMessage object
$timeout: time out (in sec)

return value: DBusMessage object:success false:failure

bool DBusConnection::registerObjectPath($path, $callback)

Set "object path" to receive message. Received messages are dispatched to registered callback methods w/ DBusConnection::poll().

$path: object path to receive messages
$callback: call back function or method

return value: true:success false:failure

bool DBusConnection::poll($timeout)

Waits for messages $timeout seconds, and if a process received message, call registered function or method.

$timeout: time out (sec)

return value: true:success false:failure

DBusMessage::DBusMessage($type)

Constuctor of DBusMessage object.

$type: message type (DBUS_MESSAGE_TYPE_METHOD_CALL or DBUS_MESSAGE_TYPE_SIGNAL)

bool DBusMessage::setDestination($destination)

Specify a destination name in a DBusMessage object. See also D-Bus API Documents).

$destination: destination name

return value: true:success false:failure

DBusMessage::setPath($path)

Specify a path name in a DBUsMessage object. Ses also D-Bus API Documents).

$path: path name

return value: true:success false:failure

bool DBusMessage::setInterface($interface)

Specify an interface name in a DBusMessage object. See also D-Bus API Documents.

$interface: interface name

return value: true:success false:failure

bool DBusMessage::setMember($member)

Specify an interface member in a DBusMessage object. See also D-Bus API Documents.

$member: name of interface member

return value: true:success false:failure

bool DBusMessage::setAutoStart($auto_start)

Specify "auto start" flag in a DBusMessage object (in most cases, true(default) will do).

$auto_start: boolean value(true | false)

return value: true:success false:failure

bool DBusMessage::appendArgs($arg)

Add a parameter to a DBusMessage object.

$arg: parameter(currently string type is only available)

return value: true:success false:failure

array DBusMessage::getArgs()

Retrieve parameters in a DBusMessage object.

return value: array contains parameters