SAM: More datagram reorg

i2p2www/pages/site/docs/api/samv3.html

@@ -931,8 +931,41 @@ soon as the "forwarding" socket is closed.
 
 
 
+<h3>SAM Datagrams</h3>
+<p>
+SAMv3 provides mechanisms to send and receive datagrams over local datagram sockets.
+Some SAMv3 implementations also support the older v1/v2 way of sending/receiving
+datagrams over the SAM bridge socket. Both are documented below.
+</p><p>
+I2P supports two types of datagrams:
+</p>
+<ul><li>
+"Repliable" datagrams are prefixed with the destination of the sender,
+and contain the signature of the sender, so the receiver
+may verify that the sender's destination was not spoofed,
+and may reply to the datagram.
+</li><li>
+"Raw" datagrams do not contain the destination of the sender or a signature.
+</li></ul>
+<p>
+Default I2CP ports are defined for both repliable and raw datagrams.
+The I2CP port may be changed for raw datagrams.
+</p><p>
+A common protocol design pattern is for repliable datagrams to be sent
+to servers, with some identifier included, and the server to
+respond with a raw datagram that includes that indentifier,
+so the response may be correlated with the request.
+This design pattern eliminates the substantial overhead of repliable datagrams
+in replies.
+All choices of I2CP protocols and ports are application-specific,
+and designers should take these issues into consideration.
+</p><p>
+See also the important notes on datagram MTU in the section below.
+</p>
 
-<h3 id="v3dgsend">SAM Datagrams : Sending Repliable or Raw Datagrams</h3>
+
+
+<h4 id="v3dgsend">Sending Repliable or Raw Datagrams</h4>
 <p>
 While I2P doesn't inherently contain a FROM address, for ease of use
 an additional layer is provided as repliable datagrams - unordered
@@ -1007,7 +1040,7 @@ data of the message to the specified destination.
 For an alternate method of sending repliable and raw datagrams, see <a href="#dgsend">DATAGRAM SEND and RAW SEND</a>.
 </p>
 
-<h3>SAM Repliable Datagrams : Receiving a Datagram</h3>
+<h4>SAM Repliable Datagrams : Receiving a Datagram</h4>
 <p>
 Received datagrams are written by SAM on the socket from which the
 datagram session was opened, if a forwarding PORT is not specified in the SESSION CREATE
@@ -1038,37 +1071,6 @@ or other fields, merely the data that the sender provided.  This
 continues until the session is closed (by the client dropping the
 connection).
 
-<h3>SAM Datagrams</h3>
-<p>
-SAMv3 provides mechanisms to send and receive datagrams over local datagram sockets.
-Some SAMv3 implementations also support the older v1/v2 way of sending/receiving
-datagrams over the SAM bridge socket. Both are documented below.
-</p><p>
-I2P supports two types of datagrams:
-</p>
-<ul><li>
-"Repliable" datagrams are prefixed with the destination of the sender,
-and contain the signature of the sender, so the receiver
-may verify that the sender's destination was not spoofed,
-and may reply to the datagram.
-</li><li>
-"Raw" datagrams do not contain the destination of the sender or a signature.
-</li></ul>
-<p>
-Default I2CP ports are defined for both repliable and raw datagrams.
-The I2CP port may be changed for raw datagrams.
-</p><p>
-A common protocol design pattern is for repliable datagrams to be sent
-to servers, with some identifier included, and the server to
-respond with a raw datagram that includes that indentifier,
-so the response may be correlated with the request.
-This design pattern eliminates the substantial overhead of repliable datagrams
-in replies.
-All choices of I2CP protocols and ports are application-specific,
-and designers should take these issues into consideration.
-</p>
-
-
 
 <h4>Forwarding Raw or Repliable Datagrams</h4>
 <p>
@@ -1267,7 +1269,7 @@ 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.
 
 
-<h3 id="primary">PRIMARY Sessions (V3.3 and higher)</h3>
+<h3 id="primary">SAM PRIMARY Sessions (V3.3 and higher)</h3>
 
 <p><i>
 Version 3.3 was introduced in I2P release 0.9.25.