SAM:

- Document v1/v2 datagram modes in v3 (ticket #1334)
- Clarify DESTINATION parameter in v1/v2 modes
- Document minimum and recommended maximum datagram sizes (ticket #1335)

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:

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:

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
 ----------------------------------------------------------------------