|
|
|
telepathy-glib Reference Manual | |
|---|---|---|---|---|
TpMessageMixinTpMessageMixin — a mixin implementation of the text channel type and the Messages interface |
#include <telepathy-glib/message-mixin.h>
TpMessage;
guint tp_message_append_part (TpMessage *self);
guint tp_message_count_parts (TpMessage *self);
gboolean tp_message_delete_key (TpMessage *self,
guint part,
const gchar *key);
void tp_message_delete_part (TpMessage *self,
guint part);
void tp_message_destroy (TpMessage *self);
TpMessage* tp_message_new (TpBaseConnection *connection,
guint initial_parts,
guint size_hint);
const GHashTable* tp_message_peek (TpMessage *self,
guint part);
void tp_message_ref_handle (TpMessage *self,
TpHandleType handle_type,
TpHandle handle);
void tp_message_set (TpMessage *self,
guint part,
const gchar *key,
const GValue *source);
void tp_message_set_boolean (TpMessage *self,
guint part,
const gchar *key,
gboolean b);
void tp_message_set_bytes (TpMessage *self,
guint part,
const gchar *key,
guint len,
gconstpointer bytes);
void tp_message_set_handle (TpMessage *self,
guint part,
const gchar *key,
TpHandleType handle_type,
TpHandle handle_or_0);
#define tp_message_set_int16 (s, p, k, i)
void tp_message_set_int32 (TpMessage *self,
guint part,
const gchar *key,
gint32 i);
void tp_message_set_int64 (TpMessage *self,
guint part,
const gchar *key,
gint64 i);
void tp_message_set_string (TpMessage *self,
guint part,
const gchar *key,
const gchar *s);
void tp_message_set_string_printf (TpMessage *self,
guint part,
const gchar *key,
const gchar *fmt,
...);
#define tp_message_set_uint16 (s, p, k, u)
void tp_message_set_uint32 (TpMessage *self,
guint part,
const gchar *key,
guint32 u);
void tp_message_set_uint64 (TpMessage *self,
guint part,
const gchar *key,
guint64 u);
void tp_message_take_message (TpMessage *self,
guint part,
const gchar *key,
TpMessage *message);
TpMessageMixin;
void (*TpMessageMixinSendImpl) (GObject *object,
TpMessage *message,
TpMessageSendingFlags flags);
void tp_message_mixin_finalize (GObject *obj);
void tp_message_mixin_implement_sending (GObject *object,
TpMessageMixinSendImpl send,
guint n_types,
const TpChannelTextMessageType *types,
TpMessagePartSupportFlags message_part_support_flags,
TpDeliveryReportingSupportFlags delivery_reporting_support_flags,
const gchar * const *supported_content_types);
void tp_message_mixin_init (GObject *obj,
gsize offset,
TpBaseConnection *connection);
void tp_message_mixin_init_dbus_properties
(GObjectClass *cls);
void tp_message_mixin_messages_iface_init
(gpointer g_iface,
gpointer iface_data);
void tp_message_mixin_get_dbus_property (GObject *object,
GQuark interface,
GQuark name,
GValue *value,
gpointer unused);
void tp_message_mixin_sent (GObject *object,
TpMessage *message,
TpMessageSendingFlags flags,
const gchar *token,
const GError *error);
void tp_message_mixin_set_rescued (GObject *obj);
guint tp_message_mixin_take_received (GObject *object,
TpMessage *message);
gboolean tp_message_mixin_has_pending_messages
(GObject *object,
TpHandle *first_sender);
void tp_message_mixin_clear (GObject *obj);
void tp_message_mixin_text_iface_init (gpointer g_iface,
gpointer iface_data);
This mixin can be added to a channel GObject class to implement the text channel type (with the Messages interface) in a general way. The channel class should also have a TpDBusPropertiesMixinClass.
To use the messages mixin, include a TpMessageMixin somewhere in your
instance structure, and call tp_message_mixin_init() from your
constructor function, and tp_message_mixin_finalize() from your dispose
or finalize function. In the class_init function, call
tp_message_mixin_init_dbus_properties() to hook this mixin into the D-Bus
properties mixin class. Finally, include the following in the fourth
argument of G_DEFINE_TYPE_WITH_CODE():
G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CHANNEL_TYPE_TEXT, tp_message_mixin_text_iface_init); G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CHANNEL_INTERFACE_MESSAGES, tp_message_mixin_messages_iface_init);
To support sending messages, you must call
tp_message_mixin_implement_sending() in the constructor function. If you do
not, any attempt to send a message will fail with NotImplemented.
since 0.7.21
typedef struct _TpMessage TpMessage;
Opaque structure representing a message in the Telepathy messages interface (an array of at least one mapping from string to variant, where the first mapping contains message headers and subsequent mappings contain the message body).
guint tp_message_append_part (TpMessage *self);
Append a body part to the message.
self : |
a message |
| Returns : | the part number
since 0.7.21
|
guint tp_message_count_parts (TpMessage *self);
self : |
a message |
| Returns : | the number of parts in the message, including the headers in
part 0
since 0.7.21
|
gboolean tp_message_delete_key (TpMessage *self, guint part, const gchar *key);
Remove the given key and its value from the given part.
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
| Returns : | TRUE if the key previously existed
since 0.7.21
|
void tp_message_delete_part (TpMessage *self, guint part);
Delete the given body part from the message.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly greater than 0, and strictly
less than the number returned by tp_message_count_parts()
|
void tp_message_destroy (TpMessage *self);
Destroy self.
since 0.7.21
self : |
a message |
TpMessage* tp_message_new (TpBaseConnection *connection, guint initial_parts, guint size_hint);
connection : |
a connection on which to reference handles |
initial_parts : |
number of parts to create (at least 1) |
size_hint : |
preallocate space for this many parts (at least initial_parts)
|
| Returns : | a newly allocated message suitable to be passed to
tp_message_mixin_take_received
since 0.7.21
|
const GHashTable* tp_message_peek (TpMessage *self, guint part);
self : |
a message |
part : |
a part number |
| Returns : | the GHashTable used to implement the given part, or NULL if the
part number is out of range. The hash table is only valid as long as the
message is valid and the part is not deleted.
since 0.7.21
|
void tp_message_ref_handle (TpMessage *self, TpHandleType handle_type, TpHandle handle);
Reference the given handle until this message is destroyed.
since 0.7.21
self : |
a message |
handle_type : |
a handle type, greater than TP_HANDLE_TYPE_NONE and less than
NUM_TP_HANDLE_TYPES
|
handle : |
a handle of the given type |
void tp_message_set (TpMessage *self, guint part, const gchar *key, const GValue *source);
Set key in part part of self to have a copy of source as its value.
If source represents a data structure containing handles, they should
all be referenced with tp_message_ref_handle() first.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
source : |
a value |
void tp_message_set_boolean (TpMessage *self, guint part, const gchar *key, gboolean b);
Set key in part part of self to have b as a boolean value.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
b : |
a boolean value |
void tp_message_set_bytes (TpMessage *self, guint part, const gchar *key, guint len, gconstpointer bytes);
Set key in part part of self to have bytes as a byte-array value.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
len : |
a number of bytes |
bytes : |
an array of len bytes
|
void tp_message_set_handle (TpMessage *self, guint part, const gchar *key, TpHandleType handle_type, TpHandle handle_or_0);
If handle_or_0 is not zero, reference it with tp_message_ref_handle().
Set key in part part of self to have handle_or_0 as an unsigned integer
value.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
handle_type : |
a handle type |
handle_or_0 : |
a handle of that type, or 0 |
#define tp_message_set_int16(s, p, k, i)
Set key in part part of self to have i as a signed integer value.
since 0.7.21
s : |
a message |
p : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
k : |
a key in the mapping representing the part |
i : |
an integer value |
void tp_message_set_int32 (TpMessage *self, guint part, const gchar *key, gint32 i);
Set key in part part of self to have i as a signed integer value.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
i : |
an integer value |
void tp_message_set_int64 (TpMessage *self, guint part, const gchar *key, gint64 i);
Set key in part part of self to have i as a signed integer value.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
i : |
an integer value |
void tp_message_set_string (TpMessage *self, guint part, const gchar *key, const gchar *s);
Set key in part part of self to have s as a string value.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
s : |
a string value |
void tp_message_set_string_printf (TpMessage *self, guint part, const gchar *key, const gchar *fmt, ...);
Set key in part part of self to have a string value constructed from a
printf-style format string.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
fmt : |
a printf-style format string for the string value |
... : |
arguments for the format string |
#define tp_message_set_uint16(s, p, k, u)
Set key in part part of self to have u as an unsigned integer value.
since 0.7.21
s : |
a message |
p : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
k : |
a key in the mapping representing the part |
u : |
an unsigned integer value |
void tp_message_set_uint32 (TpMessage *self, guint part, const gchar *key, guint32 u);
Set key in part part of self to have u as an unsigned integer value.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
u : |
an unsigned integer value |
void tp_message_set_uint64 (TpMessage *self, guint part, const gchar *key, guint64 u);
Set key in part part of self to have u as an unsigned integer value.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
u : |
an unsigned integer value |
void tp_message_take_message (TpMessage *self, guint part, const gchar *key, TpMessage *message);
Set key in part part of self to have message as an aa{sv} value (that
is, an array of Message_Part), and take ownership of message. The caller
should not use message after passing it to this function. All handle
references owned by message will subsequently belong to and be released
with self.
since 0.7.21
self : |
a message |
part : |
a part number, which must be strictly less than the number
returned by tp_message_count_parts()
|
key : |
a key in the mapping representing the part |
message : |
another (distinct) message created for the same TpBaseConnection |
typedef struct {
} TpMessageMixin;
Structure to be included in the instance structure of objects that
use this mixin. Initialize it with tp_message_mixin_init().
There are no public fields.
since 0.7.21
void (*TpMessageMixinSendImpl) (GObject *object, TpMessage *message, TpMessageSendingFlags flags);
Signature of a virtual method which may be implemented to allow messages
to be sent. It must arrange for tp_message_mixin_sent() to be called when
the message has submitted or when message submission has failed.
object : |
An instance of the implementation that uses this mixin |
message : |
An outgoing message |
flags : |
flags with which to send the message |
void tp_message_mixin_finalize (GObject *obj);
Free resources held by the text mixin.
since 0.7.21
obj : |
An object with this mixin. |
void tp_message_mixin_implement_sending (GObject *object, TpMessageMixinSendImpl send, guint n_types, const TpChannelTextMessageType *types, TpMessagePartSupportFlags message_part_support_flags, TpDeliveryReportingSupportFlags delivery_reporting_support_flags, const gchar * const *supported_content_types);
Set the callback used to implement SendMessage, and the types of message
that can be sent. This must be called from the init, constructor or
constructed callback, after tp_message_mixin_init(), and may only be called
once per object.
since 0.7.21
object : |
An instance of the implementation that uses this mixin |
send : |
An implementation of SendMessage()
|
n_types : |
Number of supported message types |
types : |
n_types supported message types
|
message_part_support_flags : |
Flags indicating what message part structures are supported |
delivery_reporting_support_flags : |
Flags indicating what kind of delivery reports are supported |
supported_content_types : |
The supported content types |
void tp_message_mixin_init (GObject *obj, gsize offset, TpBaseConnection *connection);
Initialize the mixin. Should be called from the implementation's instance init function or constructor like so:
tp_message_mixin_init ((GObject *) self,
G_STRUCT_OFFSET (SomeObject, message_mixin),
self->connection);
since 0.7.21
obj : |
An instance of the implementation that uses this mixin |
offset : |
The byte offset of the TpMessageMixin within the object structure |
connection : |
A TpBaseConnection |
void tp_message_mixin_init_dbus_properties
(GObjectClass *cls);
Set up a TpDBusPropertiesMixinClass to use this mixin's implementation of the Messages interface's properties.
This uses tp_message_mixin_get_dbus_property() as the property getter
and sets a list of the supported properties for it.
cls : |
The class of an object with this mixin |
void tp_message_mixin_messages_iface_init
(gpointer g_iface,
gpointer iface_data);
Fill in this mixin's Messages method implementations in the given interface vtable.
since 0.7.21
g_iface : |
A pointer to the TpSvcChannelInterfaceMessagesClass in an object class |
iface_data : |
Ignored |
void tp_message_mixin_get_dbus_property (GObject *object, GQuark interface, GQuark name, GValue *value, gpointer unused);
An implementation of TpDBusPropertiesMixinGetter which assumes that
the object has the messages mixin. It can only be used for the Messages
interface.
object : |
An object with this mixin |
interface : |
Must be TP_IFACE_QUARK_CHANNEL_INTERFACE_MESSAGES
|
name : |
A quark representing the D-Bus property name, either "PendingMessages", "SupportedContentTypes" or "MessagePartSupportFlags" |
value : |
A GValue pre-initialized to the right type, into which to put the value |
unused : |
Ignored |
void tp_message_mixin_sent (GObject *object, TpMessage *message, TpMessageSendingFlags flags, const gchar *token, const GError *error);
Indicate to the message mixin that message submission to the IM server has succeeded or failed.
After this function is called, message will have been freed, and must not
be dereferenced.
since 0.7.21
object : |
An object implementing the Text and Messages interfaces with this mixin |
message : |
The outgoing message |
flags : |
The flags used when sending the message, which may be a subset of
those passed to the TpMessageMixinSendImpl implementation if not all are
supported, or 0 on error.
|
token : |
A token representing the sent message (see the Telepathy D-Bus API
specification), or an empty string if no suitable identifier is available,
or NULL on error
|
error : |
NULL on success, or the error with which message submission failed
|
void tp_message_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 |
guint tp_message_mixin_take_received (GObject *object, TpMessage *message);
Receive a message into the pending messages queue, where it will stay until acknowledged, and emit the Received and ReceivedMessage signals. Also emit the SendError signal if the message is a failed delivery report.
object : |
a channel with this mixin |
message : |
the message. Its ownership is claimed by the message mixin, so it must no longer be modified or freed |
| Returns : | the message ID
since 0.7.21
|
gboolean tp_message_mixin_has_pending_messages (GObject *object, 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.
object : |
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
|
void tp_message_mixin_clear (GObject *obj);
Clear the pending message queue, deleting all messages without emitting PendingMessagesRemoved.
obj : |
An object with this mixin |
void tp_message_mixin_text_iface_init (gpointer g_iface, gpointer iface_data);
Fill in this mixin's Text method implementations in the given interface vtable.
since 0.7.21
g_iface : |
A pointer to the TpSvcChannelTypeTextClass in an object class |
iface_data : |
Ignored |