Contacts

`contacts_erase`

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

Declaration

BOOL contacts_erase(
    [in, out]   config_object*  conf,
    [in]    const char*     session_id
);

Parameters

conf — [in, out] Pointer to the config object
session_id — [in] Text containing null terminated hex string

Returns

bool — True if erasing was successful

`contacts_get`

Fills contact with the contact info given a session ID (specified as a null-terminated hex string), if the contact exists, and returns true. If the contact does not exist then contact is left unchanged and false is returned.

Declaration

BOOL contacts_get(
    [in]    config_object*      conf,
    [out]   contacts_contact*   contact,
    [in]    const char*         session_id
);

Parameters

conf — [in] Pointer to the config object
contact — [out] the contact info data
session_id — [in] null terminated hex string

Returns

bool — Returns true if contact exsts

`contacts_get_or_construct`

Same as the above contacts_get() except that when the contact does not exist, this sets all the contact fields to defaults and loads it with the given session_id.

Returns true as long as it is given a valid session_id. A false return is considered an error, and means the session_id was not a valid session_id.

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

Declaration

BOOL contacts_get_or_construct(
    [in]    config_object*      conf,
    [out]   contacts_contact*   contact,
    [in]    const char*         session_id
);

Parameters

conf — [in] Pointer to the config object
contact — [out] the contact info data
session_id — [in] null terminated hex string

Returns

bool — Returns true if contact exsts

`contacts_init`

Constructs a contacts config object and sets a pointer to it in conf.

When done with the object the config_object must be destroyed by passing the pointer to config_free() (in session/config/base.h).

Declaration

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

Parameters

conf — [out] Pointer to the config object
ed25519_secretkey — [in] must be the 32-byte secret key seed value. (You can also pass the pointer to the beginning of the 64-byte value libsodium calls the "secret key" as the first 32 bytes of that are the seed). This field cannot be null.
dump — [in] if non-NULL this restores the state from the dumped byte string produced by a past instantiation's call to dump(). To construct a new, empty object this should be NULL.
dumplen — [in] the length of dump when restoring from a dump, or 0 when dump is NULL.
error — [out] the pointer to a buffer in which we will write an error string if an error occurs; error messages are discarded if this is given as NULL. If non-NULL this must be a buffer of at least 256 bytes.

Returns

int — Returns 0 on success; returns a non-zero error code and write the exception message as a C-string into error (if not NULL) on failure.

`contacts_iterator_advance`

Advances the iterator.

Declaration

VOID contacts_iterator_advance(
    [in]    contacts_iterator*  it
);

Parameters

it — [in] Pointer to the contacts_iterator

Returns

`contacts_iterator_done`

Returns true if iteration has reached the end. Otherwise c is populated and false is returned.

Declaration

BOOL contacts_iterator_done(
    [in]    contacts_iterator*  it,
    [out]   contacts_contact*   c
);

Parameters

it — [in] Pointer to the contacts_iterator
c — [out] Pointer to the contact, will be populated if false

Returns

bool — True if iteration has reached the end

`contacts_iterator_free`

Frees an iterator once no longer needed.

Declaration

VOID contacts_iterator_free(
    [in]   contacts_iterator*   it
);

Parameters

it — [in] Pointer to the contacts_iterator

Returns

`contacts_iterator_new`

Starts a new iterator.

Functions for iterating through the entire contact list, in sorted order. Intended use is:

contacts_contact c;
contacts_iterator *it = contacts_iterator_new(contacts);
for (; !contacts_iterator_done(it, &c); contacts_iterator_advance(it)) {
    // c.session_id, c.nickname, etc. are loaded
}
contacts_iterator_free(it);

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

Declaration

CONTACTS_ITERATOR* contacts_iterator_new(
    [in]   const config_object*  conf
);

Parameters

conf — [in] Pointer to the config object

Returns

contacts_iterator* — pointer to the iterator

`contacts_set`

Adds or updates a contact from the given contact info struct.

Declaration

VOID contacts_set(
    [in, out]   config_object*              conf,
    [in]        const contacts_contact*     contact
);

Parameters

conf — [in, out] Pointer to the config object
contact — [in] Pointer containing the contact info data

Returns

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

`contacts_size`

Returns the number of contacts.

Declaration

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

Parameters

conf — input - Pointer to the config object

Returns

size_t — number of contacts