The TpSvc* interfaces

The GInterfaces whose names start with TpSvc are generated automatically
from the Telepathy specification, and can be used to make it
somewhat easier to export methods and signals onto D-Bus.

The media session interface makes a convenient example
because it only has two methods (Error() and Ready())
and one signal (NewStreamHandler), and media session handlers
aren't expected to implement any other interfaces.

The first thing to do is pre-declare the interface init function,
and define the type you'll be using, declaring it to implement the
media stream handler interface:

Here we're using a subclass of G_TYPE_OBJECT. You can of course subclass
any type.

If you're implementing more than one interface on the same object,
define more than one init function, and call G_IMPLEMENT_INTERFACE
more than once. The interface init functions can even be extern
if you want to separate off chunks of functionality into a different
.c file. For instance, here's GabbleConnection:

The _class_init, _init etc. functions are just like normal, so I
won't describe them here. One thing to note, though, is that for
signals which are defined by the GInterface, you do not need to do
anything in the _class_init - the GInterface has already set the
signal up for you.

For each exported D-Bus method, there's a typedef ending with _impl
giving the signature you should use for your method implementation.
For example, here's the signature for the Error method on the
media session handler interface:

The method implementation's last parameter is a GDBusMethodInvocation.
To send the reply, you must either call
g_dbus_method_invocation_return_gerror or similar (for a failure),
g_dbus_method_invocation_return_value (for a successful return),
or an inline function whose name contains "_return_from_" provided by
the TpSvc interface. For example, for Error there's an inline function
tp_svc_media_session_handler_return_from_error(). These inline functions
are just a simple wrapper around g_dbus_method_invocation_return_value()
to make it type-safe.

For instance, Error doesn't return anything, so
tp_svc_media_session_handler_return_from_error() doesn't take any
parameters apart from the GDBusMethodInvocation:

As for signals, they're named as dictated by dbus-glib
(even though we don't actually use dbus-glib any more). This normally
gives you a sensible lower-case name - for instance NewStreamHandler
is mapped to "new-stream-handler".

To emit a signal, the generated code contains another convenience
function whose name contains _emit_. This is prototyped to take
the correct arguments for the signal, and emits it efficiently:

Finally, the interface init function needs to be written. Normally
you'd set the fields of a vtable to be pointers to your method
implementations. However, we couldn't do this in telepathy-glib
because that would mean breaking the ABI every time we added methods
to an interface. Instead, you call functions, with pointers to your
method implementations as a parameter: