From 223745e0782602c780c0d66b0c342750fdbd58db Mon Sep 17 00:00:00 2001 From: iphydf Date: Mon, 19 Feb 2018 15:03:37 +0000 Subject: [PATCH] Add deprecation notices to functions that will go away in v0.3.0. --- toxcore/tox.api.h | 36 ++++++++++++++++++++++++++++++------ toxcore/tox.h | 26 +++++++++++++++++++++++++- 2 files changed, 55 insertions(+), 7 deletions(-) diff --git a/toxcore/tox.api.h b/toxcore/tox.api.h index 90020a83..493307e9 100644 --- a/toxcore/tox.api.h +++ b/toxcore/tox.api.h @@ -257,26 +257,36 @@ const ADDRESS_SIZE = PUBLIC_KEY_SIZE + NOSPAM_SIZE + sizeof(uint1 /** * Maximum length of a nickname in bytes. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ const MAX_NAME_LENGTH = 128; /** * Maximum length of a status message in bytes. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ const MAX_STATUS_MESSAGE_LENGTH = 1007; /** * Maximum length of a friend request message in bytes. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ const MAX_FRIEND_REQUEST_LENGTH = 1016; /** * Maximum length of a single message after which it should be split. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ const MAX_MESSAGE_LENGTH = 1372; /** * Maximum size of custom packets. TODO(iphydf): should be LENGTH? + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ const MAX_CUSTOM_PACKET_SIZE = 1373; @@ -292,6 +302,8 @@ const FILE_ID_LENGTH = 32; /** * Maximum file name length for file transfers. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ const MAX_FILENAME_LENGTH = 255; @@ -443,7 +455,7 @@ static class options { * @deprecated The memory layout of this struct (size, alignment, and field * order) is not part of the ABI. To remain compatible, prefer to use $new to * allocate the object and accessor functions to set the members. The struct - * will become opaque (i.e. the definition will become private) in v0.2.0. + * will become opaque (i.e. the definition will become private) in v0.3.0. */ struct this [get, set] { /** @@ -801,6 +813,9 @@ inline namespace self { /** * Return whether we are connected to the DHT. The return value is equal to the * last value received through the `${event connection_status}` callback. + * + * @deprecated This getter is deprecated. Use the event and store the status + * in the client state. */ get(); } @@ -1217,11 +1232,11 @@ namespace friend { uint64_t last_online { /** - * Return a unix-time timestamp of the last time the friend associated with a given - * friend number was seen online. This function will return UINT64_MAX on error. - * - * @param friend_number The friend number you want to query. - */ + * Return a unix-time timestamp of the last time the friend associated with a given + * friend number was seen online. This function will return UINT64_MAX on error. + * + * @param friend_number The friend number you want to query. + */ get(uint32_t friend_number) { /** * No friend with the given number exists on the friend list. @@ -1351,6 +1366,9 @@ namespace friend { * * The status returned is equal to the last status received through the * `${event status}` callback. + * + * @deprecated This getter is deprecated. Use the event and store the status + * in the client state. */ get(uint32_t friend_number) with error for query; @@ -1382,6 +1400,9 @@ namespace friend { * * @return the friend's connection status as it was received through the * `${event connection_status}` event. + * + * @deprecated This getter is deprecated. Use the event and store the status + * in the client state. */ get(uint32_t friend_number) with error for query; @@ -1415,6 +1436,9 @@ namespace friend { * @return true if the friend is typing. * @return false if the friend is not typing, or the friend number was * invalid. Inspect the error code to determine which case it is. + * + * @deprecated This getter is deprecated. Use the event and store the status + * in the client state. */ get(uint32_t friend_number) with error for query; diff --git a/toxcore/tox.h b/toxcore/tox.h index 3dac6770..f2e746c8 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -266,6 +266,8 @@ uint32_t tox_address_size(void); /** * Maximum length of a nickname in bytes. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ #define TOX_MAX_NAME_LENGTH 128 @@ -273,6 +275,8 @@ uint32_t tox_max_name_length(void); /** * Maximum length of a status message in bytes. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ #define TOX_MAX_STATUS_MESSAGE_LENGTH 1007 @@ -280,6 +284,8 @@ uint32_t tox_max_status_message_length(void); /** * Maximum length of a friend request message in bytes. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ #define TOX_MAX_FRIEND_REQUEST_LENGTH 1016 @@ -287,6 +293,8 @@ uint32_t tox_max_friend_request_length(void); /** * Maximum length of a single message after which it should be split. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ #define TOX_MAX_MESSAGE_LENGTH 1372 @@ -294,6 +302,8 @@ uint32_t tox_max_message_length(void); /** * Maximum size of custom packets. TODO(iphydf): should be LENGTH? + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ #define TOX_MAX_CUSTOM_PACKET_SIZE 1373 @@ -315,6 +325,8 @@ uint32_t tox_file_id_length(void); /** * Maximum file name length for file transfers. + * + * @deprecated The macro will be removed in 0.3.0. Use the function instead. */ #define TOX_MAX_FILENAME_LENGTH 255 @@ -494,7 +506,7 @@ typedef void tox_log_cb(Tox *tox, TOX_LOG_LEVEL level, const char *file, uint32_ * @deprecated The memory layout of this struct (size, alignment, and field * order) is not part of the ABI. To remain compatible, prefer to use tox_options_new to * allocate the object and accessor functions to set the members. The struct - * will become opaque (i.e. the definition will become private) in v0.2.0. + * will become opaque (i.e. the definition will become private) in v0.3.0. */ struct Tox_Options { @@ -956,6 +968,9 @@ typedef enum TOX_CONNECTION { /** * Return whether we are connected to the DHT. The return value is equal to the * last value received through the `self_connection_status` callback. + * + * @deprecated This getter is deprecated. Use the event and store the status + * in the client state. */ TOX_CONNECTION tox_self_get_connection_status(const Tox *tox); @@ -1525,6 +1540,9 @@ void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb * * * The status returned is equal to the last status received through the * `friend_status` callback. + * + * @deprecated This getter is deprecated. Use the event and store the status + * in the client state. */ TOX_USER_STATUS tox_friend_get_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); @@ -1554,6 +1572,9 @@ void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *callback); * * @return the friend's connection status as it was received through the * `friend_connection_status` event. + * + * @deprecated This getter is deprecated. Use the event and store the status + * in the client state. */ TOX_CONNECTION tox_friend_get_connection_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); @@ -1586,6 +1607,9 @@ void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_statu * @return true if the friend is typing. * @return false if the friend is not typing, or the friend number was * invalid. Inspect the error code to determine which case it is. + * + * @deprecated This getter is deprecated. Use the event and store the status + * in the client state. */ bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);