User-visible client information (nickname/status) docs

This commit is contained in:
Андрей Владимирович 2016-02-19 22:47:19 +03:00
parent d45993071f
commit 165ac7d780
2 changed files with 76 additions and 5 deletions

View file

@ -260,7 +260,7 @@ class Tox(object):
""" """
Copy the Tox Secret Key from the Tox object. Copy the Tox Secret Key from the Tox object.
:param secret_key: A memory region of at least TOX_SECRET_KEY_SIZE bytes. If this parameter is NULL, this :param secret_key: pointer (c_char_p) to a memory region of at least TOX_SECRET_KEY_SIZE bytes. If this parameter is NULL, this
function allocates memory for Tox Secret Key. function allocates memory for Tox Secret Key.
:return: pointer (c_char_p) to a memory region with the Tox Secret Key :return: pointer (c_char_p) to a memory region with the Tox Secret Key
""" """
@ -273,10 +273,18 @@ class Tox(object):
# User-visible client information (nickname/status) # User-visible client information (nickname/status)
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------
def self_set_name(self, name, length): def self_set_name(self, name):
"""
Set the nickname for the Tox client.
Nickname length cannot exceed TOX_MAX_NAME_LENGTH. If length is 0, the name parameter is ignored
(it can be None), and the nickname is set back to empty.
:param name: New nickname.
:return: True on success.
"""
tox_err_set_info = c_int() tox_err_set_info = c_int()
result = self.libtoxcore.tox_self_set_name(self._tox_pointer, c_char_p(name), result = self.libtoxcore.tox_self_set_name(self._tox_pointer, c_char_p(name),
c_size_t(length), addressof(tox_err_set_info)) c_size_t(len(name)), addressof(tox_err_set_info))
if tox_err_set_info == TOX_ERR_SET_INFO['TOX_ERR_SET_INFO_OK']: if tox_err_set_info == TOX_ERR_SET_INFO['TOX_ERR_SET_INFO_OK']:
return bool(result) return bool(result)
elif tox_err_set_info == TOX_ERR_SET_INFO['TOX_ERR_SET_INFO_NULL']: elif tox_err_set_info == TOX_ERR_SET_INFO['TOX_ERR_SET_INFO_NULL']:
@ -285,18 +293,45 @@ class Tox(object):
raise ArgumentError('Information length exceeded maximum permissible size.') raise ArgumentError('Information length exceeded maximum permissible size.')
def self_get_name_size(self): def self_get_name_size(self):
"""
Return the length of the current nickname as passed to tox_self_set_name.
If no nickname was set before calling this function, the name is empty, and this function returns 0.
:return: length of the current nickname
"""
return int(self.libtoxcore.tox_self_get_name_size(self._tox_pointer).value) return int(self.libtoxcore.tox_self_get_name_size(self._tox_pointer).value)
def self_get_name(self, name=None): def self_get_name(self, name=None):
"""
Write the nickname set by tox_self_set_name to a byte array.
If no nickname was set before calling this function, the name is empty, and this function has no effect.
Call tox_self_get_name_size to find out how much memory to allocate for the result.
:param name: pointer (c_char_p) to a memory region location large enough to hold the nickname. If this parameter
is NULL, the function allocates memory for the nickname.
:return: pointer (c_char_p) to a memory region with the nickname
"""
if name is None: if name is None:
name = create_string_buffer(self.self_get_name_size()) name = create_string_buffer(self.self_get_name_size())
self.libtoxcore.tox_self_get_name(self._tox_pointer, name) self.libtoxcore.tox_self_get_name(self._tox_pointer, name)
return name return name
def self_set_status_message(self, status_message, length): def self_set_status_message(self, status_message):
"""
Set the client's status message.
Status message length cannot exceed TOX_MAX_STATUS_MESSAGE_LENGTH. If length is 0, the status parameter is
ignored, and the user status is set back to empty.
:param status_message: new status message
:return: True on success.
"""
tox_err_set_info = c_int() tox_err_set_info = c_int()
result = self.libtoxcore.tox_self_set_status_message(self._tox_pointer, c_char_p(status_message), result = self.libtoxcore.tox_self_set_status_message(self._tox_pointer, c_char_p(status_message),
c_size_t(length), addressof(tox_err_set_info)) c_size_t(len(status_message)), addressof(tox_err_set_info))
if tox_err_set_info == TOX_ERR_SET_INFO['TOX_ERR_SET_INFO_OK']: if tox_err_set_info == TOX_ERR_SET_INFO['TOX_ERR_SET_INFO_OK']:
return bool(result) return bool(result)
elif tox_err_set_info == TOX_ERR_SET_INFO['TOX_ERR_SET_INFO_NULL']: elif tox_err_set_info == TOX_ERR_SET_INFO['TOX_ERR_SET_INFO_NULL']:
@ -305,20 +340,49 @@ class Tox(object):
raise ArgumentError('Information length exceeded maximum permissible size.') raise ArgumentError('Information length exceeded maximum permissible size.')
def self_get_status_message_size(self): def self_get_status_message_size(self):
"""
Return the length of the current status message as passed to tox_self_set_status_message.
If no status message was set before calling this function, the status is empty, and this function returns 0.
:return: length of the current status message
"""
return int(self.libtoxcore.tox_self_get_status_message_size(self._tox_pointer).value) return int(self.libtoxcore.tox_self_get_status_message_size(self._tox_pointer).value)
def self_get_status_message(self, status_message=None): def self_get_status_message(self, status_message=None):
"""
Write the status message set by tox_self_set_status_message to a byte array.
If no status message was set before calling this function, the status is empty, and this function has no effect.
Call tox_self_get_status_message_size to find out how much memory to allocate for the result.
:param status_message: pointer (c_char_p) to a valid memory location large enough to hold the status message.
If this parameter is None, the function allocates memory for the status message.
:return: pointer (c_char_p) to a memory region with the status message
"""
if status_message is None: if status_message is None:
status_message = create_string_buffer(self.self_get_status_message_size()) status_message = create_string_buffer(self.self_get_status_message_size())
self.libtoxcore.tox_self_get_status_message(self._tox_pointer, status_message) self.libtoxcore.tox_self_get_status_message(self._tox_pointer, status_message)
return status_message return status_message
def self_set_status(self, status): def self_set_status(self, status):
"""
Set the client's user status.
:param status: One of the user statuses listed in the enumeration TOX_USER_STATUS.
"""
self.libtoxcore.tox_self_set_status(self._tox_pointer, c_int(status)) self.libtoxcore.tox_self_set_status(self._tox_pointer, c_int(status))
def self_get_status(self): def self_get_status(self):
"""
Returns the client's user status.
:return: client's user status
"""
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
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------
@ -381,6 +445,7 @@ class Tox(object):
elif tox_err_friend_delete == TOX_ERR_FRIEND_DELETE['TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND']: elif tox_err_friend_delete == TOX_ERR_FRIEND_DELETE['TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND']:
raise ArgumentError('There was no friend with the given friend number. No friends were deleted.') raise ArgumentError('There was no friend with the given friend number. No friends were deleted.')
# TODO create docs
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------
# Friend list queries # Friend list queries
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------
@ -428,6 +493,7 @@ class Tox(object):
elif tox_err_last_online == TOX_ERR_FRIEND_GET_LAST_ONLINE['TOX_ERR_FRIEND_GET_LAST_ONLINE_FRIEND_NOT_FOUND']: elif tox_err_last_online == TOX_ERR_FRIEND_GET_LAST_ONLINE['TOX_ERR_FRIEND_GET_LAST_ONLINE_FRIEND_NOT_FOUND']:
raise ArgumentError('No friend with the given number exists on the friend list.') raise ArgumentError('No friend with the given number exists on the friend list.')
# TODO create docs
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------
# Friend-specific state queries (can also be received through callbacks) # Friend-specific state queries (can also be received through callbacks)
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------
@ -548,6 +614,7 @@ class Tox(object):
c_callback = tox_friend_typing_cb(callback) c_callback = tox_friend_typing_cb(callback)
self.libtoxcore.tox_callback_friend_typing(self._tox_pointer, c_callback, c_void_p(user_data)) self.libtoxcore.tox_callback_friend_typing(self._tox_pointer, c_callback, c_void_p(user_data))
# TODO create docs
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------
# Sending private messages # Sending private messages
# ----------------------------------------------------------------------------------------------------------------- # -----------------------------------------------------------------------------------------------------------------

View file

@ -195,3 +195,7 @@ TOX_ADDRESS_SIZE = TOX_PUBLIC_KEY_SIZE + 48
TOX_MAX_FRIEND_REQUEST_LENGTH = 1016 TOX_MAX_FRIEND_REQUEST_LENGTH = 1016
TOX_MAX_MESSAGE_LENGTH = 1372 TOX_MAX_MESSAGE_LENGTH = 1372
TOX_MAX_NAME_LENGTH = 128
TOX_MAX_STATUS_MESSAGE_LENGTH = 1007