Add by_id and get_id functions, renaming from *_uid.

`UID` sounds like `User ID`. While it is a Unique ID, the property of an
"identifier" is generally that it identifies a unique thing, so the 'U'
is redundant, and `GUID` as a globally unique id (which is likely also
true for these IDs) has a specific meaning and syntax, so we're not using
that. So, we just say conference `id`.
This commit is contained in:
iphydf 2018-07-23 21:04:50 +00:00
parent 051eb1d5a7
commit 1f27fcb5af
No known key found for this signature in database
GPG Key ID: 3855DBA2D74403C9
3 changed files with 125 additions and 8 deletions

View File

@ -245,9 +245,16 @@ const SECRET_KEY_SIZE = 32;
/**
* The size of a Tox Conference unique id in bytes.
*
* @deprecated Use $CONFERENCE_ID_SIZE instead.
*/
const CONFERENCE_UID_SIZE = 32;
/**
* The size of a Tox Conference unique id in bytes.
*/
const CONFERENCE_ID_SIZE = 32;
/**
* The size of the nospam in bytes when written in a Tox address.
*/
@ -2461,6 +2468,32 @@ namespace conference {
}
}
/**
* Get the conference unique ID.
*
* If id is NULL, this function has no effect.
*
* @param id A memory region large enough to store $CONFERENCE_ID_SIZE bytes.
*
* @return true on success.
*/
const bool get_id(uint32_t conference_number, uint8_t[CONFERENCE_ID_SIZE] id);
/**
* Return the conference number associated with the specified id.
*
* @param id A byte array containing the conference id ($CONFERENCE_ID_SIZE).
*
* @return the conference number on success, an unspecified value on failure.
*/
const uint32_t by_id(const uint8_t[CONFERENCE_ID_SIZE] id) {
NULL,
/**
* No conference with the given id exists on the conference list.
*/
NOT_FOUND,
}
/**
* Get the conference unique ID.
*
@ -2469,6 +2502,7 @@ namespace conference {
* @param uid A memory region large enough to store $CONFERENCE_UID_SIZE bytes.
*
* @return true on success.
* @deprecated use $get_id instead (exactly the same function, just renamed).
*/
const bool get_uid(uint32_t conference_number, uint8_t[CONFERENCE_UID_SIZE] uid);
@ -2478,6 +2512,7 @@ namespace conference {
* @param uid A byte array containing the conference id ($CONFERENCE_UID_SIZE).
*
* @return the conference number on success, an unspecified value on failure.
* @deprecated use $by_id instead (exactly the same function, just renamed).
*/
const uint32_t by_uid(const uint8_t[CONFERENCE_UID_SIZE] uid) {
NULL,
@ -2678,6 +2713,7 @@ typedef TOX_ERR_FILE_SEND_CHUNK Tox_Err_File_Send_Chunk;
typedef TOX_ERR_CONFERENCE_NEW Tox_Err_Conference_New;
typedef TOX_ERR_CONFERENCE_DELETE Tox_Err_Conference_Delete;
typedef TOX_ERR_CONFERENCE_PEER_QUERY Tox_Err_Conference_Peer_Query;
typedef TOX_ERR_CONFERENCE_BY_ID Tox_Err_Conference_By_Id;
typedef TOX_ERR_CONFERENCE_BY_UID Tox_Err_Conference_By_Uid;
typedef TOX_ERR_CONFERENCE_INVITE Tox_Err_Conference_Invite;
typedef TOX_ERR_CONFERENCE_JOIN Tox_Err_Conference_Join;

View File

@ -1457,31 +1457,60 @@ Tox_Conference_Type tox_conference_get_type(const Tox *tox, uint32_t conference_
return (Tox_Conference_Type)ret;
}
bool tox_conference_get_uid(const Tox *tox, uint32_t conference_number, uint8_t *uid /* TOX_CONFERENCE_ID_SIZE bytes */)
bool tox_conference_get_id(const Tox *tox, uint32_t conference_number, uint8_t *id /* TOX_CONFERENCE_ID_SIZE bytes */)
{
const Messenger *m = tox;
return conference_get_uid((Group_Chats *)m->conferences_object, conference_number, uid);
return conference_get_uid((Group_Chats *)m->conferences_object, conference_number, id);
}
uint32_t tox_conference_by_uid(const Tox *tox, const uint8_t *uid, Tox_Err_Conference_By_Uid *error)
// TODO(iphydf): Delete in 0.3.0.
bool tox_conference_get_uid(const Tox *tox, uint32_t conference_number, uint8_t *uid /* TOX_CONFERENCE_ID_SIZE bytes */)
{
if (!uid) {
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_UID_NULL);
return tox_conference_get_id(tox, conference_number, uid);
}
uint32_t tox_conference_by_id(const Tox *tox, const uint8_t *id, Tox_Err_Conference_By_Id *error)
{
if (!id) {
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_ID_NULL);
return UINT32_MAX;
}
const Messenger *m = tox;
int32_t ret = conference_by_uid((Group_Chats *)m->conferences_object, uid);
int32_t ret = conference_by_uid((Group_Chats *)m->conferences_object, id);
if (ret == -1) {
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_UID_NOT_FOUND);
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_ID_NOT_FOUND);
return UINT32_MAX;
}
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_UID_OK);
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_ID_OK);
return ret;
}
// TODO(iphydf): Delete in 0.3.0.
uint32_t tox_conference_by_uid(const Tox *tox, const uint8_t *uid, Tox_Err_Conference_By_Uid *error)
{
Tox_Err_Conference_By_Id id_error;
const uint32_t res = tox_conference_by_id(tox, uid, &id_error);
switch (id_error) {
case TOX_ERR_CONFERENCE_BY_ID_OK:
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_UID_OK);
break;
case TOX_ERR_CONFERENCE_BY_ID_NULL:
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_UID_NULL);
break;
case TOX_ERR_CONFERENCE_BY_ID_NOT_FOUND:
SET_ERROR_PARAMETER(error, TOX_ERR_CONFERENCE_BY_UID_NOT_FOUND);
break;
}
return res;
}
static void set_custom_packet_error(int ret, Tox_Err_Friend_Custom_Packet *error)
{
switch (ret) {

View File

@ -250,11 +250,20 @@ uint32_t tox_secret_key_size(void);
/**
* The size of a Tox Conference unique id in bytes.
*
* @deprecated Use TOX_CONFERENCE_ID_SIZE instead.
*/
#define TOX_CONFERENCE_UID_SIZE 32
uint32_t tox_conference_uid_size(void);
/**
* The size of a Tox Conference unique id in bytes.
*/
#define TOX_CONFERENCE_ID_SIZE 32
uint32_t tox_conference_id_size(void);
/**
* The size of the nospam in bytes when written in a Tox address.
*/
@ -2814,6 +2823,46 @@ typedef enum TOX_ERR_CONFERENCE_GET_TYPE {
TOX_CONFERENCE_TYPE tox_conference_get_type(const Tox *tox, uint32_t conference_number,
TOX_ERR_CONFERENCE_GET_TYPE *error);
/**
* Get the conference unique ID.
*
* If id is NULL, this function has no effect.
*
* @param id A memory region large enough to store TOX_CONFERENCE_ID_SIZE bytes.
*
* @return true on success.
*/
bool tox_conference_get_id(const Tox *tox, uint32_t conference_number, uint8_t *id);
typedef enum TOX_ERR_CONFERENCE_BY_ID {
/**
* The function returned successfully.
*/
TOX_ERR_CONFERENCE_BY_ID_OK,
/**
* One of the arguments to the function was NULL when it was not expected.
*/
TOX_ERR_CONFERENCE_BY_ID_NULL,
/**
* No conference with the given id exists on the conference list.
*/
TOX_ERR_CONFERENCE_BY_ID_NOT_FOUND,
} TOX_ERR_CONFERENCE_BY_ID;
/**
* Return the conference number associated with the specified id.
*
* @param id A byte array containing the conference id (TOX_CONFERENCE_ID_SIZE).
*
* @return the conference number on success, an unspecified value on failure.
*/
uint32_t tox_conference_by_id(const Tox *tox, const uint8_t *id, TOX_ERR_CONFERENCE_BY_ID *error);
/**
* Get the conference unique ID.
*
@ -2822,6 +2871,7 @@ TOX_CONFERENCE_TYPE tox_conference_get_type(const Tox *tox, uint32_t conference_
* @param uid A memory region large enough to store TOX_CONFERENCE_UID_SIZE bytes.
*
* @return true on success.
* @deprecated use tox_conference_get_id instead (exactly the same function, just renamed).
*/
bool tox_conference_get_uid(const Tox *tox, uint32_t conference_number, uint8_t *uid);
@ -2851,6 +2901,7 @@ typedef enum TOX_ERR_CONFERENCE_BY_UID {
* @param uid A byte array containing the conference id (TOX_CONFERENCE_UID_SIZE).
*
* @return the conference number on success, an unspecified value on failure.
* @deprecated use tox_conference_by_id instead (exactly the same function, just renamed).
*/
uint32_t tox_conference_by_uid(const Tox *tox, const uint8_t *uid, TOX_ERR_CONFERENCE_BY_UID *error);
@ -3054,6 +3105,7 @@ typedef TOX_ERR_FILE_SEND_CHUNK Tox_Err_File_Send_Chunk;
typedef TOX_ERR_CONFERENCE_NEW Tox_Err_Conference_New;
typedef TOX_ERR_CONFERENCE_DELETE Tox_Err_Conference_Delete;
typedef TOX_ERR_CONFERENCE_PEER_QUERY Tox_Err_Conference_Peer_Query;
typedef TOX_ERR_CONFERENCE_BY_ID Tox_Err_Conference_By_Id;
typedef TOX_ERR_CONFERENCE_BY_UID Tox_Err_Conference_By_Uid;
typedef TOX_ERR_CONFERENCE_INVITE Tox_Err_Conference_Invite;
typedef TOX_ERR_CONFERENCE_JOIN Tox_Err_Conference_Join;