TpBaseRoomConfig: telepathy-glib API Reference Manual

## TpBaseRoomConfig TpBaseRoomConfig — implements the RoomConfig interface for chat rooms. |

## Functions

void | (*TpBaseRoomConfigUpdateAsync) ()
gboolean | (*TpBaseRoomConfigUpdateFinish) ()
void | tp_base_room_config_register_class ()
void | tp_base_room_config_iface_init ()
TpBaseChannel * | tp_base_room_config_dup_channel ()
void | tp_base_room_config_set_can_update_configuration ()
void | tp_base_room_config_set_property_mutable ()
void | tp_base_room_config_emit_properties_changed ()
void | tp_base_room_config_set_retrieved ()

## Properties

gboolean | anonymous | Read / Write
gboolean | can-update-configuration | Read / Write
TpBaseChannel * | channel | Read / Write / Construct Only
gboolean | configuration-retrieved | Read
gchar * | description | Read / Write
gboolean | invite-only | Read / Write
guint | limit | Read / Write
gboolean | moderated | Read / Write
GStrv | mutable-properties | Read
gchar * | password | Read / Write
gchar * | password-hint | Read / Write
gboolean | password-protected | Read / Write
gboolean | persistent | Read / Write
gboolean | private | Read / Write
gchar * | title | Read / Write

## Types and Values

struct | TpBaseRoomConfig
struct | TpBaseRoomConfigClass
enum | TpBaseRoomConfigProperty
#define | TP_TYPE_BASE_ROOM_CONFIG_PROPERTY

## Object Hierarchy

        GEnum
        ╰── TpBaseRoomConfigProperty
        GObject
        ╰── TpBaseRoomConfig

## Includes

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

## Description

This class implements the TpSvcChannelInterfaceRoomConfig interface on multi-user chat room channels. CMs are expected to subclass this base class to implement the protocol-specific details of changing room configuration. Then, in the connection manager's subclass of TpBaseChannel for multi-user chats:

- in G_DEFINE_TYPE_WITH_CODE, implement TP_TYPE_SVC_CHANNEL_INTERFACE_ROOM_CONFIG using `tp_base_room_config_iface_init()`:

      1
      2
      3
      4
      5
      6
      7
      G_DEFINE_TYPE_WITH_CODE (MyMucChannel, my_muc_channel,
          TP_TYPE_BASE_CHANNEL,
          // ...
          G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CHANNEL_INTERFACE_ROOM_CONFIG,
              tp_base_room_config_iface_init)
          // ...
          )

- in the `class_init` method, call `tp_base_room_config_register_class()`:

      1
      2
      3
      4
      5
      6
      7
      static void
      my_muc_channel_class_init (MyMucChannelClass *klass)
      {
        // ...
        tp_base_room_config_register_class (TP_BASE_CHANNEL_CLASS (klass));
        // ...
      }

- include `TP_IFACE_CHANNEL_INTERFACE_ROOM_CONFIG` in the return of TpBaseChannelClass.get_interfaces.

If this protocol supports modifying some aspects of the room's configuration, the subclass should call `tp_base_room_config_set_property_mutable()` to mark appropriate properties as potentially-modifiable, call `tp_base_room_config_set_can_update_configuration()` to indicate whether the local user has permission to modify those properties at present, and implement TpBaseRoomConfigClass.update_async. When updates to properties are received from the network, they should be updated on this object using `g_object_set()`:

    1
    2
    3
    4
    5
    g_object_self (room_config,
       "description", "A place to bury strangers",
       "private", TRUE,
       NULL);
    tp_base_room_config_emit_properties_changed (room_config);

On joining the room, once the entire room configuration has been retrieved from the network, the CM should call `tp_base_room_config_set_retrieved()`.

## Functions

### TpBaseRoomConfigUpdateAsync ()

    void
    (*TpBaseRoomConfigUpdateAsync) (TpBaseRoomConfig *self,
                                    GHashTable *validated_properties,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Signature for a function to begin a network request to update the room configuration. It is guaranteed that `validated_properties` will only contain properties which were marked as mutable when the D-Bus method invocation arrived.

Note that TpBaseRoomConfig will take care of applying the property updates to itself if the operation succeeds.

#### Parameters

self | a TpBaseRoomConfig |
validated_properties | a mapping from TpBaseRoomConfigProperty to GValue, whose types have already been validated. The function should not modify this hash table. |
callback | a callback to call on success, failure or disconnection |
user_data | user data for the callback |

### TpBaseRoomConfigUpdateFinish ()

    gboolean
    (*TpBaseRoomConfigUpdateFinish) (TpBaseRoomConfig *self,
                                     GAsyncResult *result,
                                     GError **error);

Signature for a function to complete a call to a corresponding implementation of TpBaseRoomConfigUpdateAsync.

#### Parameters

self | a TpBaseRoomConfig |
result | the result passed to the callback |
error | used to return an error if `FALSE` is returned. |

#### Returns

`TRUE` if the room configuration update was accepted by the server; `FALSE`, with `error` set, otherwise.

### tp_base_room_config_register_class ()

    void
    tp_base_room_config_register_class (TpBaseChannelClass *base_channel_class);

Registers that D-Bus properties for the RoomConfig1 interface should be handled by a TpBaseRoomConfig object associated with instances of `base_channel_class` .

`base_channel_class` must implement TP_SVC_CHANNEL_INTERFACE_ROOM_CONFIG using `tp_base_room_config_iface_init()`, and instances of `base_channel_class` must construct an instance of TpBaseRoomConfig, passing themself as “channel”.

#### Parameters

base_channel_class | the class structure for a subclass of TpBaseChannel which uses this object to implement TP_SVC_CHANNEL_INTERFACE_ROOM_CONFIG |

### tp_base_room_config_iface_init ()

    void
    tp_base_room_config_iface_init (gpointer g_iface,
                                    gpointer iface_data);

Pass this as the second argument to `G_IMPLEMENT_INTERFACE()` when defining a TpBaseChannel subclass to declare that TP_SVC_CHANNEL_INTERFACE_ROOM_CONFIG is implemented using this class. The TpBaseChannel subclass must also call `tp_base_room_config_register_class()` in its class_init function, and construct a TpBaseRoomConfig object for each instance.

#### Parameters

g_iface | a pointer to a TpSvcChannelInterfaceRoomConfigClass structure |
iface_data | ignored |

### tp_base_room_config_dup_channel ()

    TpBaseChannel *
    tp_base_room_config_dup_channel (TpBaseRoomConfig *self);

Returns the channel to which `self` is attached.

#### Parameters

self | a TpBaseChannel |

#### Returns

the “channel” property.

[transfer full]

### tp_base_room_config_set_can_update_configuration ()

    void
    tp_base_room_config_set_can_update_configuration
                                   (TpBaseRoomConfig *self,
                                    gboolean can_update_configuration);

Specify whether or not the local user currently has permission to modify the room configuration.

Changes made by calling this function are not signalled over D-Bus until `tp_base_room_config_emit_properties_changed()` is next called.

#### Parameters

self | a TpBaseRoomConfig object. |
can_update_configuration | `TRUE` if the local user has permission to modify properties marked as mutable. |

### tp_base_room_config_set_property_mutable ()

    void
    tp_base_room_config_set_property_mutable
                                   (TpBaseRoomConfig *self,
                                    TpBaseRoomConfigProperty property_id,
                                    gboolean is_mutable);

Specify whether it is possible for room members to modify the value of `property_id` (possibly dependent on them having channel-operator powers), or whether `property_id` 's value is an intrinsic fact about the protocol.

For example, on IRC it is impossible to configure a channel to hide the identities of participants from others, so `TP_BASE_ROOM_CONFIG_ANONYMOUS` should be marked as immutable on IRC; whereas channel operators can mark rooms as invite-only, so `TP_BASE_ROOM_CONFIG_INVITE_ONLY` should be marked as mutable on IRC.

By default, all properties are considered immutable.

Call `tp_base_room_config_set_can_update_configuration()` to specify whether or not it is currently possible for the local user to alter properties marked as mutable.

Changes made by calling this function are not signalled over D-Bus until `tp_base_room_config_emit_properties_changed()` is next called.

#### Parameters

self | a TpBaseRoomConfig object. |
property_id | a property identifier (not including `TP_NUM_BASE_ROOM_CONFIG_PROPERTIES`) |
is_mutable | `TRUE` if it is possible for Telepathy clients to modify |
property_id when #TpBaseRoomConfig | can-update-configuration is `TRUE`. |

### tp_base_room_config_emit_properties_changed ()

    void
    tp_base_room_config_emit_properties_changed
                                   (TpBaseRoomConfig *self);

Signal the new values of properties which have been modified since the last call to this method, if any. This includes changes made by calling `tp_base_room_config_set_can_update_configuration()` and `tp_base_room_config_set_property_mutable()`, as well as changes to any of the (writeable) GObject properties on this object.

#### Parameters

self | a TpBaseRoomConfig object. |

### tp_base_room_config_set_retrieved ()

    void
    tp_base_room_config_set_retrieved (TpBaseRoomConfig *self);

Signal that the room's configuration has been retrieved, as well as signalling any queued property changes. This function should be called once all properties have been set to meaningful values.

It is safe to call this function more than once; second and subsequent calls are equivalent to calling `tp_base_room_config_emit_properties_changed()`.

#### Parameters

self | a TpBaseRoomConfig object |

## Types and Values

### struct TpBaseRoomConfig

    struct TpBaseRoomConfig;

An object representing the configuration of a multi-user chat room.

There are no public fields.

### struct TpBaseRoomConfigClass

    struct TpBaseRoomConfigClass {
        TpBaseRoomConfigUpdateAsync update_async;
        TpBaseRoomConfigUpdateFinish update_finish;
    };

Class structure for TpBaseRoomConfig. By default, `update_async` is `NULL`, indicating that updating room configuration is not implemented; subclasses should override it if they wish to support updating room configuration.

#### Members

TpBaseRoomConfigUpdateAsync `update_async`; | begins a request to modify the room's configuration. |
TpBaseRoomConfigUpdateFinish `update_finish`; | completes a call to `update_async` ; the default implementation may be used if `update_async` uses GSimpleAsyncResult |

### enum TpBaseRoomConfigProperty

An enumeration of room configuration fields, corresponding to GObject properties and, in turn, to D-Bus properties.

#### Members

TP_BASE_ROOM_CONFIG_ANONYMOUS | corresponds to “anonymous” |
TP_BASE_ROOM_CONFIG_INVITE_ONLY | corresponds to “invite-only” |
TP_BASE_ROOM_CONFIG_LIMIT | corresponds to “limit” |
TP_BASE_ROOM_CONFIG_MODERATED | corresponds to “moderated” |
TP_BASE_ROOM_CONFIG_TITLE | corresponds to “title” |
TP_BASE_ROOM_CONFIG_DESCRIPTION | corresponds to “description” |
TP_BASE_ROOM_CONFIG_PERSISTENT | corresponds to “persistent” |
TP_BASE_ROOM_CONFIG_PRIVATE | corresponds to “private” |
TP_BASE_ROOM_CONFIG_PASSWORD_PROTECTED | corresponds to “password-protected” |
TP_BASE_ROOM_CONFIG_PASSWORD | corresponds to “password” |
TP_BASE_ROOM_CONFIG_PASSWORD_HINT | corresponds to “password-hint” |
TP_NUM_BASE_ROOM_CONFIG_PROPERTIES | the number of configuration properties currently defined. |

### TP_TYPE_BASE_ROOM_CONFIG_PROPERTY

    #define TP_TYPE_BASE_ROOM_CONFIG_PROPERTY (tp_base_room_config_property_get_type ())

The GEnumClass type of TpBaseRoomConfigProperty. (The nicknames are chosen to correspond to unqualified D-Bus property names.)

## Property Details

### The `“anonymous”` property

      “anonymous”                gboolean

True if people may join the channel without other members being made aware of their identity.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: FALSE

### The `“can-update-configuration”` property

      “can-update-configuration” gboolean

If True, the user may call UpdateConfiguration to change the values of the properties listed in MutableProperties.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: FALSE

### The `“channel”` property

      “channel”                  TpBaseChannel *

Parent TpBaseChannel.

Owner: TpBaseRoomConfig

Flags: Read / Write / Construct Only

### The `“configuration-retrieved”` property

      “configuration-retrieved”  gboolean

Becomes True once the room config has been fetched from the network.

Owner: TpBaseRoomConfig

Flags: Read

Default value: FALSE

### The `“description”` property

      “description”              gchar *

A human-readable description of the channel's overall purpose; if any.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: ""

### The `“invite-only”` property

      “invite-only”              gboolean

True if people may not join the channel until they have been invited.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: FALSE

### The `“limit”` property

      “limit”                    guint

The limit to the number of members; or 0 if there is no limit.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: 0

### The `“moderated”` property

      “moderated”                gboolean

True if channel membership is not sufficient to allow participation.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: FALSE

### The `“mutable-properties”` property

      “mutable-properties”       GStrv

A list of (unqualified) property names on this interface which may be modified using UpdateConfiguration (if CanUpdateConfiguration is True). Properties not listed here cannot be modified.

Owner: TpBaseRoomConfig

Flags: Read

### The `“password”` property

      “password”                 gchar *

If PasswordProtected is True, the password required to enter the channel, if known. If the password is unknown, or PasswordProtected is False, the empty string.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: ""

### The `“password-hint”` property

      “password-hint”            gchar *

If PasswordProtected is True, a hint for the password. If the passwordpassword is unknown, or PasswordProtected is False, the empty string.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: ""

### The `“password-protected”` property

      “password-protected”       gboolean

True if contacts joining this channel must provide a password to be granted entry.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: FALSE

### The `“persistent”` property

      “persistent”               gboolean

True if the channel will remain in existence on the server after all members have left it.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: FALSE

### The `“private”` property

      “private”                  gboolean

True if the channel is not visible to non-members.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: FALSE

### The `“title”` property

      “title”                    gchar *

A human-visible name for the channel, if it differs from Room.DRAFT.RoomName; the empty string, otherwise.

Owner: TpBaseRoomConfig

Flags: Read / Write

Default value: ""