<spanid="api-main"></span><h1>API Reference<aclass="headerlink"href="#api-reference"title="Permalink to this heading">#</a></h1>
<p>Communication over Reticulum networks is achieved by using a simple set of classes exposed by the RNS API.
This chapter lists and explains all classes exposed by the Reticulum Network Stack API, along with their method signatures and usage. It can be used as a reference while writing applications that utilise Reticulum, or it can be read in entirity to gain an understanding of the complete functionality of RNS from a developers perspective.</p>
<pid="api-reticulum"><h3> Reticulum </h3></p>
<dlclass="py class">
<dtclass="sig sig-object py"id="RNS.Reticulum">
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">Reticulum</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">configdir</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">loglevel</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">logdest</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">verbosity</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Reticulum"title="Permalink to this definition">#</a></dt>
<dd><p>This class is used to initialise access to Reticulum within a
program. You must create exactly one instance of this class before
carrying out any other RNS operations, such as creating destinations
or sending traffic. Every independently executed program must create
their own instance of the Reticulum class, but Reticulum will
automatically handle inter-program communication on the same system,
and expose all connected programs to external interfaces as well.</p>
<p>As soon as an instance of this class is created, Reticulum will start
opening and configuring any hardware devices specified in the supplied
configuration.</p>
<p>Currently the first running instance must be kept running while other
local instances are connected, as the first created instance will
act as a master instance that directly communicates with external
hardware such as modems, TNCs and radios. If a master instance is
asked to exit, it will not exit until all client processes have
terminated (unless killed forcibly).</p>
<p>If you are running Reticulum on a system with several different
programs that use RNS starting and terminating at different times,
it will be advantageous to run a master RNS instance as a daemon for
<spanclass="sig-name descname"><spanclass="pre">MTU</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">500</span></em><aclass="headerlink"href="#RNS.Reticulum.MTU"title="Permalink to this definition">#</a></dt>
<dd><p>The MTU that Reticulum adheres to, and will expect other peers to
<spanclass="sig-name descname"><spanclass="pre">ANNOUNCE_CAP</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">2</span></em><aclass="headerlink"href="#RNS.Reticulum.ANNOUNCE_CAP"title="Permalink to this definition">#</a></dt>
<dd><p>The maximum percentage of interface bandwidth that, at any given time,
may be used to propagate announces. If an announce was scheduled for
broadcasting on an interface, but doing so would exceed the allowed
bandwidth allocation, the announce will be queued for transmission
when there is bandwidth available.</p>
<p>Reticulum will always prioritise propagating announces with fewer
hops, ensuring that distant, large networks with many peers on fast
links don’t overwhelm the capacity of smaller networks on slower
mediums. If an announce remains queued for an extended amount of time,
it will eventually be dropped.</p>
<p>This value will be applied by default to all created interfaces,
<spanclass="sig-name descname"><spanclass="pre">MINIMUM_BITRATE</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">5</span></em><aclass="headerlink"href="#RNS.Reticulum.MINIMUM_BITRATE"title="Permalink to this definition">#</a></dt>
<dd><p>Minimum bitrate required across a medium for Reticulum to be able
to successfully establish links. Currently 5 bits per second.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">get_instance</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Reticulum.get_instance"title="Permalink to this definition">#</a></dt>
<dd><p>Return the currently running Reticulum instance</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">should_use_implicit_proof</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Reticulum.should_use_implicit_proof"title="Permalink to this definition">#</a></dt>
<dd><p>Returns whether proofs sent are explicit or implicit.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">transport_enabled</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Reticulum.transport_enabled"title="Permalink to this definition">#</a></dt>
<dd><p>Returns whether Transport is enabled for the running
instance.</p>
<p>When Transport is enabled, Reticulum will
route traffic for other peers, respond to path requests
<ddclass="field-odd"><p>True if Transport is enabled, False if not.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
<pid="api-identity"><h3> Identity </h3></p>
<dlclass="py class">
<dtclass="sig sig-object py"id="RNS.Identity">
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">Identity</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">create_keys</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">True</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity"title="Permalink to this definition">#</a></dt>
<dd><p>This class is used to manage identities in Reticulum. It provides methods
for encryption, decryption, signatures and verification, and is the basis
for all encrypted communication over Reticulum networks.</p>
<spanclass="sig-name descname"><spanclass="pre">CURVE</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">'Curve25519'</span></em><aclass="headerlink"href="#RNS.Identity.CURVE"title="Permalink to this definition">#</a></dt>
<dd><p>The curve used for Elliptic Curve DH key exchanges</p>
<spanclass="sig-name descname"><spanclass="pre">KEYSIZE</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">512</span></em><aclass="headerlink"href="#RNS.Identity.KEYSIZE"title="Permalink to this definition">#</a></dt>
<dd><p>X25519 key size in bits. A complete key is the concatenation of a 256 bit encryption key, and a 256 bit signing key.</p>
<spanclass="sig-name descname"><spanclass="pre">TRUNCATED_HASHLENGTH</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">128</span></em><aclass="headerlink"href="#RNS.Identity.TRUNCATED_HASHLENGTH"title="Permalink to this definition">#</a></dt>
<dd><p>Constant specifying the truncated hash length (in bits) used by Reticulum
for addressable hashes and other purposes. Non-configurable.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">recall</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination_hash</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.recall"title="Permalink to this definition">#</a></dt>
<dd><p>Recall identity for a destination hash.</p>
<ddclass="field-even"><p>An <aclass="reference internal"href="#api-identity"><spanclass="std std-ref">RNS.Identity</span></a> instance that can be used to create an outgoing <aclass="reference internal"href="#api-destination"><spanclass="std std-ref">RNS.Destination</span></a>, or <em>None</em> if the destination is unknown.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">recall_app_data</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination_hash</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.recall_app_data"title="Permalink to this definition">#</a></dt>
<dd><p>Recall last heard app_data for a destination hash.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">full_hash</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">data</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.full_hash"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">truncated_hash</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">data</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.truncated_hash"title="Permalink to this definition">#</a></dt>
<dd><p>Get a truncated SHA-256 hash of passed data.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">get_random_hash</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.get_random_hash"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">from_bytes</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">prv_bytes</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.from_bytes"title="Permalink to this definition">#</a></dt>
<dd><p>Create a new <aclass="reference internal"href="#api-identity"><spanclass="std std-ref">RNS.Identity</span></a> instance from <em>bytes</em> of private key.
Can be used to load previously created and saved identities into Reticulum.</p>
<ddclass="field-odd"><p><strong>prv_bytes</strong>– The <em>bytes</em> of private a saved private key. <strong>HAZARD!</strong> Never use this to generate a new key by feeding random data in prv_bytes.</p>
<ddclass="field-even"><p>A <aclass="reference internal"href="#api-identity"><spanclass="std std-ref">RNS.Identity</span></a> instance, or <em>None</em> if the <em>bytes</em> data was invalid.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">from_file</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">path</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.from_file"title="Permalink to this definition">#</a></dt>
<dd><p>Create a new <aclass="reference internal"href="#api-identity"><spanclass="std std-ref">RNS.Identity</span></a> instance from a file.
Can be used to load previously created and saved identities into Reticulum.</p>
<ddclass="field-odd"><p><strong>path</strong>– The full path to the saved <aclass="reference internal"href="#api-identity"><spanclass="std std-ref">RNS.Identity</span></a> data</p>
<ddclass="field-even"><p>A <aclass="reference internal"href="#api-identity"><spanclass="std std-ref">RNS.Identity</span></a> instance, or <em>None</em> if the loaded data was invalid.</p>
<spanclass="sig-name descname"><spanclass="pre">to_file</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">path</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.to_file"title="Permalink to this definition">#</a></dt>
<dd><p>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
communication for the identity. Be very careful with this method.</p>
<spanclass="sig-name descname"><spanclass="pre">get_private_key</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.get_private_key"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_public_key</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.get_public_key"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">load_private_key</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">prv_bytes</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.load_private_key"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">load_public_key</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">pub_bytes</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.load_public_key"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">encrypt</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">plaintext</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.encrypt"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">decrypt</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">ciphertext_token</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.decrypt"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">sign</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">message</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.sign"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">validate</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">signature</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">message</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Identity.validate"title="Permalink to this definition">#</a></dt>
<dd><p>Validates the signature of a signed message.</p>
<ddclass="field-odd"><p><em>KeyError</em> if the instance does not hold a public key.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
<pid="api-destination"><h3> Destination </h3></p>
<dlclass="py class">
<dtclass="sig sig-object py"id="RNS.Destination">
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">Destination</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">identity</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">direction</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">type</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">app_name</span></span></em>, <emclass="sig-param"><spanclass="o"><spanclass="pre">*</span></span><spanclass="n"><spanclass="pre">aspects</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination"title="Permalink to this definition">#</a></dt>
<dd><p>A class used to describe endpoints in a Reticulum Network. Destination
instances are used both to create outgoing and incoming endpoints. The
destination type will decide if encryption, and what type, is used in
communication with the endpoint. A destination can also announce its
presence on the network, which will also distribute necessary keys for
<li><p><strong>identity</strong>– An instance of <aclass="reference internal"href="#api-identity"><spanclass="std std-ref">RNS.Identity</span></a>. Can hold only public keys for an outgoing destination, or holding private keys for an ingoing.</p></li>
<li><p><strong>direction</strong>–<codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.IN</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.OUT</span></code>.</p></li>
<li><p><strong>type</strong>–<codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.SINGLE</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.GROUP</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.PLAIN</span></code>.</p></li>
<li><p><strong>app_name</strong>– A string specifying the app name.</p></li>
<li><p><strong>*aspects</strong>– Any non-zero number of string arguments.</p></li>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">expand_name</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">identity</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">app_name</span></span></em>, <emclass="sig-param"><spanclass="o"><spanclass="pre">*</span></span><spanclass="n"><spanclass="pre">aspects</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.expand_name"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">app_and_aspects_from_name</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">full_name</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.app_and_aspects_from_name"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">hash_from_name_and_identity</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">full_name</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">identity</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.hash_from_name_and_identity"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">hash</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">identity</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">app_name</span></span></em>, <emclass="sig-param"><spanclass="o"><spanclass="pre">*</span></span><spanclass="n"><spanclass="pre">aspects</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.hash"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">announce</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">app_data</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">path_response</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">False</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">attached_interface</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">tag</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">send</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">True</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.announce"title="Permalink to this definition">#</a></dt>
<dd><p>Creates an announce packet for this destination and broadcasts it on all
relevant interfaces. Application specific data can be added to the announce.</p>
<li><p><strong>app_data</strong>–<em>bytes</em> containing the app_data.</p></li>
<li><p><strong>path_response</strong>– Internal flag used by <aclass="reference internal"href="#api-transport"><spanclass="std std-ref">RNS.Transport</span></a>. Ignore.</p></li>
<spanclass="sig-name descname"><spanclass="pre">accepts_links</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">accepts</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.accepts_links"title="Permalink to this definition">#</a></dt>
<dd><p>Set or query whether the destination accepts incoming link requests.</p>
<ddclass="field-odd"><p><strong>accepts</strong>– If <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code>, this method sets whether the destination accepts incoming link requests. If not provided or <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>, the method returns whether the destination currently accepts link requests.</p>
<ddclass="field-even"><p><codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code> depending on whether the destination accepts incoming link requests, if the <em>accepts</em> parameter is not provided or <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>.</p>
<spanclass="sig-name descname"><spanclass="pre">set_link_established_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.set_link_established_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Registers a function to be called when a link has been established to
<ddclass="field-odd"><p><strong>callback</strong>– A function or method with the signature <em>callback(link)</em> to be called when a new link is established with this destination.</p>
<spanclass="sig-name descname"><spanclass="pre">set_packet_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.set_packet_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Registers a function to be called when a packet has been received by
<ddclass="field-odd"><p><strong>callback</strong>– A function or method with the signature <em>callback(data, packet)</em> to be called when this destination receives a packet.</p>
<spanclass="sig-name descname"><spanclass="pre">set_proof_requested_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.set_proof_requested_callback"title="Permalink to this definition">#</a></dt>
<dd><p>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
proofs should be returned for received packets.</p>
<ddclass="field-odd"><p><strong>callback</strong>– A function or method to with the signature <em>callback(packet)</em> 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.</p>
<spanclass="sig-name descname"><spanclass="pre">set_proof_strategy</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">proof_strategy</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.set_proof_strategy"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p><strong>proof_strategy</strong>– One of <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.PROVE_NONE</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.PROVE_ALL</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.PROVE_APP</span></code>. If <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.PROVE_APP</span></code> is set, the <cite>proof_requested_callback</cite> will be called to determine whether a proof should be sent or not.</p>
<spanclass="sig-name descname"><spanclass="pre">register_request_handler</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">path</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">response_generator</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">allow</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">ALLOW_NONE</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">allowed_list</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.register_request_handler"title="Permalink to this definition">#</a></dt>
<li><p><strong>path</strong>– The path for the request handler to be registered.</p></li>
<li><p><strong>response_generator</strong>– A function or method with the signature <em>response_generator(path, data, request_id, link_id, remote_identity, requested_at)</em> to be called. Whatever this funcion returns will be sent as a response to the requester. If the function returns <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>, no response will be sent.</p></li>
<li><p><strong>allow</strong>– One of <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.ALLOW_NONE</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.ALLOW_ALL</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.ALLOW_LIST</span></code>. If <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.ALLOW_LIST</span></code> is set, the request handler will only respond to requests for identified peers in the supplied list.</p></li>
<li><p><strong>allowed_list</strong>– A list of <em>bytes-like</em><aclass="reference internal"href="#api-identity"><spanclass="std std-ref">RNS.Identity</span></a> hashes.</p></li>
<ddclass="field-even"><p><codeclass="docutils literal notranslate"><spanclass="pre">ValueError</span></code> if any of the supplied arguments are invalid.</p>
<spanclass="sig-name descname"><spanclass="pre">deregister_request_handler</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">path</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.deregister_request_handler"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">create_keys</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.create_keys"title="Permalink to this definition">#</a></dt>
<dd><p>For a <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.GROUP</span></code> type destination, creates a new symmetric key.</p>
<ddclass="field-odd"><p><codeclass="docutils literal notranslate"><spanclass="pre">TypeError</span></code> if called on an incompatible type of destination.</p>
<spanclass="sig-name descname"><spanclass="pre">get_private_key</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.get_private_key"title="Permalink to this definition">#</a></dt>
<dd><p>For a <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.GROUP</span></code> type destination, returns the symmetric private key.</p>
<ddclass="field-odd"><p><codeclass="docutils literal notranslate"><spanclass="pre">TypeError</span></code> if called on an incompatible type of destination.</p>
<spanclass="sig-name descname"><spanclass="pre">load_private_key</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">key</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.load_private_key"title="Permalink to this definition">#</a></dt>
<dd><p>For a <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.GROUP</span></code> type destination, loads a symmetric private key.</p>
<ddclass="field-even"><p><codeclass="docutils literal notranslate"><spanclass="pre">TypeError</span></code> if called on an incompatible type of destination.</p>
<spanclass="sig-name descname"><spanclass="pre">encrypt</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">plaintext</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.encrypt"title="Permalink to this definition">#</a></dt>
<dd><p>Encrypts information for <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.SINGLE</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.GROUP</span></code> type destination.</p>
<ddclass="field-even"><p><codeclass="docutils literal notranslate"><spanclass="pre">ValueError</span></code> if destination does not hold a necessary key for encryption.</p>
<spanclass="sig-name descname"><spanclass="pre">decrypt</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">ciphertext</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.decrypt"title="Permalink to this definition">#</a></dt>
<dd><p>Decrypts information for <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.SINGLE</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.GROUP</span></code> type destination.</p>
<ddclass="field-even"><p><codeclass="docutils literal notranslate"><spanclass="pre">ValueError</span></code> if destination does not hold a necessary key for decryption.</p>
<spanclass="sig-name descname"><spanclass="pre">sign</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">message</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.sign"title="Permalink to this definition">#</a></dt>
<dd><p>Signs information for <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.SINGLE</span></code> type destination.</p>
<spanclass="sig-name descname"><spanclass="pre">set_default_app_data</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">app_data</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.set_default_app_data"title="Permalink to this definition">#</a></dt>
<dd><p>Sets the default app_data for the destination. If set, the default
app_data will be included in every announce sent by the destination,
unless other app_data is specified in the <em>announce</em> method.</p>
<ddclass="field-odd"><p><strong>app_data</strong>– A <em>bytes-like</em> containing the default app_data, or a <em>callable</em> returning a <em>bytes-like</em> containing the app_data.</p>
<spanclass="sig-name descname"><spanclass="pre">clear_default_app_data</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Destination.clear_default_app_data"title="Permalink to this definition">#</a></dt>
<dd><p>Clears default app_data previously set for the destination.</p>
</dd></dl>
</dd></dl>
<pid="api-packet"><h3> Packet </h3></p>
<dlclass="py class">
<dtclass="sig sig-object py"id="RNS.Packet">
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">Packet</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">data</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">create_receipt</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">True</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Packet"title="Permalink to this definition">#</a></dt>
<dd><p>The Packet class is used to create packet instances that can be sent
over a Reticulum network. Packets will automatically be encrypted if
<codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.GROUP</span></code> destination or a <aclass="reference internal"href="#api-link"><spanclass="std std-ref">RNS.Link</span></a>.</p>
<p>For <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.GROUP</span></code> destinations, Reticulum will use the
pre-shared key configured for the destination. All packets to group
destinations are encrypted with the same AES-128 key.</p>
<p>For <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Destination.SINGLE</span></code> destinations, Reticulum will use a newly
derived ephemeral AES-128 key for every packet.</p>
<p>For <aclass="reference internal"href="#api-link"><spanclass="std std-ref">RNS.Link</span></a> destinations, Reticulum will use per-link
ephemeral keys, and offers <strong>Forward Secrecy</strong>.</p>
<li><p><strong>destination</strong>– A <aclass="reference internal"href="#api-destination"><spanclass="std std-ref">RNS.Destination</span></a> instance to which the packet will be sent.</p></li>
<li><p><strong>data</strong>– The data payload to be included in the packet as <em>bytes</em>.</p></li>
<li><p><strong>create_receipt</strong>– Specifies whether a <aclass="reference internal"href="#api-packetreceipt"><spanclass="std std-ref">RNS.PacketReceipt</span></a> should be created when instantiating the packet.</p></li>
<spanclass="sig-name descname"><spanclass="pre">ENCRYPTED_MDU</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">383</span></em><aclass="headerlink"href="#RNS.Packet.ENCRYPTED_MDU"title="Permalink to this definition">#</a></dt>
<dd><p>The maximum size of the payload data in a single encrypted packet</p>
<spanclass="sig-name descname"><spanclass="pre">PLAIN_MDU</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">464</span></em><aclass="headerlink"href="#RNS.Packet.PLAIN_MDU"title="Permalink to this definition">#</a></dt>
<dd><p>The maximum size of the payload data in a single unencrypted packet</p>
</dd></dl>
<dlclass="py method">
<dtclass="sig sig-object py"id="RNS.Packet.send">
<spanclass="sig-name descname"><spanclass="pre">send</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Packet.send"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p>A <aclass="reference internal"href="#api-packetreceipt"><spanclass="std std-ref">RNS.PacketReceipt</span></a> instance if <em>create_receipt</em> was set to <em>True</em> when the packet was instantiated, if not returns <em>None</em>. If the packet could not be sent <em>False</em> is returned.</p>
<spanclass="sig-name descname"><spanclass="pre">resend</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Packet.resend"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p>A <aclass="reference internal"href="#api-packetreceipt"><spanclass="std std-ref">RNS.PacketReceipt</span></a> instance if <em>create_receipt</em> was set to <em>True</em> when the packet was instantiated, if not returns <em>None</em>. If the packet could not be sent <em>False</em> is returned.</p>
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">PacketReceipt</span></span><aclass="headerlink"href="#RNS.PacketReceipt"title="Permalink to this definition">#</a></dt>
<dd><p>The PacketReceipt class is used to receive notifications about
<aclass="reference internal"href="#api-packet"><spanclass="std std-ref">RNS.Packet</span></a> instances sent over the network. Instances
of this class are never created manually, but always returned from
the <em>send()</em> method of a <aclass="reference internal"href="#api-packet"><spanclass="std std-ref">RNS.Packet</span></a> instance.</p>
<spanclass="sig-name descname"><spanclass="pre">get_status</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.PacketReceipt.get_status"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p>The status of the associated <aclass="reference internal"href="#api-packet"><spanclass="std std-ref">RNS.Packet</span></a> instance. Can be one of <codeclass="docutils literal notranslate"><spanclass="pre">RNS.PacketReceipt.SENT</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.PacketReceipt.DELIVERED</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.PacketReceipt.FAILED</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.PacketReceipt.CULLED</span></code>.</p>
<spanclass="sig-name descname"><spanclass="pre">get_rtt</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.PacketReceipt.get_rtt"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">set_timeout</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">timeout</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.PacketReceipt.set_timeout"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">set_delivery_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.PacketReceipt.set_delivery_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Sets a function that gets called if a successfull delivery has been proven.</p>
<spanclass="sig-name descname"><spanclass="pre">set_timeout_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.PacketReceipt.set_timeout_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Sets a function that gets called if the delivery times out.</p>
<ddclass="field-odd"><p><strong>callback</strong>– A <em>callable</em> with the signature <em>callback(packet_receipt)</em></p>
</dd>
</dl>
</dd></dl>
</dd></dl>
<pid="api-link"><h3> Link </h3></p>
<dlclass="py class">
<dtclass="sig sig-object py"id="RNS.Link">
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">Link</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">established_callback</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">closed_callback</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link"title="Permalink to this definition">#</a></dt>
<dd><p>This class is used to establish and manage links to other peers. When a
link instance is created, Reticulum will attempt to establish verified
and encrypted connectivity with the specified destination.</p>
<li><p><strong>destination</strong>– A <aclass="reference internal"href="#api-destination"><spanclass="std std-ref">RNS.Destination</span></a> instance which to establish a link to.</p></li>
<li><p><strong>established_callback</strong>– An optional function or method with the signature <em>callback(link)</em> to be called when the link has been established.</p></li>
<li><p><strong>closed_callback</strong>– An optional function or method with the signature <em>callback(link)</em> to be called when the link is closed.</p></li>
</ul>
</dd>
</dl>
<dlclass="py attribute">
<dtclass="sig sig-object py"id="RNS.Link.CURVE">
<spanclass="sig-name descname"><spanclass="pre">CURVE</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">'Curve25519'</span></em><aclass="headerlink"href="#RNS.Link.CURVE"title="Permalink to this definition">#</a></dt>
<dd><p>The curve used for Elliptic Curve DH key exchanges</p>
<spanclass="sig-name descname"><spanclass="pre">ESTABLISHMENT_TIMEOUT_PER_HOP</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">6</span></em><aclass="headerlink"href="#RNS.Link.ESTABLISHMENT_TIMEOUT_PER_HOP"title="Permalink to this definition">#</a></dt>
<dd><p>Timeout for link establishment in seconds per hop to destination.</p>
<spanclass="sig-name descname"><spanclass="pre">KEEPALIVE_TIMEOUT_FACTOR</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">4</span></em><aclass="headerlink"href="#RNS.Link.KEEPALIVE_TIMEOUT_FACTOR"title="Permalink to this definition">#</a></dt>
<dd><p>RTT timeout factor used in link timeout calculation.</p>
<spanclass="sig-name descname"><spanclass="pre">STALE_GRACE</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">2</span></em><aclass="headerlink"href="#RNS.Link.STALE_GRACE"title="Permalink to this definition">#</a></dt>
<dd><p>Grace period in seconds used in link timeout calculation.</p>
<spanclass="sig-name descname"><spanclass="pre">KEEPALIVE</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">360</span></em><aclass="headerlink"href="#RNS.Link.KEEPALIVE"title="Permalink to this definition">#</a></dt>
<dd><p>Interval for sending keep-alive packets on established links in seconds.</p>
<spanclass="sig-name descname"><spanclass="pre">STALE_TIME</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">720</span></em><aclass="headerlink"href="#RNS.Link.STALE_TIME"title="Permalink to this definition">#</a></dt>
<dd><p>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.
If after this no traffic or keep-alive packets are received within <codeclass="docutils literal notranslate"><spanclass="pre">RTT</span></code> *
<codeclass="docutils literal notranslate"><spanclass="pre">KEEPALIVE_TIMEOUT_FACTOR</span></code> + <codeclass="docutils literal notranslate"><spanclass="pre">STALE_GRACE</span></code>, the link is considered timed out,
<spanclass="sig-name descname"><spanclass="pre">identify</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">identity</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.identify"title="Permalink to this definition">#</a></dt>
<dd><p>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.
The identity is only revealed to the remote peer, and initiator anonymity is
thus preserved. This method can be used for authentication.</p>
<spanclass="sig-name descname"><spanclass="pre">request</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">path</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">data</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">response_callback</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">failed_callback</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">progress_callback</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">timeout</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.request"title="Permalink to this definition">#</a></dt>
<li><p><strong>path</strong>– The request path.</p></li>
<li><p><strong>response_callback</strong>– An optional function or method with the signature <em>response_callback(request_receipt)</em> to be called when a response is received. See the <aclass="reference internal"href="examples.html#example-request"><spanclass="std std-ref">Request Example</span></a> for more info.</p></li>
<li><p><strong>failed_callback</strong>– An optional function or method with the signature <em>failed_callback(request_receipt)</em> to be called when a request fails. See the <aclass="reference internal"href="examples.html#example-request"><spanclass="std std-ref">Request Example</span></a> for more info.</p></li>
<li><p><strong>progress_callback</strong>– An optional function or method with the signature <em>progress_callback(request_receipt)</em> to be called when progress is made receiving the response. Progress can be accessed as a float between 0.0 and 1.0 by the <em>request_receipt.progress</em> property.</p></li>
<li><p><strong>timeout</strong>– An optional timeout in seconds for the request. If <em>None</em> is supplied it will be calculated based on link RTT.</p></li>
<ddclass="field-even"><p>A <aclass="reference internal"href="#api-requestreceipt"><spanclass="std std-ref">RNS.RequestReceipt</span></a> instance if the request was sent, or <em>False</em> if it was not.</p>
<spanclass="sig-name descname"><spanclass="pre">track_phy_stats</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">track</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.track_phy_stats"title="Permalink to this definition">#</a></dt>
<dd><p>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
statistics, you will be able to retrieve stats such as <em>RSSI</em>, <em>SNR</em> and physical
<ddclass="field-odd"><p><strong>track</strong>– Whether or not to keep track of physical layer statistics. Value must be <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code>.</p>
<spanclass="sig-name descname"><spanclass="pre">get_rssi</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.get_rssi"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p>The physical layer <em>Received Signal Strength Indication</em> if available, otherwise <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>. Physical layer statistics must be enabled on the link for this method to return a value.</p>
<spanclass="sig-name descname"><spanclass="pre">get_snr</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.get_snr"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p>The physical layer <em>Signal-to-Noise Ratio</em> if available, otherwise <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>. Physical layer statistics must be enabled on the link for this method to return a value.</p>
</dd>
</dl>
</dd></dl>
<dlclass="py method">
<dtclass="sig sig-object py"id="RNS.Link.get_q">
<spanclass="sig-name descname"><spanclass="pre">get_q</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.get_q"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p>The physical layer <em>Link Quality</em> if available, otherwise <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>. Physical layer statistics must be enabled on the link for this method to return a value.</p>
<spanclass="sig-name descname"><spanclass="pre">get_establishment_rate</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.get_establishment_rate"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">no_inbound_for</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.no_inbound_for"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">no_outbound_for</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.no_outbound_for"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">inactive_for</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.inactive_for"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_remote_identity</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.get_remote_identity"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p>The identity of the remote peer, if it is known. Calling this method will not query the remote initiator to reveal its identity. Returns <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> if the link initiator has not already independently called the <codeclass="docutils literal notranslate"><spanclass="pre">identify(identity)</span></code> method.</p>
<spanclass="sig-name descname"><spanclass="pre">teardown</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.teardown"title="Permalink to this definition">#</a></dt>
<dd><p>Closes the link and purges encryption keys. New keys will
be used if a new link to the same destination is established.</p>
<spanclass="sig-name descname"><spanclass="pre">get_channel</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.get_channel"title="Permalink to this definition">#</a></dt>
<dd><p>Get the <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code> for this link.</p>
<spanclass="sig-name descname"><spanclass="pre">set_link_closed_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.set_link_closed_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Registers a function to be called when a link has been
<spanclass="sig-name descname"><spanclass="pre">set_packet_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.set_packet_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Registers a function to be called when a packet has been
<spanclass="sig-name descname"><spanclass="pre">set_resource_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.set_resource_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Registers a function to be called when a resource has been
advertised over this link. If the function returns <em>True</em>
the resource will be accepted. If it returns <em>False</em> it will
<ddclass="field-odd"><p><strong>callback</strong>– A function or method with the signature <em>callback(resource)</em> to be called. Please note that only the basic information of the resource is available at this time, such as <em>get_transfer_size()</em>, <em>get_data_size()</em>, <em>get_parts()</em> and <em>is_compressed()</em>.</p>
<spanclass="sig-name descname"><spanclass="pre">set_resource_started_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.set_resource_started_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Registers a function to be called when a resource has begun
<spanclass="sig-name descname"><spanclass="pre">set_resource_concluded_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.set_resource_concluded_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Registers a function to be called when a resource has concluded
<spanclass="sig-name descname"><spanclass="pre">set_remote_identified_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.set_remote_identified_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Registers a function to be called when an initiating peer has
<spanclass="sig-name descname"><spanclass="pre">set_resource_strategy</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">resource_strategy</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Link.set_resource_strategy"title="Permalink to this definition">#</a></dt>
<dd><p>Sets the resource strategy for the link.</p>
<ddclass="field-odd"><p><strong>resource_strategy</strong>– One of <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Link.ACCEPT_NONE</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Link.ACCEPT_ALL</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Link.ACCEPT_APP</span></code>. If <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Link.ACCEPT_APP</span></code> is set, the <cite>resource_callback</cite> will be called to determine whether the resource should be accepted or not.</p>
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">RequestReceipt</span></span><aclass="headerlink"href="#RNS.RequestReceipt"title="Permalink to this definition">#</a></dt>
<dd><p>An instance of this class is returned by the <codeclass="docutils literal notranslate"><spanclass="pre">request</span></code> method of <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Link</span></code>
instances. It should never be instantiated manually. It provides methods to
check status, response time and response data when the request concludes.</p>
<spanclass="sig-name descname"><spanclass="pre">get_request_id</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RequestReceipt.get_request_id"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_status</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RequestReceipt.get_status"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p>The current status of the request, one of <codeclass="docutils literal notranslate"><spanclass="pre">RNS.RequestReceipt.FAILED</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.RequestReceipt.SENT</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.RequestReceipt.DELIVERED</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">RNS.RequestReceipt.READY</span></code>.</p>
<spanclass="sig-name descname"><spanclass="pre">get_progress</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RequestReceipt.get_progress"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_response</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RequestReceipt.get_response"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_response_time</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RequestReceipt.get_response_time"title="Permalink to this definition">#</a></dt>
<li><p><strong>data</strong>– The data to be transferred. Can be <em>bytes</em> or an open <em>file handle</em>. See the <aclass="reference internal"href="examples.html#example-filetransfer"><spanclass="std std-ref">Filetransfer Example</span></a> for details.</p></li>
<li><p><strong>link</strong>– The <aclass="reference internal"href="#api-link"><spanclass="std std-ref">RNS.Link</span></a> instance on which to transfer the data.</p></li>
<li><p><strong>advertise</strong>– Optional. Whether to automatically advertise the resource. Can be <em>True</em> or <em>False</em>.</p></li>
<li><p><strong>auto_compress</strong>– Optional. Whether to auto-compress the resource. Can be <em>True</em> or <em>False</em>.</p></li>
<li><p><strong>callback</strong>– An optional <em>callable</em> with the signature <em>callback(resource)</em>. Will be called when the resource transfer concludes.</p></li>
<li><p><strong>progress_callback</strong>– An optional <em>callable</em> with the signature <em>callback(resource)</em>. Will be called whenever the resource transfer progress is updated.</p></li>
<spanclass="sig-name descname"><spanclass="pre">advertise</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.advertise"title="Permalink to this definition">#</a></dt>
<dd><p>Advertise the resource. If the other end of the link accepts
the resource advertisement it will begin transferring.</p>
<spanclass="sig-name descname"><spanclass="pre">cancel</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.cancel"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_progress</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.get_progress"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_transfer_size</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.get_transfer_size"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_data_size</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.get_data_size"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_parts</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.get_parts"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_segments</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.get_segments"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">get_hash</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.get_hash"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">is_compressed</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Resource.is_compressed"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.Channel.</span></span><spanclass="sig-name descname"><spanclass="pre">Channel</span></span><aclass="headerlink"href="#RNS.Channel.Channel"title="Permalink to this definition">#</a></dt>
<dd><p>Provides reliable delivery of messages over
a link.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code> differs from <codeclass="docutils literal notranslate"><spanclass="pre">Request</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">Resource</span></code> in some important ways:</p>
<blockquote>
<div><dlclass="simple">
<dt><strong>Continuous</strong></dt><dd><p>Messages can be sent or received as long as
the <codeclass="docutils literal notranslate"><spanclass="pre">Link</span></code> is open.</p>
</dd>
<dt><strong>Bi-directional</strong></dt><dd><p>Messages can be sent in either direction on
the <codeclass="docutils literal notranslate"><spanclass="pre">Link</span></code>; neither end is the client or
server.</p>
</dd>
<dt><strong>Size-constrained</strong></dt><dd><p>Messages must be encoded into a single packet.</p>
</dd>
</dl>
</div></blockquote>
<p><codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code> is similar to <codeclass="docutils literal notranslate"><spanclass="pre">Packet</span></code>, except that it
provides reliable delivery (automatic retries) as well
as a structure for exchanging several types of
messages over the <codeclass="docutils literal notranslate"><spanclass="pre">Link</span></code>.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code> is not instantiated directly, but rather
obtained from a <codeclass="docutils literal notranslate"><spanclass="pre">Link</span></code> with <codeclass="docutils literal notranslate"><spanclass="pre">get_channel()</span></code>.</p>
<spanclass="sig-name descname"><spanclass="pre">register_message_type</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">message_class</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Type</span><spanclass="p"><spanclass="pre">[</span></span><aclass="reference internal"href="#RNS.MessageBase"title="RNS.Channel.MessageBase"><spanclass="pre">MessageBase</span></a><spanclass="p"><spanclass="pre">]</span></span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Channel.Channel.register_message_type"title="Permalink to this definition">#</a></dt>
<dd><p>Register a message class for reception over a <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code>.</p>
<p>Message classes must extend <codeclass="docutils literal notranslate"><spanclass="pre">MessageBase</span></code>.</p>
<spanclass="sig-name descname"><spanclass="pre">add_message_handler</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">MessageCallbackType</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Channel.Channel.add_message_handler"title="Permalink to this definition">#</a></dt>
<dd><p>Add a handler for incoming messages. A handler
<spanclass="sig-name descname"><spanclass="pre">remove_message_handler</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">MessageCallbackType</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Channel.Channel.remove_message_handler"title="Permalink to this definition">#</a></dt>
<dd><p>Remove a handler added with <codeclass="docutils literal notranslate"><spanclass="pre">add_message_handler</span></code>.</p>
<spanclass="sig-name descname"><spanclass="pre">is_ready_to_send</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">bool</span></span></span><aclass="headerlink"href="#RNS.Channel.Channel.is_ready_to_send"title="Permalink to this definition">#</a></dt>
<dd><p>Check if <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code> is ready to send.</p>
<spanclass="sig-name descname"><spanclass="pre">send</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">message</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="#RNS.MessageBase"title="RNS.Channel.MessageBase"><spanclass="pre">MessageBase</span></a></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">Envelope</span></span></span><aclass="headerlink"href="#RNS.Channel.Channel.send"title="Permalink to this definition">#</a></dt>
<dd><p>Send a message. If a message send is attempted and
<codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code> is not ready, an exception is thrown.</p>
<ddclass="field-odd"><p><strong>message</strong>– an instance of a <codeclass="docutils literal notranslate"><spanclass="pre">MessageBase</span></code> subclass</p>
<emclass="property"><spanclass="pre">property</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">MDU</span></span><aclass="headerlink"href="#RNS.Channel.Channel.MDU"title="Permalink to this definition">#</a></dt>
<dd><p>Maximum Data Unit: the number of bytes available
for a message to consume in a single send. This
value is adjusted from the <codeclass="docutils literal notranslate"><spanclass="pre">Link</span></code> MDU to accommodate
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">MessageBase</span></span><aclass="headerlink"href="#RNS.MessageBase"title="Permalink to this definition">#</a></dt>
<dd><p>Base type for any messages sent or received on a Channel.
Subclasses must define the two abstract methods as well as
the <codeclass="docutils literal notranslate"><spanclass="pre">MSGTYPE</span></code> class variable.</p>
<spanclass="sig-name descname"><spanclass="pre">MSGTYPE</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">None</span></em><aclass="headerlink"href="#RNS.MessageBase.MSGTYPE"title="Permalink to this definition">#</a></dt>
<dd><p>Defines a unique identifier for a message class.</p>
<ulclass="simple">
<li><p>Must be unique within all classes registered with a <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code></p></li>
<li><p>Must be less than <codeclass="docutils literal notranslate"><spanclass="pre">0xf000</span></code>. Values greater than or equal to <codeclass="docutils literal notranslate"><spanclass="pre">0xf000</span></code> are reserved.</p></li>
<emclass="property"><spanclass="pre">abstract</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">pack</span></span><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">bytes</span></span></span><aclass="headerlink"href="#RNS.MessageBase.pack"title="Permalink to this definition">#</a></dt>
<dd><p>Create and return the binary representation of the message</p>
<emclass="property"><spanclass="pre">abstract</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">unpack</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">raw</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">bytes</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.MessageBase.unpack"title="Permalink to this definition">#</a></dt>
<dd><p>Populate message from binary representation</p>
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">Buffer</span></span><aclass="headerlink"href="#RNS.Buffer"title="Permalink to this definition">#</a></dt>
<dd><p>Static functions for creating buffered streams that send
and receive over a <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code>.</p>
<p>These functions use <codeclass="docutils literal notranslate"><spanclass="pre">BufferedReader</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">BufferedWriter</span></code>,
and <codeclass="docutils literal notranslate"><spanclass="pre">BufferedRWPair</span></code> to add buffering to
<codeclass="docutils literal notranslate"><spanclass="pre">RawChannelReader</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">RawChannelWriter</span></code>.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">create_reader</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">stream_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">channel</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="#RNS.Channel.Channel"title="RNS.Channel.Channel"><spanclass="pre">Channel</span></a></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">ready_callback</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Callable</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="p"><spanclass="pre">[</span></span><spanclass="pre">int</span><spanclass="p"><spanclass="pre">]</span></span><spanclass="p"><spanclass="pre">,</span></span><spanclass="w"></span><spanclass="pre">None</span><spanclass="p"><spanclass="pre">]</span></span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">None</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">BufferedReader</span></span></span><aclass="headerlink"href="#RNS.Buffer.create_reader"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">create_writer</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">stream_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">channel</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="#RNS.Channel.Channel"title="RNS.Channel.Channel"><spanclass="pre">Channel</span></a></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">BufferedWriter</span></span></span><aclass="headerlink"href="#RNS.Buffer.create_writer"title="Permalink to this definition">#</a></dt>
<dd><p>Create a buffered writer that writes binary data over
a <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code>.</p>
<p>For more information on the writer-specific functions
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">create_bidirectional_buffer</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">receive_stream_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">send_stream_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">channel</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="#RNS.Channel.Channel"title="RNS.Channel.Channel"><spanclass="pre">Channel</span></a></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">ready_callback</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Callable</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="p"><spanclass="pre">[</span></span><spanclass="pre">int</span><spanclass="p"><spanclass="pre">]</span></span><spanclass="p"><spanclass="pre">,</span></span><spanclass="w"></span><spanclass="pre">None</span><spanclass="p"><spanclass="pre">]</span></span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">None</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">BufferedRWPair</span></span></span><aclass="headerlink"href="#RNS.Buffer.create_bidirectional_buffer"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">RawChannelReader</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">stream_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">channel</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="#RNS.Channel.Channel"title="RNS.Channel.Channel"><spanclass="pre">Channel</span></a></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RawChannelReader"title="Permalink to this definition">#</a></dt>
<dd><p>An implementation of RawIOBase that receives
binary stream data sent over a <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code>.</p>
<blockquote>
<div><p>This class generally need not be instantiated directly.
Use <aclass="reference internal"href="#RNS.Buffer.create_reader"title="RNS.Buffer.create_reader"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">RNS.Buffer.create_reader()</span></code></a>,
<aclass="reference internal"href="#RNS.Buffer.create_writer"title="RNS.Buffer.create_writer"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">RNS.Buffer.create_writer()</span></code></a>, and
<spanclass="sig-name descname"><spanclass="pre">__init__</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">stream_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">channel</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="#RNS.Channel.Channel"title="RNS.Channel.Channel"><spanclass="pre">Channel</span></a></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RawChannelReader.__init__"title="Permalink to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">add_ready_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">cb</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Callable</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="p"><spanclass="pre">[</span></span><spanclass="pre">int</span><spanclass="p"><spanclass="pre">]</span></span><spanclass="p"><spanclass="pre">,</span></span><spanclass="w"></span><spanclass="pre">None</span><spanclass="p"><spanclass="pre">]</span></span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RawChannelReader.add_ready_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Add a function to be called when new data is available.
The function should have the signature <codeclass="docutils literal notranslate"><spanclass="pre">(ready_bytes:</span><spanclass="pre">int)</span><spanclass="pre">-></span><spanclass="pre">None</span></code></p>
<spanclass="sig-name descname"><spanclass="pre">remove_ready_callback</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">cb</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Callable</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="p"><spanclass="pre">[</span></span><spanclass="pre">int</span><spanclass="p"><spanclass="pre">]</span></span><spanclass="p"><spanclass="pre">,</span></span><spanclass="w"></span><spanclass="pre">None</span><spanclass="p"><spanclass="pre">]</span></span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RawChannelReader.remove_ready_callback"title="Permalink to this definition">#</a></dt>
<dd><p>Remove a function added with <aclass="reference internal"href="#RNS.RawChannelReader.add_ready_callback"title="RNS.RawChannelReader.add_ready_callback"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">RNS.RawChannelReader.add_ready_callback()</span></code></a></p>
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">RawChannelWriter</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">stream_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">channel</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="#RNS.Channel.Channel"title="RNS.Channel.Channel"><spanclass="pre">Channel</span></a></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RawChannelWriter"title="Permalink to this definition">#</a></dt>
<dd><p>An implementation of RawIOBase that receives
binary stream data sent over a channel.</p>
<blockquote>
<div><p>This class generally need not be instantiated directly.
Use <aclass="reference internal"href="#RNS.Buffer.create_reader"title="RNS.Buffer.create_reader"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">RNS.Buffer.create_reader()</span></code></a>,
<aclass="reference internal"href="#RNS.Buffer.create_writer"title="RNS.Buffer.create_writer"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">RNS.Buffer.create_writer()</span></code></a>, and
<spanclass="sig-name descname"><spanclass="pre">__init__</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">stream_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">channel</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="#RNS.Channel.Channel"title="RNS.Channel.Channel"><spanclass="pre">Channel</span></a></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.RawChannelWriter.__init__"title="Permalink to this definition">#</a></dt>
<li><p><strong>stream_id</strong>– remote stream id to sent do</p></li>
<li><p><strong>channel</strong>–<codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code> object to send on</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
<pid="api-transport"><h3> Transport </h3></p>
<dlclass="py class">
<dtclass="sig sig-object py"id="RNS.Transport">
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">RNS.</span></span><spanclass="sig-name descname"><spanclass="pre">Transport</span></span><aclass="headerlink"href="#RNS.Transport"title="Permalink to this definition">#</a></dt>
<dd><p>Through static methods of this class you can interact with the
<spanclass="sig-name descname"><spanclass="pre">PATHFINDER_M</span></span><emclass="property"><spanclass="w"></span><spanclass="p"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="pre">128</span></em><aclass="headerlink"href="#RNS.Transport.PATHFINDER_M"title="Permalink to this definition">#</a></dt>
<dd><p>Maximum amount of hops that Reticulum will transport a packet.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">register_announce_handler</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">handler</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Transport.register_announce_handler"title="Permalink to this definition">#</a></dt>
<ddclass="field-odd"><p><strong>handler</strong>– Must be an object with an <em>aspect_filter</em> attribute and a <em>received_announce(destination_hash, announced_identity, app_data)</em> callable. See the <aclass="reference internal"href="examples.html#example-announce"><spanclass="std std-ref">Announce Example</span></a> for more info.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">deregister_announce_handler</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">handler</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Transport.deregister_announce_handler"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">has_path</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination_hash</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Transport.has_path"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">hops_to</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination_hash</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Transport.hops_to"title="Permalink to this definition">#</a></dt>
<ddclass="field-even"><p>The number of hops to the specified destination, or <codeclass="docutils literal notranslate"><spanclass="pre">RNS.Transport.PATHFINDER_M</span></code> if the number of hops is unknown.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">next_hop</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination_hash</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Transport.next_hop"title="Permalink to this definition">#</a></dt>
<ddclass="field-even"><p>The destination hash as <em>bytes</em> for the next hop to the specified destination, or <em>None</em> if the next hop is unknown.</p>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">next_hop_interface</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination_hash</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Transport.next_hop_interface"title="Permalink to this definition">#</a></dt>
<emclass="property"><spanclass="pre">static</span><spanclass="w"></span></em><spanclass="sig-name descname"><spanclass="pre">request_path</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">destination_hash</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">on_interface</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">tag</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">recursive</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">False</span></span></em><spanclass="sig-paren">)</span><aclass="headerlink"href="#RNS.Transport.request_path"title="Permalink to this definition">#</a></dt>
<dd><p>Requests a path to the destination from the network. If
another reachable peer on the network knows a path, it
<li><p><strong>destination_hash</strong>– A destination hash as <em>bytes</em>.</p></li>
<li><p><strong>on_interface</strong>– If specified, the path request will only be sent on this interface. In normal use, Reticulum handles this automatically, and this parameter should not be used.</p></li>
