TpMessageMixin

TpMessageMixin — a mixin implementation of the text channel type and the Messages interface

Synopsis

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

struct              TpMessageMixin;
void                (*TpMessageMixinSendImpl)           (GObject *object,
                                                         TpMessage *message,
                                                         TpMessageSendingFlags flags);
void                tp_message_mixin_finalize           (GObject *obj);
void                tp_message_mixin_implement_sending  (GObject *object,
                                                         TpMessageMixinSendImpl send,
                                                         guint n_types,
                                                         const TpChannelTextMessageType *types,
                                                         TpMessagePartSupportFlags message_part_support_flags,
                                                         TpDeliveryReportingSupportFlags delivery_reporting_support_flags,
                                                         const gchar * const *supported_content_types);
void                tp_message_mixin_init               (GObject *obj,
                                                         gsize offset,
                                                         TpBaseConnection *connection);
void                tp_message_mixin_init_dbus_properties
                                                        (GObjectClass *cls);
void                tp_message_mixin_messages_iface_init
                                                        (gpointer g_iface,
                                                         gpointer iface_data);
void                tp_message_mixin_get_dbus_property  (GObject *object,
                                                         GQuark interface,
                                                         GQuark name,
                                                         GValue *value,
                                                         gpointer unused);
void                tp_message_mixin_sent               (GObject *object,
                                                         TpMessage *message,
                                                         TpMessageSendingFlags flags,
                                                         const gchar *token,
                                                         const GError *error);
void                tp_message_mixin_set_rescued        (GObject *obj);
guint               tp_message_mixin_take_received      (GObject *object,
                                                         TpMessage *message);
gboolean            tp_message_mixin_has_pending_messages
                                                        (GObject *object,
                                                         TpHandle *first_sender);
void                tp_message_mixin_clear              (GObject *obj);
void                tp_message_mixin_text_iface_init    (gpointer g_iface,
                                                         gpointer iface_data);

gboolean            (*TpMessageMixinSendChatStateImpl)  (GObject *object,
                                                         TpChannelChatState state,
                                                         GError **error);
void                tp_message_mixin_chat_state_iface_init
                                                        (gpointer g_iface,
                                                         gpointer iface_data);
void                tp_message_mixin_change_chat_state  (GObject *object,
                                                         TpHandle member,
                                                         TpChannelChatState state);
void                tp_message_mixin_implement_send_chat_state
                                                        (GObject *object,
                                                         TpMessageMixinSendChatStateImpl send_chat_state);
void                tp_message_mixin_maybe_send_gone    (GObject *object);

Description

This mixin can be added to a channel GObject class to implement the text channel type (with the Messages interface) in a general way. The channel class should also have a TpDBusPropertiesMixinClass.

To use the messages mixin, include a TpMessageMixin somewhere in your instance structure, and call tp_message_mixin_init() from your constructor function, and tp_message_mixin_finalize() from your dispose or finalize function. In the class_init function, call tp_message_mixin_init_dbus_properties() to hook this mixin into the D-Bus properties mixin class. Finally, include the following in the fourth argument of G_DEFINE_TYPE_WITH_CODE(): 

1
2
3
4
 
G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CHANNEL_TYPE_TEXT,
  tp_message_mixin_text_iface_init);
G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CHANNEL_INTERFACE_MESSAGES,
  tp_message_mixin_messages_iface_init);

To support sending messages, you must call tp_message_mixin_implement_sending() in the constructor function. If you do not, any attempt to send a message will fail with NotImplemented.

To support chat state, you must call tp_message_mixin_implement_send_chat_state() in the constructor function, and include the following in the fourth argument of G_DEFINE_TYPE_WITH_CODE(): 

1
2
 
G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CHANNEL_INTERFACE_CHAT_STATE,
  tp_message_mixin_chat_state_iface_init);

Details

struct TpMessageMixin

struct TpMessageMixin {
};

Structure to be included in the instance structure of objects that use this mixin. Initialize it with tp_message_mixin_init().

There are no public fields.

Since 0.7.21

TpMessageMixinSendImpl ()

void                (*TpMessageMixinSendImpl)           (GObject *object,
                                                         TpMessage *message,
                                                         TpMessageSendingFlags flags);

Signature of a virtual method which may be implemented to allow messages to be sent. It must arrange for tp_message_mixin_sent() to be called when the message has submitted or when message submission has failed.

object :

 An instance of the implementation that uses this mixin

message :

 An outgoing message

flags :

 flags with which to send the message

tp_message_mixin_finalize ()

void                tp_message_mixin_finalize           (GObject *obj);

Free resources held by the text mixin.

obj :

 An object with this mixin.

Since 0.7.21

tp_message_mixin_implement_sending ()

void                tp_message_mixin_implement_sending  (GObject *object,
                                                         TpMessageMixinSendImpl send,
                                                         guint n_types,
                                                         const TpChannelTextMessageType *types,
                                                         TpMessagePartSupportFlags message_part_support_flags,
                                                         TpDeliveryReportingSupportFlags delivery_reporting_support_flags,
                                                         const gchar * const *supported_content_types);

Set the callback used to implement SendMessage, and the types of message that can be sent. This must be called from the init, constructor or constructed callback, after tp_message_mixin_init(), and may only be called once per object.

object :

 An instance of the implementation that uses this mixin

send :

 An implementation of SendMessage()

n_types :

 Number of supported message types

types :

 n_types supported message types

message_part_support_flags :

 Flags indicating what message part structures are supported

delivery_reporting_support_flags :

 Flags indicating what kind of delivery reports are supported

supported_content_types :

 The supported content types

Since 0.7.21

tp_message_mixin_init ()

void                tp_message_mixin_init               (GObject *obj,
                                                         gsize offset,
                                                         TpBaseConnection *connection);

Initialize the mixin. Should be called from the implementation's instance init function or constructor like so: 

1
2
3
 
tp_message_mixin_init ((GObject *) self,
    G_STRUCT_OFFSET (SomeObject, message_mixin),
    self->connection);

obj :

 An instance of the implementation that uses this mixin

offset :

 The byte offset of the TpMessageMixin within the object structure

connection :

 A TpBaseConnection

Since 0.7.21

tp_message_mixin_init_dbus_properties ()

void                tp_message_mixin_init_dbus_properties
                                                        (GObjectClass *cls);

Set up a TpDBusPropertiesMixinClass to use this mixin's implementation of the Messages interface's properties.

This uses tp_message_mixin_get_dbus_property() as the property getter and sets a list of the supported properties for it.

cls :

 The class of an object with this mixin

tp_message_mixin_messages_iface_init ()

void                tp_message_mixin_messages_iface_init
                                                        (gpointer g_iface,
                                                         gpointer iface_data);

Fill in this mixin's Messages method implementations in the given interface vtable.

g_iface :

 A pointer to the TpSvcChannelInterfaceMessagesClass in an object class

iface_data :

 Ignored

Since 0.7.21

tp_message_mixin_get_dbus_property ()

void                tp_message_mixin_get_dbus_property  (GObject *object,
                                                         GQuark interface,
                                                         GQuark name,
                                                         GValue *value,
                                                         gpointer unused);

An implementation of TpDBusPropertiesMixinGetter which assumes that the object has the messages mixin. It can only be used for the Messages interface.

object :

 An object with this mixin

interface :

 Must be TP_IFACE_QUARK_CHANNEL_INTERFACE_MESSAGES

name :

 A quark representing the D-Bus property name, either "PendingMessages", "SupportedContentTypes" or "MessagePartSupportFlags"

value :

 A GValue pre-initialized to the right type, into which to put the value

unused :

 Ignored

tp_message_mixin_sent ()

void                tp_message_mixin_sent               (GObject *object,
                                                         TpMessage *message,
                                                         TpMessageSendingFlags flags,
                                                         const gchar *token,
                                                         const GError *error);

Indicate to the message mixin that message submission to the IM server has succeeded or failed. This should be called as soon as the CM determines it's theoretically possible to send the message (e.g. the parameters are supported and correct).

After this function is called, message will have been freed, and must not be dereferenced.

object :

 An object implementing the Text and Messages interfaces with this mixin

message :

 The outgoing message

flags :

 The flags used when sending the message, which may be a subset of those passed to the TpMessageMixinSendImpl implementation if not all are supported, or 0 on error.

token :

 A token representing the sent message (see the Telepathy D-Bus API specification), or an empty string if no suitable identifier is available, or NULL on error

error :

 NULL on success, or the error with which message submission failed

Since 0.7.21

tp_message_mixin_set_rescued ()

void                tp_message_mixin_set_rescued        (GObject *obj);

Mark all pending messages as having been "rescued" from a channel that previously closed.

obj :

 An object with this mixin

tp_message_mixin_take_received ()

guint               tp_message_mixin_take_received      (GObject *object,
                                                         TpMessage *message);

Receive a message into the pending messages queue, where it will stay until acknowledged, and emit the Received and ReceivedMessage signals. Also emit the SendError signal if the message is a failed delivery report.

object :

 a channel with this mixin

message :

 the message. Its ownership is claimed by the message mixin, so it must no longer be modified or freed

Returns :

 the message ID

Since 0.7.21

tp_message_mixin_has_pending_messages ()

gboolean            tp_message_mixin_has_pending_messages
                                                        (GObject *object,
                                                         TpHandle *first_sender);

Return whether the channel obj has unacknowledged messages. If so, and first_sender is not NULL, the handle of the sender of the first message is placed in it, without incrementing the handle's reference count.

object :

 An object with this mixin

first_sender :

 If not NULL, used to store the sender of the oldest pending message

Returns :

 TRUE if there are pending messages

tp_message_mixin_clear ()

void                tp_message_mixin_clear              (GObject *obj);

Clear the pending message queue, deleting all messages without emitting PendingMessagesRemoved.

obj :

 An object with this mixin

tp_message_mixin_text_iface_init ()

void                tp_message_mixin_text_iface_init    (gpointer g_iface,
                                                         gpointer iface_data);

Fill in this mixin's Text method implementations in the given interface vtable.

g_iface :

 A pointer to the TpSvcChannelTypeTextClass in an object class

iface_data :

 Ignored

Since 0.7.21

TpMessageMixinSendChatStateImpl ()

gboolean            (*TpMessageMixinSendChatStateImpl)  (GObject *object,
                                                         TpChannelChatState state,
                                                         GError **error);

Signature of a virtual method which may be implemented to allow sending chat state.

object :

 an instance of the implementation that uses this mixin

state :

 a TpChannelChatState to be send

error :

 a GError to fill

Returns :

 TRUE on success, FALSE otherwise.

Since 0.19.0

tp_message_mixin_chat_state_iface_init ()

void                tp_message_mixin_chat_state_iface_init
                                                        (gpointer g_iface,
                                                         gpointer iface_data);

Fill in this mixin's ChatState method implementations in the given interface vtable.

g_iface :

 A pointer to the TpSvcChannelInterfaceChatStateClass in an object class

iface_data :

 Ignored

Since 0.19.0

tp_message_mixin_change_chat_state ()

void                tp_message_mixin_change_chat_state  (GObject *object,
                                                         TpHandle member,
                                                         TpChannelChatState state);

Change the current chat state of member to be state. This emits ChatStateChanged signal and update ChatStates property.

object :

 an instance of the implementation that uses this mixin

member :

 a member of this chat

state :

 the new state to set

Since 0.19.0

tp_message_mixin_implement_send_chat_state ()

void                tp_message_mixin_implement_send_chat_state
                                                        (GObject *object,
                                                         TpMessageMixinSendChatStateImpl send_chat_state);

Set the callback used to implement SetChatState. This must be called from the init, constructor or constructed callback, after tp_message_mixin_init(), and may only be called once per object.

object :

 an instance of the implementation that uses this mixin

send_chat_state :

 send our chat state

Since 0.19.0

tp_message_mixin_maybe_send_gone ()

void                tp_message_mixin_maybe_send_gone    (GObject *object);

Send TP_CHANNEL_CHAT_STATE_GONE if needed. This should be called on private chats when channel is closed.

object :

 An instance of the implementation that uses this mixin

Since 0.19.0

See Also

TpSvcChannelTypeText, TpSvcChannelInterfaceMessages, TpDBusPropertiesMixin
Generated by GTK-Doc V1.19