TpTextMixin

TpTextMixin — a mixin implementation of the text channel type

Synopsis

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

                    TpTextMixin;
                    TpTextMixinClass;
GQuark              tp_text_mixin_class_get_offset_quark
                                                        (void);
GQuark              tp_text_mixin_get_offset_quark      (void);
void                tp_text_mixin_class_init            (GObjectClass *obj_cls,
                                                         glong offset);
void                tp_text_mixin_init                  (GObject *obj,
                                                         glong offset,
                                                         TpHandleRepoIface *contacts_repo);
void                tp_text_mixin_set_message_types     (GObject *obj,
                                                         ...);
void                tp_text_mixin_finalize              (GObject *obj);
gboolean            tp_text_mixin_receive_with_flags    (GObject *obj,
                                                         TpChannelTextMessageType type,
                                                         TpHandle sender,
                                                         time_t timestamp,
                                                         const char *text,
                                                         TpChannelTextMessageFlags flags);
gboolean            tp_text_mixin_receive               (GObject *obj,
                                                         TpChannelTextMessageType type,
                                                         TpHandle sender,
                                                         time_t timestamp,
                                                         const char *text);
gboolean            tp_text_mixin_acknowledge_pending_messages
                                                        (GObject *obj,
                                                         const GArray *ids,
                                                         GError **error);
gboolean            tp_text_mixin_list_pending_messages (GObject *obj,
                                                         gboolean clear,
                                                         GPtrArray **ret,
                                                         GError **error);
gboolean            tp_text_mixin_get_message_types     (GObject *obj,
                                                         GArray **ret,
                                                         GError **error);
void                tp_text_mixin_clear                 (GObject *obj);
gboolean            tp_text_mixin_has_pending_messages  (GObject *obj,
                                                         TpHandle *first_sender);
void                tp_text_mixin_set_rescued           (GObject *obj);
void                tp_text_mixin_iface_init            (gpointer g_iface,
                                                         gpointer iface_data);

Description

This mixin can be added to a channel GObject class to implement the text channel type in a general way. It implements the pending message queue and GetMessageTypes, so the implementation should only need to implement Send.

To use the text mixin, include a TpTextMixinClass somewhere in your class structure and a TpTextMixin somewhere in your instance structure, and call tp_text_mixin_class_init() from your class_init function, tp_text_mixin_init() from your init function or constructor, and tp_text_mixin_finalize() from your dispose or finalize function.

To use the text mixin as the implementation of TpSvcChannelTypeText, in the function you pass to G_IMPLEMENT_INTERFACE, you should first call tp_text_mixin_iface_init(), then call tp_svc_channel_type_text_implement_send() to register your implementation of the Send method.

Details

TpTextMixin

typedef struct {
} TpTextMixin;

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

There are no public fields.


TpTextMixinClass

typedef struct {
} TpTextMixinClass;

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

There are no public fields.


tp_text_mixin_class_get_offset_quark ()

GQuark              tp_text_mixin_class_get_offset_quark
                                                        (void);

Returns :

the quark used for storing mixin offset on a GObjectClass

tp_text_mixin_get_offset_quark ()

GQuark              tp_text_mixin_get_offset_quark      (void);

Returns :

the quark used for storing mixin offset on a GObject

tp_text_mixin_class_init ()

void                tp_text_mixin_class_init            (GObjectClass *obj_cls,
                                                         glong offset);

Initialize the text mixin. Should be called from the implementation's class_init function like so:

1
2
tp_text_mixin_class_init ((GObjectClass *) klass,
                          G_STRUCT_OFFSET (SomeObjectClass, text_mixin));

obj_cls :

The class of the implementation that uses this mixin

offset :

The byte offset of the TpTextMixinClass within the class structure

tp_text_mixin_init ()

void                tp_text_mixin_init                  (GObject *obj,
                                                         glong offset,
                                                         TpHandleRepoIface *contacts_repo);

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

1
2
3
tp_text_mixin_init ((GObject *) self,
                    G_STRUCT_OFFSET (SomeObject, text_mixin),
                    self->contact_repo);

obj :

An instance of the implementation that uses this mixin

offset :

The byte offset of the TpTextMixin within the object structure

contacts_repo :

The connection's TP_HANDLE_TYPE_CONTACT repository

tp_text_mixin_set_message_types ()

void                tp_text_mixin_set_message_types     (GObject *obj,
                                                         ...);

Set the supported message types.

obj :

An object with this mixin

... :

guints representing members of TpChannelTextMessageType, terminated by G_MAXUINT

tp_text_mixin_finalize ()

void                tp_text_mixin_finalize              (GObject *obj);

Free resources held by the text mixin.

obj :

An object with this mixin.

tp_text_mixin_receive_with_flags ()

gboolean            tp_text_mixin_receive_with_flags    (GObject *obj,
                                                         TpChannelTextMessageType type,
                                                         TpHandle sender,
                                                         time_t timestamp,
                                                         const char *text,
                                                         TpChannelTextMessageFlags flags);

Add a message to the pending queue and emit Received.

obj :

An object with the text mixin

type :

The type of message received from the underlying protocol

sender :

The handle of the message sender

timestamp :

The time the message was received

text :

The text of the message

flags :

the message's flags

Returns :

TRUE on success; FALSE if the message was lost due to the memory limit.

tp_text_mixin_receive ()

gboolean            tp_text_mixin_receive               (GObject *obj,
                                                         TpChannelTextMessageType type,
                                                         TpHandle sender,
                                                         time_t timestamp,
                                                         const char *text);

Add a message to the pending queue and emit Received. Exactly equivalent to tp_text_mixin_receive_with_flags() with flags == 0.

obj :

An object with the text mixin

type :

The type of message received from the underlying protocol

sender :

The handle of the message sender

timestamp :

The time the message was received

text :

The text of the message

Returns :

TRUE on success; FALSE if the message was lost due to the memory limit.

tp_text_mixin_acknowledge_pending_messages ()

gboolean            tp_text_mixin_acknowledge_pending_messages
                                                        (GObject *obj,
                                                         const GArray *ids,
                                                         GError **error);

Implements D-Bus method AcknowledgePendingMessages on interface org.freedesktop.Telepathy.Channel.Type.Text

obj :

An object with this mixin

ids :

An array of guint representing message IDs

error :

Used to return a pointer to a GError detailing any error that occurred, D-Bus will throw the error only if this function returns false.

Returns :

TRUE if successful, FALSE if an error was thrown.

tp_text_mixin_list_pending_messages ()

gboolean            tp_text_mixin_list_pending_messages (GObject *obj,
                                                         gboolean clear,
                                                         GPtrArray **ret,
                                                         GError **error);

Implements D-Bus method ListPendingMessages on interface org.freedesktop.Telepathy.Channel.Type.Text

obj :

An object with this mixin

clear :

If TRUE, delete the pending messages from the queue

ret :

Used to return a pointer to a new GPtrArray of D-Bus structures

error :

Used to return a pointer to a GError detailing any error that occurred, D-Bus will throw the error only if this function returns false.

Returns :

TRUE if successful, FALSE if an error was thrown.

tp_text_mixin_get_message_types ()

gboolean            tp_text_mixin_get_message_types     (GObject *obj,
                                                         GArray **ret,
                                                         GError **error);

Return a newly allocated GArray of guint, representing message types taken from TpChannelTextMessageType, through ret.

obj :

An object with this mixin

ret :

A pointer to where a GArray of guint will be placed on success

error :

A pointer to where an error will be placed on failure

Returns :

TRUE on success

tp_text_mixin_clear ()

void                tp_text_mixin_clear                 (GObject *obj);

Clear the pending message queue, deleting all messages.

obj :

An object with this mixin

tp_text_mixin_has_pending_messages ()

gboolean            tp_text_mixin_has_pending_messages  (GObject *obj,
                                                         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.

obj :

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_text_mixin_set_rescued ()

void                tp_text_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_text_mixin_iface_init ()

void                tp_text_mixin_iface_init            (gpointer g_iface,
                                                         gpointer iface_data);

Fill in this mixin's AcknowledgePendingMessages, GetMessageTypes and ListPendingMessages implementations in the given interface vtable. In addition to calling this function during interface initialization, the implementor is expected to call tp_svc_channel_type_text_implement_send(), providing a Send implementation.

g_iface :

A pointer to the TpSvcChannelTypeTextClass in an object class

iface_data :

Ignored

See Also

TpSvcChannelTypeText