--- a/libpurple/purplemessage.h Fri Jul 12 19:57:40 2024 -0500
+++ b/libpurple/purplemessage.h Sat Jul 13 01:13:52 2024 -0500
@@ -30,6 +30,7 @@
#include <glib-object.h>
#include "purpleattachment.h"
+#include "purplecontactinfo.h"
#include "purpleversion.h"
G_BEGIN_DECLS
@@ -90,6 +91,20 @@
G_DECLARE_FINAL_TYPE(PurpleMessage, purple_message, PURPLE, MESSAGE, GObject)
/**
+ * purple_message_new:
+ * @author: The author.
+ * @contents: The contents of the message.
+ *
+ * Creates a new message from @author with @contents.
+ *
+ * Returns: (transfer full): The new message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+PurpleMessage *purple_message_new(PurpleContactInfo *author, const char *contents);
+
+/**
* purple_message_new_outgoing:
* @author: The author.
* @contents: The contents.
@@ -104,7 +119,7 @@
*
* Since: 3.0
*/
-PURPLE_AVAILABLE_IN_3_0
+PURPLE_DEPRECATED_FOR(purple_message_new)
PurpleMessage *purple_message_new_outgoing(const char *author, const char *contents, PurpleMessageFlags flags);
/**
@@ -122,7 +137,7 @@
*
* Since: 3.0
*/
-PURPLE_AVAILABLE_IN_3_0
+PURPLE_DEPRECATED_FOR(purple_message_new)
PurpleMessage *purple_message_new_incoming(const char *who, const char *contents, PurpleMessageFlags flags, guint64 timestamp);
/**
@@ -138,303 +153,10 @@
*
* Since: 3.0
*/
-PURPLE_AVAILABLE_IN_3_0
+PURPLE_DEPRECATED_FOR(purple_message_new)
PurpleMessage *purple_message_new_system(const char *contents, PurpleMessageFlags flags);
/**
- * purple_message_get_id:
- * @message: 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 @message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-const char *purple_message_get_id(PurpleMessage *message);
-
-/**
- * purple_message_set_id:
- * @message: The instance.
- * @id: (nullable): The new id to set.
- *
- * Sets the id of @message to @id.
- *
- * > Note: This should really only be used by protocol plugins to update an id
- * of a sent message when the server has assigned the final id to the message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_set_id(PurpleMessage *message, const char *id);
-
-/**
- * purple_message_get_author:
- * @message: The message.
- *
- * Returns the author of the message, not a local alias.
- *
- * Returns: the author of @message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-const char *purple_message_get_author(PurpleMessage *message);
-
-/**
- * purple_message_set_author_name_color:
- * @message: The #PurpleMessage instance.
- * @color: The hex color code for the author of @message.
- *
- * Sets the author's name color of @message to @color. This is the color that
- * will be used to display the author's name in a user interface. The user
- * interface might not use this exact color, as it might need to adapt for
- * contrast or limits on the number of colors.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_set_author_name_color(PurpleMessage *message, const char *color);
-
-/**
- * purple_message_get_author_name_color:
- * @message: The #PurpleMessage instance.
- *
- * Gets the author's name color for @message.
- *
- * Returns: (transfer none): The hex color for the author of @message's name.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-const char *purple_message_get_author_name_color(PurpleMessage *message);
-
-/**
- * purple_message_set_author_alias:
- * @message: The message.
- * @alias: The alias.
- *
- * Sets the alias of @message's author. You don't normally need to call this.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_set_author_alias(PurpleMessage *message, const char *alias);
-
-/**
- * purple_message_get_author_alias:
- * @message: The message.
- *
- * Returns the alias of @message author.
- *
- * Returns: the @message author's alias.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-const char *purple_message_get_author_alias(PurpleMessage *message);
-
-/**
- * purple_message_set_contents:
- * @message: The message.
- * @cont: The contents.
- *
- * Sets the contents of the @message. It might be HTML.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_set_contents(PurpleMessage *message, const char *cont);
-
-/**
- * purple_message_get_contents:
- * @message: The message.
- *
- * Returns the contents of the message.
- *
- * Returns: the contents of @message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-const char *purple_message_get_contents(PurpleMessage *message);
-
-/**
- * purple_message_is_empty:
- * @message: The message.
- *
- * Checks, if the message's body is empty.
- *
- * Returns: %TRUE, if @message is empty.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-gboolean purple_message_is_empty(PurpleMessage *message);
-
-/**
- * purple_message_set_timestamp:
- * @message: The #PurpleMessage instance.
- * @timestamp: (nullable): The #GDateTime of the message.
- *
- * Sets the timestamp of @message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_set_timestamp(PurpleMessage *message, GDateTime *timestamp);
-
-/**
- * purple_message_get_timestamp:
- * @message: The message.
- *
- * Returns a @message's timestamp. If @message does not currently have a
- * timestamp, the current time will be set as the time stamp and returned.
- *
- * Returns: (transfer none): The #GDateTime timestamp from @message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-GDateTime *purple_message_get_timestamp(PurpleMessage *message);
-
-/**
- * purple_message_format_timestamp:
- * @message: The #PurpleMessage instance.
- * @format: The format to output the time stamp as.
- *
- * Formats the timestamp of @message and returns it.
- *
- * Returns: The formatted timestamp.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-char *purple_message_format_timestamp(PurpleMessage *message, const char *format);
-
-/**
- * purple_message_set_flags:
- * @message: The message.
- * @flags: The message flags.
- *
- * Sets flags for @message. It shouldn't be in a conflict with a message type,
- * so use it carefully.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_set_flags(PurpleMessage *message, PurpleMessageFlags flags);
-
-/**
- * purple_message_get_flags:
- * @message: The message.
- *
- * Returns the flags of a @message.
- *
- * Returns: the flags of a @message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-PurpleMessageFlags purple_message_get_flags(PurpleMessage *message);
-
-/**
- * purple_message_set_error:
- * @message: The instance.
- * @error: (nullable) (transfer none): The error to set.
- *
- * Sets the error of @message to @error. Primarily this will be used for
- * delivery failure.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_set_error(PurpleMessage *message, GError *error);
-
-/**
- * purple_message_get_error:
- * @message: The instance.
- *
- * Gets the error from @message.
- *
- * Returns: (nullable) (transfer none): The error from @message or %NULL.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-GError *purple_message_get_error(PurpleMessage *message);
-
-/**
- * purple_message_add_attachment:
- * @message: The #PurpleMessage instance.
- * @attachment: The #PurpleAttachment instance.
- *
- * Adds @attachment to @message.
- *
- * Returns: %TRUE if an attachment with the same ID did not already exist.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-gboolean purple_message_add_attachment(PurpleMessage *message, PurpleAttachment *attachment);
-
-/**
- * purple_message_remove_attachment:
- * @message: The #PurpleMessage instance.
- * @id: The id of the #PurpleAttachment
- *
- * Removes the #PurpleAttachment identified by @id if it exists.
- *
- * Returns: %TRUE if the #PurpleAttachment was found and removed, %FALSE
- * otherwise.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-gboolean purple_message_remove_attachment(PurpleMessage *message, guint64 id);
-
-/**
- * purple_message_get_attachment:
- * @message: The #PurpleMessage instance.
- * @id: The id of the #PurpleAttachment to get.
- *
- * Retrieves the #PurpleAttachment identified by @id from @message.
- *
- * Returns: (transfer full): The #PurpleAttachment if it was found, otherwise
- * %NULL.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-PurpleAttachment *purple_message_get_attachment(PurpleMessage *message, guint64 id);
-
-/**
- * purple_message_foreach_attachment:
- * @message: The #PurpleMessage instance.
- * @func: (scope call): The #PurpleAttachmentForeachFunc to call.
- * @data: User data to pass to @func.
- *
- * Calls @func for each #PurpleAttachment that's attached to @message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_foreach_attachment(PurpleMessage *message, PurpleAttachmentForeachFunc func, gpointer data);
-
-/**
- * purple_message_clear_attachments:
- * @message: The #PurpleMessage instance.
- *
- * Removes all attachments from @message.
- *
- * Since: 3.0
- */
-PURPLE_AVAILABLE_IN_3_0
-void purple_message_clear_attachments(PurpleMessage *message);
-
-/**
* purple_message_get_action:
* @message: The instance.
*
@@ -464,6 +186,110 @@
void purple_message_set_action(PurpleMessage *message, gboolean action);
/**
+ * purple_message_get_author:
+ * @message: The message.
+ *
+ * Returns the author of the message, not a local alias.
+ *
+ * Returns: the author of @message.
+ *
+ * Deprecated: 3.0: this is being repurposed in the future.
+ */
+PURPLE_DEPRECATED_FOR(purple_message_get_author_name)
+const char *purple_message_get_author(PurpleMessage *message);
+
+/**
+ * purple_message_get_author_name:
+ * @message: The message.
+ *
+ * Returns the author of the message, not a local alias.
+ *
+ * Returns: the author of @message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+const char *purple_message_get_author_name(PurpleMessage *message);
+
+/**
+ * purple_message_get_author_name_color:
+ * @message: The #PurpleMessage instance.
+ *
+ * Gets the author's name color for @message.
+ *
+ * Returns: (transfer none): The hex color for the author of @message's name.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+const char *purple_message_get_author_name_color(PurpleMessage *message);
+
+/**
+ * purple_message_set_author_name_color:
+ * @message: The #PurpleMessage instance.
+ * @color: The hex color code for the author of @message.
+ *
+ * Sets the author's name color of @message to @color. This is the color that
+ * will be used to display the author's name in a user interface. The user
+ * interface might not use this exact color, as it might need to adapt for
+ * contrast or limits on the number of colors.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_author_name_color(PurpleMessage *message, const char *color);
+
+/**
+ * purple_message_get_author_alias:
+ * @message: The message.
+ *
+ * Returns the alias of @message author.
+ *
+ * Returns: the @message author's alias.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+const char *purple_message_get_author_alias(PurpleMessage *message);
+
+/**
+ * purple_message_set_author_alias:
+ * @message: The message.
+ * @alias: The alias.
+ *
+ * Sets the alias of @message's author. You don't normally need to call this.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_author_alias(PurpleMessage *message, const char *alias);
+
+/**
+ * purple_message_get_contents:
+ * @message: The message.
+ *
+ * Returns the contents of the message.
+ *
+ * Returns: the contents of @message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+const char *purple_message_get_contents(PurpleMessage *message);
+
+/**
+ * purple_message_set_contents:
+ * @message: The message.
+ * @cont: The contents.
+ *
+ * Sets the contents of the @message. It might be HTML.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_contents(PurpleMessage *message, const char *cont);
+
+/**
* purple_message_get_delivered:
* @message: The instance.
*
@@ -558,6 +384,31 @@
void purple_message_set_edited(PurpleMessage *message, gboolean edited);
/**
+ * purple_message_get_event:
+ * @message: The instance.
+ *
+ * Gets whether or not @message is for an event.
+ *
+ * Returns: %TRUE if the message is for an event, otherwise %FALSE.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+gboolean purple_message_get_event(PurpleMessage *message);
+
+/**
+ * purple_message_set_event:
+ * @message: The instance.
+ * @event: The new event state.
+ *
+ * Sets whether or not @message is for an event.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_event(PurpleMessage *message, gboolean event);
+
+/**
* purple_message_get_edited_at:
* @message: The instance.
*
@@ -586,6 +437,244 @@
PURPLE_AVAILABLE_IN_3_0
void purple_message_set_edited_at(PurpleMessage *message, GDateTime *datetime);
+/**
+ * purple_message_get_error:
+ * @message: The instance.
+ *
+ * Gets the error from @message.
+ *
+ * Returns: (nullable) (transfer none): The error from @message or %NULL.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+GError *purple_message_get_error(PurpleMessage *message);
+
+/**
+ * purple_message_set_error:
+ * @message: The instance.
+ * @error: (nullable) (transfer none): The error to set.
+ *
+ * Sets the error of @message to @error. Primarily this will be used for
+ * delivery failure.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_error(PurpleMessage *message, GError *error);
+
+/**
+ * purple_message_get_flags:
+ * @message: The message.
+ *
+ * Returns the flags of a @message.
+ *
+ * Returns: the flags of a @message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+PurpleMessageFlags purple_message_get_flags(PurpleMessage *message);
+
+/**
+ * purple_message_set_flags:
+ * @message: The message.
+ * @flags: The message flags.
+ *
+ * Sets flags for @message. It shouldn't be in a conflict with a message type,
+ * so use it carefully.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_flags(PurpleMessage *message, PurpleMessageFlags flags);
+
+/**
+ * purple_message_get_id:
+ * @message: 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 @message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+const char *purple_message_get_id(PurpleMessage *message);
+
+/**
+ * purple_message_set_id:
+ * @message: The instance.
+ * @id: (nullable): The new id to set.
+ *
+ * Sets the id of @message to @id.
+ *
+ * > Note: This should really only be used by protocol plugins to update an id
+ * of a sent message when the server has assigned the final id to the message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_id(PurpleMessage *message, const char *id);
+
+/**
+ * purple_message_is_empty:
+ * @message: The message.
+ *
+ * Checks, if the message's body is empty.
+ *
+ * Returns: %TRUE, if @message is empty.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+gboolean purple_message_is_empty(PurpleMessage *message);
+
+/**
+ * purple_message_get_notice:
+ * @message: The instance.
+ *
+ * Gets whether or not @message is a notice.
+ *
+ * Returns: %TRUE if @message is a notice, otherwise %FALSE.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+gboolean purple_message_get_notice(PurpleMessage *message);
+
+/**
+ * purple_message_set_notice:
+ * @message: The instance.
+ * @notice: %TRUE if this message is a NOTICE.
+ *
+ * Sets whether or not @message is a notice.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_notice(PurpleMessage *message, gboolean notice);
+
+/**
+ * purple_message_get_timestamp:
+ * @message: The message.
+ *
+ * Returns a @message's timestamp. If @message does not currently have a
+ * timestamp, the current time will be set as the time stamp and returned.
+ *
+ * Returns: (transfer none): The #GDateTime timestamp from @message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+GDateTime *purple_message_get_timestamp(PurpleMessage *message);
+
+/**
+ * purple_message_set_timestamp:
+ * @message: The #PurpleMessage instance.
+ * @timestamp: (nullable): The #GDateTime of the message.
+ *
+ * Sets the timestamp of @message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_timestamp(PurpleMessage *message, GDateTime *timestamp);
+
+/**
+ * purple_message_set_timestamp_now:
+ * @message: The instance.
+ *
+ * Calls [method@Message.set_timestamp] with the current UTC time.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_set_timestamp_now(PurpleMessage *message);
+
+/**
+ * purple_message_format_timestamp:
+ * @message: The #PurpleMessage instance.
+ * @format: The format to output the time stamp as.
+ *
+ * Formats the timestamp of @message and returns it.
+ *
+ * Returns: The formatted timestamp.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+char *purple_message_format_timestamp(PurpleMessage *message, const char *format);
+
+/**
+ * purple_message_add_attachment:
+ * @message: The #PurpleMessage instance.
+ * @attachment: The #PurpleAttachment instance.
+ *
+ * Adds @attachment to @message.
+ *
+ * Returns: %TRUE if an attachment with the same ID did not already exist.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+gboolean purple_message_add_attachment(PurpleMessage *message, PurpleAttachment *attachment);
+
+/**
+ * purple_message_remove_attachment:
+ * @message: The #PurpleMessage instance.
+ * @id: The id of the #PurpleAttachment
+ *
+ * Removes the #PurpleAttachment identified by @id if it exists.
+ *
+ * Returns: %TRUE if the #PurpleAttachment was found and removed, %FALSE
+ * otherwise.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+gboolean purple_message_remove_attachment(PurpleMessage *message, guint64 id);
+
+/**
+ * purple_message_get_attachment:
+ * @message: The #PurpleMessage instance.
+ * @id: The id of the #PurpleAttachment to get.
+ *
+ * Retrieves the #PurpleAttachment identified by @id from @message.
+ *
+ * Returns: (transfer full): The #PurpleAttachment if it was found, otherwise
+ * %NULL.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+PurpleAttachment *purple_message_get_attachment(PurpleMessage *message, guint64 id);
+
+/**
+ * purple_message_foreach_attachment:
+ * @message: The #PurpleMessage instance.
+ * @func: (scope call): The #PurpleAttachmentForeachFunc to call.
+ * @data: User data to pass to @func.
+ *
+ * Calls @func for each #PurpleAttachment that's attached to @message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_foreach_attachment(PurpleMessage *message, PurpleAttachmentForeachFunc func, gpointer data);
+
+/**
+ * purple_message_clear_attachments:
+ * @message: The #PurpleMessage instance.
+ *
+ * Removes all attachments from @message.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_message_clear_attachments(PurpleMessage *message);
+
G_END_DECLS
#endif /* PURPLE_MESSAGE_H */
