## TpTextMixin TpTextMixin — a mixin implementation of the text channel type |

## Synopsis

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

                        TpTextMixin;
    struct              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 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.

### struct TpTextMixinClass

    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