qulogic/pidgin

Add Since and visibility tags for status API

8 months ago, Elliott Sales de Andrade
dde461efd3e0
Parents 9ca3a03253ca
Children 561a6ccf39c6
Add Since and visibility tags for status API

Compared with `status.h` from v2.0.0.

Testing Done:
Compiled.

Bugs closed: PIDGIN-17838

Reviewed at https://reviews.imfreedom.org/r/2714/
2 files changed, 164 insertions(+), 2 deletions(-)
  • +51 -2
    libpurple/purplepresence.h
  • +113 -0
    libpurple/status.h
    • --- 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);
    /**************************************************************************/