Add deprecation notices to functions that will go away in v0.3.0.

This commit is contained in:
iphydf 2018-02-19 15:03:37 +00:00
parent c8359c843b
commit 223745e078
No known key found for this signature in database
GPG Key ID: 3855DBA2D74403C9
2 changed files with 55 additions and 7 deletions

View File

@ -257,26 +257,36 @@ const ADDRESS_SIZE = PUBLIC_KEY_SIZE + NOSPAM_SIZE + sizeof(uint1
/** /**
* Maximum length of a nickname in bytes. * 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; const MAX_NAME_LENGTH = 128;
/** /**
* Maximum length of a status message in bytes. * 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; const MAX_STATUS_MESSAGE_LENGTH = 1007;
/** /**
* Maximum length of a friend request message in bytes. * 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; const MAX_FRIEND_REQUEST_LENGTH = 1016;
/** /**
* Maximum length of a single message after which it should be split. * 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; const MAX_MESSAGE_LENGTH = 1372;
/** /**
* Maximum size of custom packets. TODO(iphydf): should be LENGTH? * 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; const MAX_CUSTOM_PACKET_SIZE = 1373;
@ -292,6 +302,8 @@ const FILE_ID_LENGTH = 32;
/** /**
* Maximum file name length for file transfers. * 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; const MAX_FILENAME_LENGTH = 255;
@ -443,7 +455,7 @@ static class options {
* @deprecated The memory layout of this struct (size, alignment, and field * @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 * 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 * 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] { 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 * Return whether we are connected to the DHT. The return value is equal to the
* last value received through the `${event connection_status}` callback. * 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(); get();
} }
@ -1217,11 +1232,11 @@ namespace friend {
uint64_t last_online { uint64_t last_online {
/** /**
* Return a unix-time timestamp of the last time the friend associated with a given * 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. * friend number was seen online. This function will return UINT64_MAX on error.
* *
* @param friend_number The friend number you want to query. * @param friend_number The friend number you want to query.
*/ */
get(uint32_t friend_number) { get(uint32_t friend_number) {
/** /**
* No friend with the given number exists on the friend list. * 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 * The status returned is equal to the last status received through the
* `${event status}` callback. * `${event status}` callback.
*
* @deprecated This getter is deprecated. Use the event and store the status
* in the client state.
*/ */
get(uint32_t friend_number) get(uint32_t friend_number)
with error for query; with error for query;
@ -1382,6 +1400,9 @@ namespace friend {
* *
* @return the friend's connection status as it was received through the * @return the friend's connection status as it was received through the
* `${event connection_status}` event. * `${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) get(uint32_t friend_number)
with error for query; with error for query;
@ -1415,6 +1436,9 @@ namespace friend {
* @return true if the friend is typing. * @return true if the friend is typing.
* @return false if the friend is not typing, or the friend number was * @return false if the friend is not typing, or the friend number was
* invalid. Inspect the error code to determine which case it is. * 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) get(uint32_t friend_number)
with error for query; with error for query;

View File

@ -266,6 +266,8 @@ uint32_t tox_address_size(void);
/** /**
* Maximum length of a nickname in bytes. * 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 #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. * 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 #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. * 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 #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. * 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 #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? * 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 #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. * 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 #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 * @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 * 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 * 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 { 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 * Return whether we are connected to the DHT. The return value is equal to the
* last value received through the `self_connection_status` callback. * 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); 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 * The status returned is equal to the last status received through the
* `friend_status` callback. * `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); 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 * @return the friend's connection status as it was received through the
* `friend_connection_status` event. * `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); 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 true if the friend is typing.
* @return false if the friend is not typing, or the friend number was * @return false if the friend is not typing, or the friend number was
* invalid. Inspect the error code to determine which case it is. * 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); bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);