From 1f27fcb5afdecc0ea027908cf4b8645bb919175b Mon Sep 17 00:00:00 2001 From: iphydf Date: Mon, 23 Jul 2018 21:04:50 +0000 Subject: [PATCH] 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`. --- toxcore/tox.api.h | 36 ++++++++++++++++++++++++++++++++ toxcore/tox.c | 45 ++++++++++++++++++++++++++++++++-------- toxcore/tox.h | 52 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 125 insertions(+), 8 deletions(-) diff --git a/toxcore/tox.api.h b/toxcore/tox.api.h index 97a85312..6cb3145b 100644 --- a/toxcore/tox.api.h +++ b/toxcore/tox.api.h @@ -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; diff --git a/toxcore/tox.c b/toxcore/tox.c index cdccbe45..101494cc 100644 --- a/toxcore/tox.c +++ b/toxcore/tox.c @@ -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) { diff --git a/toxcore/tox.h b/toxcore/tox.h index f8279afe..4c83ca23 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -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;