/pidgin/main: e1f9a50effbc: Fill comments for PurpleMessage
Tomasz Wasilczyk
twasilczyk at pidgin.im
Fri Jun 13 18:28:57 EDT 2014
Changeset: e1f9a50effbcaf9211d9305f320f00b65a7461c6
Author: Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date: 2014-06-14 00:28 +0200
Branch: default
URL: https://hg.pidgin.im/pidgin/main/rev/e1f9a50effbc
Description:
Fill comments for PurpleMessage
diffstat:
doc/reference/libpurple/libpurple-docs.xml | 18 ++-
libpurple/internal.h | 16 +++
libpurple/message.c | 2 +-
libpurple/message.h | 147 +++++++++++++++++++++++++++-
4 files changed, 169 insertions(+), 14 deletions(-)
diffs (truncated from 322 to 300 lines):
diff --git a/doc/reference/libpurple/libpurple-docs.xml b/doc/reference/libpurple/libpurple-docs.xml
--- a/doc/reference/libpurple/libpurple-docs.xml
+++ b/doc/reference/libpurple/libpurple-docs.xml
@@ -38,7 +38,6 @@
<xi:include href="xml/pounce.xml" />
<xi:include href="xml/circularbuffer.xml" />
<xi:include href="xml/cipher.xml" />
- <xi:include href="xml/cmds.xml" />
<xi:include href="xml/connection.xml" />
<xi:include href="xml/conversation.xml" />
<xi:include href="xml/conversationtypes.xml" />
@@ -54,7 +53,6 @@
<xi:include href="xml/http.xml" />
<xi:include href="xml/idle.xml" />
<xi:include href="xml/keyring.xml" />
- <xi:include href="xml/log.xml" />
<xi:include href="xml/memorypool.xml" />
<xi:include href="xml/desktopitem.xml" />
<xi:include href="xml/mime.xml" />
@@ -97,6 +95,14 @@
<reference label="">
<reference label="a">
+ <title>Messaging</title>
+
+ <xi:include href="xml/message.xml" />
+ <xi:include href="xml/log.xml" />
+ <xi:include href="xml/cmds.xml" />
+ </reference>
+
+ <reference label="b">
<title>Ciphers and Hashes</title>
<xi:include href="xml/aescipher.xml" />
@@ -111,7 +117,7 @@
<xi:include href="xml/sha256hash.xml" />
</reference>
- <reference label="b">
+ <reference label="c">
<title>Smiley APIs</title>
<xi:include href="xml/smiley.xml" />
@@ -121,7 +127,7 @@
<xi:include href="xml/smiley-parser.xml" />
</reference>
- <reference label="c">
+ <reference label="d">
<title>Graphics</title>
<xi:include href="xml/image.xml" />
@@ -129,7 +135,7 @@
<xi:include href="xml/whiteboard.xml" />
</reference>
- <reference label="d">
+ <reference label="e">
<title>Media APIs</title>
<xi:include href="xml/media.xml" />
@@ -141,7 +147,7 @@
<xi:include href="xml/enum-types.xml" />
</reference>
- <reference label="e">
+ <reference label="f">
<title>D-Bus Server APIs</title>
<xi:include href="xml/dbus-bindings.xml" />
diff --git a/libpurple/internal.h b/libpurple/internal.h
--- a/libpurple/internal.h
+++ b/libpurple/internal.h
@@ -395,6 +395,22 @@ void
void
_purple_socket_uninit(void);
+/**
+ * _purple_message_init: (skip)
+ *
+ * Initializes the #PurpleMessage subsystem.
+ */
+void
+_purple_message_init(void);
+
+/**
+ * _purple_message_uninit: (skip)
+ *
+ * Uninitializes the #PurpleMessage subsystem.
+ */
+void
+_purple_message_uninit(void);
+
void
_purple_assert_connection_is_valid(PurpleConnection *gc,
const gchar *file, int line);
diff --git a/libpurple/message.c b/libpurple/message.c
--- a/libpurple/message.c
+++ b/libpurple/message.c
@@ -362,7 +362,7 @@ purple_message_class_init(PurpleMessageC
"Contents", "The message text",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
properties[PROP_TIME] = g_param_spec_uint64("time",
- "Time", "Message time",
+ "Time", "Message timestamp",
0, G_MAXUINT64, 0, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
properties[PROP_FLAGS] = g_param_spec_flags("flags",
"Flags", "Bitwise set of #PurpleMessageFlags flags",
diff --git a/libpurple/message.h b/libpurple/message.h
--- a/libpurple/message.h
+++ b/libpurple/message.h
@@ -48,7 +48,7 @@ typedef struct _PurpleMessageClass Purpl
/**
* PurpleMessage:
*
- * An message data container.
+ * A message data container.
*/
struct _PurpleMessage
{
@@ -82,62 +82,195 @@ G_BEGIN_DECLS
GType
purple_message_get_type(void);
+/**
+ * purple_message_new_outgoing:
+ * @who: Message's recipient.
+ * @contents: The contents of a message.
+ * @flags: The message flags.
+ *
+ * Creates new outgoing message (the user is the author).
+ *
+ * You don't need to set the #PURPLE_MESSAGE_SEND flag.
+ *
+ * Returns: the new #PurpleMessage.
+ */
PurpleMessage *
purple_message_new_outgoing(const gchar *who, const gchar *contents,
PurpleMessageFlags flags);
+/**
+ * purple_message_new_incoming:
+ * @who: Message's author.
+ * @contents: The contents of a message.
+ * @flags: The message flags.
+ * @timestamp: The time of transmitting a message. May be %0 for a current time.
+ *
+ * Creates new incoming message (the user is the recipient).
+ *
+ * You don't need to set the #PURPLE_MESSAGE_RECV flag.
+ *
+ * Returns: the new #PurpleMessage.
+ */
PurpleMessage *
purple_message_new_incoming(const gchar *who, const gchar *contents,
PurpleMessageFlags flags, guint64 timestamp);
+/**
+ * purple_message_new_system:
+ * @contents: The contents of a message.
+ * @flags: The message flags.
+ *
+ * Creates new system message.
+ *
+ * You don't need to set the #PURPLE_MESSAGE_SYSTEM flag.
+ *
+ * Returns: the new #PurpleMessage.
+ */
PurpleMessage *
purple_message_new_system(const gchar *contents, PurpleMessageFlags flags);
+/**
+ * purple_message_get_id:
+ * @msg: The message.
+ *
+ * Returns the unique identifier of the message. These identifiers are not
+ * serialized - it's a per-session id.
+ *
+ * Returns: the global identifier of @msg.
+ */
guint
purple_message_get_id(const PurpleMessage *msg);
+/**
+ * purple_message_find_by_id:
+ * @id: The message identifier.
+ *
+ * Finds the message with a given @id.
+ *
+ * Returns: the #PurpleMessage, or %NULL if not found.
+ */
PurpleMessage *
purple_message_find_by_id(guint id);
+/**
+ * purple_message_get_author:
+ * @msg: The message.
+ *
+ * Returns the author of the message - his screen name (not a local alias).
+ *
+ * Returns: the author of @msg.
+ */
const gchar *
purple_message_get_author(const PurpleMessage *msg);
+/**
+ * purple_message_get_recipient:
+ * @msg: The message.
+ *
+ * Returns the recipient of the message - his screen name (not a local alias).
+ *
+ * Returns: the recipient of @msg.
+ */
const gchar *
purple_message_get_recipient(const PurpleMessage *msg);
+/**
+ * purple_message_set_author_alias:
+ * @msg: The message.
+ * @alias: The alias.
+ *
+ * Sets the alias of @msg's author. You don't normally need to call this.
+ */
void
purple_message_set_author_alias(PurpleMessage *msg, const gchar *alias);
+/**
+ * purple_message_get_author_alias:
+ * @msg: The message.
+ *
+ * Returns the alias of @msg author.
+ *
+ * Returns: the @msg author's alias.
+ */
const gchar *
purple_message_get_author_alias(const PurpleMessage *msg);
+/**
+ * purple_message_set_contents:
+ * @msg: The message.
+ * @cont: The contents.
+ *
+ * Sets the contents of the @msg. It might be HTML.
+ */
void
purple_message_set_contents(PurpleMessage *msg, const gchar *cont);
+/**
+ * purple_message_get_contents:
+ * @msg: The message.
+ *
+ * Returns the contents of the message.
+ *
+ * Returns: the contents of @msg.
+ */
const gchar *
purple_message_get_contents(const PurpleMessage *msg);
+/**
+ * purple_message_is_empty:
+ * @msg: The message.
+ *
+ * Checks, if the message's body is empty.
+ *
+ * Returns: %TRUE, if @msg is empty.
+ */
gboolean
purple_message_is_empty(const PurpleMessage *msg);
+/**
+ * purple_message_set_time:
+ * @msg: The message.
+ * @msgtime: The timestamp of a message.
+ *
+ * Sets the @msg's timestamp. It should be a date of posting, but it can be
+ * a date of receiving (if the former is not available).
+ */
void
purple_message_set_time(PurpleMessage *msg, guint64 msgtime);
+/**
+ * purple_message_get_time:
+ * @msg: The message.
+ *
+ * Returns a @msg's timestamp.
+ *
+ * Returns: @msg's timestamp.
+ */
guint64
purple_message_get_time(const PurpleMessage *msg);
+/**
+ * purple_message_set_flags:
+ * @msg: The message.
+ * @flags: The message flags.
+ *
+ * Sets flags for @msg. It shouldn't be in a conflict with a message type,
+ * so use it carefully.
+ */
void
More information about the Commits
mailing list