TpTextChannel

TpTextChannel — proxy object for a text channel

Functions

Properties

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

Signals

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

Types and Values

Object Hierarchy

    GObject
    ╰── TpProxy
        ╰── TpChannel
            ╰── TpTextChannel

Implemented Interfaces

TpTextChannel implements TpChannelIface.

Includes

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

Description

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

Functions

tp_text_channel_new ()

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

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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);

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.

Parameters

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.

Parameters

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

Parameters

self

a TpTextChannel

 

Returns

the value of “message-types”.

[transfer none][element-type TelepathyGLib.ChannelTextMessageType]

Since: 0.13.16


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

gboolean
tp_text_channel_is_sms_channel (TpTextChannel *self);

Return the “is-sms-channel” property

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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_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.

Parameters

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

Types and Values

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_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_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_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

Property Details

The “delivery-reporting-support” property

  “delivery-reporting-support” guint

A TpDeliveryReportingSupportFlags indicating features supported by this channel.

Owner: TpTextChannel

Flags: Read

Default value: 0

Since: 0.13.10


The “is-sms-channel” property

  “is-sms-channel”           gboolean

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.

Owner: TpTextChannel

Flags: Read

Default value: FALSE

Since: 0.15.1


The “message-part-support-flags” property

  “message-part-support-flags” guint

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

Owner: TpTextChannel

Flags: Read

Default value: 0

Since: 0.13.10


The “message-types” property

  “message-types”            GArray_guint_ *

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

Owner: TpTextChannel

Flags: Read

Since: 0.13.16


The “sms-flash” property

  “sms-flash”                gboolean

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.

Owner: TpTextChannel

Flags: Read

Default value: FALSE

Since: 0.15.1


The “supported-content-types” property

  “supported-content-types”  GStrv

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

Owner: TpTextChannel

Flags: Read

Since: 0.13.10

Signal Details

The “contact-chat-state-changed” signal

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

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.

Parameters

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.

 

Flags: Has Details

Since: 0.19.0


The “message-received” signal

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

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.

Parameters

self

the TpTextChannel

 

message

a TpSignalledMessage

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.13.10


The “message-sent” signal

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

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.

Parameters

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.

 

Flags: Run Last

Since: 0.13.10


The “pending-message-removed” signal

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

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.

Parameters

self

the TpTextChannel

 

message

a TpSignalledMessage

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.13.10