telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
#include <telepathy-glib/telepathy-glib.h> TpBaseRoomConfig; struct TpBaseRoomConfigClass; void (*TpBaseRoomConfigUpdateAsync) (TpBaseRoomConfig *self
,GHashTable *validated_properties
,GAsyncReadyCallback callback
,gpointer user_data
); gboolean (*TpBaseRoomConfigUpdateFinish) (TpBaseRoomConfig *self
,GAsyncResult *result
,GError **error
); void tp_base_room_config_register_class (TpBaseChannelClass *base_channel_class
); void tp_base_room_config_iface_init (gpointer g_iface
,gpointer iface_data
); enum TpBaseRoomConfigProperty; #define TP_TYPE_BASE_ROOM_CONFIG_PROPERTY TpBaseChannel * tp_base_room_config_dup_channel (TpBaseRoomConfig *self
); void tp_base_room_config_set_can_update_configuration (TpBaseRoomConfig *self
,gboolean can_update_configuration
); void tp_base_room_config_set_property_mutable (TpBaseRoomConfig *self
,TpBaseRoomConfigProperty property_id
,gboolean is_mutable
); void tp_base_room_config_emit_properties_changed (TpBaseRoomConfig *self
); void tp_base_room_config_set_retrieved (TpBaseRoomConfig *self
);
"anonymous" gboolean : Read / Write "can-update-configuration" gboolean : Read / Write "channel" TpBaseChannel* : Read / Write / Construct Only "configuration-retrieved" gboolean : Read "description" gchar* : Read / Write "invite-only" gboolean : Read / Write "limit" guint : Read / Write "moderated" gboolean : Read / Write "mutable-properties" GStrv : Read "password" gchar* : Read / Write "password-hint" gchar* : Read / Write "password-protected" gboolean : Read / Write "persistent" gboolean : Read / Write "private" gboolean : Read / Write "title" gchar* : Read / Write
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()
.
typedef struct _TpBaseRoomConfig TpBaseRoomConfig;
An object representing the configuration of a multi-user chat room.
There are no public fields.
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.
TpBaseRoomConfigUpdateAsync |
begins a request to modify the room's configuration. |
TpBaseRoomConfigUpdateFinish |
completes a call to update_async ; the default
implementation may be used if update_async uses GSimpleAsyncResult
|
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.
|
a TpBaseRoomConfig |
|
a mapping from TpBaseRoomConfigProperty to GValue, whose types have already been validated. The function should not modify this hash table. |
|
a callback to call on success, failure or disconnection |
|
user data for the callback |
gboolean (*TpBaseRoomConfigUpdateFinish) (TpBaseRoomConfig *self
,GAsyncResult *result
,GError **error
);
Signature for a function to complete a call to a corresponding implementation of TpBaseRoomConfigUpdateAsync.
|
a TpBaseRoomConfig |
|
the result passed to the callback |
|
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. |
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".
|
the class structure for a subclass of TpBaseChannel which uses this object to implement TP_SVC_CHANNEL_INTERFACE_ROOM_CONFIG |
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.
|
a pointer to a TpSvcChannelInterfaceRoomConfigClass structure |
|
ignored |
typedef enum { TP_BASE_ROOM_CONFIG_ANONYMOUS = 0, /*< nick=Anonymous >*/ TP_BASE_ROOM_CONFIG_INVITE_ONLY, /*< nick=InviteOnly >*/ TP_BASE_ROOM_CONFIG_LIMIT, /*< nick=Limit >*/ TP_BASE_ROOM_CONFIG_MODERATED, /*< nick=Moderated >*/ TP_BASE_ROOM_CONFIG_TITLE, /*< nick=Title >*/ TP_BASE_ROOM_CONFIG_DESCRIPTION, /*< nick=Description >*/ TP_BASE_ROOM_CONFIG_PERSISTENT, /*< nick=Persistent >*/ TP_BASE_ROOM_CONFIG_PRIVATE, /*< nick=Private >*/ TP_BASE_ROOM_CONFIG_PASSWORD_PROTECTED, /*< nick=PasswordProtected >*/ TP_BASE_ROOM_CONFIG_PASSWORD, /*< nick=Password >*/ TP_BASE_ROOM_CONFIG_PASSWORD_HINT, /*< nick=PasswordHint >*/ TP_NUM_BASE_ROOM_CONFIG_PROPERTIES /*< skip >*/ } TpBaseRoomConfigProperty;
An enumeration of room configuration fields, corresponding to GObject properties and, in turn, to D-Bus properties.
corresponds to "anonymous" | |
corresponds to "invite-only" | |
corresponds to "limit" | |
corresponds to "moderated" | |
corresponds to "title" | |
corresponds to "description" | |
corresponds to "persistent" | |
corresponds to "private" | |
corresponds to "password-protected" | |
corresponds to "password" | |
corresponds to "password-hint" | |
the number of configuration properties currently defined. |
#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.)
TpBaseChannel * tp_base_room_config_dup_channel (TpBaseRoomConfig *self
);
Returns the channel to which self
is attached.
|
a TpBaseChannel |
Returns : |
the "channel" property. [transfer full] |
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.
|
a TpBaseRoomConfig object. |
|
TRUE if the local user has permission to modify
properties marked as 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.
|
a TpBaseRoomConfig object. |
|
a property identifier (not including
TP_NUM_BASE_ROOM_CONFIG_PROPERTIES ) |
|
TRUE if it is possible for Telepathy clients to modify
property_id when "can-update-configuration" is TRUE . |
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.
|
a TpBaseRoomConfig object. |
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()
.
|
a TpBaseRoomConfig object |
"anonymous"
property "anonymous" gboolean : Read / Write
True if people may join the channel without other members being made aware of their identity.
Default value: FALSE
"can-update-configuration"
property "can-update-configuration" gboolean : Read / Write
If True, the user may call UpdateConfiguration to change the values of the properties listed in MutableProperties.
Default value: FALSE
"channel"
property"channel" TpBaseChannel* : Read / Write / Construct Only
Parent TpBaseChannel.
"configuration-retrieved"
property "configuration-retrieved" gboolean : Read
Becomes True once the room config has been fetched from the network.
Default value: FALSE
"description"
property "description" gchar* : Read / Write
A human-readable description of the channel's overall purpose; if any.
Default value: ""
"invite-only"
property "invite-only" gboolean : Read / Write
True if people may not join the channel until they have been invited.
Default value: FALSE
"limit"
property "limit" guint : Read / Write
The limit to the number of members; or 0 if there is no limit.
Default value: 0
"moderated"
property "moderated" gboolean : Read / Write
True if channel membership is not sufficient to allow participation.
Default value: FALSE
"mutable-properties"
property "mutable-properties" GStrv : Read
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.
"password"
property "password" gchar* : Read / Write
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.
Default value: ""
"password-hint"
property "password-hint" gchar* : Read / Write
If PasswordProtected is True, a hint for the password. If the passwordpassword is unknown, or PasswordProtected is False, the empty string.
Default value: ""
"password-protected"
property "password-protected" gboolean : Read / Write
True if contacts joining this channel must provide a password to be granted entry.
Default value: FALSE
"persistent"
property "persistent" gboolean : Read / Write
True if the channel will remain in existence on the server after all members have left it.
Default value: FALSE
"private"
property "private" gboolean : Read / Write
True if the channel is not visible to non-members.
Default value: FALSE