Convo Info Volatile

`convo_info_volatile_erase_1to1`

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

Declaration

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

Parameters

conf — [in] Pointer to the config object
convo — [in] Pointer to community info structure

Returns

bool - Returns true if conversation was found and removed

`convo_info_volatile_erase_community`

Erases a community. Returns true if the community was found and removed, false if the community was not present. You must not call this during iteration.

Declaration

BOOL convo_info_volatile_erase_community(
    [in]    config_object*  conf,
    [in]    const char*     base_url,
    [in]    const char*     room
);

Parameters

conf — [in] Pointer to the config object
base_url — [in] Null terminated string
room — [in] Null terminated string

Returns

bool - Returns true if community was found and removed

`convo_info_volatile_erase_group`

Erases a group. Returns true if the group was found and removed, false if the group was not present. You must not call this during iteration.

Declaration

BOOL convo_info_volatile_erase_group(
    [in]    config_object*  conf,
    [in]    const char*     group_id
);

Parameters

conf — [in] Pointer to the config object
group_id — [in] Null terminated hex string

Returns

bool - Returns true if group was found and removed

`convo_info_volatile_erase_legacy_group`

Erases a legacy group. Returns true if the group was found and removed, false if the group was not present. You must not call this during iteration.

Declaration

BOOL convo_info_volatile_erase_legacy_group(
    [in]    config_object*  conf,
    [in]    const char*     group_id
);

Parameters

conf — [in] Pointer to the config object
group_id — [in] Null terminated hex string

Returns

bool - Returns true if group was found and removed

`convo_info_volatile_get_1to1`

Fills convo with the conversation info given a session ID (specified as a null-terminated hex string), if the conversation exists, and returns true. If the conversation does not exist then convo is left unchanged and false is returned. If an error occurs, false is returned and conf->last_error will be set to non-NULL containing the error string (if no error occurs, such as in the case where the conversation merely doesn't exist, last_error will be set to NULL).

Declaration

BOOL convo_info_volatile_get_1to1(
    [in]    config_object*              conf,
    [out]   convo_info_volatile_1to1*   convo,
    [in]    const char*                 session_id
);

Parameters

conf — [in] Pointer to the config object
convo — [out] Pointer to conversation info
session_id — [in] Null terminated hex string of the session_id

Returns

bool - Returns true if the conversation exists

`convo_info_volatile_get_community`

community versions of the 1-to-1 functions:

Gets a community convo info. base_url and room are null-terminated c strings. base_url and room will always be lower-cased (if not already).

Error handling works the same as the 1-to-1 version.

Declaration

BOOL convo_info_volatile_get_community(
    [in]    config_object*                  conf,
    [out]   convo_info_volatile_community*  comm,
    [in]    const char*                     base_url,
    [in]    const char*                     room
);

Parameters

conf — [in] Pointer to the config object
comm — [out] Pointer to community info structure
base_url — [in] Null terminated string
room — [in] Null terminated string

Returns

bool - Returns true if the community exists

`convo_info_volatile_get_group`

Fills convo with the conversation info given a group ID (specified as a null-terminated hex string), if the conversation exists, and returns true. If the conversation does not exist then convo is left unchanged and false is returned. On error, false is returned and the error is set in conf->last_error (on non-error, last_error is cleared).

Declaration

BOOL convo_info_volatile_get_group(
    [in]    config_object*               conf,
    [out]   convo_info_volatile_group*   convo,
    [in]    const char*                  id
);

Parameters

conf — [in] Pointer to the config object
convo — [out] Pointer to group
id — [in] Null terminated hex string (66 chars, beginning with 03) specifying the ID of the group

Returns

bool - Returns true if the group exists

`convo_info_volatile_get_legacy_group`

Fills convo with the conversation info given a legacy group ID (specified as a null-terminated hex string), if the conversation exists, and returns true. If the conversation does not exist then convo is left unchanged and false is returned. On error, false is returned and the error is set in conf->last_error (on non-error, last_error is cleared).

Declaration

BOOL convo_info_volatile_get_legacy_group(
    [in]    config_object*                      conf,
    [out]   convo_info_volatile_legacy_group*   convo,
    [in]    const char*                         id
);

Parameters

conf — [in] Pointer to the config object
convo — [out] Pointer to legacy group
id — [in] Null terminated hex string specifying the ID of the legacy group

Returns

bool - Returns true if the legacy group exists

`convo_info_volatile_get_or_construct_1to1`

Same as the above convo_info_volatile_get_1to1 except that when the conversation does not exist, this sets all the convo 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. In such a case conf->last_error will be set to an error string.

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

Declaration

BOOL convo_info_volatile_get_or_construct_1to1(
    [in]    config_object*              conf,
    [out]   convo_info_volatile_1to1*   convo,
    [in]    const char*                 session_id
);

Parameters

conf — [in] Pointer to the config object
convo — [out] Pointer to conversation info
session_id — [in] Null terminated hex string of the session_id

Returns

bool - Returns true if the conversation exists

`convo_info_volatile_get_or_construct_community`

Gets a community convo info, but if the community does not exist will set all the fileds to defaults and load it. base_url and room are null-terminated c strings; pubkey is 32 bytes. base_url and room will always be lower-cased (if not already).

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().

Error handling works the same as the 1-to-1 version.

Declaration

BOOL convo_info_volatile_get_or_construct_community(
    [in]    config_object*                  conf,
    [out]   convo_info_volatile_community*  comm,
    [in]    const char*                     base_url,
    [in]    const char*                     room,
    [in]    unsigned const char*            pubkey
);

Parameters

conf — [in] Pointer to the config object
convo — [out] Pointer to community info structure
base_url — [in] Null terminated string
room — [in] Null terminated string
pubkey — [in] 32 byte binary data of the pubkey

Returns

bool - Returns true if the call succeeds

`convo_info_volatile_get_or_construct_group`

Same as the above except that when the conversation does not exist, this sets all the convo fields to defaults and loads it with the given id.

Returns true as long as it is given a valid group id (i.e. 66 hex chars beginning with "03"). A false return is considered an error, and means the id was not a valid session id; an error string will be set in conf->last_error.

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

Declaration

BOOL convo_info_volatile_get_or_construct_group(
    [in]    config_object*               conf,
    [out]   convo_info_volatile_group*   convo,
    [in]    const char*                  id
);

Parameters

conf — [in] Pointer to the config object
convo — [out] Pointer to group
id — [in] Null terminated hex string specifying the ID of the group

Returns

bool - Returns true if the call succeeds

`convo_info_volatile_get_or_construct_legacy_group`

Same as the above except that when the conversation does not exist, this sets all the convo fields to defaults and loads it with the given id.

Returns true as long as it is given a valid legacy group id (i.e. same format as a session id). A false return is considered an error, and means the id was not a valid session id; an error string will be set in conf->last_error.

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

Declaration

BOOL convo_info_volatile_get_or_construct_legacy_group(
    [in]    config_object*                      conf,
    [out]   convo_info_volatile_legacy_group*   convo,
    [in]    const char*                         id
);

Parameters

conf — [in] Pointer to the config object
convo — [out] Pointer to legacy group
id — [in] Null terminated hex string specifying the ID of the legacy group

Returns

bool - Returns true if the call succeeds

`convo_info_volatile_init`

Constructs a conversations 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 convo_info_volatile_init(
    [out]           config_object**     conf,
    [in]            unsigned char*      ed25519_secretkey,
    [in, optional]  unsigned char*      dump,
    [in, optional]  size_t              dumplen,
    [out]           char*               error
);

Parameters

ed25519_secretkey — [out] 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, optional] 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, optional] 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.

`convo_info_volatile_it_is_1to1`

If the current iterator record is a 1-to-1 conversation this sets the details into c and returns true. Otherwise it returns false.

Declaration

BOOL convo_info_volatile_it_is_1to1(
    [in]    convo_info_volatile_iterator*   it,
    [out]   convo_info_volatile_1to1*       c
);

Parameters

it — [in] The convo_info_volatile_iterator
c — [out] Pointer to the convo_info_volatile, will be populated if true

Returns

bool — True if the record is a 1-to-1 conversation

`convo_info_volatile_it_is_community`

Declaration

BOOL convo_info_volatile_it_is_community(
    [in]    convo_info_volatile_iterator*   it,
    [out]   convo_info_volatile_community*  c
);

If the current iterator record is a community conversation this sets the details into c and returns true. Otherwise it returns false.

Parameters

it — [in] The convo_info_volatile_iterator
c — [out] Pointer to the convo_info_volatile, will be populated if true

Returns

bool — True if the record is a community conversation

`convo_info_volatile_it_is_group`

If the current iterator record is a group conversation this sets the details into g and returns true. Otherwise it returns false.

Declaration

BOOL convo_info_volatile_it_is_group(
    [in]    convo_info_volatile_iterator*   it,
    [out]   convo_info_volatile_group*      g
);

Parameters

it — [in] The convo_info_volatile_iterator
c — [out] Pointer to the convo_info_volatile, will be populated if true

Returns

bool — True if the record is a group conversation

`convo_info_volatile_it_is_legacy_group`

If the current iterator record is a legacy group conversation this sets the details into c and returns true. Otherwise it returns false.

Declaration

BOOL convo_info_volatile_it_is_legacy_group(
    [in]    convo_info_volatile_iterator*     it,
    [out]   convo_info_volatile_legacy_group* c
);

Parameters

it — [in] The convo_info_volatile_iterator
c — [out] Pointer to the convo_info_volatile, will be populated if true

Returns

bool — True if the record is a legacy group conversation

`convo_info_volatile_iterator_advance`

Advances the iterator.

Declaration

VOID convo_info_volatile_iterator_advance(
    [in]    convo_info_volatile_iterator*   it
);

Parameters

it — [in] The convo_info_volatile_iterator

Returns

`convo_info_volatile_iterator_done`

Returns true if iteration has reached the end.

Declaration

BOOL convo_info_volatile_iterator_done(
    [in]    convo_info_volatile_iterator*   it
);

Parameters

it — [in] The convo_info_volatile_iterator

Returns

bool — True if iteration has reached the end

`convo_info_volatile_iterator_free`

Frees an iterator once no longer needed.

Declaration

VOID convo_info_volatile_iterator_free(
    [in]    convo_info_volatile_iterator*   it
);

Parameters

it — [in] The convo_info_volatile_iterator

Returns

`convo_info_volatile_iterator_new`

Starts a new iterator that iterates over all conversations.

Functions for iterating through the entire conversation list. Intended use is:

    convo_info_volatile_1to1 c1;
    convo_info_volatile_community c2;
    convo_info_volatile_group c3;
    convo_info_volatile_legacy_group c4;
    convo_info_volatile_iterator *it = convo_info_volatile_iterator_new(my_convos);
    for (; !convo_info_volatile_iterator_done(it); convo_info_volatile_iterator_advance(it)) {
        if (convo_info_volatile_it_is_1to1(it, &c1)) {
            // use c1.whatever
        } else if (convo_info_volatile_it_is_community(it, &c2)) {
            // use c2.whatever
        } else if (convo_info_volatile_it_is_group(it, &c3)) {
            // use c3.whatever
        } else if (convo_info_volatile_it_is_legacy_group(it, &c4)) {
            // use c4.whatever
        }
    }
    convo_info_volatile_iterator_free(it);

It is NOT permitted to add/modify/remove records while iterating; instead you must use two loops: a first one to identify changes, and a second to apply them.

Declaration

CONVO_INFO_VOLATILE_ITERATOR* convo_info_volatile_iterator_new(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to the config object

Returns

convo_info_volatile_iterator* — Iterator

`convo_info_volatile_iterator_new_1to1`

The same as convo_info_volatile_iterator_new except that this iterates only over one type of conversation. You still need to use convo_info_volatile_it_is_1to1 (or the alternatives) to load the data in each pass of the loop. (You can, however, safely ignore the bool return value of the it_is_whatever function: it will always be true for the particular type being iterated over).

Declaration

CONVO_INFO_VOLATILE_ITERATOR* convo_info_volatile_iterator_new_1to1(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to the config object

Returns

convo_info_volatile_iterator* — Iterator

`convo_info_volatile_iterator_new_communities`

The same as convo_info_volatile_iterator_new except that this iterates only over one type of conversation. You still need to use convo_info_volatile_it_is_1to1 (or the alternatives) to load the data in each pass of the loop. (You can, however, safely ignore the bool return value of the it_is_whatever function: it will always be true for the particular type being iterated over).

Declaration

CONVO_INFO_VOLATILE_ITERATOR* convo_info_volatile_iterator_new_communities(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to the config object

Returns

convo_info_volatile_iterator* — Iterator

`convo_info_volatile_iterator_new_groups`

The same as convo_info_volatile_iterator_new except that this iterates only over one type of conversation. You still need to use convo_info_volatile_it_is_group (or the alternatives) to load the data in each pass of the loop. (You can, however, safely ignore the bool return value of the it_is_whatever function: it will always be true for the particular type being iterated over).

Declaration

CONVO_INFO_VOLATILE_ITERATOR* convo_info_volatile_iterator_new_groups(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to the config object

Returns

convo_info_volatile_iterator* — Iterator

`convo_info_volatile_iterator_new_legacy_groups`

The same as convo_info_volatile_iterator_new except that this iterates only over one type of conversation. You still need to use convo_info_volatile_it_is_1to1 (or the alternatives) to load the data in each pass of the loop. (You can, however, safely ignore the bool return value of the it_is_whatever function: it will always be true for the particular type being iterated over).

Declaration

CONVO_INFO_VOLATILE_ITERATOR* convo_info_volatile_iterator_new_legacy_groups(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to the config object

Returns

convo_info_volatile_iterator* — Iterator

`convo_info_volatile_set_1to1`

Adds or updates a conversation from the given convo info

Declaration

VOID convo_info_volatile_set_1to1(
    [in]    config_object*                      conf,
    [in]    const convo_info_volatile_1to1*     convo
);

Parameters

conf — [in] Pointer to the config object
convo — [in] Pointer to conversation info structure

Returns

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

`convo_info_volatile_set_community`

Adds or updates a community from the given convo info

Declaration

VOID convo_info_volatile_set_community(
    [in]    config_object*                          conf,
    [in]    const convo_info_volatile_community*    convo
);

Parameters

conf — [in] Pointer to the config object
convo — [in] Pointer to community info structure

Returns

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

`convo_info_volatile_set_group`

Adds or updates a group from the given convo info

Declaration

VOID convo_info_volatile_set_group(
    [in]    config_object*                       conf,
    [in]    const convo_info_volatile_group*     convo
);

Parameters

conf — [in] Pointer to the config object
convo — [in] Pointer to group info structure

Returns

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

`convo_info_volatile_set_legacy_group`

Adds or updates a legacy group from the given convo info

Declaration

VOID convo_info_volatile_set_legacy_group(
    [in]    config_object*                              conf,
    [in]    const convo_info_volatile_legacy_group*     convo
);

Parameters

conf — [in] Pointer to the config object
convo — [in] Pointer to legacy group info structure

Returns

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

`convo_info_volatile_size`

Returns the number of conversations.

Declaration

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

Parameters

conf — [in] Pointer to the config object

Returns

size_t — number of conversations

`convo_info_volatile_size_1to1`

Returns the number of conversations.

Declaration

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

Parameters

conf — [in] Pointer to the config object

Returns

size_t — number of conversations

`convo_info_volatile_size_communities`

Returns the number of communitites.

Declaration

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

Parameters

conf — [in] Pointer to the config object

Returns

size_t — number of communities

`convo_info_volatile_size_groups`

Returns the number of groups.

Declaration

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

Parameters

conf — [in] Pointer to the config object

Returns

size_t — number of groups

`convo_info_volatile_size_legacy_groups`

Returns the number of legacy groups.

Declaration

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

Parameters

conf — [in] Pointer to the config object

Returns

size_t — number of legacy groups