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:

1
2
3
4
5
6
7
8

static void stream_handler_iface_init (gpointer, gpointer);

G_DEFINE_TYPE_WITH_CODE(GabbleMediaStream,
    gabble_media_stream,
    G_TYPE_OBJECT,
    G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_MEDIA_STREAM_HANDLER,
      stream_handler_iface_init)
    )

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

/* in header files */
void conn_aliasing_iface_init (gpointer, gpointer);
void conn_avatars_iface_init (gpointer, gpointer);
void conn_presence_iface_init (gpointer, gpointer);

/* in gabble-connection.c */
static void conn_iface_init (gpointer, gpointer);
static void capabilities_iface_init (gpointer, gpointer);

G_DEFINE_TYPE_WITH_CODE(GabbleConnection,
    gabble_connection,
    TP_TYPE_BASE_CONNECTION,
    G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CONNECTION,
      conn_iface_init);
    G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CONNECTION_INTERFACE_ALIASING,
      conn_aliasing_iface_init);
    G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CONNECTION_INTERFACE_AVATARS,
      conn_avatars_iface_init);
    G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CONNECTION_INTERFACE_CAPABILITIES,
      capabilities_init);
    G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CONNECTION_INTERFACE_PRESENCE,
      conn_presence_iface_init);
    )

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:

1
2
3

void (*tp_svc_media_session_handler_error_impl)
  (TpSvcMediaSessionHandler *self, guint errno, const char *message,
   GDBusMethodInvocation *context);

and here's the beginning of the corresponding implementation:

1
2
3
4
5
6
7
8
9

static void
gabble_media_session_error (TpSvcMediaSessionHandler *iface,
                            guint errno,
                            const char *message,
                            GDBusMethodInvocation *context)
{
  GabbleMediaSession *self = GABBLE_MEDIA_SESSION (iface);

  /* do stuff with self here */

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:

1
2
3
4
5
6
7
8
9
10
11
12

static void
gabble_media_session_error (TpSvcMediaSessionHandler *iface,
                            guint errno,
                            const char *message,
                            GDBusMethodInvocation *context)
{
  GabbleMediaSession *self = GABBLE_MEDIA_SESSION (iface);

  /* do stuff with self here */

  tp_svc_media_session_handler_return_from_error (context);
}

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:

1
2

tp_svc_media_session_handler_emit_new_stream_handler (session,
  object_path, id, media_type, TP_MEDIA_STREAM_DIRECTION_BIDIRECTIONAL);

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:

1
2
3
4
5
6
7
8
9
10
11

static void
session_handler_iface_init (gpointer g_iface, gpointer iface_data)
{
  TpSvcMediaSessionHandlerClass *klass =
    (TpSvcMediaSessionHandlerClass *)g_iface;

  tp_svc_media_session_handler_implement_error (klass,
      gabble_media_session_error);
  tp_svc_media_session_handler_implement_ready (klass,
      gabble_media_session_ready);
}

This is obviously quite repetitive if there are a lot of methods, so the convention I've used in telepathy-glib, Gabble and telepathy-sofiasip is to define a temporary macro called IMPLEMENT:

1
2
3
4
5
6
7
8
9
10
11
12

static void
session_handler_iface_init (gpointer g_iface, gpointer iface_data)
{
  TpSvcMediaSessionHandlerClass *klass =
    (TpSvcMediaSessionHandlerClass *)g_iface;

#define IMPLEMENT(x) tp_svc_media_session_handler_implement_##x (\
    klass, gabble_media_session_##x)
  IMPLEMENT(error);
  IMPLEMENT(ready);
#undef IMPLEMENT
}

If you're implementing many interfaces, just write many similar interface init functions.