TpTextChannel

## TpTextChannel TpTextChannel — proxy object for a text channel |

## Synopsis

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

    struct              TpTextChannel;
    struct              TpTextChannelClass;
    TpTextChannel *     tp_text_channel_new                 (TpConnection *conn,
                                                             const gchar *object_path,
                                                             const GHashTable *immutable_properties,
                                                             GError **error);
    const gchar * const * tp_text_channel_get_supported_content_types
                                                            (TpTextChannel *self);
    TpMessagePartSupportFlags tp_text_channel_get_message_part_support_flags
                                                            (TpTextChannel *self);
    TpDeliveryReportingSupportFlags tp_text_channel_get_delivery_reporting_support
                                                            (TpTextChannel *self);
    GList *             tp_text_channel_get_pending_messages
                                                            (TpTextChannel *self);
    GList *             tp_text_channel_dup_pending_messages
                                                            (TpTextChannel *self);
    GArray *            tp_text_channel_get_message_types   (TpTextChannel *self);
    #define             TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES
    void                tp_text_channel_send_message_async  (TpTextChannel *self,
                                                             TpMessage *message,
                                                             TpMessageSendingFlags flags,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_text_channel_send_message_finish (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             gchar **token,
                                                             GError **error);
    void                tp_text_channel_ack_messages_async  (TpTextChannel *self,
                                                             const GList *messages,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_text_channel_ack_messages_finish (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_text_channel_ack_message_async   (TpTextChannel *self,
                                                             TpMessage *message,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_text_channel_ack_message_finish  (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_text_channel_ack_all_pending_messages_async
                                                            (TpTextChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_text_channel_ack_all_pending_messages_finish
                                                            (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_text_channel_set_chat_state_async
                                                            (TpTextChannel *self,
                                                             TpChannelChatState state,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_text_channel_set_chat_state_finish
                                                            (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            tp_text_channel_supports_message_type
                                                            (TpTextChannel *self,
                                                             TpChannelTextMessageType message_type);

    #define             TP_TEXT_CHANNEL_FEATURE_SMS
    gboolean            tp_text_channel_is_sms_channel      (TpTextChannel *self);
    gboolean            tp_text_channel_get_sms_flash       (TpTextChannel *self);
    void                tp_text_channel_get_sms_length_async
                                                            (TpTextChannel *self,
                                                             TpMessage *message,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_text_channel_get_sms_length_finish
                                                            (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             guint *chunks_required,
                                                             gint *remaining_characters,
                                                             gint *estimated_cost,
                                                             GError **error);

    #define             TP_TEXT_CHANNEL_FEATURE_CHAT_STATES
    TpChannelChatState  tp_text_channel_get_chat_state      (TpTextChannel *self,
                                                             TpContact *contact);

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpChannel
                   +----TpTextChannel

## Implemented Interfaces

TpTextChannel implements TpChannelIface.

## Properties

      "delivery-reporting-support" guint                 : Read
      "is-sms-channel"           gboolean              : Read
      "message-part-support-flags" guint                 : Read
      "message-types"            GArray_guint_*        : Read
      "sms-flash"                gboolean              : Read
      "supported-content-types"  GStrv                 : Read

## Signals

      "contact-chat-state-changed"                     : Has Details
      "message-received"                               : Run Last
      "message-sent"                                   : Run Last
      "pending-message-removed"                        : Run Last

## Description

TpTextChannel is a sub-class of TpChannel providing convenient API to send and receive TpMessage.

## Details

### struct TpTextChannel

    struct TpTextChannel;

Data structure representing a TpTextChannel.

Since 0.13.10

### struct TpTextChannelClass

    struct TpTextChannelClass {
    };

The class of a TpTextChannel.

Since 0.13.10

### tp_text_channel_new ()

    TpTextChannel *     tp_text_channel_new                 (TpConnection *conn,
                                                             const gchar *object_path,
                                                             const GHashTable *immutable_properties,
                                                             GError **error);

### Warning

`tp_text_channel_new` is deprecated and should not be used in newly-written code. Use `tp_simple_client_factory_ensure_channel()` instead.

Convenient function to create a new TpTextChannel

`conn` : | a TpConnection; may not be `NULL`
`object_path` : | the object path of the channel; may not be `NULL`
`immutable_properties` : | the immutable properties of the channel, as signalled by the NewChannel D-Bus signal or returned by the CreateChannel and EnsureChannel D-Bus methods: a mapping from strings (D-Bus interface name + "." + property name) to GValue instances. [transfer none][element-type utf8 GObject.Value]
`error` : | used to indicate the error if `NULL` is returned
Returns : | a newly created TpTextChannel. [transfer full]

Since 0.13.10

### tp_text_channel_get_supported_content_types ()

    const gchar * const * tp_text_channel_get_supported_content_types
                                                            (TpTextChannel *self);

Return the "supported-content-types" property

`self` : | a TpTextChannel
Returns : | (transfer none) : the value of "supported-content-types"

Since 0.13.10

### tp_text_channel_get_message_part_support_flags ()

    TpMessagePartSupportFlags tp_text_channel_get_message_part_support_flags
                                                            (TpTextChannel *self);

Return the "message-part-support-flags" property

`self` : | a TpTextChannel
Returns : | the value of "message-part-support-flags"

Since 0.13.10

### tp_text_channel_get_delivery_reporting_support ()

    TpDeliveryReportingSupportFlags tp_text_channel_get_delivery_reporting_support
                                                            (TpTextChannel *self);

Return the "delivery-reporting-support" property

`self` : | a TpTextChannel
Returns : | the value of "delivery-reporting-support" property

Since 0.13.10

### tp_text_channel_get_pending_messages ()

    GList *             tp_text_channel_get_pending_messages
                                                            (TpTextChannel *self);

### Warning

`tp_text_channel_get_pending_messages` is deprecated and should not be used in newly-written code. Since 0.19.9. New code should use `tp_text_channel_dup_pending_messages()` instead.

Return a newly allocated list of unacknowledged TpSignalledMessage objects.

It is guaranteed that the "sender" of each TpSignalledMessage has all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

`self` : | a TpTextChannel
Returns : | a GList of borrowed TpSignalledMessage. [transfer container][element-type TelepathyGLib.SignalledMessage]

Since 0.13.10

### tp_text_channel_dup_pending_messages ()

    GList *             tp_text_channel_dup_pending_messages
                                                            (TpTextChannel *self);

Return a newly allocated list of unacknowledged TpSignalledMessage objects.

It is guaranteed that the "sender" of each TpSignalledMessage has all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

`self` : | a TpTextChannel
Returns : | a GList of reffed TpSignalledMessage. [transfer full][element-type TelepathyGLib.SignalledMessage]

Since 0.19.9

### tp_text_channel_get_message_types ()

    GArray *            tp_text_channel_get_message_types   (TpTextChannel *self);

Return the "message-types" property

`self` : | a TpTextChannel
Returns : | the value of "message-types". [transfer none][element-type TelepathyGLib.ChannelTextMessageType]

Since 0.13.16

### TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES

    #define             TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES

Expands to a call to a function that returns a quark representing the incoming messages features of a TpTextChannel.

When this feature is prepared, `tp_text_channel_dup_pending_messages()` will return a non-empty list if any unacknowledged messages are waiting, and the "message-received" and "pending-message-removed" signals will be emitted.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since 0.13.10

### tp_text_channel_send_message_async ()

    void                tp_text_channel_send_message_async  (TpTextChannel *self,
                                                             TpMessage *message,
                                                             TpMessageSendingFlags flags,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Submit a message to the server for sending. Once the message has been submitted to the sever, `callback` will be called. You can then call `tp_text_channel_send_message_finish()` to get the result of the operation.

`self` : | a TpTextChannel
`message` : | a TpClientMessage
`flags` : | flags affecting how the message is sent
`callback` : | a callback to call when the message has been submitted to the server
`user_data` : | data to pass to `callback`

Since 0.13.10

### tp_text_channel_send_message_finish ()

    gboolean            tp_text_channel_send_message_finish (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             gchar **token,
                                                             GError **error);

Completes a call to `tp_text_channel_send_message_async()`.

`token` can be used to match any incoming delivery or failure reports against the sent message. If this function returns true but the returned token is `NULL`, the message was sent successfully but the protocol does not provide a way to identify it later.

`self` : | a TpTextChannel
`result` : | a GAsyncResult passed to the callback for `tp_text_channel_send_message_async()`
`token` : | if not `NULL`, used to return the token of the sent message. [out][transfer full]
`error` : | a GError to fill
Returns : | `TRUE` if the message has been submitted to the server, `FALSE` otherwise.

Since 0.13.10

### tp_text_channel_ack_messages_async ()

    void                tp_text_channel_ack_messages_async  (TpTextChannel *self,
                                                             const GList *messages,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Acknowledge all the messages in `messages`. Once the messages have been acked, `callback` will be called. You can then call `tp_text_channel_ack_messages_finish()` to get the result of the operation.

You should use the TpSignalledMessage received from `tp_text_channel_dup_pending_messages()` or the "message-received" signal.

See `tp_text_channel_ack_message_async()` about acknowledging messages.

`self` : | a TpTextChannel
`messages` : | a GList of TpSignalledMessage. [element-type TelepathyGLib.SignalledMessage]
`callback` : | a callback to call when the message have been acked
`user_data` : | data to pass to `callback`

Since 0.13.10

### tp_text_channel_ack_messages_finish ()

    gboolean            tp_text_channel_ack_messages_finish (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes acknowledging a list of messages.

`self` : | a TpTextChannel
`result` : | a GAsyncResult passed to the callback for `tp_text_channel_ack_messages_async()`
`error` : | a GError to fill
Returns : | `TRUE` if the messages have been acked, `FALSE` otherwise.

Since 0.13.10

### tp_text_channel_ack_message_async ()

    void                tp_text_channel_ack_message_async   (TpTextChannel *self,
                                                             TpMessage *message,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Acknowledge `message`. Once the message has been acked, `callback` will be called. You can then call `tp_text_channel_ack_message_finish()` to get the result of the operation.

A message should be acknowledged once it has been shown to the user by the Handler of the channel. So Observers and Approvers should NOT acknowledge messages themselves. Once a message has been acknowledged, it is removed from the pending-message queue and so the "pending-message-removed" signal is fired.

You should use the TpSignalledMessage received from `tp_text_channel_dup_pending_messages()` or the "message-received" signal.

`self` : | a TpTextChannel
`message` : | a TpSignalledMessage
`callback` : | a callback to call when the message have been acked
`user_data` : | data to pass to `callback`

Since 0.13.10

### tp_text_channel_ack_message_finish ()

    gboolean            tp_text_channel_ack_message_finish  (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes acknowledging a message.

`self` : | a TpTextChannel
`result` : | a GAsyncResult passed to the callback for `tp_text_channel_ack_message_async()`
`error` : | a GError to fill
Returns : | `TRUE` if the message has been acked, `FALSE` otherwise.

Since 0.13.10

### tp_text_channel_ack_all_pending_messages_async ()

    void                tp_text_channel_ack_all_pending_messages_async
                                                            (TpTextChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Acknowledge all the pending messages. This is equivalent of calling `tp_text_channel_ack_messages_async()` with the list of TpSignalledMessage returned by `tp_text_channel_dup_pending_messages()`.

Once the messages have been acked, `callback` will be called. You can then call `tp_text_channel_ack_all_pending_messages_finish()` to get the result of the operation.

See `tp_text_channel_ack_message_async()` about acknowledging messages.

`self` : | a TpTextChannel
`callback` : | a callback to call when the messages have been acked
`user_data` : | data to pass to `callback`

Since 0.15.3

### tp_text_channel_ack_all_pending_messages_finish ()

    gboolean            tp_text_channel_ack_all_pending_messages_finish
                                                            (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finish an asynchronous acknowledgement operation of all messages.

`self` : | a TpTextChannel
`result` : | a GAsyncResult
`error` : | a GError to fill
Returns : | `TRUE` if the messages have been acked, `FALSE` otherwise.

Since 0.15.3

### tp_text_channel_set_chat_state_async ()

    void                tp_text_channel_set_chat_state_async
                                                            (TpTextChannel *self,
                                                             TpChannelChatState state,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Set the local state on channel `self` to `state`. Once the state has been set, `callback` will be called. You can then call `tp_text_channel_set_chat_state_finish()` to get the result of the operation.

`self` : | a TpTextChannel
`state` : | a TpChannelChatState to set
`callback` : | a callback to call when the chat state has been set
`user_data` : | data to pass to `callback`

Since 0.13.10

### tp_text_channel_set_chat_state_finish ()

    gboolean            tp_text_channel_set_chat_state_finish
                                                            (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Completes a call to `tp_text_channel_set_chat_state_async()`.

`self` : | a TpTextChannel
`result` : | a GAsyncResult passed to the callback for `tp_text_channel_set_chat_state_async()`
`error` : | a GError to fill
Returns : | `TRUE` if the chat state has been changed, `FALSE` otherwise.

Since 0.13.10

### tp_text_channel_supports_message_type ()

    gboolean            tp_text_channel_supports_message_type
                                                            (TpTextChannel *self,
                                                             TpChannelTextMessageType message_type);

Check if message of type `message_type` can be sent on this channel.

`self` : | a TpTextChannel
`message_type` : | a TpChannelTextMessageType
Returns : | `TRUE` if message of type `message_type` can be sent on `self`, `FALSE` otherwise

Since 0.13.16

### TP_TEXT_CHANNEL_FEATURE_SMS

    #define             TP_TEXT_CHANNEL_FEATURE_SMS

Expands to a call to a function that returns a quark representing the SMS feature of a TpTextChannel.

When this feature is prepared, the TpTextChannel:is-sms-channel property will have a meaningful value and will be updated when needed.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since 0.15.1

### tp_text_channel_is_sms_channel ()

    gboolean            tp_text_channel_is_sms_channel      (TpTextChannel *self);

Return the "is-sms-channel" property

`self` : | a TpTextChannel
Returns : | the value of "is-sms-channel" property

Since 0.15.1

### tp_text_channel_get_sms_flash ()

    gboolean            tp_text_channel_get_sms_flash       (TpTextChannel *self);

Return the "sms-flash" property

`self` : | a TpTextChannel
Returns : | the value of "sms-flash" property

Since 0.15.1

### tp_text_channel_get_sms_length_async ()

    void                tp_text_channel_get_sms_length_async
                                                            (TpTextChannel *self,
                                                             TpMessage *message,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Starts an async call to get the number of 140 octet chunks required to send a message via SMS on self, as well as the number of remaining characters available in the final chunk and, if possible, an estimate of the cost.

Once the request has been satisfied, `callback` will be called. You can then call `tp_text_channel_get_sms_length_finish()` to get the result of the operation.

`self` : | a TpTextChannel
`message` : | a TpClientMessage
`callback` : | a callback to call when the request has been satisfied
`user_data` : | data to pass to `callback`

Since 0.15.1

### tp_text_channel_get_sms_length_finish ()

    gboolean            tp_text_channel_get_sms_length_finish
                                                            (TpTextChannel *self,
                                                             GAsyncResult *result,
                                                             guint *chunks_required,
                                                             gint *remaining_characters,
                                                             gint *estimated_cost,
                                                             GError **error);

Finishes an async SMS length request.

`self` : | a TpTextChannel
`result` : | a GAsyncResult
`chunks_required` : | if not `NULL` used to return the number of 140 octet chunks required to send the message. [out]
`remaining_characters` : | if not `NULL` used to return the number of further characters that can be fit in the final chunk. A negative value indicates that the message will be truncated by abs(`remaining_characters`). The value G_MININT32 indicates the message will be truncated by an unknown amount. [out]
`estimated_cost` : | if not `NULL` used to return the estimated cost of sending this message. The currency and scale of this value are the same as the values of the "balance-scale" and "balance-currency" properties. A value of -1 indicates the cost could not be estimated. [out]
`error` : | a GError to fill
Returns : | `TRUE` if the number of 140 octet chunks required to send the message has been retrieved, `FALSE` otherwise.

Since 0.15.1

### TP_TEXT_CHANNEL_FEATURE_CHAT_STATES

    #define             TP_TEXT_CHANNEL_FEATURE_CHAT_STATES

Expands to a call to a function that returns a quark representing the chat states feature on a TpTextChannel.

When this feature is prepared, `tp_text_channel_get_chat_state()` and the "contact-chat-state-changed" signal become useful.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since 0.19.0

### tp_text_channel_get_chat_state ()

    TpChannelChatState  tp_text_channel_get_chat_state      (TpTextChannel *self,
                                                             TpContact *contact);

Return the chat state for the given contact. If `tp_proxy_is_prepared()` would return `FALSE` for the feature `TP_TEXT_CHANNEL_FEATURE_CHAT_STATES`, the result will always be `TP_CHANNEL_CHAT_STATE_INACTIVE`.

`self` : | a channel
`contact` : | a TpContact
Returns : | the chat state for `contact`, or `TP_CHANNEL_CHAT_STATE_INACTIVE` if their chat state is not known

Since 0.19.0

## Property Details

### The `"delivery-reporting-support"` property

      "delivery-reporting-support" guint                 : Read

A TpDeliveryReportingSupportFlags indicating features supported by this channel.

Default value: 0

Since 0.13.10

### The `"is-sms-channel"` property

      "is-sms-channel"           gboolean              : Read

`TRUE` if messages sent and received on this channel are transmitted via SMS.

This property is not guaranteed to have a meaningful value until TP_TEXT_CHANNEL_FEATURE_SMS has been prepared.

Default value: FALSE

Since 0.15.1

### The `"message-part-support-flags"` property

      "message-part-support-flags" guint                 : Read

A TpMessagePartSupportFlags indicating the level of support for message parts on this channel.

Default value: 0

Since 0.13.10

### The `"message-types"` property

      "message-types"            GArray_guint_*        : Read

A GArray containing the TpChannelTextMessageType which may be sent on this channel.

Since 0.13.16

### The `"sms-flash"` property

      "sms-flash"                gboolean              : Read

`TRUE` if this channel is exclusively for receiving class 0 SMSes (and no SMSes can be sent using `tp_text_channel_send_message_async()` on this channel). If `FALSE`, no incoming class 0 SMSes will appear on this channel.

Default value: FALSE

Since 0.15.1

### The `"supported-content-types"` property

      "supported-content-types"  GStrv                 : Read

A GStrv containing the MIME types supported by this channel, with more preferred MIME types appearing earlier in the array.

Since 0.13.10

## Signal Details

### The `"contact-chat-state-changed"` signal

    void                user_function                      (TpTextChannel *self,
                                                            TpContact     *contact,
                                                            guint          state,
                                                            gpointer       user_data)      : Has Details

Emitted when a contact's chat state changes after `tp_proxy_prepare_async()` has finished preparing features `TP_TEXT_CHANNEL_FEATURE_CHAT_STATES`, `TP_CHANNEL_FEATURE_GROUP` and `TP_CHANNEL_FEATURE_CONTACTS`.

`self` : | a channel
`contact` : | a TpContact for the local user or another contact
`state` : | the new TpChannelChatState for the contact
`user_data` : | user data set when the signal handler was connected.

Since 0.19.0

### The `"message-received"` signal

    void                user_function                      (TpTextChannel      *self,
                                                            TpSignalledMessage *message,
                                                            gpointer            user_data)      : Run Last

The ::message-received signal is emitted when a new message has been received on `self`.

The same `message` object will be used by the "pending-message-removed" signal once `message` has been acked so you can simply compare pointers to identify the message.

Note that this signal is only fired once the TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES has been prepared.

It is guaranteed that `message`'s "sender" has all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

`self` : | the TpTextChannel
`message` : | a TpSignalledMessage
`user_data` : | user data set when the signal handler was connected.

Since 0.13.10

### The `"message-sent"` signal

    void                user_function                      (TpTextChannel      *self,
                                                            TpSignalledMessage *message,
                                                            guint               flags,
                                                            gchar              *token,
                                                            gpointer            user_data)      : Run Last

The ::message-sent signal is emitted when `message` has been submitted for sending.

It is guaranteed that `message`'s "sender" has all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

`self` : | the TpTextChannel
`message` : | a TpSignalledMessage
`flags` : | the TpMessageSendingFlags affecting how the message was sent
`token` : | an opaque token used to match any incoming delivery or failure reports against this message, or `NULL` if the message is not readily identifiable.
`user_data` : | user data set when the signal handler was connected.

Since 0.13.10

### The `"pending-message-removed"` signal

    void                user_function                      (TpTextChannel      *self,
                                                            TpSignalledMessage *message,
                                                            gpointer            user_data)      : Run Last

The ::pending-message-removed signal is emitted when `message` has been acked and so removed from the pending messages list.

Note that this signal is only fired once the TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES has been prepared.

It is guaranteed that `message`'s "sender" has all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

`self` : | the TpTextChannel
`message` : | a TpSignalledMessage
`user_data` : | user data set when the signal handler was connected.

Since 0.13.10