Merge branch 'anders/diameter/doc/OTP-14561' into maint

* anders/diameter/doc/OTP-14561:
  Document new(ish) options in diameter_tcp/sctp

1 files changed, 44 insertions, 16 deletions

diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml
index c9b74a9ec5..62e958870e 100644
--- a/lib/diameter/doc/src/diameter_sctp.xml
+++ b/lib/diameter/doc/src/diameter_sctp.xml
@@ -1,5 +1,7 @@
 <?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd" [
+  <!ENTITY man_tcp_sender
+  '<seealso marker="diameter_tcp#sender">diameter_tcp(3)</seealso>'>
   <!ENTITY gen_sctp '<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>'>
   <!ENTITY gen_sctp_open1
   '<seealso marker="kernel:gen_sctp#open-1">gen_sctp:open/1</seealso>'>
@@ -78,7 +80,11 @@ and implements the behaviour documented in
 <v>Reason = term()</v>
 <v>OwnOpt = {raddr, &ip_address;}
           | {rport, integer()}
-          | {accept, Match}</v>
+          | {accept, Match}
+          | {unordered, boolean() | pos_integer()}
+          | {packet, boolean() | raw}
+          | {message_cb, &mod_eval;}
+          | {sender, boolean()}</v>
 <v>SctpOpt = term()</v>
 <v>Match = &ip_address; | string() | [Match]</v>
 </type>
@@ -106,6 +112,41 @@ A string-valued <c>Match</c> that does not parse as an address is
 interpreted as a regular expression.</p>
 
 <p>
+Option <c>unordered</c> specifies whether or not to use unordered
+delivery, integer <c>N</c> being equivalent to <c>N =&lt; OS</c>,
+where <c>OS</c> is the number of outbound streams negotiated on the
+association in question.
+Regardless of configuration, sending is ordered on stream 0
+until reception of a second incoming message, to ensure that a peer
+receives capabilities exchange messages before any other.
+Defaults to <c>false</c>.</p>
+
+<p>
+Option <c>packet</c> determines how/if an incoming message is
+packaged into a diameter_packet record.
+If <c>false</c> then messages are received as binary().
+If <c>true</c> then as a record with the binary() message in the
+<c>bin</c> field and a <c>{stream, Id}</c> tuple in the
+<c>transport_data</c> field, where <c>Id</c> is the identifier of the
+inbound stream the message was received on.
+If <c>raw</c> then as a record with the received ancillary
+sctp_sndrcvinfo record in the <c>transport_data</c> field.
+Defaults to <c>true</c>.</p>
+
+<p>
+Options <c>message_cb</c> and <c>sender</c> have semantics identical
+to those documented in &man_tcp_sender;, but with the message argument
+to a <c>recv</c> callback being as directed by the <c>packet</c>
+option.</p>
+
+<p>
+An <c>{outstream, Id}</c> tuple in the <c>transport_data</c> field of
+a outgoing diameter_packet record sets the outbound stream on which
+the message is sent, modulo the negotiated number of outbound streams.
+Any other value causes successive such sends to cycle though all
+outbound streams.</p>
+
+<p>
 Remaining options are any accepted by &gen_sctp_open1;, with the exception
 of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c>
 and <c>sctp_events</c>.
@@ -121,29 +162,16 @@ connecting transport.</p>
 
 <warning>
 <p>
-An insufficiently large receive buffer may result in a peer having to
+An small receive buffer may result in a peer having to
 resend incoming messages: set the &inet; option <c>recbuf</c> to increase
 the buffer size.</p>
 
 <p>
-An insufficiently large send buffer may result in outgoing messages
+An small send buffer may result in outgoing messages
 being discarded: set the &inet; option <c>sndbuf</c> to increase
 the buffer size.</p>
 </warning>
 
-<p>
-The <c>transport_data</c> field of record <c>diameter_packet</c>
-is used to communicate the stream on which an inbound message
-has been received, or on which an outbound message should be sent.
-The value will be of the form <c>{stream, Id}</c> for an inbound
-message passed to a &app_handle_request; or &app_handle_answer;
-callback.
-For an outbound message, <c>{outstream, Id}</c> in the return value of
-&app_handle_request; or &app_prepare_retransmit; sets the outbound
-stream, the stream id being interpreted modulo the number of outbound
-streams.
-Any other value, or not setting a value, causes successive such sends
-to cycle though all outbound streams.</p>
 </desc>
 </func>