Contacts
Contacts::Contacts
Constructs a contact 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
Contacts(
std::span<const unsigned char> ed25519_secretkey,
std::optional<std::span<const unsigned char>> 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— eitherstd::nulloptto construct a new, empty object; or binary state data that was previously dumped from an instance of this class by callingdump().
Returns
Contact- Constructor
Contacts::blinded
Retrieves a list of all known blinded contacts.
Declaration
Parameters
This endpoint takes no inputs.
Returns
std::vector<blinded_contact_info>- Returns a list of blinded_contact_info
Contacts::encryption_domain
Returns the domain. Is constant, will always return "Contacts"
Declaration
Parameters
This endpoint takes no inputs.
Returns
const char*- Will return "Contacts"
Contacts::get
Looks up and returns a contact by session ID (hex). Returns nullopt if the session ID was
not found, otherwise returns a filled out contact_info.
Declaration
Parameters
pubkey_hex— hex string of the session id
Returns
std::optional<contact_info>- Returns nullopt if session ID was not found, otherwise a filled out contact_info
Contacts::get_blinded
Looks up and returns a blinded contact by blinded session ID (hex). Returns nullopt if the
blinded session ID was not found, otherwise returns a filled out blinded_contact_info.
Declaration
Parameters
blinded_id_hex— hex string of the session id
Returns
std::optional<blinded_contact_info>- Returns nullopt if blinded session ID was not found, otherwise a filled out blinded_contact_info
Contacts::get_or_construct
Similar to get(), but if the session ID does not exist this returns a filled-out
contact_info containing the session_id (all other fields will be empty/defaulted). This is
intended to be combined with set to set-or-create a record.
NB: calling this does not add the session id to the contact list when called: that
requires also calling set with this value.
Declaration
Parameters
pubkey_hex— hex string of the session id
Returns
contact_info- Returns a filled out contact_info
Contacts::get_or_construct_blinded
Similar to get_blinded(), but if the blinded ID does not exist this returns a filled-out
blinded_contact_info containing the blinded_id, community info and legacy_blinded flag (all
other fields will be empty/defaulted). This is intended to be combined with set_blinded
to set-or-create a record.
NB: calling this does not add the blinded id to the blinded list when called: that
requires also calling set_blinded with this value.
Declaration
blinded_contact_info get_or_construct_blinded(
std::string_view community_base_url,
std::string_view community_pubkey_hex,
std::string_view blinded_id_hex);
Parameters
community_base_url— String of the base URL for the community this blinded id originates fromcommunity_pubkey_hex— Hex string of the public key for the community this blinded id originates fromblinded_id_hex— hex string of the blinded id
Returns
blinded_contact_info- Returns a filled out blinded_contact_info
Contacts::storage_namespace
Returns the Contacts namespace. Is constant, will always return 3
Declaration
Parameters
This endpoint takes no inputs.
Returns
Namespace- Will return 3
blinded_contact_info::community_base_url
Accesses the base url for the community (i.e. not including room or pubkey). Always lower-case/normalized.
Declaration
Parameters
This endpoint takes no inputs.
Returns
const std::string&— Returns the base url
blinded_contact_info::community_pubkey
Accesses the community server pubkey (32 bytes).
Declaration
Parameters
This endpoint takes no inputs.
Returns
const std::vector<unsigned char>&— Returns the pubkey
blinded_contact_info::community_pubkey_hex
Accesses the community server pubkey as hex (64 hex digits).
Declaration
Parameters
This endpoint takes no inputs.
Returns
std::string— Returns the pubkey
blinded_contact_info::into
converts the contact info into a c struct
Declaration
Parameters
c— Return Parameter that will be filled with data in blinded_contact_info
Returns
blinded_contact_info::set_name
Sets a name; this is exactly the same as assigning to .name directly, except that we throw an exception if the given name is longer than MAX_NAME_LENGTH.
Declaration
Parameters
name— Name to assign to the contact
Returns
contact_info::into
converts the contact info into a c struct
Declaration
Parameters
c— Return Parameter that will be filled with data in contact_info
Returns
contact_info::set_name
Sets a name or nickname; this is exactly the same as assigning to .name/.nickname directly, except that we throw an exception if the given name is longer than MAX_NAME_LENGTH.
Declaration
Parameters
name— Name to assign to the contact
Returns
contacts::begin
Iterators for iterating through all contacts. Typically you access this implicit via a for
loop over the Contacts object:
This iterates in sorted order through the session_ids.
It is NOT permitted to add/modify/remove records while iterating; instead such modifications require two passes: an iterator loop to collect the required modifications, then a second pass to apply the modifications.
Declaration
Parameters
This endpoint takes no inputs.
Returns
iterator- Returns an iterator for the beginning of the contacts
contacts::empty
Returns true if the contact list is empty.
Declaration
Parameters
This endpoint takes no inputs.
Returns
bool- Returns true if the contact list is empty
contacts::end
Iterator for passing the end of the contacts
Declaration
Parameters
This endpoint takes no inputs.
Returns
iterator- Returns an iterator for the end of the contacts
contacts::erase
Removes a contact, if present. Returns true if it was found and removed, false otherwise. Note that this removes all fields related to a contact, even fields we do not know about.
Declaration
Parameters
session_id— hex string of the session id
Returns
bool- Returns true if contact was found and removed, false otherwise
contacts::erase_blinded
Removes a blinded contact, if present. Returns true if it was found and removed, false otherwise. Note that this removes all fields related to a blinded contact, even fields we do not know about.
Declaration
Parameters
base_url— the base url for the community this blinded contact originated fromblinded_id— hex string of the blinded id
Returns
bool- Returns true if contact was found and removed, false otherwise
contacts::set
Sets or updates multiple contact info values at once with the given info. The usual use is to access the current info, change anything desired, then pass it back into set_contact, e.g.:
auto c = contacts.get_or_construct(pubkey);
c.name = "Session User 42";
c.nickname = "BFF";
contacts.set(c);
Declaration
Parameters
contact— contact_info value to set
Returns
contacts::set_approved
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idapproved— boolean on whether the contact is approved by me (to send messages to me)
Returns
contacts::set_approved_me
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idapproved_me— boolean on whether the contact has approved the user (so we can send messages to them)
Returns
contacts::set_blinded
Sets or updates multiple blinded contact info values at once with the given info. The usual use is to access the current info, change anything desired, then pass it back into set_blinded, e.g.:
auto c = contacts.get_blinded(pubkey, legacy_blinding);
c.name = "Session User 42";
contacts.set_blinded(c);
Declaration
Parameters
bc— set_blinded value to set
Returns
contacts::set_blocked
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idblocked— boolean on whether the contact is blocked by us
Returns
contacts::set_created
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idtimestamp— standard unix timestamp of the time contact was created
Returns
contacts::set_expiry
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
void set_expiry(
std::string_view session_id,
expiration_mode exp_mode,
std::chrono::seconds expiration_timer = 0min);
Parameters
session_id— hex string of the session idexp_mode— detail on expirationsexpiration_timer— how long the expiration timer should be, defaults to zero
Returns
contacts::set_name
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idname— string of the contacts name
Returns
contacts::set_nickname
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idnickname— string of the contacts nickname
Returns
contacts::set_nickname_truncated
Alternative to set() for setting a single field. The same as set_name except truncates
the value when it's too long. (If setting multiple fields at once you should use set()
instead).
Declaration
Parameters
session_id— hex string of the session idnickname— string of the contacts nickname
Returns
contacts::set_notifications
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idnotifications— detail on notifications
Returns
contacts::set_priority
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idpriority— numerical value on the contacts priority (pinned, normal, hidden etc)
Returns
contacts::set_profile_pic
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idprofile_pic— profile pic of the contact
Returns
contacts::set_profile_updated
Alternative to set() for setting a single field. (If setting multiple fields at once you
should use set() instead).
Declaration
Parameters
session_id— hex string of the session idprofile_updated— profile updated unix timestamp (seconds) of the contact. (To convert a raw s/ms/µs integer value, use session::to_sys_seconds).
Returns
contacts::size
Returns the number of contacts.
Declaration
Parameters
This endpoint takes no inputs.
Returns
size_t- Returns the number of contacts