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
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::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_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::storage_namespace
Returns the Contacts namespace. Is constant, will always return 3
Declaration
Parameters
This endpoint takes no inputs.
Returns
Namespace- Will return 3
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::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_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::size
Returns the number of contacts.
Declaration
Parameters
This endpoint takes no inputs.
Returns
size_t- Returns the number of contacts