diff --git a/i2p2www/pages/site/docs/api/sam.html b/i2p2www/pages/site/docs/api/sam.html
index 9fcea68d57d7b5c7e27b8d5f27f0da78d26833ae..eb4076d10132bfcdfc2b7d44211f868abb3cb371 100644
--- a/i2p2www/pages/site/docs/api/sam.html
+++ b/i2p2www/pages/site/docs/api/sam.html
@@ -1,6 +1,6 @@
{% extends "global/layout.html" %}
{% block title %}SAM V1 Specification{% endblock %}
-{% block lastupdated %}June 2014{% endblock %}
+{% block lastupdated %}July 2014{% endblock %}
{% block accuratefor %}0.9.14{% endblock %}
{% block content %}
<p>Specified below is version 1 of a simple client protocol for interacting with
@@ -103,11 +103,14 @@ follows:
DESTINATION specifies what destination should be used for
sending and receiving messages/streams. If a $name is given, the
-SAM bridge looks through its own local storage for an associated
+SAM bridge looks through its own local storage (the sam.keys file) for an associated
destination (and private key). If no association exists matching
that name, it creates a new one. If the destination is specified
as TRANSIENT, it always creates a new one.
+Note that DESTINATION is an identifier, <i>not</i> Base 64 encoded data.
+To specify the Destination, you must use <a href="samv3>SAM V3</a>.
+
The DIRECTION can be specified for STREAM sessions, instructing
the bridge that the client will either be creating or receiving
streams, or both. If this is not specified, BOTH will be assumed.
@@ -142,6 +145,12 @@ The RESULT value may be one of:
If it's not OK, the MESSAGE should contain human-readable information
as to why the session could not be created.
+Note that there is no warning given if the $name is not found and
+a transient destination is created instead.
+Note that the actual transient destination is not output in the reply.
+If you need these features, you must use <a href="samv3>SAM V3</a>.
+
+
----------------------------------------------------------------------
SAM virtual streams
----------------------------------------------------------------------
@@ -250,11 +259,14 @@ SAM repliable datagrams
----------------------------------------------------------------------
While I2P doesn't inherently contain a FROM address, for ease of use
an additional layer is provided as repliable datagrams - unordered
-and unreliable messages of up to 31KB in size that include a FROM
+and unreliable messages of up to 31744 bytes that include a FROM
address (leaving up to 1KB for header material). This FROM address
is authenticated internally by SAM (making use of the destination's
signing key to verify the source) and includes replay prevention.
+Minimum size is 1. For best delivery reliability, recommended maximum
+size is approximately 11 KB.
+
After establishing a SAM session with STYLE=DATAGRAM, the client can
send the SAM bridge:
@@ -279,7 +291,10 @@ SAM anonymous datagrams
Squeezing the most out of I2P's bandwidth, SAM allows clients to send
and receive anonymous datagrams, leaving authentication and reply
information up to the client themselves. These datagrams are
-unreliable and unordered, and may be up to 32KB in size.
+unreliable and unordered, and may be up to 32768 bytes.
+
+Minimum size is 1. For best delivery reliability, recommended maximum
+size is approximately 11 KB.
After establishing a SAM session with STYLE=RAW, the client can
send the SAM bridge:
diff --git a/i2p2www/pages/site/docs/api/samv2.html b/i2p2www/pages/site/docs/api/samv2.html
index e5c734770be936e070995344b2b074434435355d..10c57b8c9ec15b7f7d922f76dc7682235859145e 100644
--- a/i2p2www/pages/site/docs/api/samv2.html
+++ b/i2p2www/pages/site/docs/api/samv2.html
@@ -1,6 +1,6 @@
{% extends "global/layout.html" %}
{% block title %}SAM V2 Specification{% endblock %}
-{% block lastupdated %}June 2014{% endblock %}
+{% block lastupdated %}July 2014{% endblock %}
{% block accuratefor %}0.9.14{% endblock %}
{% block content %}
<p>Specified below is a simple client protocol for interacting with I2P.
@@ -107,11 +107,14 @@ follows:
DESTINATION specifies what destination should be used for
sending and receiving messages/streams. If a $name is given, the
-SAM bridge looks through its own local storage for an associated
+SAM bridge looks through its own local storage (the sam.keys file) for an associated
destination (and private key). If no association exists matching
that name, it creates a new one. If the destination is specified
as TRANSIENT, it always creates a new one.
+Note that DESTINATION is an identifier, <i>not</i> Base 64 encoded data.
+To specify the Destination, you must use <a href="samv3>SAM V3</a>.
+
The DIRECTION can be specified for STREAM sessions, instructing
the bridge that the client will either be creating or receiving
streams, or both. If this is not specified, BOTH will be assumed.
@@ -146,6 +149,12 @@ The RESULT value may be one of:
If it's not OK, the MESSAGE should contain human-readable information
as to why the session could not be created.
+Note that there is no warning given if the $name is not found and
+a transient destination is created instead.
+Note that the actual transient destination is not output in the reply.
+If you need these features, you must use <a href="samv3>SAM V3</a>.
+
+
----------------------------------------------------------------------
SAM virtual streams
----------------------------------------------------------------------
@@ -307,11 +316,14 @@ SAM repliable datagrams
----------------------------------------------------------------------
While I2P doesn't inherently contain a FROM address, for ease of use
an additional layer is provided as repliable datagrams - unordered
-and unreliable messages of up to 31KB in size that include a FROM
+and unreliable messages of up to 31744 bytes that include a FROM
address (leaving up to 1KB for header material). This FROM address
is authenticated internally by SAM (making use of the destination's
signing key to verify the source) and includes replay prevention.
+Minimum size is 1. For best delivery reliability, recommended maximum
+size is approximately 11 KB.
+
After establishing a SAM session with STYLE=DATAGRAM, the client can
send the SAM bridge:
@@ -336,7 +348,10 @@ SAM anonymous datagrams
Squeezing the most out of I2P's bandwidth, SAM allows clients to send
and receive anonymous datagrams, leaving authentication and reply
information up to the client themselves. These datagrams are
-unreliable and unordered, and may be up to 32KB in size.
+unreliable and unordered, and may be up to 32768 bytes.
+
+Minimum size is 1. For best delivery reliability, recommended maximum
+size is approximately 11 KB.
After establishing a SAM session with STYLE=RAW, the client can
send the SAM bridge:
diff --git a/i2p2www/pages/site/docs/api/samv3.html b/i2p2www/pages/site/docs/api/samv3.html
index 6ab9cef2d46fe5616acc115e222b633af7deb60e..619a35b943042d587c423e976e603024760e3073 100644
--- a/i2p2www/pages/site/docs/api/samv3.html
+++ b/i2p2www/pages/site/docs/api/samv3.html
@@ -1,6 +1,6 @@
{% extends "global/layout.html" %}
{% block title %}SAM V3{% endblock %}
-{% block lastupdated %}June 2014{% endblock %}
+{% block lastupdated %}July 2014{% endblock %}
{% block accuratefor %}0.9.14{% endblock %}
{% block content %}
<p>Specified below is a simple client protocol for interacting with I2P.
@@ -46,6 +46,7 @@ Version 3.1 was introduced in I2P release 0.9.14.
<li>DEST GENERATE and SESSION CREATE now support a SIGNATURE_TYPE parameter.
<li>The MIN and MAX parameters in HELLO VERSION are now optional.
<li>The MIN and MAX parameters in HELLO VERSION now support single-digit versions such as "3".
+<li>RAW SEND is now supported on the bridge socket.
</ul>
</p>
@@ -352,11 +353,14 @@ SAM repliable datagrams : sending a datagram
----------------------------------------------------------------------
While I2P doesn't inherently contain a FROM address, for ease of use
an additional layer is provided as repliable datagrams - unordered
-and unreliable messages of up to 31KB in size that include a FROM
+and unreliable messages of up to 31744 bytes that include a FROM
address (leaving up to 1KB for header material). This FROM address
is authenticated internally by SAM (making use of the destination's
signing key to verify the source) and includes replay prevention.
+Minimum size is 1. For best delivery reliability, recommended maximum
+size is approximately 11 KB.
+
After establishing a SAM session with STYLE=DATAGRAM, the client can
send datagrams through SAM's UDP port (7655).
@@ -427,7 +431,10 @@ SAM anonymous datagrams
Squeezing the most out of I2P's bandwidth, SAM allows clients to send
and receive anonymous datagrams, leaving authentication and reply
information up to the client themselves. These datagrams are
-unreliable and unordered, and may be up to 32KB in size.
+unreliable and unordered, and may be up to 32768 bytes.
+
+Minimum size is 1. For best delivery reliability, recommended maximum
+size is approximately 11 KB.
After establishing a SAM session with STYLE=RAW, the client can
send anonymous datagrams through the SAM bridge exactly the same way
@@ -449,6 +456,25 @@ the following data :
{$datagram_payload}
+----------------------------------------------------------------------
+V1/V2 Compatible Datagram Handling
+----------------------------------------------------------------------
+
+In SAM V3, the preferred way to send datagrams is via the datagram socket
+at port 7655 as documented above. However, repliable datagrams may be sent
+directly via the SAM bridge socket using the DATAGRAM SEND command,
+as documented in <a href="sam>SAM V1</a> and <a href="samv2>SAM V2</a>.
+
+As of release 0.9.14 (version 3.1), anonymous datagrams may be sent
+directly via the SAM bridge socket using the RAW SEND command,
+as documented in <a href="sam>SAM V1</a> and <a href="samv2>SAM V2</a>.
+
+These commands do <i>not</i> support the ID parameter. The datagrams are
+sent to the most recently created DATAGRAM- or RAW-style session,
+as appropriate. Support for the ID parameter may be added in a future release.
+
+
+
----------------------------------------------------------------------
SAM utility functionality
----------------------------------------------------------------------