From a6a3cc9bac7dee7d97a7a1e905b738de7246b2a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BD=D0=B4=D1=80=D0=B5=D0=B9=20=D0=92=D0=BB=D0=B0?= =?UTF-8?q?=D0=B4=D0=B8=D0=BC=D0=B8=D1=80=D0=BE=D0=B2=D0=B8=D1=87?= Date: Fri, 19 Feb 2016 22:58:45 +0300 Subject: [PATCH] Friend list management docs --- src/tox.py | 45 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/src/tox.py b/src/tox.py index a92a612..335ab5d 100644 --- a/src/tox.py +++ b/src/tox.py @@ -382,15 +382,31 @@ class Tox(object): """ return self.libtoxcore.tox_self_get_status(self._tox_pointer) - # TODO create docs # ----------------------------------------------------------------------------------------------------------------- # Friend list management # ----------------------------------------------------------------------------------------------------------------- - def friend_add(self, address, message, length): + def friend_add(self, address, message): + """ + Add a friend to the friend list and send a friend request. + + A friend request message must be at least 1 byte long and at most TOX_MAX_FRIEND_REQUEST_LENGTH. + + Friend numbers are unique identifiers used in all functions that operate on friends. Once added, a friend number + is stable for the lifetime of the Tox object. After saving the state and reloading it, the friend numbers may + not be the same as before. Deleting a friend creates a gap in the friend number set, which is filled by the next + adding of a friend. Any pattern in friend numbers should not be relied on. + + If more than INT32_MAX friends are added, this function causes undefined behaviour. + + :param address: The address of the friend (returned by tox_self_get_address of the friend you wish to add) it + must be TOX_ADDRESS_SIZE bytes. + :param message: The message that will be sent along with the friend request. + :return: the friend number on success, UINT32_MAX on failure. + """ tox_err_friend_add = c_int() result = self.libtoxcore.tox_friend_add(self._tox_pointer, c_char_p(address), c_char_p(message), - c_size_t(length), addressof(tox_err_friend_add)) + c_size_t(len(message)), addressof(tox_err_friend_add)) if tox_err_friend_add == TOX_ERR_FRIEND_ADD['TOX_ERR_FRIEND_ADD_OK']: return int(result.value) elif tox_err_friend_add == TOX_ERR_FRIEND_ADD['TOX_ERR_FRIEND_ADD_NULL']: @@ -413,6 +429,20 @@ class Tox(object): raise MemoryError('A memory allocation failed when trying to increase the friend list size.') def friend_add_norequest(self, public_key): + """ + Add a friend without sending a friend request. + + This function is used to add a friend in response to a friend request. If the client receives a friend request, + it can be reasonably sure that the other client added this client as a friend, eliminating the need for a friend + request. + + This function is also useful in a situation where both instances are controlled by the same entity, so that this + entity can perform the mutual friend adding. In this case, there is no need for a friend request, either. + + :param public_key: A byte array of length TOX_PUBLIC_KEY_SIZE containing the Public Key (not the Address) of the + friend to add. + :return: the friend number on success, UINT32_MAX on failure. + """ tox_err_friend_add = c_int() result = self.libtoxcore.tox_friend_add(self._tox_pointer, c_char_p(public_key), addressof(tox_err_friend_add)) if tox_err_friend_add == TOX_ERR_FRIEND_ADD['TOX_ERR_FRIEND_ADD_OK']: @@ -437,6 +467,15 @@ class Tox(object): raise MemoryError('A memory allocation failed when trying to increase the friend list size.') def friend_delete(self, friend_number): + """ + Remove a friend from the friend list. + + This does not notify the friend of their deletion. After calling this function, this client will appear offline + to the friend and no communication can occur between the two. + + :param friend_number: Friend number for the friend to be deleted. + :return: True on success. + """ tox_err_friend_delete = c_int() result = self.libtoxcore.tox_friend_delete(self._tox_pointer, c_uint32(friend_number), addressof(tox_err_friend_delete))