diff --git a/docs/clean_md.py b/docs/clean_md.py index 13f1bbe0..942f6473 100755 --- a/docs/clean_md.py +++ b/docs/clean_md.py @@ -52,8 +52,9 @@ def clean_markdown_content(content, start_patterns, any_patterns, api_ref=False) if api_ref: if line.startswith("### ") or line.startswith("#### "): line = line.replace("*", "") - line = line.replace("#### ", "#### `") - line = line.replace("### ", "### `") + line = line.replace("\\_", "_") + if line.startswith("### "): line = line.replace("### ", "### `") + if line.startswith("#### "): line = line.replace("#### ", "#### `") line = f"{line}`" result.append(line) diff --git a/docs/markdown/reference.md b/docs/markdown/reference.md index d54f8d91..5ec93287 100644 --- a/docs/markdown/reference.md +++ b/docs/markdown/reference.md @@ -29,7 +29,7 @@ programs that use RNS starting and terminating at different times, it will be advantageous to run a master RNS instance as a daemon for other programs to use on demand. -#### ``MTU = 500` +#### `MTU = 500` The MTU that Reticulum adheres to, and will expect other peers to adhere to. By default, the MTU is 500 bytes. In custom RNS network @@ -40,12 +40,12 @@ MTU is a prerequisite for peers to communicate in the same network. Unless you really know what you are doing, the MTU should be left at the default value. -#### ``LINK_MTU_DISCOVERY = True` +#### `LINK_MTU_DISCOVERY = True` Whether automatic link MTU discovery is enabled by default. Link MTU discovery significantly increases throughput over fast links. -#### ``ANNOUNCE_CAP = 2` +#### `ANNOUNCE_CAP = 2` The maximum percentage of interface bandwidth that, at any given time, may be used to propagate announces. If an announce was scheduled for @@ -64,23 +64,23 @@ but it can be configured individually on a per-interface basis. In general, the global default setting should not be changed, and any alterations should be made on a per-interface basis instead. -#### ``MINIMUM_BITRATE = 5` +#### `MINIMUM_BITRATE = 5` Minimum bitrate required across a medium for Reticulum to be able to successfully establish links. Currently 5 bits per second. -#### ``static get_instance()` +#### `static get_instance()` Return the currently running Reticulum instance -#### ``static should_use_implicit_proof()` +#### `static should_use_implicit_proof()` Returns whether proofs sent are explicit or implicit. * **Returns:** True if the current running configuration specifies to use implicit proofs. False if not. -#### ``static transport_enabled()` +#### `static transport_enabled()` Returns whether Transport is enabled for the running instance. @@ -92,7 +92,7 @@ and pass announces over the network. * **Returns:** True if Transport is enabled, False if not. -#### ``static link_mtu_discovery()` +#### `static link_mtu_discovery()` Returns whether link MTU discovery is enabled for the running instance. @@ -104,7 +104,7 @@ value, increasing transfer speed and efficiency. * **Returns:** True if link MTU discovery is enabled, False if not. -#### ``static remote_management_enabled()` +#### `static remote_management_enabled()` Returns whether remote management is enabled for the running instance. @@ -115,7 +115,7 @@ can remotely query and manage this instance. * **Returns:** True if remote management is enabled, False if not. -#### ``static required_discovery_value()` +#### `static required_discovery_value()` Returns the required stamp value for a discovered interface to be considered valid and remembered. @@ -123,7 +123,7 @@ to be considered valid and remembered. * **Returns:** The required stamp value as an integer. -#### ``static publish_blackhole_enabled()` +#### `static publish_blackhole_enabled()` Returns whether blackhole list publishing is enabled for the running instance. @@ -131,7 +131,7 @@ running instance. * **Returns:** True if blackhole list publishing is enabled, False if not. -#### ``static blackhole_sources()` +#### `static blackhole_sources()` Returns the list of transport identity hashes from which blackhole lists are sourced. @@ -139,14 +139,14 @@ blackhole lists are sourced. * **Returns:** A list of identity hashes. -#### ``static discovered_interfaces()` +#### `static discovered_interfaces()` Returns a list of interfaces discovered over the network. * **Returns:** A list of discovered interfaces. -#### ``static interface_discovery_sources()` +#### `static interface_discovery_sources()` Returns the list of network identity hashes from which interfaces are discovered. @@ -163,30 +163,30 @@ for all encrypted communication over Reticulum networks. * **Parameters:** **create_keys** – Specifies whether new encryption and signing keys should be generated. -#### ``CURVE = 'Curve25519'` +#### `CURVE = 'Curve25519'` The curve used for Elliptic Curve DH key exchanges -#### ``KEYSIZE = 512` +#### `KEYSIZE = 512` X.25519 key size in bits. A complete key is the concatenation of a 256 bit encryption key, and a 256 bit signing key. -#### ``RATCHETSIZE = 256` +#### `RATCHETSIZE = 256` X.25519 ratchet key size in bits. -#### ``RATCHET_EXPIRY = 2592000` +#### `RATCHET_EXPIRY = 2592000` The expiry time for received ratchets in seconds, defaults to 30 days. Reticulum will always use the most recently announced ratchet, and remember it for up to `RATCHET_EXPIRY` since receiving it, after which it will be discarded. If a newer ratchet is announced in the meantime, it will be replace the already known ratchet. -#### ``TRUNCATED_HASHLENGTH = 128` +#### `TRUNCATED_HASHLENGTH = 128` Constant specifying the truncated hash length (in bits) used by Reticulum for addressable hashes and other purposes. Non-configurable. -#### ``static recall(target_hash, from_identity_hash=False, \_no_use=False)` +#### `static recall(target_hash, from_identity_hash=False, _no_use=False)` Recall identity for a destination or identity hash. By default, this function will return the identity associated with a given *destination* hash. As an @@ -201,7 +201,7 @@ search for an identity from a known *identity hash*, by setting the * **Returns:** An [RNS.Identity](#api-identity) instance that can be used to create an outgoing [RNS.Destination](#api-destination), or *None* if the destination is unknown. -#### ``static recall_app_data(destination_hash, \_no_use=False)` +#### `static recall_app_data(destination_hash, _no_use=False)` Recall last heard app_data for a destination hash. @@ -210,7 +210,7 @@ Recall last heard app_data for a destination hash. * **Returns:** *Bytes* containing app_data, or *None* if the destination is unknown. -#### ``static full_hash(data)` +#### `static full_hash(data)` Get a SHA-256 hash of passed data. @@ -219,7 +219,7 @@ Get a SHA-256 hash of passed data. * **Returns:** SHA-256 hash as *bytes*. -#### ``static truncated_hash(data)` +#### `static truncated_hash(data)` Get a truncated SHA-256 hash of passed data. @@ -228,7 +228,7 @@ Get a truncated SHA-256 hash of passed data. * **Returns:** Truncated SHA-256 hash as *bytes*. -#### ``static get_random_hash()` +#### `static get_random_hash()` Get a random SHA-256 hash. @@ -237,7 +237,7 @@ Get a random SHA-256 hash. * **Returns:** Truncated SHA-256 hash of random data as *bytes*. -#### ``static current_ratchet_id(destination_hash)` +#### `static current_ratchet_id(destination_hash)` Get the ID of the currently used ratchet key for a given destination hash @@ -246,7 +246,7 @@ Get the ID of the currently used ratchet key for a given destination hash * **Returns:** A ratchet ID as *bytes* or *None*. -#### ``static from_bytes(prv_bytes)` +#### `static from_bytes(prv_bytes)` Create a new [RNS.Identity](#api-identity) instance from *bytes* of private key. Can be used to load previously created and saved identities into Reticulum. @@ -256,7 +256,7 @@ Can be used to load previously created and saved identities into Reticulum. * **Returns:** A [RNS.Identity](#api-identity) instance, or *None* if the *bytes* data was invalid. -#### ``static from_file(path)` +#### `static from_file(path)` Create a new [RNS.Identity](#api-identity) instance from a file. Can be used to load previously created and saved identities into Reticulum. @@ -266,7 +266,7 @@ Can be used to load previously created and saved identities into Reticulum. * **Returns:** A [RNS.Identity](#api-identity) instance, or *None* if the loaded data was invalid. -#### ``to_file(path)` +#### `to_file(path)` Saves the identity to a file. This will write the private key to disk, and anyone with access to this file will be able to decrypt all @@ -277,17 +277,17 @@ communication for the identity. Be very careful with this method. * **Returns:** True if the file was saved, otherwise False. -#### ``get_private_key()` +#### `get_private_key()` * **Returns:** The private key as *bytes* -#### ``get_public_key()` +#### `get_public_key()` * **Returns:** The public key as *bytes* -#### ``load_private_key(prv_bytes)` +#### `load_private_key(prv_bytes)` Load a private key into the instance. @@ -296,7 +296,7 @@ Load a private key into the instance. * **Returns:** True if the key was loaded, otherwise False. -#### ``load_public_key(pub_bytes)` +#### `load_public_key(pub_bytes)` Load a public key into the instance. @@ -305,7 +305,7 @@ Load a public key into the instance. * **Returns:** True if the key was loaded, otherwise False. -#### ``encrypt(plaintext, ratchet=None)` +#### `encrypt(plaintext, ratchet=None)` Encrypts information for the identity. @@ -316,7 +316,7 @@ Encrypts information for the identity. * **Raises:** *KeyError* if the instance does not hold a public key. -#### ``decrypt(ciphertext_token, ratchets=None, enforce_ratchets=False, ratchet_id_receiver=None)` +#### `decrypt(ciphertext_token, ratchets=None, enforce_ratchets=False, ratchet_id_receiver=None)` Decrypts information for the identity. @@ -327,7 +327,7 @@ Decrypts information for the identity. * **Raises:** *KeyError* if the instance does not hold a private key. -#### ``sign(message)` +#### `sign(message)` Signs information by the identity. @@ -338,7 +338,7 @@ Signs information by the identity. * **Raises:** *KeyError* if the instance does not hold a private key. -#### ``validate(signature, message)` +#### `validate(signature, message)` Validates the signature of a signed message. @@ -366,35 +366,35 @@ encrypted communication with it. * **app_name** – A string specifying the app name. * **\*aspects** – Any non-zero number of string arguments. -#### ``RATCHET_COUNT = 512` +#### `RATCHET_COUNT = 512` The default number of generated ratchet keys a destination will retain, if it has ratchets enabled. -#### ``RATCHET_INTERVAL = 1800` +#### `RATCHET_INTERVAL = 1800` The minimum interval between rotating ratchet keys, in seconds. -#### ``static expand_name(identity, app_name, \aspects)` +#### `static expand_name(identity, app_name, \aspects)` * **Returns:** A string containing the full human-readable name of the destination, for an app_name and a number of aspects. -#### ``static app_and_aspects_from_name(full_name)` +#### `static app_and_aspects_from_name(full_name)` * **Returns:** A tuple containing the app name and a list of aspects, for a full-name string. -#### ``static hash_from_name_and_identity(full_name, identity)` +#### `static hash_from_name_and_identity(full_name, identity)` * **Returns:** A destination name in adressable hash form, for a full name string and Identity instance. -#### ``static hash(identity, app_name, \aspects)` +#### `static hash(identity, app_name, \aspects)` * **Returns:** A destination name in adressable hash form, for an app_name and a number of aspects. -#### ``announce(app_data=None, path_response=False, attached_interface=None, tag=None, send=True)` +#### `announce(app_data=None, path_response=False, attached_interface=None, tag=None, send=True)` Creates an announce packet for this destination and broadcasts it on all relevant interfaces. Application specific data can be added to the announce. @@ -403,7 +403,7 @@ relevant interfaces. Application specific data can be added to the announce. * **app_data** – *bytes* containing the app_data. * **path_response** – Internal flag used by [RNS.Transport](#api-transport). Ignore. -#### ``accepts_links(accepts=None)` +#### `accepts_links(accepts=None)` Set or query whether the destination accepts incoming link requests. @@ -412,7 +412,7 @@ Set or query whether the destination accepts incoming link requests. * **Returns:** `True` or `False` depending on whether the destination accepts incoming link requests, if the *accepts* parameter is not provided or `None`. -#### ``set_link_established_callback(callback)` +#### `set_link_established_callback(callback)` Registers a function to be called when a link has been established to this destination. @@ -420,7 +420,7 @@ this destination. * **Parameters:** **callback** – A function or method with the signature *callback(link)* to be called when a new link is established with this destination. -#### ``set_packet_callback(callback)` +#### `set_packet_callback(callback)` Registers a function to be called when a packet has been received by this destination. @@ -428,7 +428,7 @@ this destination. * **Parameters:** **callback** – A function or method with the signature *callback(data, packet)* to be called when this destination receives a packet. -#### ``set_proof_requested_callback(callback)` +#### `set_proof_requested_callback(callback)` Registers a function to be called when a proof has been requested for a packet sent to this destination. Allows control over when and if @@ -437,14 +437,14 @@ proofs should be returned for received packets. * **Parameters:** **callback** – A function or method to with the signature *callback(packet)* be called when a packet that requests a proof is received. The callback must return one of True or False. If the callback returns True, a proof will be sent. If it returns False, a proof will not be sent. -#### ``set_proof_strategy(proof_strategy)` +#### `set_proof_strategy(proof_strategy)` Sets the destinations proof strategy. * **Parameters:** **proof_strategy** – One of `RNS.Destination.PROVE_NONE`, `RNS.Destination.PROVE_ALL` or `RNS.Destination.PROVE_APP`. If `RNS.Destination.PROVE_APP` is set, the proof_requested_callback will be called to determine whether a proof should be sent or not. -#### ``register_request_handler(path, response_generator=None, allow=ALLOW_NONE, allowed_list=None, auto_compress=True)` +#### `register_request_handler(path, response_generator=None, allow=ALLOW_NONE, allowed_list=None, auto_compress=True)` Registers a request handler. @@ -457,7 +457,7 @@ Registers a request handler. * **Raises:** `ValueError` if any of the supplied arguments are invalid. -#### ``deregister_request_handler(path)` +#### `deregister_request_handler(path)` Deregisters a request handler. @@ -466,7 +466,7 @@ Deregisters a request handler. * **Returns:** True if the handler was deregistered, otherwise False. -#### ``enable_ratchets(ratchets_path)` +#### `enable_ratchets(ratchets_path)` Enables ratchets on the destination. When ratchets are enabled, Reticulum will automatically rotate the keys used to encrypt packets to this destination, and include the latest ratchet key in announces. @@ -483,13 +483,13 @@ Enabling ratchets will have a small impact on announce size, adding 32 bytes to * **Returns:** True if the operation succeeded, otherwise False. -#### ``enforce_ratchets()` +#### `enforce_ratchets()` When ratchet enforcement is enabled, this destination will never accept packets that use its base Identity key for encryption, but only accept packets encrypted with one of the retained ratchet keys. -#### ``set_retained_ratchets(retained_ratchets)` +#### `set_retained_ratchets(retained_ratchets)` Sets the number of previously generated ratchet keys this destination will retain, and try to use when decrypting incoming packets. Defaults to `Destination.RATCHET_COUNT`. @@ -499,7 +499,7 @@ and try to use when decrypting incoming packets. Defaults to `Destination.RATCHE * **Returns:** True if the operation succeeded, False if not. -#### ``set_ratchet_interval(interval)` +#### `set_ratchet_interval(interval)` Sets the minimum interval in seconds between ratchet key rotation. Defaults to `Destination.RATCHET_INTERVAL`. @@ -509,21 +509,21 @@ Defaults to `Destination.RATCHET_INTERVAL`. * **Returns:** True if the operation succeeded, False if not. -#### ``create_keys()` +#### `create_keys()` For a `RNS.Destination.GROUP` type destination, creates a new symmetric key. * **Raises:** `TypeError` if called on an incompatible type of destination. -#### ``get_private_key()` +#### `get_private_key()` For a `RNS.Destination.GROUP` type destination, returns the symmetric private key. * **Raises:** `TypeError` if called on an incompatible type of destination. -#### ``load_private_key(key)` +#### `load_private_key(key)` For a `RNS.Destination.GROUP` type destination, loads a symmetric private key. @@ -532,7 +532,7 @@ For a `RNS.Destination.GROUP` type destination, loads a symmetric private key. * **Raises:** `TypeError` if called on an incompatible type of destination. -#### ``encrypt(plaintext)` +#### `encrypt(plaintext)` Encrypts information for `RNS.Destination.SINGLE` or `RNS.Destination.GROUP` type destination. @@ -541,7 +541,7 @@ Encrypts information for `RNS.Destination.SINGLE` or `RNS.Destination.GROUP` typ * **Raises:** `ValueError` if destination does not hold a necessary key for encryption. -#### ``decrypt(ciphertext)` +#### `decrypt(ciphertext)` Decrypts information for `RNS.Destination.SINGLE` or `RNS.Destination.GROUP` type destination. @@ -550,7 +550,7 @@ Decrypts information for `RNS.Destination.SINGLE` or `RNS.Destination.GROUP` typ * **Raises:** `ValueError` if destination does not hold a necessary key for decryption. -#### ``sign(message)` +#### `sign(message)` Signs information for `RNS.Destination.SINGLE` type destination. @@ -559,7 +559,7 @@ Signs information for `RNS.Destination.SINGLE` type destination. * **Returns:** A *bytes-like* containing the message signature, or *None* if the destination could not sign the message. -#### ``set_default_app_data(app_data=None)` +#### `set_default_app_data(app_data=None)` Sets the default app_data for the destination. If set, the default app_data will be included in every announce sent by the destination, @@ -568,7 +568,7 @@ unless other app_data is specified in the *announce* method. * **Parameters:** **app_data** – A *bytes-like* containing the default app_data, or a *callable* returning a *bytes-like* containing the app_data. -#### ``clear_default_app_data()` +#### `clear_default_app_data()` Clears default app_data previously set for the destination. @@ -594,39 +594,39 @@ ephemeral keys, and offers **Forward Secrecy**. * **data** – The data payload to be included in the packet as *bytes*. * **create_receipt** – Specifies whether a [RNS.PacketReceipt](#api-packetreceipt) should be created when instantiating the packet. -#### ``ENCRYPTED_MDU = 383` +#### `ENCRYPTED_MDU = 383` The maximum size of the payload data in a single encrypted packet -#### ``PLAIN_MDU = 464` +#### `PLAIN_MDU = 464` The maximum size of the payload data in a single unencrypted packet -#### ``send()` +#### `send()` Sends the packet. * **Returns:** A [RNS.PacketReceipt](#api-packetreceipt) instance if *create_receipt* was set to *True* when the packet was instantiated, if not returns *None*. If the packet could not be sent *False* is returned. -#### ``resend()` +#### `resend()` Re-sends the packet. * **Returns:** A [RNS.PacketReceipt](#api-packetreceipt) instance if *create_receipt* was set to *True* when the packet was instantiated, if not returns *None*. If the packet could not be sent *False* is returned. -#### ``get_rssi()` +#### `get_rssi()` * **Returns:** The physical layer *Received Signal Strength Indication* if available, otherwise `None`. -#### ``get_snr()` +#### `get_snr()` * **Returns:** The physical layer *Signal-to-Noise Ratio* if available, otherwise `None`. -#### ``get_q()` +#### `get_q()` * **Returns:** The physical layer *Link Quality* if available, otherwise `None`. @@ -638,31 +638,31 @@ The PacketReceipt class is used to receive notifications about of this class are never created manually, but always returned from the *send()* method of a [RNS.Packet](#api-packet) instance. -#### ``get_status()` +#### `get_status()` * **Returns:** The status of the associated [RNS.Packet](#api-packet) instance. Can be one of `RNS.PacketReceipt.SENT`, `RNS.PacketReceipt.DELIVERED`, `RNS.PacketReceipt.FAILED` or `RNS.PacketReceipt.CULLED`. -#### ``get_rtt()` +#### `get_rtt()` * **Returns:** The round-trip-time in seconds -#### ``set_timeout(timeout)` +#### `set_timeout(timeout)` Sets a timeout in seconds * **Parameters:** **timeout** – The timeout in seconds. -#### ``set_delivery_callback(callback)` +#### `set_delivery_callback(callback)` Sets a function that gets called if a successfull delivery has been proven. * **Parameters:** **callback** – A *callable* with the signature *callback(packet_receipt)* -#### ``set_timeout_callback(callback)` +#### `set_timeout_callback(callback)` Sets a function that gets called if the delivery times out. @@ -680,27 +680,27 @@ and encrypted connectivity with the specified destination. * **established_callback** – An optional function or method with the signature *callback(link)* to be called when the link has been established. * **closed_callback** – An optional function or method with the signature *callback(link)* to be called when the link is closed. -#### ``CURVE = 'Curve25519'` +#### `CURVE = 'Curve25519'` The curve used for Elliptic Curve DH key exchanges -#### ``ESTABLISHMENT_TIMEOUT_PER_HOP = 6` +#### `ESTABLISHMENT_TIMEOUT_PER_HOP = 6` Timeout for link establishment in seconds per hop to destination. -#### ``KEEPALIVE_TIMEOUT_FACTOR = 4` +#### `KEEPALIVE_TIMEOUT_FACTOR = 4` RTT timeout factor used in link timeout calculation. -#### ``STALE_GRACE = 5` +#### `STALE_GRACE = 5` Grace period in seconds used in link timeout calculation. -#### ``KEEPALIVE = 360` +#### `KEEPALIVE = 360` Default interval for sending keep-alive packets on established links in seconds. -#### ``STALE_TIME = 720` +#### `STALE_TIME = 720` If no traffic or keep-alive packets are received within this period, the link will be marked as stale, and a final keep-alive packet will be sent. @@ -708,7 +708,7 @@ If after this no traffic or keep-alive packets are received within `RTT` \* `KEEPALIVE_TIMEOUT_FACTOR` + `STALE_GRACE`, the link is considered timed out, and will be torn down. -#### ``identify(identity)` +#### `identify(identity)` Identifies the initiator of the link to the remote peer. This can only happen once the link has been established, and is carried out over the encrypted link. @@ -718,7 +718,7 @@ thus preserved. This method can be used for authentication. * **Parameters:** **identity** – An RNS.Identity instance to identify as. -#### ``request(path, data=None, response_callback=None, failed_callback=None, progress_callback=None, timeout=None)` +#### `request(path, data=None, response_callback=None, failed_callback=None, progress_callback=None, timeout=None)` Sends a request to the remote peer. @@ -731,7 +731,7 @@ Sends a request to the remote peer. * **Returns:** A [RNS.RequestReceipt](#api-requestreceipt) instance if the request was sent, or *False* if it was not. -#### ``track_phy_stats(track)` +#### `track_phy_stats(track)` You can enable physical layer statistics on a per-link basis. If this is enabled, and the link is running over an interface that supports reporting physical layer @@ -741,89 +741,89 @@ statistics, you will be able to retrieve stats such as *RSSI*, *SNR* and physica * **Parameters:** **track** – Whether or not to keep track of physical layer statistics. Value must be `True` or `False`. -#### ``get_rssi()` +#### `get_rssi()` * **Returns:** The physical layer *Received Signal Strength Indication* if available, otherwise `None`. Physical layer statistics must be enabled on the link for this method to return a value. -#### ``get_snr()` +#### `get_snr()` * **Returns:** The physical layer *Signal-to-Noise Ratio* if available, otherwise `None`. Physical layer statistics must be enabled on the link for this method to return a value. -#### ``get_q()` +#### `get_q()` * **Returns:** The physical layer *Link Quality* if available, otherwise `None`. Physical layer statistics must be enabled on the link for this method to return a value. -#### ``get_establishment_rate()` +#### `get_establishment_rate()` * **Returns:** The data transfer rate at which the link establishment procedure ocurred, in bits per second. -#### ``get_mtu()` +#### `get_mtu()` * **Returns:** The MTU of an established link. -#### ``get_mdu()` +#### `get_mdu()` * **Returns:** The packet MDU of an established link. -#### ``get_expected_rate()` +#### `get_expected_rate()` * **Returns:** The packet expected in-flight data rate of an established link. -#### ``get_mode()` +#### `get_mode()` * **Returns:** The mode of an established link. -#### ``get_age()` +#### `get_age()` * **Returns:** The time in seconds since this link was established. -#### ``no_inbound_for()` +#### `no_inbound_for()` * **Returns:** The time in seconds since last inbound packet on the link. This includes keepalive packets. -#### ``no_outbound_for()` +#### `no_outbound_for()` * **Returns:** The time in seconds since last outbound packet on the link. This includes keepalive packets. -#### ``no_data_for()` +#### `no_data_for()` * **Returns:** The time in seconds since payload data traversed the link. This excludes keepalive packets. -#### ``inactive_for()` +#### `inactive_for()` * **Returns:** The time in seconds since activity on the link. This includes keepalive packets. -#### ``get_remote_identity()` +#### `get_remote_identity()` * **Returns:** The identity of the remote peer, if it is known. Calling this method will not query the remote initiator to reveal its identity. Returns `None` if the link initiator has not already independently called the `identify(identity)` method. -#### ``teardown()` +#### `teardown()` Closes the link and purges encryption keys. New keys will be used if a new link to the same destination is established. -#### ``get_channel()` +#### `get_channel()` Get the `Channel` for this link. * **Returns:** `Channel` object -#### ``set_link_closed_callback(callback)` +#### `set_link_closed_callback(callback)` Registers a function to be called when a link has been torn down. @@ -831,7 +831,7 @@ torn down. * **Parameters:** **callback** – A function or method with the signature *callback(link)* to be called. -#### ``set_packet_callback(callback)` +#### `set_packet_callback(callback)` Registers a function to be called when a packet has been received over this link. @@ -839,7 +839,7 @@ received over this link. * **Parameters:** **callback** – A function or method with the signature *callback(message, packet)* to be called. -#### ``set_resource_callback(callback)` +#### `set_resource_callback(callback)` Registers a function to be called when a resource has been advertised over this link. If the function returns *True* @@ -849,7 +849,7 @@ be ignored. * **Parameters:** **callback** – A function or method with the signature *callback(resource)* to be called. Please note that only the basic information of the resource is available at this time, such as *get_transfer_size()*, *get_data_size()*, *get_parts()* and *is_compressed()*. -#### ``set_resource_started_callback(callback)` +#### `set_resource_started_callback(callback)` Registers a function to be called when a resource has begun transferring over this link. @@ -857,7 +857,7 @@ transferring over this link. * **Parameters:** **callback** – A function or method with the signature *callback(resource)* to be called. -#### ``set_resource_concluded_callback(callback)` +#### `set_resource_concluded_callback(callback)` Registers a function to be called when a resource has concluded transferring over this link. @@ -865,7 +865,7 @@ transferring over this link. * **Parameters:** **callback** – A function or method with the signature *callback(resource)* to be called. -#### ``set_remote_identified_callback(callback)` +#### `set_remote_identified_callback(callback)` Registers a function to be called when an initiating peer has identified over this link. @@ -873,7 +873,7 @@ identified over this link. * **Parameters:** **callback** – A function or method with the signature *callback(link, identity)* to be called. -#### ``set_resource_strategy(resource_strategy)` +#### `set_resource_strategy(resource_strategy)` Sets the resource strategy for the link. @@ -888,32 +888,32 @@ An instance of this class is returned by the `request` method of `RNS.Link` instances. It should never be instantiated manually. It provides methods to check status, response time and response data when the request concludes. -#### ``get_request_id()` +#### `get_request_id()` * **Returns:** The request ID as *bytes*. -#### ``get_status()` +#### `get_status()` * **Returns:** The current status of the request, one of `RNS.RequestReceipt.FAILED`, `RNS.RequestReceipt.SENT`, `RNS.RequestReceipt.DELIVERED`, `RNS.RequestReceipt.READY`. -#### ``get_progress()` +#### `get_progress()` * **Returns:** The progress of a response being received as a *float* between 0.0 and 1.0. -#### ``get_response()` +#### `get_response()` * **Returns:** The response as *bytes* if it is ready, otherwise *None*. -#### ``get_response_time()` +#### `get_response_time()` * **Returns:** The response time of the request in seconds. -#### ``concluded()` +#### `concluded()` * **Returns:** True if the associated request has concluded (successfully or with a failure), otherwise False. @@ -932,46 +932,46 @@ compression, coordination and checksumming. * **callback** – An optional *callable* with the signature *callback(resource)*. Will be called when the resource transfer concludes. * **progress_callback** – An optional *callable* with the signature *callback(resource)*. Will be called whenever the resource transfer progress is updated. -#### ``advertise()` +#### `advertise()` Advertise the resource. If the other end of the link accepts the resource advertisement it will begin transferring. -#### ``cancel()` +#### `cancel()` Cancels transferring the resource. -#### ``get_progress()` +#### `get_progress()` * **Returns:** The current progress of the resource transfer as a *float* between 0.0 and 1.0. -#### ``get_transfer_size()` +#### `get_transfer_size()` * **Returns:** The number of bytes needed to transfer the resource. -#### ``get_data_size()` +#### `get_data_size()` * **Returns:** The total data size of the resource. -#### ``get_parts()` +#### `get_parts()` * **Returns:** The number of parts the resource will be transferred in. -#### ``get_segments()` +#### `get_segments()` * **Returns:** The number of segments the resource is divided into. -#### ``get_hash()` +#### `get_hash()` * **Returns:** The hash of the resource. -#### ``is_compressed()` +#### `is_compressed()` * **Returns:** Whether the resource is compressed. @@ -1004,7 +1004,7 @@ messages over the `Link`. `Channel` is not instantiated directly, but rather obtained from a `Link` with `get_channel()`. -#### ``register_message_type(message_class: Type[[MessageBase](#RNS.MessageBase)])` +#### `register_message_type(message_class: Type[[MessageBase](#RNS.MessageBase)])` Register a message class for reception over a `Channel`. @@ -1013,7 +1013,7 @@ Message classes must extend `MessageBase`. * **Parameters:** **message_class** – Class to register -#### ``add_message_handler(callback: MessageCallbackType)` +#### `add_message_handler(callback: MessageCallbackType)` Add a handler for incoming messages. A handler has the following signature: @@ -1028,21 +1028,21 @@ returning handler will not be called. * **Parameters:** **callback** – Function to call -#### ``remove_message_handler(callback: MessageCallbackType)` +#### `remove_message_handler(callback: MessageCallbackType)` Remove a handler added with `add_message_handler`. * **Parameters:** **callback** – handler to remove -#### ``is_ready_to_send() → bool` +#### `is_ready_to_send() → bool` Check if `Channel` is ready to send. * **Returns:** True if ready -#### ``send(message: [MessageBase](#RNS.MessageBase)) → Envelope` +#### `send(message: [MessageBase](#RNS.MessageBase)) → Envelope` Send a message. If a message send is attempted and `Channel` is not ready, an exception is thrown. @@ -1050,7 +1050,7 @@ Send a message. If a message send is attempted and * **Parameters:** **message** – an instance of a `MessageBase` subclass -#### ``property mdu` +#### `property mdu` Maximum Data Unit: the number of bytes available for a message to consume in a single send. This @@ -1066,21 +1066,21 @@ Base type for any messages sent or received on a Channel. Subclasses must define the two abstract methods as well as the `MSGTYPE` class variable. -#### ``MSGTYPE = None` +#### `MSGTYPE = None` Defines a unique identifier for a message class. * Must be unique within all classes registered with a `Channel` * Must be less than `0xf000`. Values greater than or equal to `0xf000` are reserved. -#### ``abstractmethod pack() → bytes` +#### `abstractmethod pack() → bytes` Create and return the binary representation of the message * **Returns:** binary representation of message -#### ``abstractmethod unpack(raw: bytes)` +#### `abstractmethod unpack(raw: bytes)` Populate message from binary representation @@ -1096,7 +1096,7 @@ These functions use `BufferedReader`, `BufferedWriter`, and `BufferedRWPair` to add buffering to `RawChannelReader` and `RawChannelWriter`. -#### ``static create_reader(stream_id: int, channel: [Channel](#RNS.Channel.Channel), ready_callback: Callable[[int], None] | None = None) → BufferedReader` +#### `static create_reader(stream_id: int, channel: [Channel](#RNS.Channel.Channel), ready_callback: Callable[[int], None] | None = None) → BufferedReader` Create a buffered reader that reads binary data sent over a `Channel`, with an optional callback when @@ -1115,7 +1115,7 @@ of this object, see the Python documentation for * **Returns:** a BufferedReader object -#### ``static create_writer(stream_id: int, channel: [Channel](#RNS.Channel.Channel)) → BufferedWriter` +#### `static create_writer(stream_id: int, channel: [Channel](#RNS.Channel.Channel)) → BufferedWriter` Create a buffered writer that writes binary data over a `Channel`. @@ -1130,7 +1130,7 @@ of this object, see the Python documentation for * **Returns:** a BufferedWriter object -#### ``static create_bidirectional_buffer(receive_stream_id: int, send_stream_id: int, channel: [Channel](#RNS.Channel.Channel), ready_callback: Callable[[int], None] | None = None) → BufferedRWPair` +#### `static create_bidirectional_buffer(receive_stream_id: int, send_stream_id: int, channel: [Channel](#RNS.Channel.Channel), ready_callback: Callable[[int], None] | None = None) → BufferedRWPair` Create a buffered reader/writer pair that reads and writes binary data over a `Channel`, with an @@ -1165,7 +1165,7 @@ binary stream data sent over a `Channel`. > object, see the Python documentation for > `RawIOBase`. -#### ``\_\_init_\_(stream_id: int, channel: [Channel](#RNS.Channel.Channel))` +#### `__init__(stream_id: int, channel: [Channel](#RNS.Channel.Channel))` Create a raw channel reader. @@ -1173,7 +1173,7 @@ Create a raw channel reader. * **stream_id** – local stream id to receive at * **channel** – `Channel` object to receive from -#### ``add_ready_callback(cb: Callable[[int], None])` +#### `add_ready_callback(cb: Callable[[int], None])` Add a function to be called when new data is available. The function should have the signature `(ready_bytes: int) -> None` @@ -1181,7 +1181,7 @@ The function should have the signature `(ready_bytes: int) -> None` * **Parameters:** **cb** – function to call -#### ``remove_ready_callback(cb: Callable[[int], None])` +#### `remove_ready_callback(cb: Callable[[int], None])` Remove a function added with [`RNS.RawChannelReader.add_ready_callback()`](#RNS.RawChannelReader.add_ready_callback) @@ -1203,7 +1203,7 @@ binary stream data sent over a channel. > object, see the Python documentation for > `RawIOBase`. -#### ``\_\_init_\_(stream_id: int, channel: [Channel](#RNS.Channel.Channel))` +#### `__init__(stream_id: int, channel: [Channel](#RNS.Channel.Channel))` Create a raw channel writer. @@ -1216,11 +1216,11 @@ Create a raw channel writer. Through static methods of this class you can interact with the Transport system of Reticulum. -#### ``PATHFINDER_M = 128` +#### `PATHFINDER_M = 128` Maximum amount of hops that Reticulum will transport a packet. -#### ``static register_announce_handler(handler)` +#### `static register_announce_handler(handler)` Registers an announce handler. @@ -1231,42 +1231,42 @@ Registers an announce handler. optionally have a *receive_path_responses* attribute set to `True`, to also receive all path responses, in addition to live announces. See the [Announce Example](examples.md#example-announce) for more info. -#### ``static deregister_announce_handler(handler)` +#### `static deregister_announce_handler(handler)` Deregisters an announce handler. * **Parameters:** **handler** – The announce handler to be deregistered. -#### ``static has_path(destination_hash)` +#### `static has_path(destination_hash)` * **Parameters:** **destination_hash** – A destination hash as *bytes*. * **Returns:** *True* if a path to the destination is known, otherwise *False*. -#### ``static hops_to(destination_hash)` +#### `static hops_to(destination_hash)` * **Parameters:** **destination_hash** – A destination hash as *bytes*. * **Returns:** The number of hops to the specified destination, or `RNS.Transport.PATHFINDER_M` if the number of hops is unknown. -#### ``static next_hop(destination_hash)` +#### `static next_hop(destination_hash)` * **Parameters:** **destination_hash** – A destination hash as *bytes*. * **Returns:** The destination hash as *bytes* for the next hop to the specified destination, or *None* if the next hop is unknown. -#### ``static next_hop_interface(destination_hash)` +#### `static next_hop_interface(destination_hash)` * **Parameters:** **destination_hash** – A destination hash as *bytes*. * **Returns:** The interface for the next hop to the specified destination, or *None* if the interface is unknown. -#### ``static await_path(destination_hash, timeout=None, on_interface=None)` +#### `static await_path(destination_hash, timeout=None, on_interface=None)` Requests a path to the destination from the network and blocks until the path is available, or the timeout is reached. @@ -1278,7 +1278,7 @@ blocks until the path is available, or the timeout is reached. * **Returns:** *True* if a path to the destination is found, otherwise *False*. -#### ``static request_path(destination_hash, on_interface=None, tag=None, recursive=False)` +#### `static request_path(destination_hash, on_interface=None, tag=None, recursive=False)` Requests a path to the destination from the network. If another reachable peer on the network knows a path, it