Skip to content

Convo Info Volatile

ConvoInfoVolatile::ConvoInfoVolatile

Constructs a conversation 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

ConvoInfoVolatile(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

ConvoInfoVolatile::begin

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

    for (auto& convo : conversations) {
        if (const auto* dm = std::get_if<convo::one_to_one>(&convo)) {
            // use dm->session_id, dm->last_read, etc.
        } else if (const auto* og = std::get_if<convo::community>(&convo)) {
            // use og->base_url, og->room, om->last_read, etc.
        } else if (const auto* cg = std::get_if<convo::group>(&convo)) {
            // use cg->id, cg->last_read
        } else if (const auto* lcg = std::get_if<convo::legacy_group>(&convo)) {
            // use lcg->id, lcg->last_read
        }
    }

This iterates through all conversations in sorted order (sorted first by convo type, then by id within the type).

The begin_TYPE() versions of the iterator return an iterator that loops only through the given TYPE of conversations. (The .end() iterator works for all the iterator variations).

It is NOT permitted to add/modify/remove records while iterating; performing modifications based on a condition requires two passes: one to collect the required changes, and another to apply them key by key.

Declaration

iterator begin() const;
subtype_iterator<convo::one_to_one> begin_1to1() const;
subtype_iterator<convo::community> begin_communities() const;
subtype_iterator<convo::group> begin_groups() const;
subtype_iterator<convo::legacy_group> begin_legacy_groups() const;

Parameters

This endpoint takes no inputs.

Returns

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

ConvoInfoVolatile::empty

Returns true if the conversation list is empty.

Declaration

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

Parameters

This endpoint takes no inputs.

Returns

  • bool — Returns true if the convesation list is empty

ConvoInfoVolatile::encryption_domain

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

Declaration

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

Parameters

This endpoint takes no inputs.

Returns

  • const char* - Will return "ConvoInfoVolatile"

ConvoInfoVolatile::end

Iterator for passing the end of the conversations. This works for both the all-convo iterator (begin()) and the type-specific iterators (e.g. begin_groups()).

Declaration

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

Parameters

This endpoint takes no inputs.

Returns

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

ConvoInfoVolatile::erase

Removes a conversation taking the convo::whatever record (rather than the pubkey/url).

Declaration

bool erase(const convo::one_to_one& c);
bool erase(const convo::community& c);
bool erase(const convo::legacy_group& c);
bool erase(const convo::any& c);  // Variant of any of them

Parameters

  • c — Any contact, group or community

Returns

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

ConvoInfoVolatile::erase_1to1

Removes a one-to-one conversation. Returns true if found and removed, false if not present.

Declaration

bool erase_1to1(std::string_view pubkey);

Parameters

  • pubkey — hex session id

Returns

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

ConvoInfoVolatile::erase_community

Removes a community conversation record. 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 — String of the base URL
  • room — String of the room

Returns

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

ConvoInfoVolatile::erase_group

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

Declaration

bool erase_group(std::string_view pubkey_hex);

Parameters

  • pubkey_hex — String of the group pubkey

Returns

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

ConvoInfoVolatile::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 — String of the legacy groups pubkey

Returns

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

ConvoInfoVolatile::get_1to1

Looks up and returns a contact by session ID (hex). Returns nullopt if the session ID was not found, otherwise returns a filled out convo::one_to_one.

Declaration

std::optional<convo::one_to_one> get_1to1(std::string_view session_id) const;

Parameters

  • session_id — Hex string of the Session ID

Returns

  • std::optional<convo::one_to_one> - Returns a contact

ConvoInfoVolatile::get_community

Looks up and returns a community conversation. Takes the base URL and room name (case insensitive). Retuns nullopt if the community was not found, otherwise a filled out convo::community.

Declaration

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

Parameters

  • base_url — String of the base URL
  • room — String of the room

Returns

  • std::optional<convo::community> - Returns a community

ConvoInfoVolatile::get_community(partial_url)

Shortcut for calling community::parse_partial_url then calling the above with the base url and room. The URL is not required to contain the pubkey (if present it will be ignored).

Declaration

std::optional<convo::community> get_community(std::string_view partial_url) const;

Parameters

  • partial_url — String of the partial URL

Returns

  • std::optional<convo::community> - Returns a community

ConvoInfoVolatile::get_group

Looks up and returns a group conversation by ID. The ID is a 66-character hex string beginning with "03". Returns nullopt if there is no record of the group conversation.

Declaration

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

Parameters

  • pubkey_hex — Hex string of the group ID

Returns

  • std::optional<convo::group> - Returns a group

ConvoInfoVolatile::get_legacy_group

Looks up and returns a legacy group conversation by ID. The ID looks like a hex Session ID, but isn't really a Session ID. Returns nullopt if there is no record of the group conversation.

Declaration

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

Parameters

  • pubkey_hex — Hex string of the legacy group Session ID

Returns

  • std::optional<convo::legacy_group> - Returns a group

ConvoInfoVolatile::get_or_construct_1to1

These are the same as the above get methods (without "_or_construct" in the name), except that when the conversation doesn't exist a new one is created, prefilled with the pubkey/url/etc.

Declaration

convo::one_to_one get_or_construct_1to1(std::string_view session_id) const;

Parameters

  • session_id — Hex string Session ID

Returns

  • convo::one_to_one - Returns a contact

ConvoInfoVolatile::get_or_construct_community

This is similar to get_community, except that it also takes the pubkey; the community is looked up by the url & room; if not found, it is constructed using room, url, and pubkey; if it is found, then it will always have the input pubkey, not the stored pubkey (effectively the provided pubkey replaces the stored one in the returned object; this is not applied to storage, however, unless/until the instance is given to set()).

Note, however, that when modifying an object like this the update is only applied to the returned object; like other fields, it is not updated in the internal state unless/until that community instance is passed to set().

Declaration

convo::community get_or_construct_community(
        std::string_view base_url, std::string_view room, std::string_view pubkey_hex)
        const;
convo::community get_or_construct_community(
        std::string_view base_url, std::string_view room, ustring_view pubkey) const;

Parameters

  • base_url — String of the base URL
  • room — String of the room
  • pubkey — Pubkey either as a hex string or binary

Returns

  • convo::community - Returns a group

ConvoInfoVolatile::get_or_construct_community(full_url)

Shortcut for calling community::parse_full_url then calling the above get_or_construct_community`

Declaration

convo::community get_or_construct_community(std::string_view full_url) const;

Parameters

  • full_url — String of the full URL

Returns

  • convo::community - Returns a group

ConvoInfoVolatile::get_or_construct_group

These are the same as the above get methods (without "_or_construct" in the name), except that when the conversation doesn't exist a new one is created, prefilled with the pubkey/url/etc.

Declaration

convo::group get_or_construct_group(std::string_view pubkey_hex) const;

Parameters

  • pubkey_hex — Hex string pubkey

Returns

  • convo::group - Returns a group

ConvoInfoVolatile::get_or_construct_legacy_group

These are the same as the above get methods (without "_or_construct" in the name), except that when the conversation doesn't exist a new one is created, prefilled with the pubkey/url/etc.

Declaration

convo::legacy_group get_or_construct_legacy_group(std::string_view pubkey_hex) const;

Parameters

  • pubkey_hex — Hex string pubkey

Returns

  • convo::legacy_group - Returns a group

ConvoInfoVolatile::prune_stale

Prunes any "stale" conversations: that is, ones with a last read more than prune ago that are not specifically "marked as unread" by the client.

This method is called automatically by push() and does not typically need to be invoked directly.

Declaration

void prune_stale(std::chrono::milliseconds prune = PRUNE_HIGH);

Parameters

  • prune the "too old" time; any conversations with a last_read time more than this duration ago will be removed (unless they have the explicit unread flag set). If omitted, defaults to the PRUNE_HIGH constant (45 days).

Returns

  • returns nothing.

ConvoInfoVolatile::push

Overrides push() to prune stale last-read values before we do the push.

Declaration

std::tuple<seqno_t, ustring, std::vector<std::string>> push() override;

Parameters

This endpoint takes no inputs.

Returns

  • std::tuple<seqno_t, ustring, std::vector<std::string>> - Returns a tuple containing
  • seqno_t — sequence number
  • ustring — data message to push to the server
  • std::vector<std::string> — list of known message hashes

ConvoInfoVolatile::set

Inserts or replaces existing conversation info. For example, to update a 1-to-1 conversation last read time you would do:

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

Declaration

void set(const convo::one_to_one& c);
void set(const convo::group& c);
void set(const convo::legacy_group& c);
void set(const convo::community& c);
void set(const convo::any& c);  // Variant which can be any of the above

Parameters

  • c — struct containing any contact, community or group

Returns

ConvoInfoVolatile::size

Returns the number of conversations, if size() is called it will return the total of any conversations. Utilising the other functions to get specific counts of 1-to-1, community and legacy group converstations.

Declaration

size_t size() const;
size_t size_1to1() const;
size_t size_communities() const;
size_t size_groups() const;
size_t size_legacy_groups() const;

Parameters

This endpoint takes no inputs.

Returns

  • size_t - Returns the number of conversations

ConvoInfoVolatile::storage_namespace

Returns the ConvoInfoVolatile namespace. Is constant, will always return 4

Declaration

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

Parameters

This endpoint takes no inputs.

Returns

  • Namespace - Will return 4

community::community

Internal ctor/method for C API implementations:

Declaration

community(const convo_info_volatile_community& c);  // From c struct

Parameters

  • c — From c struct

Returns

group::group

Constructs an empty group from an id

Declaration

explicit group(std::string&& group_id);

Parameters

  • group_id — hex string of group_id, 66 hex bytes starting with "03"

Returns

legacy_group::legacy_group

Constructs an empty legacy_group from a quasi-session_id

Declaration

explicit legacy_group(std::string&& group_id);
explicit legacy_group(std::string_view group_id);

Parameters

  • group_id — hex string of group_id, similar to a session_id

Returns

one_to_one::one_to_one

Constructs an empty one_to_one from a session_id. Session ID can be either bytes (33) or hex (66).

Declaration

explicit one_to_one(std::string&& session_id);
explicit one_to_one(std::string_view session_id);

Parameters

  • session_id — Hex string of the session id

Returns