User Groups

`ugroups_group_is_destroyed`

Returns true if the group was destroyed by one of the admin.

Declaration

LIBSESSION_EXPORT bool ugroups_group_is_destroyed(const ugroups_group_info* group);

Parameters

group — [in] pointer to the group info to query

Returns

`ugroups_group_is_kicked`

Returns true if we have been kicked (i.e. our secret key and auth data are empty).

Declaration

LIBSESSION_EXPORT bool ugroups_group_is_kicked(const ugroups_group_info* group);

Parameters

group — [in] pointer to the group info to query

Returns

`ugroups_group_set_destroyed`

Mark the group as permanently destroyed and clears auth_data & secret_key. This cannot be unset once set.

Declaration

LIBSESSION_EXPORT void ugroups_group_set_destroyed(ugroups_group_info* group);

Parameters

group — [in] pointer to the group info which we should set to kicked

Returns

`ugroups_group_set_invited`

Call when we have been invited to a group to reset the 'kicked' state.

Declaration

LIBSESSION_EXPORT void ugroups_group_set_invited(ugroups_group_info* group);

Parameters

group — [in] pointer to the group info which we should set to kicked

Returns

`ugroups_group_set_kicked`

Call when we have been kicked from a group; this clears group's secret key and auth key from the group config setting.

Declaration

LIBSESSION_EXPORT void ugroups_group_set_kicked(ugroups_group_info* group);

Parameters

group — [in] pointer to the group info which we should set to kicked

Returns

`ugroups_legacy_group_free`

Properly frees memory associated with a ugroups_legacy_group_info pointer (as returned by get_legacy_group/get_or_construct_legacy_group).

Declaration

VOID ugroups_legacy_group_free(
    [in]    ugroups_community_info*   group
);

Parameters

group — [in] Pointer to ugroups_legacy_group_info

Returns

`ugroups_legacy_members_add`

Adds a member (by session id and admin status) to this group. Returns true if the member was inserted or had the admin status changed, false if the member already existed with the given status, or if the session_id is not valid.

Declaration

BOOL ugroups_legacy_member_add(
    [in]    ugroups_legacy_group_info*      group,
    [in]    const char*                     session_id,
    [in]    bool                            admin
);

Parameters

group — [in, out] group to be modified by adding a member
session_id — [in] null terminated session id
admin — [in] admin status of member

Returns

bool — Returns True if member was inserted or admin changed

`ugroups_legacy_members_begin`

Group member iteration; this lets you walk through the full group member list. Example usage:

    const char* session_id;
    bool admin;
    ugroups_legacy_members_iterator* it = ugroups_legacy_members_begin(legacy_info);
    while (ugroups_legacy_members_next(it, &session_id, &admin)) {
        if (admin)
            printf("ADMIN: %s", session_id);
    }
    ugroups_legacy_members_free(it);

Declaration

UGROUPS_LEGACY_MEMBERS_ITERATOR ugroups_legacy_members_begin(
    [in]    ugroups_legacy_group_info*      group
);

Parameters

group — [in] Pointer to ugroups_legacy_group_info

Returns

ugroups_legacy_members_iterator* — Iterator

`ugroups_legacy_members_count`

Accesses the number of members in the group. The overall number is returned (both admins and non-admins); if the given variables are not NULL, they will be populated with the individual counts of members/admins.

Declaration

SIZE_T ugroups_legacy_members_count(
    [in]    const ugroups_legacy_group_info*    group,
    [out]   size_t*                             members,
    [out]   size_t*                             admins
);

Parameters

group — [in] Users group
members — [out] the count of non-admin members
admins — [out] the count of admin members

Returns

size_t — Returns the count of all members

`ugroups_legacy_members_erase`

This erases the group member at the current iteration location during a member iteration, allowing iteration to continue.

Example:

    while (ugroups_legacy_members_next(it, &sid, &admin)) {
        if (should_remove(sid))
            ugroups_legacy_members_erase(it);
    }

Declaration

VOID ugroups_legacy_members_erase(
    [in]    ugroups_legacy_members_iterator*    it
);

Parameters

it — [in] The ugroups_legacy_members iterator

Returns

`ugroups_legacy_members_free`

Frees an iterator once no longer needed.

Declaration

VOID ugroups_legacy_members_free(
    [in]    ugroups_legacy_members_iterator*    it
);

Parameters

it — [in] The ugroups_legacy_members iterator

Returns

`ugroups_legacy_members_next`

Group member iteration; this lets you walk through the full group member list. Example usage:

    const char* session_id;
    bool admin;
    ugroups_legacy_members_iterator* it = ugroups_legacy_members_begin(legacy_info);
    while (ugroups_legacy_members_next(it, &session_id, &admin)) {
        if (admin)
            printf("ADMIN: %s", session_id);
    }
    ugroups_legacy_members_free(it);

Declaration

BOOL ugroups_legacy_members_next(
    [in]    ugroups_legacy_members_iterator*    it,
    [out]   const char**                        session_id,
    [out]   bool*                               admin
);

Parameters

it — [in] Iterator
session_id — [out] the session_id of the next member will be put here
admin — [out] will be true if the next member is an admin

Returns

bool — Returns False when end of group is reached

`ugroups_legacy_members_remove`

Removes a member (including admins) from the group given the member's session id. This is not safe to use on the current member during member iteration; for that see the above method instead. Returns true if the session id was found and removed, false if not found.

Declaration

BOOL ugroups_legacy_member_remove(
    [in]    ugroups_legacy_group_info*      group,
    [in]    const char*                     session_id
);

Parameters

group — [in, out] group to be modified by removing a member
session_id — [in] null terminated session id

Returns

bool — Returns True if member was removed

`user_groups_erase_community`

Erases a conversation from the conversation list. Returns true if the conversation was found and removed, false if the conversation was not present. You must not call this during iteration; see details below.

Declaration

BOOL user_groups_erase_community(
    [in]    config_object*      conf,
    [in]    const char*         base_url,
    [in]    const char*         room
);

Parameters

conf — [in] Pointer to config_object object
base_url — [in] null terminated string of the base url
room — [in] null terminated string of the room

Returns

bool — Returns True if conversation was found and removed

`user_groups_erase_group`

Erases a group conversation from the conversation list. Returns true if the conversation was found and removed, false if the conversation was not present. You must not call this during iteration; see details below.

Declaration

BOOL user_groups_erase_group(
    [in]    config_object*      conf,
    [in]    const char*         group_id
);

Parameters

conf — [in] Pointer to config_object object
group_id — [in] null terminated string of the hex group id (starting with "03")

Returns

bool — Returns True if conversation was found and removed

`user_groups_erase_legacy_group`

Erases a conversation from the conversation list. Returns true if the conversation was found and removed, false if the conversation was not present. You must not call this during iteration; see details below.

Declaration

BOOL user_groups_erase_legacy_group(
    [in]    config_object*      conf,
    [in]    const char*         group_id
);

Parameters

conf — [in] Pointer to config_object object
group_id — [in] null terminated string of the base url

Returns

bool — Returns True if conversation was found and removed

`user_groups_get_community`

Gets community conversation info into comm, if the community info was found. base_url and room are null-terminated c strings. base_url will be normalized/lower-cased; room is case-insensitive for the lookup: note that this may well return a community info with a different room capitalization than the one provided to the call.

Returns true if the community was found and comm populated; false otherwise. A false return can either be because it didn't exist (conf->last_error will be NULL) or because of some error (last_error will be set to an error string).

Declaration

BOOL user_groups_get_community(
    [in]    config_object*              conf,
    [out]   ugroups_community_info*     comm,
    [in]    const char*                 base_url,
    [in]    const char*                 room
);

Parameters

conf — [in] pointer to config_object object
comm — [out] pointer to ugroups_community_info object
base_url — [in] text of the url
room — [in] text of the room

Returns

bool — Whether the function succeeded or not

`user_groups_get_group`

Gets (non-legacy) group info into group, if the group was found. group_id is a null-terminated C string containing the 66 character group id in hex (beginning with "03").

Declaration

LIBSESSION_EXPORT bool user_groups_get_group(
        config_object* conf, ugroups_group_info* group, const char* group_id);

Parameters

conf — pointer to the group config object group — [out] ugroups_group_info struct into which to store the group info. group_id — C string containing the hex group id (starting with "03")

Returns

Returns true and populates group if the group was found; returns false otherwise.

`user_groups_get_legacy_group`

Returns a ugroups_legacy_group_info pointer containing the conversation info for a given legacy group ID (specified as a null-terminated hex string), if the conversation exists. If the conversation does not exist, returns NULL. Sets conf->last_error on error.

The returned pointer must be freed either by calling ugroups_legacy_group_free() when done with it, or by passing it to user_groups_set_free_legacy_group().

Declaration

UGROUPS_LEGACY_GROUP_INFO* user_groups_get_legacy_group(
    [in]    config_object*      conf,
    [in]    const char*         id
);

Parameters

conf — [in] Pointer to config_object object
id — [in] Null terminated hex string

Returns

ugroupts_legacy_group_info* — Pointer containing conversation info

`user_groups_get_or_construct_community`

Like the above, but if the community was not found, this constructs one that can be inserted. base_url will be normalized in the returned object. room is a case-insensitive lookup key for the room token. Note that it has subtle handling w.r.t its case: if an existing room is found, you get back a record with the found case (which could differ in case from what you provided). If you want to override to what you provided regardless of what is there you should immediately set the name of the returned object to the case you prefer. If a new record is constructed, however, it will match the room token case as given here.

Note that this is all different from convo_info_volatile, which always forces the room token to lower-case (because it does not preserve the case).

Returns false (and sets conf->last_error) on error.

Declaration

BOOL user_groups_get_or_construct_community(
    [in]    config_object*              conf,
    [out]   ugroups_community_info*     comm,
    [in]    const char*                 base_url,
    [in]    const char*                 room,
    [in]    unsigned const char*        pubkey
);

Parameters

conf — [in] pointer to config_object object
comm — [out] pointer to ugroups_community_info object
base_url — [in] text of the url
room — [in] text of the room
pubkey — [in] binary of pubkey

Returns

bool — Whether the function succeeded or not

`user_groups_get_or_construct_group`

Gets (non-legacy) group info into group, if the group was found. Otherwise initialize group to default values (and set its .id appropriately).

Declaration

LIBSESSION_EXPORT bool user_groups_get_or_construct_group(
        config_object* conf, ugroups_group_info* group, const char* group_id);

Parameters

conf — pointer to the group config object group — [out] ugroups_group_info struct into which to store the group info. group_id — C string containing the hex group id (starting with "03")

Returns

Returns true on success, false upon error (such as when given an invalid group id).

`user_groups_get_or_construct_legacy_group`

Same as the above get_legacy_group()except that when the conversation does not exist, this sets all the group fields to defaults and loads it with the given id.

Returns a ugroups_legacy_group_info as long as it is given a valid legacy group id (i.e. same format as a session id); it will return NULL only if the given id is invalid (and so the caller needs to either pre-validate the id, or post-validate the return value).

The returned pointer must be freed either by calling ugroups_legacy_group_free() when done with it, or by passing it to user_groups_set_free_legacy_group().

This is the method that should usually be used to create or update a conversation, followed by setting fields in the group, and then giving it to user_groups_set().

On error, this returns NULL and sets conf->last_error.

Declaration

UGROUPS_LEGACY_GROUP_INFO* user_groups_get_or_construct_legacy_group(
    [in]    config_object*      conf,
    [in]    const char*         id
);

Parameters

conf — [in] Pointer to config_object object
id — [in] Null terminated hex string

Returns

ugroupts_legacy_group_info* — Pointer containing conversation info

`user_groups_init`

Initializes the user groups object

Declaration

INT user_groups_init(
    [out]           config_object**     conf,
    [in]            unsigned char*      ed25519_secretkey,
    [in, optional]  unsigned char*      dump,
    [in, optional]  size_t              dumplen,
    [out]           char*               error
);

Parameters

conf — [in] pointer to config_object object
ed25519_secretkey — [in] pointer to secret key
dump — [in, optional] text of dump
dumplen — [in, optional] size of the text passed in as dump
error — [out] of the error if failed

Returns

int — Whether the function succeeded or not

`user_groups_it_is_community`

If the current iterator record is a community conversation this sets the details into c and returns true. Otherwise it returns false.

Declaration

BOOL user_groups_it_is_community(
    [in]    user_groups_iterator*       it,
    [out]   ugroups_community_info*     c
);

Parameters

it — [in] The iterator
c — [out] sets details of community into here if true

Returns

bool — Returns True if the group is a community

`user_groups_it_is_group`

If the current iterator record is a non-legacy group conversation this sets the details into group and returns true. Otherwise it returns false.

Declaration

LIBSESSION_EXPORT bool user_groups_it_is_group(user_groups_iterator* it, ugroups_group_info* group);

Parameters

it — [in] The Iterator
group — [out] sets details of the group into here (if true is returned)

Returns

bool — Returns true and sets group if the group is a non-legacy group (aka closed group).

`user_groups_it_is_legacy_group`

If the current iterator record is a legacy group conversation this sets the details into c and returns true. Otherwise it returns false.

Declaration

BOOL user_groups_it_is_legacy_group(
    [in]    user_groups_iterator*       it,
    [out]   ugroups_legacy_group_info*  c
);

Parameters

it — [in] The iterator
c — [out] sets details of legacy group into here if true

Returns

bool — Returns True if the group is a legacy group

`user_groups_iterator_advance`

Advances the iterator.

Declaration

VOID user_groups_iterator_advance(
    [in]    user_groups_iterator*   it
);

Parameters

it — [in, out] The Iterator

Returns

`user_groups_iterator_done`

Returns true if iteration has reached the end.

Declaration

BOOL user_groups_iterator_done(
    [in]    user_groups_iterator*   it
);

Parameters

it — [in, out] The Iterator

Returns

bool — Returns true if iteration has reached the end

`user_groups_iterator_free`

Frees an iterator once no longer needed.

Declaration

VOID user_groups_iterator_free(
    [in]    user_groups_iterator*   it
);

Parameters

it — [in, out] The Iterator

Returns

`user_groups_iterator_new`

Starts a new iterator that iterates over all conversations.

Intended use is:

    ugroups_community_info c2;
    ugroups_legacy_group_info c3;
    ugroups_group_info c4;
    user_groups_iterator *it = user_groups_iterator_new(my_groups);
    for (; !user_groups_iterator_done(it); user_groups_iterator_advance(it)) {
        if (user_groups_it_is_community(it, &c2)) {
            // use c2.whatever
        } else if (user_groups_it_is_legacy_group(it, &c3)) {
            // use c3.whatever
        } else if (user_groups_it_is_group(it, &c4)) {
            // use c4.whatever
        }
    }
    user_groups_iterator_free(it);

It is NOT permitted to add/remove/modify records while iterating.

Declaration

USER_GROUPS_ITERATOR* user_groups_iterator_new(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

user_groups_iterator* — The Iterator

`user_groups_iterator_new_communities`

The same as user_groups_iterator_new except that this iterates only over one type of conversation. You still need to use user_groups_it_is_community (or the alternatives) to load the data in each pass of the loop. (You can, however, safely ignore the bool return value of the it_is_whatever function: it will always be true for the particular type being iterated over).

Declaration

USER_GROUPS_ITERATOR* user_groups_iterator_new_communities(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

user_groups_iterator* — The Iterator

`user_groups_iterator_new_groups`

The same as user_groups_iterator_new except that this iterates only over one type of conversation: non-legacy groups. You still need to use user_groups_it_is_group to load the data in each pass of the loop. (You can, however, safely ignore the bool return value of the it_is_group function: it will always be true for iterations for this iterator).

Declaration

LIBSESSION_EXPORT user_groups_iterator* user_groups_iterator_new_groups(const config_object* conf);

Parameters

conf — [in] Pointer to config_object object

Returns

user_groups_iterator* — The Iterator

`user_groups_iterator_new_legacy_groups`

The same as user_groups_iterator_new except that this iterates only over one type of conversation. You still need to use user_groups_it_is_community (or the alternatives) to load the data in each pass of the loop. (You can, however, safely ignore the bool return value of the it_is_whatever function: it will always be true for the particular type being iterated over).

Declaration

USER_GROUPS_ITERATOR* user_groups_iterator_new_legacy_groups(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

user_groups_iterator* — The Iterator

`user_groups_set_community`

Adds or updates a community conversation from the given group info

Declaration

VOID user_groups_set_community(
    [in]    config_object*                  conf,
    [in]    const ugroups_community_info*   group
);

Parameters

conf — [in] Pointer to config_object object
group — [in] Pointer to a community group info object

Returns

`user_groups_set_free_legacy_group`

Same as above user_groups_set_free_legacy_group(), except that this also frees the pointer for you, which is commonly what is wanted when updating fields. This is equivalent to, but more efficient than, setting and then freeing.

Declaration

VOID user_groups_set_free_legacy_group(
    [in]    config_object*                      conf,
    [in]    const ugroups_legacy_group_info*    group
);

Parameters

conf — [in] Pointer to config_object object
group — [in] Pointer to a legacy group info object

Returns

bool — Returns true if the call succeeds, false if an error occurs.

`user_groups_set_group`

Adds or updates a (non-legacy) group conversation from the given group info

Declaration

LIBSESSION_EXPORT bool user_groups_set_group(config_object* conf, const ugroups_group_info* group);

Parameters

conf — [in] Pointer to config_object object
group — [in] Pointer to a group info object

Returns

bool — Returns true if the call succeeds, false if an error occurs.

`user_groups_set_legacy_group`

Adds or updates a legacy group conversation from the into. This version of the method should only be used when you explicitly want the group to remain valid; if the set is the last thing you need to do with it (which is common) it is more efficient to call the freeing version, below.

Declaration

VOID user_groups_set_legacy_group(
    [in]    config_object*                      conf,
    [in]    const ugroups_legacy_group_info*    group
);

Parameters

conf — [in] Pointer to config_object object
group — [in] Pointer to a legacy group info object

Returns

bool — Returns true if the call succeeds, false if an error occurs.

`user_groups_size`

Returns the number of conversations.

Declaration

SIZE_T user_groups_size(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

size_t — Returns the number of conversations

`user_groups_size_communities`

Returns the number of community conversations.

Declaration

SIZE_T user_groups_size_communities(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

size_t — Returns the number of conversations

`user_groups_size_groups`

Returns the number of (non-legacy) group conversations.

Declaration

SIZE_T user_groups_size_groups(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

size_t — Returns the number of conversations

`user_groups_size_legacy_groups`

Returns the number of legacy group conversations.

Declaration

SIZE_T user_groups_size_legacy_groups(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

size_t — Returns the number of conversations