pidgin/pidgin

Fill comments for PurpleMessage

2014-06-14, Tomasz Wasilczyk
e1f9a50effbc
Parents 09387009bb17
Children b2ad25dfbd57c0eccc6696da
Fill comments for PurpleMessage
4 files changed, 169 insertions(+), 14 deletions(-)
  • +12 -6
    doc/reference/libpurple/libpurple-docs.xml
  • +16 -0
    libpurple/internal.h
  • +1 -1
    libpurple/message.c
  • +140 -7
    libpurple/message.h
    • --- a/doc/reference/libpurple/libpurple-docs.xml Fri Jun 13 23:42:59 2014 +0200
    +++ b/doc/reference/libpurple/libpurple-docs.xml Sat Jun 14 00:28:48 2014 +0200
    @@ -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" />
    --- a/libpurple/internal.h Fri Jun 13 23:42:59 2014 +0200
    +++ b/libpurple/internal.h Sat Jun 14 00:28:48 2014 +0200
    @@ -395,6 +395,22 @@
    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);
    --- a/libpurple/message.c Fri Jun 13 23:42:59 2014 +0200
    +++ b/libpurple/message.c Sat Jun 14 00:28:48 2014 +0200
    @@ -362,7 +362,7 @@
    "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",
    --- a/libpurple/message.h Fri Jun 13 23:42:59 2014 +0200
    +++ b/libpurple/message.h Sat Jun 14 00:28:48 2014 +0200
    @@ -48,7 +48,7 @@
    /**
    * PurpleMessage:
    *
    - * An message data container.
    + * A message data container.
    */
    struct _PurpleMessage
    {
    @@ -82,62 +82,195 @@
    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
    purple_message_set_flags(PurpleMessage *msg, PurpleMessageFlags flags);
    +/**
    + * purple_message_get_flags:
    + * @msg: The message.
    + *
    + * Returns the flags of a @msg.
    + *
    + * Returns: the flags of a @msg.
    + */
    PurpleMessageFlags
    purple_message_get_flags(const PurpleMessage *msg);
    -void
    -_purple_message_init(void);
    -
    -void
    -_purple_message_uninit(void);
    -
    G_END_DECLS
    #endif /* _PURPLE_MESSAGE_H_ */