Mercurial > pidgin3 / changeset

--- a/libpurple/purplepresence.h	Thu Oct 26 03:41:25 2023 -0500
+++ b/libpurple/purplepresence.h	Thu Oct 26 04:02:53 2023 -0500
@@ -46,6 +46,8 @@
  *
  * Note: When a presence is destroyed with the last g_object_unref(), all
  * statuses added to this list will be destroyed along with the presence.
+ *
+ * Since: 2.0.0
  */
 
 typedef struct _PurplePresence PurplePresence;
@@ -94,6 +96,8 @@
  *               presence changes.
  *
  * The base class for all #PurplePresence's.
+ *
+ * Since: 3.0.0
  */
 struct _PurplePresenceClass {
 	/*< private >*/
@@ -120,9 +124,9 @@
  *
  * Returns: (transfer full): The new instance.
  *
- * Since: 3.0.0
+ * Since: 2.0.0
  */
-PURPLE_AVAILABLE_IN_3_0
+PURPLE_AVAILABLE_IN_ALL
 PurplePresence *purple_presence_new(void);
 
 /**
@@ -136,7 +140,10 @@
  * Only independent statuses can be set inactive. Normal statuses can only
  * be set active, so if you wish to disable a status, set another
  * non-independent status to active, or use purple_presence_switch_status().
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 void purple_presence_set_status_active(PurplePresence *presence, const gchar *status_id, gboolean active);
 
 /**
@@ -148,7 +155,10 @@
  *
  * This is similar to purple_presence_set_status_active(), except it won't
  * activate independent statuses.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 void purple_presence_switch_status(PurplePresence *presence, const gchar *status_id);
 
 /**
@@ -160,7 +170,10 @@
  *             then %NULL should be used.
  *
  * Sets the idle state and time of @presence.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 void purple_presence_set_idle(PurplePresence *presence, gboolean idle, GDateTime *idle_time);
 
 /**
@@ -169,7 +182,10 @@
  * @login_time: (transfer none): The login time.
  *
  * Sets the login time on a presence.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 void purple_presence_set_login_time(PurplePresence *presence, GDateTime *login_time);
 
 /**
@@ -179,7 +195,10 @@
  * Gets a list of all the statuses in @presence.
  *
  * Returns: (element-type PurpleStatus) (transfer none): The statuses.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 GList *purple_presence_get_statuses(PurplePresence *presence);
 
 /**
@@ -190,7 +209,10 @@
  * Gets the status with the specified ID from @presence.
  *
  * Returns: (transfer none): The #PurpleStatus if found, or %NULL.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatus *purple_presence_get_status(PurplePresence *presence, const gchar *status_id);
 
 /**
@@ -200,7 +222,10 @@
  * Gets the active exclusive status from @presence.
  *
  * Returns: (transfer none): The active exclusive status.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatus *purple_presence_get_active_status(PurplePresence *presence);
 
 /**
@@ -212,7 +237,10 @@
  * Available presences are online and possibly invisible, but not away or idle.
  *
  * Returns: %TRUE if the presence is available, or %FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_presence_is_available(PurplePresence *presence);
 
 /**
@@ -222,7 +250,10 @@
  * Gets whether or not @presence is online.
  *
  * Returns: %TRUE if the presence is online, or %FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_presence_is_online(PurplePresence *presence);
 
 /**
@@ -235,7 +266,10 @@
  * A status is active if itself or any of its sub-statuses are active.
  *
  * Returns: %TRUE if the status is active, or %FALSE.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_presence_is_status_active(PurplePresence *presence, const gchar *status_id);
 
 /**
@@ -249,7 +283,10 @@
  * A status is active if itself or any of its sub-statuses are active.
  *
  * Returns: %TRUE if the status is active, or %FALSE.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_presence_is_status_primitive_active(PurplePresence *presence, PurpleStatusPrimitive primitive);
 
 /**
@@ -261,7 +298,10 @@
  * Returns: %TRUE if the presence is idle, or %FALSE otherwise.  If the
  *          presence is offline (purple_presence_is_online() returns %FALSE)
  *          then %FALSE is returned.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_presence_is_idle(PurplePresence *presence);
 
 /**
@@ -272,7 +312,10 @@
  * support idle times or if the presence isn't in an idle state.
  *
  * Returns: (nullable): The idle time of @presence or %NULL.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 GDateTime *purple_presence_get_idle_time(PurplePresence *presence);
 
 /**
@@ -282,7 +325,10 @@
  * Gets the login time of @presence.
  *
  * Returns: (transfer none): The login time of @presence.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 GDateTime *purple_presence_get_login_time(PurplePresence *presence);
 
 /**
@@ -295,7 +341,10 @@
  * Returns: -1 if @presence1 is more available than @presence2.
  *           0 if @presence1 is equal to @presence2.
  *           1 if @presence1 is less available than @presence2.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gint purple_presence_compare(PurplePresence *presence1, PurplePresence *presence2);
 
 /**

--- a/libpurple/status.h	Thu Oct 26 03:41:25 2023 -0500
+++ b/libpurple/status.h	Thu Oct 26 04:02:53 2023 -0500
@@ -45,6 +45,8 @@
  * that later).  PurpleStatusTypes are very permanent.  They are
  * hardcoded in each protocol and will not change often.  And because
  * they are hardcoded, they do not need to be saved to any XML file.
+ *
+ * Since: 2.0.0
  */
 typedef struct _PurpleStatusType PurpleStatusType;
 
@@ -80,6 +82,8 @@
  * other random info).
  *
  * See <link linkend="libpurple-purplepresence">Presence API</link>
+ *
+ * Since: 2.0.0
  */
 typedef struct _PurpleStatusAttribute PurpleStatusAttribute;
 
@@ -96,6 +100,8 @@
  * @PURPLE_STATUS_NUM_PRIMITIVES: The number of #PurpleStatusPrimitive<!-- -->s
  *
  * A primitive defining the basic structure of a status type.
+ *
+ * Since: 2.0.0
  */
 /*
  * If you add a value to this enum, make sure you update
@@ -131,7 +137,10 @@
  * ID is a unique plain-text name of the status, without spaces.
  *
  * Returns: The unique ID for this type.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 const char *purple_primitive_get_id_from_type(PurpleStatusPrimitive type);
 
 /**
@@ -143,7 +152,10 @@
  * or two words.
  *
  * Returns: The name of this type, suitable for users to see.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 const char *purple_primitive_get_name_from_type(PurpleStatusPrimitive type);
 
 /**
@@ -154,7 +166,10 @@
  * ID is a unique plain-text name of the status, without spaces.
  *
  * Returns: The PurpleStatusPrimitive value.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatusPrimitive purple_primitive_get_type_from_id(const char *id);
 
 /**************************************************************************/
@@ -188,7 +203,10 @@
  * Creates a new status type.
  *
  * Returns: (transfer full): A new status type.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatusType *purple_status_type_new_full(PurpleStatusPrimitive primitive,
 										  const char *id, const char *name,
 										  gboolean saveable,
@@ -208,7 +226,10 @@
  * independent).
  *
  * Returns: (transfer full): A new status type.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatusType *purple_status_type_new(PurpleStatusPrimitive primitive,
 									 const char *id, const char *name,
 									 gboolean user_settable);
@@ -232,7 +253,10 @@
  * Creates a new status type with attributes.
  *
  * Returns: (transfer full): A new status type.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatusType *purple_status_type_new_with_attrs(PurpleStatusPrimitive primitive,
 												const char *id,
 												const char *name,
@@ -282,7 +306,10 @@
  * @status_type: The status type to destroy.
  *
  * Destroys a status type.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 void purple_status_type_destroy(PurpleStatusType *status_type);
 
 /**
@@ -292,7 +319,10 @@
  * Returns the primitive type of a status type.
  *
  * Returns: The primitive type of the status type.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatusPrimitive purple_status_type_get_primitive(
 	const PurpleStatusType *status_type);
 
@@ -303,7 +333,10 @@
  * Returns the ID of a status type.
  *
  * Returns: The ID of the status type.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 const char *purple_status_type_get_id(const PurpleStatusType *status_type);
 
 /**
@@ -313,7 +346,10 @@
  * Returns the name of a status type.
  *
  * Returns: The name of the status type.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 const char *purple_status_type_get_name(const PurpleStatusType *status_type);
 
 /**
@@ -324,7 +360,10 @@
  *
  * Returns: TRUE if user-defined statuses based off this type are saveable.
  *         FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_type_is_saveable(const PurpleStatusType *status_type);
 
 /**
@@ -336,7 +375,10 @@
  *
  * Returns: TRUE if the status type can be set or modified by the user.
  *         FALSE if it's a protocol-set setting.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_type_is_user_settable(const PurpleStatusType *status_type);
 
 /**
@@ -349,7 +391,10 @@
  * the same hierarchy level are set, this one will not be affected.
  *
  * Returns: TRUE if the status type is independent, or FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_type_is_independent(const PurpleStatusType *status_type);
 
 /**
@@ -359,7 +404,10 @@
  * Returns whether the status type is exclusive.
  *
  * Returns: TRUE if the status type is exclusive, FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_type_is_exclusive(const PurpleStatusType *status_type);
 
 /**
@@ -371,7 +419,10 @@
  * Available status types are online and possibly invisible, but not away.
  *
  * Returns: TRUE if the status is available, or FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_type_is_available(const PurpleStatusType *status_type);
 
 /**
@@ -382,7 +433,10 @@
  * Returns the attribute with the specified ID.
  *
  * Returns: The attribute, if found. NULL otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatusAttribute *purple_status_type_get_attr(const PurpleStatusType *status_type,
 										  const char *id);
 
@@ -393,7 +447,10 @@
  * Returns a list of all attributes in a status type.
  *
  * Returns: (element-type PurpleStatusAttribute) (transfer none): The list of attributes.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 GList *purple_status_type_get_attrs(const PurpleStatusType *status_type);
 
 /**
@@ -406,7 +463,10 @@
  *
  * Returns: The status type with the given ID, or NULL if one could
  *         not be found.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 const PurpleStatusType *purple_status_type_find_with_id(GList *status_types,
 													const char *id);
 
@@ -502,6 +562,8 @@
  * The standard _get_type function for #PurpleStatus.
  *
  * Returns: The #GType for #PurpleStatus.
+ *
+ * Since: 2.0.0
  */
 PURPLE_AVAILABLE_IN_ALL
 G_DECLARE_FINAL_TYPE(PurpleStatus, purple_status, PURPLE, STATUS, GObject)
@@ -514,7 +576,10 @@
  * Creates a new status.
  *
  * Returns: The new status.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurpleStatus *purple_status_new(PurpleStatusType *status_type,
 							PurplePresence *presence);
 
@@ -526,7 +591,10 @@
  * Sets whether or not a status is active.
  *
  * This should only be called by the account, conversation, and buddy APIs.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 void purple_status_set_active(PurpleStatus *status, gboolean active);
 
 /**
@@ -567,7 +635,10 @@
  * Returns the status's presence.
  *
  * Returns: (transfer none): The status's presence.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 PurplePresence *purple_status_get_presence(PurpleStatus *status);
 
 /**
@@ -580,7 +651,10 @@
  * purple_status_type_get_id(purple_status_get_status_type(status)).
  *
  * Returns: The status's ID.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 const char *purple_status_get_id(PurpleStatus *status);
 
 /**
@@ -593,7 +667,10 @@
  * purple_status_type_get_name(purple_status_get_status_type(status)).
  *
  * Returns: The status's name.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 const char *purple_status_get_name(PurpleStatus *status);
 
 /**
@@ -606,7 +683,10 @@
  * purple_status_type_is_independent(purple_status_get_status_type(status)).
  *
  * Returns: TRUE if the status is independent, or FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_is_independent(PurpleStatus *status);
 
 /**
@@ -619,7 +699,10 @@
  * purple_status_type_is_exclusive(purple_status_get_status_type(status)).
  *
  * Returns: TRUE if the status is exclusive, FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_is_exclusive(PurpleStatus *status);
 
 /**
@@ -634,7 +717,10 @@
  * purple_status_type_is_available(purple_status_get_status_type(status)).
  *
  * Returns: TRUE if the status is available, or FALSE otherwise.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_is_available(PurpleStatus *status);
 
 /**
@@ -644,7 +730,10 @@
  * Returns the active state of a status.
  *
  * Returns: The active state of the status.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_is_active(PurpleStatus *status);
 
 /**
@@ -654,7 +743,10 @@
  * Returns whether or not a status is considered 'online'
  *
  * Returns: TRUE if the status is considered online, FALSE otherwise
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_is_online(PurpleStatus *status);
 
 /**
@@ -665,7 +757,10 @@
  * Returns the value of an attribute in a status with the specified ID.
  *
  * Returns: The value of the attribute.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 GValue *purple_status_get_attr_value(PurpleStatus *status,
 									 const char *id);
 
@@ -677,7 +772,10 @@
  * Returns the boolean value of an attribute in a status with the specified ID.
  *
  * Returns: The boolean value of the attribute.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gboolean purple_status_get_attr_boolean(PurpleStatus *status,
 									    const char *id);
 
@@ -689,7 +787,10 @@
  * Returns the integer value of an attribute in a status with the specified ID.
  *
  * Returns: The integer value of the attribute.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 int purple_status_get_attr_int(PurpleStatus *status, const char *id);
 
 /**
@@ -700,7 +801,10 @@
  * Returns the string value of an attribute in a status with the specified ID.
  *
  * Returns: The string value of the attribute.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 const char *purple_status_get_attr_string(PurpleStatus *status, const char *id);
 
 /**
@@ -713,7 +817,10 @@
  * Returns: -1 if @status1 is more available than @status2.
  *           0 if @status1 is equal to @status2.
  *           1 if @status2 is more available than @status1.
+ *
+ * Since: 2.0.0
  */
+PURPLE_AVAILABLE_IN_ALL
 gint purple_status_compare(PurpleStatus *status1, PurpleStatus *status2);
 
 /**************************************************************************/
@@ -736,14 +843,20 @@
  * purple_statuses_init:
  *
  * Initializes the status subsystem.
+ *
+ * Since: 3.0.0
  */
+PURPLE_AVAILABLE_IN_3_0
 void purple_statuses_init(void);
 
 /**
  * purple_statuses_uninit:
  *
  * Uninitializes the status subsystem.
+ *
+ * Since: 3.0.0
  */
+PURPLE_AVAILABLE_IN_3_0
 void purple_statuses_uninit(void);
 
 /**************************************************************************/