168 lines
8.2 KiB
HTML
168 lines
8.2 KiB
HTML
{% extends "global/layout.html" %}
|
|
{% block title %}{% trans %}Streaming Library Specification{% endtrans %}{% endblock %}
|
|
{% block lastupdated %}{% trans %}August 2014{% endtrans %}{% endblock %}
|
|
{% block accuratefor %}0.9.14.1{% endblock %}
|
|
{% block content %}
|
|
<p><a href="{{ site_url('docs/api/streaming') }}">{% trans -%}
|
|
See the Streaming page for an overview of the Streaming Library.
|
|
{%- endtrans %}</a></p>
|
|
|
|
<h2>{% trans %}Protocol Specification{% endtrans %}</h2>
|
|
<h3>{% trans %}Packet Format{% endtrans %}</h3>
|
|
<p>{% trans -%}
|
|
The format of a single packet in the streaming protocol is:
|
|
{%- endtrans %}</p>
|
|
{% highlight lang='dataspec' %}
|
|
|
|
+----+----+----+----+----+----+----+----+
|
|
| send Stream ID | rcv Stream ID |
|
|
+----+----+----+----+----+----+----+----+
|
|
| sequence Num | ack Through |
|
|
+----+----+----+----+----+----+----+----+
|
|
| nc | NACKs ...
|
|
+----+----+----+----+----+----+----+----+
|
|
| rd | flags | opt size| opt data
|
|
+----+----+----+----+----+----+----+----+
|
|
... |
|
|
+----+----+----+----+----+----+----+----+
|
|
| payload ...
|
|
+----+----+----+-//
|
|
|
|
|
|
{% endhighlight %}
|
|
|
|
<table>
|
|
<tr><th>{{ _('Field') }}<th>{{ _('Length') }}<th>{{ _('Contents') }}
|
|
<tr><td>sendStreamId <td>4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
|
|
<td>Random number selected by the packet recipient before sending the first SYN reply packet
|
|
and constant for the life of the connection.
|
|
0 in the SYN message sent by the connection originator, and in subsequent messages, until a SYN reply is received,
|
|
containing the peer's stream ID.
|
|
|
|
<tr><td>receiveStreamId <td>4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a>
|
|
<td>Random number selected by the packet originator before sending the first SYN packet
|
|
and constant for the life of the connection. May be 0 if unknown, for example in a RESET packet.
|
|
|
|
<tr><td>sequenceNum <td>4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a><td>
|
|
The sequence for this message, starting at 0 in the SYN message,
|
|
and incremented by 1 in each message except for plain ACKs and retransmissions.
|
|
If the sequenceNum is 0 and the SYN flag is not set, this is a plain ACK
|
|
packet that should not be ACKed.
|
|
|
|
<tr><td>ackThrough <td>4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a><td>
|
|
The highest packet sequence number that was received
|
|
on the receiveStreamId. This field is ignored on the initial
|
|
connection packet (where receiveStreamId is the unknown id) or
|
|
if the NO_ACK flag set.
|
|
All packets up to and including this sequence number are ACKed,
|
|
EXCEPT for those listed in NACKs below.
|
|
|
|
<tr><td>NACK count<td>1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a><td>
|
|
The number of 4-byte NACKs in the next field
|
|
|
|
<tr><td>NACKs <td>n * 4 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integers</a><td>
|
|
Sequence numbers less than ackThrough that are not yet received.
|
|
Two NACKs of a packet is a request for a 'fast retransmit' of that packet.
|
|
|
|
<tr><td>resendDelay<td>1 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a><td>
|
|
How long is the creator of this packet going to wait before
|
|
resending this packet (if it hasn't yet been ACKed). The
|
|
value is seconds since the packet was created.
|
|
Currently ignored on receive.
|
|
|
|
<tr><td>flags <td>2 byte value<td>
|
|
See below.
|
|
|
|
<tr><td>option size<td>2 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a><td>
|
|
The number of bytes in the next field
|
|
|
|
<tr><td>option data<td>0 or more bytes<td>
|
|
As specified by the flags. See below.
|
|
|
|
<tr><td>payload <td>remaining packet size<td>
|
|
</table>
|
|
|
|
<h3>{% trans %}Flags and Option Data Fields{% endtrans %}</h3>
|
|
<p>{% trans -%}
|
|
The flags field above specifies some metadata about the packet, and in
|
|
turn may require certain additional data to be included. The flags are
|
|
as follows. Any data structures specified must be added to the options area
|
|
in the given order.
|
|
{%- endtrans %}</p>
|
|
|
|
<p>
|
|
Bit order: 15....0 (15 is MSB)
|
|
</p>
|
|
<table>
|
|
<tr><th>Bit<th>Flag<th>Option Order<th>Option Data<th>Function
|
|
<tr><td>0<td>SYNCHRONIZE<td align="center">--<td align="center">--<td>
|
|
Similar to TCP SYN. Set in the initial packet and in the first response.
|
|
FROM_INCLUDED and SIGNATURE_INCLUDED must be set also.
|
|
<tr><td>1<td>CLOSE<td align="center">--<td align="center">--<td>
|
|
Similar to TCP FIN. If the response to a SYNCHRONIZE fits in a single message, the response
|
|
will contain both SYNCHRONIZE and CLOSE.
|
|
SIGNATURE_INCLUDED must be set also.
|
|
<tr><td>2<td>RESET<td align="center">--<td align="center">--<td>
|
|
Abnormal close.
|
|
SIGNATURE_INCLUDED must be set also.
|
|
<tr><td>3<td>SIGNATURE_INCLUDED<td align="center">4<td>variable length <a href="{{ site_url('docs/spec/common-structures') }}#type_Signature">Signature</a>
|
|
<td>
|
|
Currently sent only with SYNCHRONIZE, CLOSE, and RESET, where it is required,
|
|
and with ECHO, where it is required for a ping.
|
|
The signature uses the Destination's <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPublicKey">signing keys</a>
|
|
to sign the entire header and payload with the space in the option data field
|
|
for the signature being set to all zeroes.
|
|
<br>
|
|
Prior to release 0.9.11, the signature was always 40 bytes.
|
|
As of release 0.9.11, the signature may be variable-length, see below for details.
|
|
<tr><td>4<td>SIGNATURE_REQUESTED<td align="center">--<td align="center">--<td>
|
|
Unused. Requests every packet in the other direction to have SIGNATURE_INCLUDED
|
|
<tr><td>5<td>FROM_INCLUDED<td align="center">2<td>387+ byte <a href="{{ site_url('docs/spec/common-structures') }}#struct_Destination">Destination</a>
|
|
<td>
|
|
Currently sent only with SYNCHRONIZE, where it is required,
|
|
and with ECHO, where it is required for a ping.
|
|
<tr><td>6<td>DELAY_REQUESTED<td align="center">1<td>2 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a><td>
|
|
Optional delay.
|
|
How many milliseconds the sender of this packet wants the recipient
|
|
to wait before sending any more data.
|
|
A value greater than 60000 indicates choking.
|
|
<tr><td>7<td>MAX_PACKET_SIZE_INCLUDED<td align="center">3<td>2 byte <a href="{{ site_url('docs/spec/common-structures') }}#type_Integer">Integer</a><td>
|
|
Currently sent with SYNCHRONIZE only.
|
|
Was also sent in retransmitted packets until release 0.9.1.
|
|
<tr><td>8<td>PROFILE_INTERACTIVE<td align="center">--<td align="center">--<td>
|
|
Unused or ignored; the interactive profile is unimplemented.
|
|
<tr><td>9<td>ECHO<td align="center">--<td align="center">--<td>
|
|
Unused except by ping programs.
|
|
If set, most other options, and the payload, are ignored. See
|
|
<a href="{{ site_url('docs/api/streaming') }}">the streaming docs</a>.
|
|
<tr><td>10<td>NO_ACK<td align="center">--<td align="center">--<td>
|
|
This flag simply tells the recipient to ignore the ackThrough field in the header.
|
|
Currently set in the inital SYN packet, otherwise the ackThrough field is always valid.
|
|
Note that this does not save any space, the ackThrough field is before the flags
|
|
and is always present.
|
|
<tr><td>11-15<td>unused<td><td><td>
|
|
Set to zero for compatibility with future uses.
|
|
</table>
|
|
|
|
<h4>Variable Length Signature Notes</h4>
|
|
<p>
|
|
Prior to release 0.9.11, the signature in the option field was always 40 bytes.
|
|
As of release 0.9.11, the signature is variable length.
|
|
The Signature type and length are inferred from the type of key used in the FROM_INCLUDED option
|
|
and the <a href="{{ site_url('docs/spec/common-structures') }}#type_Signature">Signature documentation</a>.
|
|
<ul><li>
|
|
When a packet contains both FROM_INCLUDED and SIGNATURE_INCLUDED (as in SYNCHRONIZE), the inference may be made directly.
|
|
</li><li>
|
|
When a packet does not contain FROM_INCLUDED, the inference must be made from a previous SYNCHRONIZE packet.
|
|
</li><li>
|
|
When a packet does not contain FROM_INCLUDED, and there was no previous SYNCHRONIZE packet
|
|
(for example a stray CLOSE or RESET packet), the inference can be made from the length of the remaining options
|
|
(since SIGNATURE_INCLUDED is the last option), but the packet will probably be discarded anyway, since there is no FROM available
|
|
to validate the signature.
|
|
If more option fields are defined in the future, they must be accounted for.
|
|
</li></ul>
|
|
</p>
|
|
|
|
|
|
{% endblock %}
|