Friend list management docs

This commit is contained in:
Андрей Владимирович 2016-02-19 22:58:45 +03:00
parent 165ac7d780
commit a6a3cc9bac

View file

@ -382,15 +382,31 @@ class Tox(object):
""" """
return self.libtoxcore.tox_self_get_status(self._tox_pointer) return self.libtoxcore.tox_self_get_status(self._tox_pointer)
# TODO create docs
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------
# Friend list management # 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() tox_err_friend_add = c_int()
result = self.libtoxcore.tox_friend_add(self._tox_pointer, c_char_p(address), c_char_p(message), 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']: if tox_err_friend_add == TOX_ERR_FRIEND_ADD['TOX_ERR_FRIEND_ADD_OK']:
return int(result.value) return int(result.value)
elif tox_err_friend_add == TOX_ERR_FRIEND_ADD['TOX_ERR_FRIEND_ADD_NULL']: 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.') raise MemoryError('A memory allocation failed when trying to increase the friend list size.')
def friend_add_norequest(self, public_key): 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() 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)) 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']: 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.') raise MemoryError('A memory allocation failed when trying to increase the friend list size.')
def friend_delete(self, friend_number): 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() tox_err_friend_delete = c_int()
result = self.libtoxcore.tox_friend_delete(self._tox_pointer, c_uint32(friend_number), result = self.libtoxcore.tox_friend_delete(self._tox_pointer, c_uint32(friend_number),
addressof(tox_err_friend_delete)) addressof(tox_err_friend_delete))