Connection lifecycle and event loop docs

This commit is contained in:
Андрей Владимирович 2016-02-19 21:07:57 +03:00
parent 9d75853437
commit e35bc7e023

View file

@ -94,9 +94,23 @@ class Tox(object):
# -----------------------------------------------------------------------------------------------------------------
def get_savedata_size(self):
"""
Calculates the number of bytes required to store the tox instance with tox_get_savedata.
This function cannot fail. The result is always greater than 0.
:return: number of bytes
"""
return self.libtoxcore.tox_get_savedata_size(self._tox_pointer)
def get_savedata(self, savedata=None):
"""
Store all information associated with the tox instance to a byte array.
:param savedata: pointer (c_char_p) to a memory region large enough to store the tox instance data.
Call tox_get_savedata_size to find the number of bytes required. If this parameter is None, this function
allocates memory for the tox instance data.
:return: pointer (c_char_p) to a memory region with the tox instance data
"""
if savedata is None:
savedata_size = self.get_savedata_size()
savedata = create_string_buffer(savedata_size)
@ -108,6 +122,17 @@ class Tox(object):
# -----------------------------------------------------------------------------------------------------------------
def bootstrap(self, address, port, public_key):
"""
Sends a "get nodes" request to the given bootstrap node with IP, port, and public key to setup connections.
This function will attempt to connect to the node using UDP. You must use this function even if
Tox_Options.udp_enabled was set to false.
:param address: The hostname or IP address (IPv4 or IPv6) of the node.
:param port: The port on the host on which the bootstrap Tox instance is listening.
:param public_key: The long term public key of the bootstrap node (TOX_PUBLIC_KEY_SIZE bytes).
:return: True on success.
"""
tox_err_bootstrap = c_int()
result = self.libtoxcore.tox_bootstrap(self._tox_pointer, c_char_p(address), c_uint16(port),
c_char_p(public_key), addressof(tox_err_bootstrap))
@ -122,6 +147,17 @@ class Tox(object):
raise ArgumentError('The port passed was invalid. The valid port range is (1, 65535).')
def add_tcp_relay(self, address, port, public_key):
"""
Adds additional host:port pair as TCP relay.
This function can be used to initiate TCP connections to different ports on the same bootstrap node, or to add
TCP relays without using them as bootstrap nodes.
:param address: The hostname or IP address (IPv4 or IPv6) of the TCP relay.
:param port: The port on the host on which the TCP relay is listening.
:param public_key: The long term public key of the TCP relay (TOX_PUBLIC_KEY_SIZE bytes).
:return: True on success.
"""
tox_err_bootstrap = c_int()
result = self.libtoxcore.tox_add_tcp_relay(self._tox_pointer, c_char_p(address), c_uint16(port),
c_char_p(public_key), addressof(tox_err_bootstrap))
@ -136,17 +172,41 @@ class Tox(object):
raise ArgumentError('The port passed was invalid. The valid port range is (1, 65535).')
def self_get_connection_status(self):
"""
Return whether we are connected to the DHT. The return value is equal to the last value received through the
`self_connection_status` callback.
:return: TOX_CONNECTION
"""
return self.libtoxcore.tox_self_get_connection_status(self._tox_pointer)
def callback_self_connection_status(self, callback, user_data):
"""
Set the callback for the `self_connection_status` event. Pass None to unset.
This event is triggered whenever there is a change in the DHT connection state. When disconnected, a client may
choose to call tox_bootstrap again, to reconnect to the DHT. Note that this state may frequently change for
short amounts of time. Clients should therefore not immediately bootstrap on receiving a disconnect.
:param callback: Python function. Should take pointer (c_void_p) to Tox object, TOX_CONNECTION (c_int), pointer
(c_void_p) to user_data
:param user_data: pointer (c_void_p) to user data
"""
tox_self_connection_status_cb = CFUNCTYPE(None, c_void_p, c_int, c_void_p)
c_callback = tox_self_connection_status_cb(callback)
self.libtoxcore.tox_callback_self_connection_status(self._tox_pointer, c_callback, c_void_p(user_data))
self.libtoxcore.tox_callback_self_connection_status(self._tox_pointer, c_callback, user_data)
def iteration_interval(self):
"""
Return the time in milliseconds before tox_iterate() should be called again for optimal performance.
:return: time in milliseconds
"""
return int(self.libtoxcore.tox_iteration_interval(self._tox_pointer).value)
def iterate(self):
"""
The main loop that needs to be run in intervals of tox_iteration_interval() milliseconds.
"""
self.libtoxcore.tox_iterate(self._tox_pointer)
# -----------------------------------------------------------------------------------------------------------------