README

This is a "plugin" for the Video Disk Recorder (VDR).

Written by:                  Lars Hanisch <dvb@flensrocker.de>

Project's homepage:          https://github.com/flensrocker/vdr-plugin-dbus2vdr

Latest version available at: git://github.com/flensrocker/vdr-plugin-dbus2vdr.git

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
See the file COPYING for more information.

Description:
This plugin will expose some methods via DBus to control the vdr.

Installation
------------
dbus2vdr will use the system bus so your box has to be configured that the user
in which context your vdr is running is allowed to connect to it.
Copy the de.tvdr.vdr.conf file to /etc/dbus-1/system.d and adjust it to your needs.
It is prepared that only the user 'vdr' can own the used destination and every user
can call its methods.

In the bin-directory you find a helper script for sending dbus messages to the vdr.
Instead of calling:
  dbus-send --system --type=method_call --dest=de.tvdr.vdr \
            --print-reply /Plugins/<pluginname> \
            de.tvdr.vdr.plugin.SVDRPCommand string:'command' string:'parameter'

you can call:
  vdr-dbus-send.sh /Plugins/<pluginname> plugin.SVDRPCommand string:'command' string:'parameter'

Implemented features
--------------------

- send SVDRP commands to plugins
  vdr-dbus-send.sh /Plugins/<pluginname> plugin.SVDRPCommand string:'command' string:'parameter'

If the SVDRP command doesn't take a parameter you can ommit it or pass an empty string.

- call Service method of plugins
  vdr-dbus-send.sh /Plugins/<pluginname> plugin.Service string:'id' string:'data'

- read EPG data from file
  vdr-dbus-send.sh /EPG epg.PutFile string:'/path/to/epg/data'

- get infos about the next timer
  vdr-dbus-send.sh /Timers timer.Next

  The following is returned:
    int32   reply code (250 for success, 550 on error)
    int32   timer id (-1 if there's no timer at all)
    int32   'rel' seconds (see SVDRP NEXT REL)
    uint64  starttime in seconds since epoch (time_t format)
    uint64  stoptime in seconds since epoch (time_t format)
    string  title of the event

- enable/disable the remote
  vdr-dbus-send.sh /Remote remote.Enable
  vdr-dbus-send.sh /Remote remote.Disable
  vdr-dbus-send.sh /Remote remote.Status

- hit a key
  vdr-dbus-send.sh /Remote remote.HitKey string:'Menu'

- open the main menu entry of a plugin
  vdr-dbus-send.sh /Remote remote.CallPlugin string:'name-of-plugin'

- trigger an update of the list of recordings
  vdr-dbus-send.sh /Recording recording.Update

Using the Python binding
------------------------
First, I don't know Python at all, I just copy code fragments from the Python Binding Tutorial [1]
and replace the sample strings with dbus2vdr related ones. I hope everybody familiar with Python
will know what to do...

  import dbus
  bus = dbus.SystemBus()
  Timers = bus.get_object('de.tvdr.vdr', '/Timers')
  props = Timers.Next(dbus_interface = 'de.tvdr.vdr.timer')
  # props is now a tuple with data like mentioned above

How to implement new interfaces
-------------------------------
- add the interface name to common.h
- create a subclass of cDBusMessageDispatcher and pass the interface name
  to its base constructor
- return subclasses of cDBusMessage in its CreateMessage method depending
  on object path, method name etc.
- return introspection data in OnIntrospect
- add your code to the Process method of your cDBusMessage classes
- add a 'new cDBusDispatcherYourName' to cPluginDbus2vdr::Start

Notes to myself
---------------
to use dbus in a ssh-shell:
look at ~/.dbus/session-bus/`dbus-uuidgen-get`-... and export DBUS_SESSION_BUS_ADDRESS

Links
-----
[1] http://dbus.freedesktop.org/doc/dbus-python/doc/tutorial.txt