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

Object Hierarchy

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

Implemented Interfaces

TpTextChannel implements TpChannelIface.

Properties

  "delivery-reporting-support" guint                 : Read
  "message-part-support-flags" guint                 : Read
  "message-types"            GArray_guint_*        : Read
  "supported-content-types"  GStrv                 : Read

Signals

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

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

Return a newly allocated list of unacknowledged TpSignalledMessage objects.

self :

a TpTextChannel

Returns :

a GList of borrowed TpSignalledMessage. [transfer container][element-type TelepathyGLib.SignalledMessage]

Since 0.13.10


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

Finishes to send a message.

token can be used to match any incoming delivery or failure reports against the sent message. If the returned token is NULL the message is not readily identifiable.

self :

a TpTextChannel

result :

a GAsyncResult

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.

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 to ack a list of messages.

self :

a TpTextChannel

result :

a GAsyncResult

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.

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 to ack a message.

self :

a TpTextChannel

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the message has been acked, FALSE otherwise.

Since 0.13.10


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

Finishes to set chat state.

self :

a TpTextChannel

result :

a GAsyncResult

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

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

Note that this signal is only fired once the TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES has been 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.

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.

self :

the TpTextChannel

message :

a TpSignalledMessage

user_data :

user data set when the signal handler was connected.

Since 0.13.10