Skip to content

User Groups

UserGroups::UserGroups

Constructs a user group list from existing data (stored from dump()) and the user's secret key for generating the data encryption key. To construct a blank list (i.e. with no pre-existing dumped data to load) pass std::nullopt as the second argument.

Declaration

UserGroups(ustring_view ed25519_secretkey, std::optional<ustring_view> dumped);

Parameters

  • ed25519_secretkey — contains the libsodium secret key used to encrypt/decrypt the data when pushing/pulling from the swarm. This can either be the full 64-byte value (which is technically the 32-byte seed followed by the 32-byte pubkey), or just the 32-byte seed of the secret key.
  • dumped — either std::nullopt to construct a new, empty object; or binary state data that was previously dumped from an instance of this class by calling dump().

Returns

  • UserGroups - Constructor

UserGroups::begin

Iterators for iterating through all groups. Typically you access this implicit via a for loop over the UserGroups object: 

    for (auto& group : usergroups) {
        if (auto* comm = std::get_if<community_info>(&group)) {
            // use comm->name, comm->priority, etc.
        } else if (auto* lg = std::get_if<legacy_group_info>(&convo)) {
            // use lg->session_id, lg->priority, etc.
        }
    }

This iterates through all groups in sorted order (sorted first by convo type [groups, communities, legacy groups], then by id within the type).

It is NOT permitted to add/remove/modify records while iterating. If such is needed it must be done in two passes: once to collect the modifications, then a loop applying the collected modifications.

Declaration

iterator begin() const { return iterator{data}; }

Parameters

This endpoint takes no inputs.

Returns

  • iterator - Returns an iterator for the beginning of the groups

UserGroups::begin_communities

Declaration

subtype_iterator<community_info> begin_communities() const { return {data}; }

Parameters

This endpoint takes no inputs.

Returns

  • an iterator that iterates only through community conversations. (The regular .end() iterator is valid for testing the end of this iterator).

UserGroups::begin_groups

Declaration

subtype_iterator<group_info> begin_groups() const { return {data}; }

Parameters

This endpoint takes no inputs.

Returns

  • an iterator that iterates only through group conversations. (The regular .end() iterator is valid for testing the end of this iterator).

UserGroups::begin_legacy_groups

Declaration

subtype_iterator<legacy_group_info> begin_legacy_groups() const { return {data}; }

Parameters

This endpoint takes no inputs.

Returns

  • an iterator that iterates only through legacy group conversations. (The regular .end() iterator is valid for testing the end of this iterator).

UserGroups::create_group

Constructs a group_info object with newly generated (random) keys and returns the group_info containing these keys. The group will have the id and secretkey populated; other fields are defaulted. You still need to pass this to set() to store it, after setting any other fields as desired.

Declaration

group_info create_group() const;

Parameters

This endpoint takes no inputs.

Returns

  • group_info - Returns a filled out group_info struct for a new, randomly generated group.

UserGroups::empty

Returns true if the group list is empty.

Declaration

bool empty() const { return size() == 0; }

Parameters

This endpoint takes no inputs.

Returns

  • bool - Returns true if the contact list is empty

UserGroups::encryption_domain

Returns the domain. Is constant, will always return "Contacts"

Declaration

const char* encryption_domain() const override { return "UserGroups"; }

Parameters

This endpoint takes no inputs.

Returns

  • const char* - Returns "UserGroups"

UserGroups::end

Iterator for passing the end of the groups

Declaration

iterator end() const { return iterator{}; }

Parameters

This endpoint takes no inputs.

Returns

  • iterator - Returns an iterator for the end of the groups

UserGroups::erase

Removes a conversation taking the community_info, group_info, or legacy_group_info instance (rather than the pubkey/url) for convenience.

Declaration

bool erase(const group_info& g);
bool erase(const community_info& g);
bool erase(const legacy_group_info& c);
bool erase(const any_group_info& info);

Parameters

  • group_info — any group info struct

Returns

  • bool - Returns true if found and removed, false otherwise

UserGroups::erase_community

Removes a community group. Returns true if found and removed, false if not present. Arguments are the same as get_community.

Declaration

bool erase_community(std::string_view base_url, std::string_view room);

Parameters

  • base_url — text string containing the base URL
  • room — room token to lookup

Returns

  • bool - Returns true if found and removed, false otherwise

UserGroups::erase_group

Removes a (new, closed) group conversation. Returns true if found and removed, false if not present.

Declaration

bool erase_group(std::string_view pubkey_hex);

Parameters

  • pubkey_hex — group ID (hex, looks like a session ID, but starts with 03)

Returns

  • bool - Returns true if found and removed, false otherwise

UserGroups::erase_legacy_group

Removes a legacy group conversation. Returns true if found and removed, false if not present.

Declaration

bool erase_legacy_group(std::string_view pubkey_hex);

Parameters

  • pubkey_hex — group ID (hex, looks like a session ID)

Returns

  • bool - Returns true if found and removed, false otherwise

UserGroups::get_community

Looks up and returns a community (aka open group) conversation. Takes the base URL and room token (case insensitive). Retuns nullopt if the open group was not found, otherwise a filled out community_info. Note that the room argument here is case-insensitive, but the returned value will be the room as stored in the object (i.e. it may have a different case from the requested room value).

Declaration

std::optional<community_info> get_community(
        std::string_view base_url, std::string_view room) const;

Parameters

  • First Function:
  • base_url — base URL
  • room — room token (case insensitive)
  • Second Function
  • partial_url — Looks up a community from a url permitting to omit the pubkey

Returns

  • std::optional<community_info> - Returns the filled out community_info struct if found

UserGroups::get_group

Looks up and returns a group (aka new closed group) by group ID (hex, looks like a Session ID but starting with 03). Returns nullopt if the group was not found, otherwise returns a filled out group_info.

Declaration

std::optional<group_info> get_group(std::string_view pubkey_hex) const;

Parameters

  • pubkey_hex — group ID (hex, looks like a session ID but starting 03 instead of 05)

Returns

  • std::optional<group_info> - Returns the filled out group_info struct if found, nullopt if not found.

UserGroups::get_legacy_group

Looks up and returns a legacy group by group ID (hex, looks like a Session ID). Returns nullopt if the group was not found, otherwise returns a filled out legacy_group_info.

Declaration

std::optional<legacy_group_info> get_legacy_group(std::string_view pubkey_hex) const;

Parameters

  • pubkey_hex — group ID (hex, looks like a session ID)

Returns

  • std::optional<legacy_group_info> - Returns the filled out legacy_group_info struct if found

UserGroups::get_or_construct_community

Same as get_community, except if the community isn't found a new blank one is created for you, prefilled with the url/room/pubkey.

Declaration

community_info get_or_construct_community(
        std::string_view base_url,
        std::string_view room,
        std::string_view pubkey_encoded) const;
community_info get_or_construct_community(
        std::string_view base_url, std::string_view room, ustring_view pubkey) const;

Parameters

  • base_url — text string containing the base URL
  • room — is case-insensitive for the lookup: if a matching room is found then the returned value reflects the room case of the existing record, which is not necessarily the same as the room argument given here (to force a case change, set it within the returned object).
  • pubkey — is not used to find an existing community, but if the community found has a different pubkey from the one given then the returned record has its pubkey updated in the return instance (note that this changed value is not committed to storage, however, until the instance is passed to set()). For the string_view version the pubkey is accepted as hex, base32z, or base64.

Returns

  • community_info - Returns the filled out community_info struct

UserGroups::get_or_construct_community(string_view)

Shortcut to pass the url through community::parse_full_url, then call the above get_or_construct_community.

Declaration

community_info get_or_construct_community(std::string_view full_url) const;

Parameters

  • full_url — text string containing the full URL including pubkey

Returns

  • community_info - Returns the filled out community_info struct

UserGroups::get_or_construct_group

Gets or constructs a blank group_info for the given group id.

Declaration

group_info get_or_construct_group(std::string_view pubkey_hex) const;

Parameters

  • pubkey_hex — group ID (hex, looks like a session ID)

Returns

  • group_info - Returns the filled out group_info struct

UserGroups::get_or_construct_legacy_group

Gets or constructs a blank legacy_group_info for the given group id.

Declaration

legacy_group_info get_or_construct_legacy_group(std::string_view pubkey_hex) const;

Parameters

  • pubkey_hex — group ID (hex, looks like a session ID)

Returns

  • legacy_group_info - Returns the filled out legacy_group_info struct

UserGroups::set

Inserts or replaces existing group info. For example, to update the info for a community you would do: 

    auto info = conversations.get_or_construct_community(some_session_id);
    info.last_read = new_unix_timestamp;
    conversations.set(info);

Declaration

void set(const group_info& info);
void set(const community_info& info);
void set(const legacy_group_info& info);

Parameters

  • info — group info struct to insert. Can be community_info, group_info, or legacy_group_info.

Returns

UserGroups::size

Returns the number of groups (of any type).

Declaration

size_t size() const;

Parameters

This endpoint takes no inputs.

Returns

  • size_t - Returns the number of groups

UserGroups::size_communities

Returns the number of communities

Declaration

size_t size_communities() const;

Parameters

This endpoint takes no inputs.

Returns

  • size_t - Returns the number of groups

UserGroups::size_groups

Returns the number of (non-legacy) groups

Declaration

size_t size_groups() const;

Parameters

This endpoint takes no inputs.

Returns

  • size_t - Returns the number of groups

UserGroups::size_legacy_groups

Returns the number of legacy groups

Declaration

size_t size_legacy_groups() const;

Parameters

This endpoint takes no inputs.

Returns

  • size_t - Returns the number of legacy groups

UserGroups::storage_namespace

Returns the Contacts namespace.

Declaration

Namespace storage_namespace() const override { return Namespace::UserGroups; }

Parameters

This endpoint takes no inputs.

Returns

  • Namespace - Returns Namespace::UserGroups

legacy_group_info::counts

Returns a pair of the number of admins, and regular members of this group. (If all you want is the overall number just use .members().size() instead).

Declaration

std::pair<size_t, size_t> counts() const;

Parameters

This endpoint takes no inputs.

Returns

  • std::pair<size_t, size_t> — Returns a pair of the counts of members of the group. Contains
  • size_t — number of admins
  • size_t — number of regular members

legacy_group_info::erase

Removes a member (by session id) from this group. Returns true if the member was removed, false if the member was not present.

Declaration

bool erase(const std::string& session_id);

Parameters

  • session_id — Hex string of the Session ID

Returns

  • bool — Returns true if the member was found and removed, false otherwise

legacy_group_info::insert

Adds a member (by session id and admin status) to this group. Returns true if the member was inserted or changed admin status, false if the member already existed. Throws std::invalid_argument if the given session id is invalid.

Declaration

bool insert(std::string session_id, bool admin);

Parameters

  • session_id — Hex string of the Session ID
  • admin — boolean if the user is to have admin powers

Returns

  • bool — Returns true if the member was inserted or changed, otherwise false.

legacy_group_info::members

Accesses the session ids (in hex) of members of this group. The key is the hex session_id; the value indicates whether the member is an admin (true) or not (false).

Declaration

const std::map<std::string, bool>& members() const { return members_; }

Parameters

This endpoint takes no inputs.

Returns

  • std::map<std::string, bool>& — Returns a reference to the members of the group. Contains
  • std::string — Hex Session ID
  • bool — Whether the member is an admin (true)