Service-side room interfaces

## Service-side room interfaces Service-side room interfaces — room-related functionality for channels |

## Synopsis

    #include <telepathy-glib/telepathy-glib-dbus.h>

                        TpSvcChannelInterfaceRoom;
                        TpSvcChannelInterfaceRoomClass;

                        TpSvcChannelInterfaceRoomConfig;
                        TpSvcChannelInterfaceRoomConfigClass;
    void                tp_svc_channel_interface_room_config_implement_update_configuration
                                                            (TpSvcChannelInterfaceRoomConfigClass *klass,
                                                             tp_svc_channel_interface_room_config_update_configuration_impl impl);
    void                tp_svc_channel_interface_room_config_return_from_update_configuration
                                                            (DBusGMethodInvocation *context);
    void                (*tp_svc_channel_interface_room_config_update_configuration_impl)
                                                            (TpSvcChannelInterfaceRoomConfig *self,
                                                             GHashTable *in_Properties,
                                                             DBusGMethodInvocation *context);

                        TpSvcChannelInterfaceSubject;
                        TpSvcChannelInterfaceSubjectClass;
    void                tp_svc_channel_interface_subject_implement_set_subject
                                                            (TpSvcChannelInterfaceSubjectClass *klass,
                                                             tp_svc_channel_interface_subject_set_subject_impl impl);
    void                tp_svc_channel_interface_subject_return_from_set_subject
                                                            (DBusGMethodInvocation *context);
    void                (*tp_svc_channel_interface_subject_set_subject_impl)
                                                            (TpSvcChannelInterfaceSubject *self,
                                                             const gchar *in_Subject,
                                                             DBusGMethodInvocation *context);

## Object Hierarchy

      GInterface
       +----TpSvcChannelInterfaceRoom

      GInterface
       +----TpSvcChannelInterfaceRoomConfig

      GInterface
       +----TpSvcChannelInterfaceSubject

## Description

This collection of interfaces is used to expose various aspects of the configuration of chat rooms.

TpSvcChannelInterfaceRoom consists of a pair of requestable, immutable properties: `"RoomName"` and `"Server"`; and a pair of immutable properties: `"Creator"`, `"CreatorHandle"`, and `"CreationTimestamp"`. It has no methods or signals. It should be implemented on channels representing a chat room (whether it be a text chat, a multi-user call, or some other media type).

TpSvcChannelInterfaceSubject may be implemented by channels which have a subject (or topic, depending on your protocol's terminology of choice). This will usually be in addition to TpSvcChannelInterfaceRoom, though in theory a 1-1 channel could have a subject. In addition to its single method, it defines a set of read-only properties, namely `"Subject"`, `"Actor"`, `"ActorHandle"`, `"Timestamp"`, and `"CanSet"`. Changes should be signalled using `tp_dbus_properties_mixin_emit_properties_changed()`.

TpSvcChannelInterfaceRoomConfig provides a vast array of properties for other aspects of a chat room's configuration (such as the maximum number of participants, and whether the room is password-protected). Channels with this interface will typically implement the other two, too.

## Details

### TpSvcChannelInterfaceRoom

    typedef struct _TpSvcChannelInterfaceRoom TpSvcChannelInterfaceRoom;

Dummy typedef representing any implementation of this interface.

### TpSvcChannelInterfaceRoomClass

    typedef struct _TpSvcChannelInterfaceRoomClass TpSvcChannelInterfaceRoomClass;

The class of TpSvcChannelInterfaceRoom. This interface has no D-Bus methods, so an implementation can typically pass `NULL` to `G_IMPLEMENT_INTERFACE()` as the interface initialization function.

### TpSvcChannelInterfaceRoomConfig

    typedef struct _TpSvcChannelInterfaceRoomConfig TpSvcChannelInterfaceRoomConfig;

Dummy typedef representing any implementation of this interface.

### TpSvcChannelInterfaceRoomConfigClass

    typedef struct _TpSvcChannelInterfaceRoomConfigClass TpSvcChannelInterfaceRoomConfigClass;

The class of TpSvcChannelInterfaceRoomConfig.

In a full implementation of this interface (i.e. all methods implemented), the interface initialization function used in `G_IMPLEMENT_INTERFACE()` would typically look like this:

    static void
    implement_channel_interface_room_config (gpointer klass,
        gpointer unused G_GNUC_UNUSED)
    {
    #define IMPLEMENT(x) tp_svc_channel_interface_room_config_implement_##x (\
      klass, my_object_##x)
      IMPLEMENT (update_configuration);
    #undef IMPLEMENT
    }

### tp_svc_channel_interface_room_config_implement_update_configuration ()

    void                tp_svc_channel_interface_room_config_implement_update_configuration
                                                            (TpSvcChannelInterfaceRoomConfigClass *klass,
                                                             tp_svc_channel_interface_room_config_update_configuration_impl impl);

Register an implementation for the UpdateConfiguration method in the vtable of an implementation of this interface. To be called from the interface init function.

`klass` : | A class whose instances implement this interface
`impl` : | A callback used to implement the UpdateConfiguration D-Bus method

### tp_svc_channel_interface_room_config_return_from_update_configuration ()

    void                tp_svc_channel_interface_room_config_return_from_update_configuration
                                                            (DBusGMethodInvocation *context);

Return successfully by calling `dbus_g_method_return()`. This inline function exists only to provide type-safety.

`context` : | The D-Bus method invocation context

### tp_svc_channel_interface_room_config_update_configuration_impl ()

    void                (*tp_svc_channel_interface_room_config_update_configuration_impl)
                                                            (TpSvcChannelInterfaceRoomConfig *self,
                                                             GHashTable *in_Properties,
                                                             DBusGMethodInvocation *context);

The signature of an implementation of the D-Bus method UpdateConfiguration on interface org.freedesktop.Telepathy.Channel.Interface.RoomConfig1.

`self` : | The object implementing this interface
`in_Properties` : | GHashTable * (FIXME, generate documentation)
`context` : | Used to return values or throw an error

### TpSvcChannelInterfaceSubject

    typedef struct _TpSvcChannelInterfaceSubject TpSvcChannelInterfaceSubject;

Dummy typedef representing any implementation of this interface.

### TpSvcChannelInterfaceSubjectClass

    typedef struct _TpSvcChannelInterfaceSubjectClass TpSvcChannelInterfaceSubjectClass;

The class of TpSvcChannelInterfaceSubject.

In a full implementation of this interface (i.e. all methods implemented), the interface initialization function used in `G_IMPLEMENT_INTERFACE()` would typically look like this:

    static void
    implement_channel_interface_subject (gpointer klass,
        gpointer unused G_GNUC_UNUSED)
    {
    #define IMPLEMENT(x) tp_svc_channel_interface_subject_implement_##x (\
      klass, my_object_##x)
      IMPLEMENT (set_subject);
    #undef IMPLEMENT
    }

### tp_svc_channel_interface_subject_implement_set_subject ()

    void                tp_svc_channel_interface_subject_implement_set_subject
                                                            (TpSvcChannelInterfaceSubjectClass *klass,
                                                             tp_svc_channel_interface_subject_set_subject_impl impl);

Register an implementation for the SetSubject method in the vtable of an implementation of this interface. To be called from the interface init function.

`klass` : | A class whose instances implement this interface
`impl` : | A callback used to implement the SetSubject D-Bus method

### tp_svc_channel_interface_subject_return_from_set_subject ()

    void                tp_svc_channel_interface_subject_return_from_set_subject
                                                            (DBusGMethodInvocation *context);

Return successfully by calling `dbus_g_method_return()`. This inline function exists only to provide type-safety.

`context` : | The D-Bus method invocation context

### tp_svc_channel_interface_subject_set_subject_impl ()

    void                (*tp_svc_channel_interface_subject_set_subject_impl)
                                                            (TpSvcChannelInterfaceSubject *self,
                                                             const gchar *in_Subject,
                                                             DBusGMethodInvocation *context);

The signature of an implementation of the D-Bus method SetSubject on interface org.freedesktop.Telepathy.Channel.Interface.Subject2.

`self` : | The object implementing this interface
`in_Subject` : | const gchar * (FIXME, generate documentation)
`context` : | Used to return values or throw an error