aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'lib/diameter/doc/src')
-rw-r--r--lib/diameter/doc/src/Makefile4
-rw-r--r--lib/diameter/doc/src/diameter.xml216
-rw-r--r--lib/diameter/doc/src/diameter_app.xml4
-rw-r--r--lib/diameter/doc/src/diameter_codec.xml8
-rw-r--r--lib/diameter/doc/src/diameter_dict.xml2
-rw-r--r--lib/diameter/doc/src/diameter_intro.xml4
-rw-r--r--lib/diameter/doc/src/diameter_make.xml94
-rw-r--r--lib/diameter/doc/src/diameter_sctp.xml2
-rw-r--r--lib/diameter/doc/src/diameter_soc_rfc6733.xml2
-rw-r--r--lib/diameter/doc/src/diameterc.xml (renamed from lib/diameter/doc/src/diameter_compile.xml)6
-rw-r--r--lib/diameter/doc/src/files.mk2
-rw-r--r--lib/diameter/doc/src/notes.xml72
-rw-r--r--lib/diameter/doc/src/ref_man.xml4
-rw-r--r--lib/diameter/doc/src/seealso.ent4
14 files changed, 287 insertions, 137 deletions
diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile
index bd2b6b103a..229812fd08 100644
--- a/lib/diameter/doc/src/Makefile
+++ b/lib/diameter/doc/src/Makefile
@@ -82,6 +82,7 @@ gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
man: $(MAN1_FILES) $(MAN3_FILES) $(MAN4_FILES)
$(INDEX_TARGET): $(INDEX_SRC) $(APP_FILE)
+ $(gen_verbose) \
sed -e 's/%VSN%/$(VSN)/; \
s/%ERLANG_SITE%/www\.erlang\.se\//; \
s/%UP_ONE_LEVEL%/..\/..\/..\/doc\/index.html/; \
@@ -140,7 +141,10 @@ release_spec:
depend.mk: depend.sed Makefile seealso.ent \
$(XML_REF_FILES) $(XML_CHAPTER_FILES)
+ $(gen_verbose)
+ $(V_at) \
sed -f seehere.sed seealso.ent > seehere.ent
+ $(V_at) \
(for f in $(XML_REF_FILES) $(XML_CHAPTER_FILES); do \
sed -f $< $$f | sed "s@%FILE%@`basename $$f .xml`@g"; \
done) \
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index db19fbb271..9864b21bc5 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -130,7 +130,7 @@ ExtraArgs = list()
<p>
A module implementing the callback interface defined in &man_app;,
along with any
-extra arguments to be appended to those documented for the interface.
+extra arguments to be appended to those documented.
Note that extra arguments specific to an outgoing request can be
specified to &call;, in which case
those are are appended to any module-specific extra arguments.</p>
@@ -138,7 +138,7 @@ those are are appended to any module-specific extra arguments.</p>
<p>
Specifying a <c>#diameter_callback{}</c> record allows individual
functions to be configured in place of the usual &man_app; callbacks.
-See that module for details.</p>
+See <c>diameter_callback.erl</c> for details.</p>
<marker id="application_opt"/>
</item>
@@ -155,7 +155,7 @@ Has one the following types.</p>
<tag><c>{alias, &application_alias;}</c></tag>
<item>
<p>
-An unique identifier for the application in the scope of the
+A unique identifier for the application in the scope of the
service.
Defaults to the value of the <c>dictionary</c> option if
unspecified.</p>
@@ -166,8 +166,8 @@ unspecified.</p>
<p>
The name of an encode/decode module for the Diameter
messages defined by the application.
-These modules are generated from a specification file whose format is
-documented in &man_dict;.</p>
+These modules are generated from files whose format is documented in
+&man_dict;.</p>
</item>
<tag><c>{module, &application_module;}</c></tag>
@@ -195,15 +195,14 @@ Specifies whether or not the &app_pick_peer;
application callback can modify the application state.
Defaults to <c>false</c> if unspecified.</p>
-<note>
+<warning>
<p>
-&app_pick_peer; callbacks
-are serialized when these are allowed to modify state, which is a
-potential performance bottleneck.
+&app_pick_peer; callbacks are serialized when this option is <c>true</c>,
+which is a potential performance bottleneck.
A simple Diameter client may suffer no ill effects from using mutable
state but a server or agent that responds to incoming request should
probably avoid it.</p>
-</note>
+</warning>
</item>
<tag><c>{answer_errors, callback|report|discard}</c></tag>
@@ -234,7 +233,7 @@ Defaults to <c>report</c> if unspecified.</p>
<item>
<p>
Determines the manner in which incoming requests are handled when an
-error other than 3007, DIAMETER_APPLICATION_UNSUPPORTED (which cannot
+error other than 3007 (DIAMETER_APPLICATION_UNSUPPORTED, which cannot
be associated with an application callback module), is detected.</p>
<p>
@@ -244,7 +243,8 @@ If <c>answer</c> then even 5xxx errors are answered without a
callback unless the connection in question has configured the RFC 3588
common dictionary as noted below.
If <c>callback</c> then a &app_handle_request; callback always takes
-place and the return value determines the answer sent to the peer.</p>
+place and its return value determines the answer sent to the peer, if
+any.</p>
<p>
Defaults to <c>answer_3xxx</c> if unspecified.</p>
@@ -252,13 +252,14 @@ Defaults to <c>answer_3xxx</c> if unspecified.</p>
<note>
<p>
Answers sent by diameter set the E-bit in the Diameter Header.
-Since RFC 3588 allowed only 3xxx result codes in an
+Since RFC 3588 allows only 3xxx result codes in an
<c>answer-message</c>, <c>answer</c> has the same semantics as
-<c>answer_3xxx</c> if the peer connection in question has configured
-the RFC 3588 common dictionary, <c>diameter_gen_base_rfc3588</c>.
-RFC 6733 allows both 3xxx and 5xxx result codes in an
-<c>answer-message</c> so a connection configured with the RFC 6733
-common dictionary, <c>diameter_gen_base_rfc6733</c>, does
+<c>answer_3xxx</c> when the transport in question has
+been configured with <c>diameter_gen_base_rfc3588</c> as its common
+dictionary.
+Since RFC 6733 allows both 3xxx and 5xxx result codes in an
+<c>answer-message</c>, a transport with
+<c>diameter_gen_base_rfc6733</c> as its common dictionary does
distinguish between <c>answer_3xxx</c> and <c>answer</c>.</p>
</note>
</item>
@@ -291,9 +292,8 @@ Multiple options append to the argument list.</p>
<tag><c>{filter, &peer_filter;}</c></tag>
<item>
<p>
-A filter to apply to the list of available peers before passing them to
-the &app_pick_peer;
-callback for the application in question.
+A filter to apply to the list of available peers before passing it to
+the &app_pick_peer; callback for the application in question.
Multiple options are equivalent a single <c>all</c> filter on the
corresponding list of filters.
Defaults to <c>none</c>.</p>
@@ -312,7 +312,7 @@ Defaults to 5000.</p>
<p>
Causes &call; to return <c>ok</c> as
soon as the request in
-question has been encoded instead of waiting for and returning
+question has been encoded, instead of waiting for and returning
the result from a subsequent &app_handle_answer; or
&app_handle_error; callback.</p>
</item>
@@ -331,8 +331,8 @@ An invalid option will cause &call; to fail.</p>
<p>
AVP values sent in outgoing CER or CEA messages during capabilities
exchange.
-Can be configured both on a service and a transport, values specified
-on the latter taking precedence over any specified on the former.
+Can be configured both on a service and a transport, values
+on the latter taking precedence.
Has one of the following types.</p>
<taglist>
@@ -358,7 +358,7 @@ question communicates an address list as described in
Origin-State-Id is optional but will be included in outgoing messages
sent by diameter itself: CER/CEA, DWR/DWA and DPR/DPA.
Setting a value of <c>0</c> (zero) is equivalent to not setting a
-value as documented in &the_rfc;.
+value, as documented in &the_rfc;.
The function &origin_state_id;
can be used as to retrieve a value that is computed when the diameter
application is started.</p>
@@ -370,8 +370,8 @@ application is started.</p>
<item>
<p>
Inband-Security-Id defaults to the empty list, which is equivalent to a
-list containing only 0 (= NO_INBAND_SECURITY).
-If 1 (= TLS) is specified then TLS is selected if the CER/CEA received
+list containing only 0 (NO_INBAND_SECURITY).
+If 1 (TLS) is specified then TLS is selected if the CER/CEA received
from the peer offers it.</p>
</item>
@@ -437,38 +437,38 @@ Has one of the following types.</p>
<p>
Matches any peer.
This is a convenience that provides a filter equivalent to no
-filter at all.</p>
+filter.</p>
</item>
<tag><c>host</c></tag>
<item>
<p>
-Matches only those peers whose <c>Origin-Host</c> has the same value
-as <c>Destination-Host</c> in the outgoing request in question,
+Matches only those peers whose Origin-Host has the same value
+as Destination-Host in the outgoing request in question,
or any peer if the request does not contain
-a <c>Destination-Host</c> AVP.</p>
+a Destination-Host AVP.</p>
</item>
<tag><c>realm</c></tag>
<item>
<p>
-Matches only those peers whose <c>Origin-Realm</c> has the same value
-as <c>Destination-Realm</c> in the outgoing request in question,
+Matches only those peers whose Origin-Realm has the same value
+as Destination-Realm in the outgoing request in question,
or any peer if the request does not contain
-a <c>Destination-Realm</c> AVP.</p>
+a Destination-Realm AVP.</p>
</item>
<tag><c>{host, any|&dict_DiameterIdentity;}</c></tag>
<item>
<p>
-Matches only those peers whose <c>Origin-Host</c> has the
+Matches only those peers whose Origin-Host has the
specified value, or all peers if the atom <c>any</c>.</p>
</item>
<tag><c>{realm, any|&dict_DiameterIdentity;</c></tag>
<item>
<p>
-Matches only those peers whose <c>Origin-Realm</c> has the
+Matches only those peers whose Origin-Realm has the
specified value, or all peers if the atom <c>any</c>.</p>
</item>
@@ -477,7 +477,8 @@ specified value, or all peers if the atom <c>any</c>.</p>
<p>
Matches only those peers for which the specified
<c>&evaluable;</c> returns
-<c>true</c> on the connection's <c>diameter_caps</c> record.
+<c>true</c> when applied to the connection's <c>diameter_caps</c>
+record.
Any other return value or exception is equivalent to <c>false</c>.</p>
</item>
@@ -508,10 +509,10 @@ that matches no peer.</p>
<note>
<p>
-The <c>host</c> and <c>realm</c> filters examine the
-outgoing request as passed to &call;,
-assuming that this is a record- or list-valued <c>&codec_message;</c>,
-and that the message contains at most one of each AVP.
+The <c>host</c> and <c>realm</c> filters cause the Destination-Host
+and Destination-Realm AVPs to be extracted from the
+outgoing request, assuming it to be a record- or list-valued
+<c>&codec_message;</c>, and assuming at most one of each AVP.
If this is not the case then the <c>{host|realm, &dict_DiameterIdentity;}</c>
filters must be used to achieve the desired result.
An empty <c>&dict_DiameterIdentity;</c>
@@ -555,7 +556,7 @@ Can have one of the following types.</p>
<p>
The service is being started or stopped.
No event precedes a <c>start</c> event.
-No event follows a <c>stop</c> event and this event
+No event follows a <c>stop</c> event, and this event
implies the termination of all transport processes.</p>
</item>
@@ -575,16 +576,15 @@ The RFC 3539 watchdog state machine has
transitioned into (<c>up</c>) or out of (<c>down</c>) the OKAY
state.
If a <c>#diameter_packet{}</c> is present in an <c>up</c> event
-then there has been a capabilties exchange on a newly established
-transport connection and the record contains the received CER or CEA.
-Otherwise a connection has reestablished without the loss or
-connectivity.</p>
+then there has been a capabilities exchange on a newly established
+transport connection and the record contains the received CER or
+CEA.</p>
<p>
Note that a single <c>up</c> or <c>down</c> event for a given peer
corresponds to multiple &app_peer_up; or &app_peer_down;
callbacks, one for each of the Diameter applications negotiated during
-capablilities exchange.
+capabilities exchange.
That is, the event communicates connectivity with the
peer as a whole while the callbacks communicate connectivity with
respect to individual Diameter applications.</p>
@@ -599,7 +599,7 @@ Opts = [&transport_opt;]
<p>
A connecting transport is attempting to establish/reestablish a
-transport connection with a peer following &reconnect_timer; or
+transport connection with a peer following &connect_timer; or
&watchdog_timer; expiry.</p>
</item>
@@ -627,10 +627,10 @@ CB = &evaluable;
</pre>
<p>
-An incoming CER has been answered with the indicated result code or
+An incoming CER has been answered with the indicated result code, or
discarded.
-<c>Caps</c> contains pairs of values for the local node and remote
-peer.
+<c>Caps</c> contains pairs of values, for the local node and remote
+peer respectively.
<c>Pkt</c> contains the CER in question.
In the case of rejection by a capabilities callback, the tuple
contains the rejecting callback.</p>
@@ -647,7 +647,7 @@ Pkt = #diameter_packet{}
<p>
An incoming CER contained errors and has been answered with the
indicated result code.
-<c>Caps</c> contains only values for the local node.
+<c>Caps</c> contains values for the local node only.
<c>Pkt</c> contains the CER in question.</p>
</item>
@@ -754,7 +754,7 @@ Defines a Diameter application supported by the service.</p>
<p>
A service must configure one tuple for each Diameter
application it intends to support.
-For an outgoing Diameter request, the relevant <c>&application_alias;</c> is
+For an outgoing request, the relevant <c>&application_alias;</c> is
passed to &call;, while for an
incoming request the application identifier in the message
header determines the application, the identifier being specified in
@@ -765,7 +765,7 @@ the application's &dictionary; file.</p>
The capabilities advertised by a node must match its configured
applications. In particular, <c>application</c> configuration must
be matched by corresponding &capability; configuration, of
-Application-Id AVP's in particular.</p>
+*-Application-Id AVPs in particular.</p>
</warning>
</item>
@@ -778,10 +778,11 @@ Application-Id AVP's in particular.</p>
<item>
<p>
Specifies the degree to which the service allows multiple transport
-connections to the same peer.</p>
+connections to the same peer, as identified by its Origin-Host
+at capabilities exchange.</p>
<p>
-If type <c>[node()]</c> then a connection is rejected if another already
+If <c>[node()]</c> then a connection is rejected if another already
exists on any of the specified nodes.
Types <c>false</c>, <c>node</c>, <c>nodes</c> and
&evaluable; are equivalent to
@@ -803,8 +804,8 @@ Defaults to <c>nodes</c>.</p>
<item>
<p>
Specifies a constant value <c>H</c> for the topmost <c>32-N</c> bits of
-of 32-bit End-to-End and Hop-by-Hop identifiers generated
-by the service, either explicity or as a return value of a function
+of 32-bit End-to-End and Hop-by-Hop Identifiers generated
+by the service, either explicitly or as a return value of a function
to be evaluated at &start_service;.
In particular, an identifier <c>Id</c> is mapped to a new identifier
as follows.</p>
@@ -812,11 +813,11 @@ as follows.</p>
(H bsl N) bor (Id band ((1 bsl N) - 1))
</pre>
<p>
-Note that &the_rfc; requires that End-to-End identifiers remain unique
+Note that &the_rfc; requires that End-to-End Identifiers remain unique
for a period of at least 4 minutes and that this and the call rate
-places a lower bound on the appropriate values of <c>N</c>:
-at a rate of <c>R</c> requests per second an <c>N</c>-bit counter
-traverses all of its values in <c>(1 bsl N) div (R*60)</c> minutes so
+places a lower bound on appropriate values of <c>N</c>:
+at a rate of <c>R</c> requests per second, an <c>N</c>-bit counter
+traverses all of its values in <c>(1 bsl N) div (R*60)</c> minutes, so
the bound is <c>4*R*60 =&lt; 1 bsl N</c>.</p>
<p><c>N</c> must lie in the range <c>0..32</c> and <c>H</c> must be a
@@ -829,7 +830,7 @@ Defaults to <c>{0,32}</c>.</p>
<p>
Multiple Erlang nodes implementing the same Diameter node should
be configured with different sequence masks to ensure that each node
-uses a unique range of End-to-End and Hop-by-Hop identifiers for
+uses a unique range of End-to-End and Hop-by-Hop Identifiers for
outgoing requests.</p>
</warning>
</item>
@@ -852,7 +853,7 @@ by the specified function, evaluated whenever a peer connection
becomes available or a remote service requests information about local
connections.
The value <c>true</c> is equivalent to <c>fun &nodes;</c>.
-The value <c>node()</c> in a node list is ignored, so a collection of
+The value <c>node()</c> in a list is ignored, so a collection of
services can all be configured to share with the same list of
nodes.</p>
@@ -899,7 +900,7 @@ If <c>evaluable()</c> then only peers returned by the specified
function are used, evaluated whenever a remote service communicates
information about an available peer connection.
The value <c>true</c> is equivalent to <c>fun &nodes;</c>.
-The value <c>node()</c> in a node list is ignored.</p>
+The value <c>node()</c> in a list is ignored.</p>
<p>
Defaults to <c>false</c>.</p>
@@ -946,7 +947,7 @@ Applications not configured on the service in question are ignored.</p>
The capabilities advertised by a node must match its configured
applications.
In particular, setting <c>applications</c> on a transport typically
-implies having to set matching Application-Id AVP's in a
+implies having to set matching *-Application-Id AVPs in a
&capabilities; tuple.</p>
</warning>
@@ -956,7 +957,7 @@ implies having to set matching Application-Id AVP's in a
<tag><c>{capabilities, [&capability;]}</c></tag>
<item>
<p>
-AVP's used to construct outgoing CER/CEA messages.
+AVPs used to construct outgoing CER/CEA messages.
Values take precedence over any specified on the service in
question.</p>
@@ -1021,14 +1022,45 @@ case the corresponding callbacks are applied until either all return
The number of milliseconds after which a transport process having an
established transport connection will be terminated if the expected
capabilities exchange message (CER or CEA) is not received from the peer.
-For a connecting transport, the timing of reconnection attempts is
-governed by &watchdog_timer; or &reconnect_timer; expiry.
+For a connecting transport, the timing of connection attempts is
+governed by &connect_timer; or &watchdog_timer; expiry.
For a listening transport, the peer determines the timing.</p>
<p>
Defaults to 10000.</p>
</item>
+<marker id="connect_timer"/>
+<tag><c>{connect_timer, Tc}</c></tag>
+<item>
+<pre>
+Tc = &dict_Unsigned32;
+</pre>
+
+<p>
+For a connecting transport, the &the_rfc; Tc timer, in milliseconds.
+This timer determines the frequency with which a transport
+attempts to establish an initial connection with its peer
+following transport configuration.
+Once an initial connection has been
+established, &watchdog_timer; determines the frequency of
+reconnection attempts, as required by RFC 3539.</p>
+
+<p>
+For a listening transport, the timer specifies the time after which a
+previously connected peer will be forgotten: a connection after this time is
+regarded as an initial connection rather than reestablishment,
+causing the RFC 3539 state machine to pass to state OKAY rather than
+REOPEN.
+Note that these semantics are not governed by the RFC and
+that a listening transport's &connect_timer; should be greater
+than its peer's Tw plus jitter.</p>
+
+<p>
+Defaults to 30000 for a connecting transport and 60000 for a listening
+transport.</p>
+</item>
+
<marker id="disconnect_cb"/>
<tag><c>{disconnect_cb, &evaluable;}</c></tag>
@@ -1036,14 +1068,12 @@ Defaults to 10000.</p>
<p>
A callback invoked prior to terminating the transport process of a
transport connection having watchdog state <c>OKAY</c>.
-Applied to <c>Reason=transport|service|application</c> and the
-<c>&transport_ref;</c> and
-<c>&app_peer;</c>
-in question, <c>Reason</c> indicating whether the diameter
-application is being stopped, the service in question is being stopped
-at &stop_service; or
-the transport in question is being removed at &remove_transport;,
-respectively.</p>
+Applied to <c>application|service|transport</c> and the
+<c>&transport_ref;</c> and <c>&app_peer;</c> in question:
+<c>application</c> indicates that the diameter application is
+being stopped, <c>service</c> that the service in question is being
+stopped by &stop_service;, and <c>transport</c> that the transport in
+question is being removed by &remove_transport;.</p>
<p>
The return value can have one of the following types.</p>
@@ -1145,36 +1175,6 @@ See &man_tcp; for the behaviour of that module.</p>
</note>
</item>
-<marker id="reconnect_timer"/>
-<tag><c>{reconnect_timer, Tc}</c></tag>
-<item>
-<pre>
-Tc = &dict_Unsigned32;
-</pre>
-
-<p>
-For a connecting transport, the &the_rfc; Tc timer, in milliseconds.
-Note that this timer determines the frequency with which a transport
-will attempt to establish a connection with its peer only <em>before</em>
-an initial connection is established: once there is an initial
-connection it's &watchdog_timer; that determines the
-frequency of reconnection attempts, as required by RFC 3539.</p>
-
-<p>
-For a listening transport, the timer specifies the time after which a
-previously connected peer will be forgotten: a connection after this time is
-regarded as an initial connection rather than a reestablishment,
-causing the RFC 3539 state machine to pass to state OKAY rather than
-REOPEN.
-Note that these semantics are not governed by the RFC and
-that a listening transport's &reconnect_timer; should be greater
-than its peer's Tw plus jitter.</p>
-
-<p>
-Defaults to 30000 for a connecting transport and 60000 for a listening
-transport.</p>
-</item>
-
<marker id="spawn_opt"/>
<tag><c>{spawn_opt, [term()]}</c></tag>
<item>
@@ -1661,7 +1661,7 @@ R_Flag}</c>.</p>
Note that <c>watchdog</c>, <c>peer</c>, <c>apps</c>, <c>caps</c>
and <c>port</c> entries depend on connectivity
with the peer and may not be present.
-Note also that the <c>statistics</c> entry presents values acuumulated
+Note also that the <c>statistics</c> entry presents values accumulated
during the lifetime of the transport configuration.</p>
<p>
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index e6c9cc9a90..0b6839dcb2 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -308,7 +308,7 @@ The return value <c>{Peer, NewState}</c> is only allowed if
the Diameter application in question was configured with the
&mod_application_opt; <c>{call_mutates_state, true}</c>.
Otherwise, the <c>State</c> argument is always
-the intial value as configured on the application, not any subsequent
+the initial value as configured on the application, not any subsequent
value returned by a &peer_up;
or &peer_down; callback.</p>
</warning>
@@ -565,7 +565,7 @@ Equivalent to</p>
</pre>
<p>
where <c>Avps</c> sets the Origin-Host, Origin-Realm, the specified
-Result-Code and (if the request contained one) Session-Id AVP's, and
+Result-Code and (if the request contained one) Session-Id AVPs, and
possibly Failed-AVP as described below.</p>
<p>
diff --git a/lib/diameter/doc/src/diameter_codec.xml b/lib/diameter/doc/src/diameter_codec.xml
index 4a77d5435b..9d26466b25 100644
--- a/lib/diameter/doc/src/diameter_codec.xml
+++ b/lib/diameter/doc/src/diameter_codec.xml
@@ -13,7 +13,7 @@
<erlref>
<header>
<copyright>
-<year>2012</year>
+<year>2012</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -73,7 +73,7 @@ are defined in diameter.hrl, which can be included as follows.</p>
</pre>
<p>
-Application-specific records are definied in the hrl
+Application-specific records are defined in the hrl
files resulting from dictionary file compilation.</p>
</description>
@@ -122,7 +122,7 @@ Fields have the following types.</p>
<item>
<p>
Values in the AVP header, corresponding to AVP Code, the M flag, P
-flags and Vendor-ID respectivelty.
+flags and Vendor-ID respectively.
A Vendor-ID other than <c>undefined</c> implies a set V flag.</p>
</item>
@@ -222,7 +222,7 @@ header.</p>
<tag><c>is_retransmitted = boolean()</c></tag>
<item>
<p>
-Values correspoding to the R(equest), P(roxiable), E(rror)
+Values corresponding to the R(equest), P(roxiable), E(rror)
and T(Potentially re-transmitted message) flags of the Diameter
header.</p>
</item>
diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml
index 8bf4a14240..4f51a12ebc 100644
--- a/lib/diameter/doc/src/diameter_dict.xml
+++ b/lib/diameter/doc/src/diameter_dict.xml
@@ -431,7 +431,7 @@ equivalent to specifying it with <c>@avp_vendor_id</c>.</p>
Defines values of AVP Name having type Enumerated.
Section content consists of names and corresponding integer values.
Integer values can be prefixed with 0x to be interpreted as
-hexidecimal.</p>
+hexadecimal.</p>
<p>
Note that the AVP in question can be defined in an inherited
diff --git a/lib/diameter/doc/src/diameter_intro.xml b/lib/diameter/doc/src/diameter_intro.xml
index 288ebc0c7c..6c1d1910d2 100644
--- a/lib/diameter/doc/src/diameter_intro.xml
+++ b/lib/diameter/doc/src/diameter_intro.xml
@@ -40,7 +40,7 @@ under the License.
The diameter application is an implementation of the Diameter protocol
as defined by &the_rfc;.
It supports arbitrary Diameter applications by way of a
-<em>dictionary</em> interface that allows messages and AVP's to be
+<em>dictionary</em> interface that allows messages and AVPs to be
defined and input into diameter as configuration.
It has support for all roles defined in the RFC: client, server and
agent.
@@ -69,7 +69,7 @@ interface</seealso>.</p>
<p>
While a service typically implements a single Diameter node (as
identified by an Origin-Host AVP), transports can themselves be
-associated with capabilities AVP's so that a single service can be
+associated with capabilities AVPs so that a single service can be
used to implement more than one Diameter node.</p>
<p>
diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml
index ec71251be1..1c1eff6c6a 100644
--- a/lib/diameter/doc/src/diameter_make.xml
+++ b/lib/diameter/doc/src/diameter_make.xml
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd" [
+ <!ENTITY compile_forms2
+ '<seealso marker="compiler:compile#forms-2">compile:forms/2</seealso>'>
<!ENTITY filename
'<seealso marker="kernel:file#type-name">file:name()</seealso>'>
<!ENTITY dictionary
@@ -51,7 +53,7 @@ under the License.
The function &codec; is used to compile a diameter
&dictionary; into Erlang source.
The resulting source implements the interface diameter required
-to encode and decode the dictionary's messages and AVP's.</p>
+to encode and decode the dictionary's messages and AVPs.</p>
<p>
The utility &man_compile; provides an alternate compilation
@@ -64,16 +66,47 @@ interface.</p>
<funcs>
<func>
-<name>codec(Path::string(), [Opt]) -> ok | {error, Reason}</name>
+<name>codec(File :: iolist() | binary(), [Opt]) -> ok
+ | {ok, [Out]}
+ | {error, Reason}</name>
<fsummary>Compile a dictionary file into Erlang source.</fsummary>
<desc>
<p>
-Compile a single dictionary file to Erlang source.
-<c>Opt</c> can have the following types.</p>
+Compile a single dictionary file.
+The input <c>File</c> can be either a path or a literal dictionary,
+the occurrence of newline (ascii NL) or carriage return (ascii CR)
+identifying the latter.
+<c>Opt</c> determines the format of the results and whether they are
+written to file or returned, and can have the following types.</p>
<taglist>
+<tag><c>parse | forms | erl | hrl</c></tag>
+<item>
+<p>
+Specifies an output format.
+Whether the output is returned or written to file depends on whether
+or not option <c>return</c> is specified.
+When written to file, the resulting file(s) will have extensions
+<c>.D</c>, <c>.F</c>, <c>.erl</c>, and <c>.hrl</c>
+respectively, basenames defaulting to <c>dictionary</c> if the input
+dictionary is literal and does not specify <c>&dict_name;</c>.
+When returned, results are in the order of the corresponding format
+options.
+Format options default to <c>erl</c> and <c>hrl</c> (in this order) if
+unspecified.</p>
+
+<p>
+The <c>parse</c> format is an internal representation that can be
+passed to &flatten; and &format;, while the <c>forms</c> format can be
+passed to &compile_forms2;.
+The <c>erl</c> and <c>hrl</c> formats are returned as
+iolists.</p>
+<!-- That codec/2 can take the parsed format is undocumented, and
+ options name and inherits have no effect in this case. -->
+</item>
+
<tag><c>{include, string()}</c></tag>
<item>
<p>
@@ -90,7 +123,15 @@ Multiple <c>include</c> options can be specified.</p>
<item>
<p>
Write generated source to the specified directory.
-Defaults to the current working directory.</p>
+Defaults to the current working directory.
+Has no effect if option <c>return</c> is specified.</p>
+</item>
+
+<tag><c>return</c></tag>
+<item>
+<p>
+Return results in a <c>{ok, [Out]}</c> tuple instead of writing to
+file and returning <c>ok</c>.</p>
</item>
<tag><c>{name|prefix, string()}</c></tag>
@@ -108,7 +149,7 @@ Transform the input dictionary before compilation, appending
<c>&dict_inherits;</c> of the specified string.</p>
<p>
-Two forms of <c>@inherits</c> have special meaning:</p>
+Two forms have special meaning:</p>
<pre>
{inherits, "-"}
@@ -127,6 +168,41 @@ Multiple <c>inherits</c> options can be specified.</p>
</taglist>
+<p>
+Note that a dictionary's <c>&dict_name;</c>, together with the
+<c>outdir</c> option, determine the output paths when the
+<c>return</c> option is not specified.
+The <c>&dict_name;</c> of a literal input dictionary defaults to
+<c>dictionary</c>.</p>
+
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>format(Parsed) -> iolist()</name>
+<fsummary>Format a parsed dictionary.</fsummary>
+<desc>
+<p>
+Turns a parsed dictionary, as returned by &codec;, back into the
+dictionary format.</p>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>flatten(Parsed) -> term()</name>
+<fsummary>Flatten a parsed dictionary.</fsummary>
+<desc>
+
+<p>
+Reconstitute a parsed dictionary, as returned by &codec;, without
+using <c>&dict_inherits;</c>.
+That is, construct an equivalent dictionary in which all AVP's are
+definined in the dictionary itself.
+The return value is also a parsed dictionary.</p>
</desc>
</func>
@@ -138,11 +214,7 @@ Multiple <c>inherits</c> options can be specified.</p>
<title>BUGS</title>
<p>
-All options are string-valued.
-In particular, it is not currently possible to specify
-an &dict_inherits; module as an atom(), or a path as an arbitrary
-&filename;</p>
-
+Unrecognized options are silently ignored.</p>
</section>
<!-- ===================================================================== -->
diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml
index 5fe14b1ef6..2be77e3dfd 100644
--- a/lib/diameter/doc/src/diameter_sctp.xml
+++ b/lib/diameter/doc/src/diameter_sctp.xml
@@ -90,7 +90,7 @@ Options <c>raddr</c> and <c>rport</c> specify the remote address
and port for a connecting transport and not valid for a listening
transport: the former is required while latter defaults to 3868 if
unspecified.
-Mupltiple <c>raddr</c> options can be specified, in which case the
+Multiple <c>raddr</c> options can be specified, in which case the
connecting transport in question attempts each in sequence until
an association is established.</p>
diff --git a/lib/diameter/doc/src/diameter_soc_rfc6733.xml b/lib/diameter/doc/src/diameter_soc_rfc6733.xml
index 8d85569650..deb4d05b0f 100644
--- a/lib/diameter/doc/src/diameter_soc_rfc6733.xml
+++ b/lib/diameter/doc/src/diameter_soc_rfc6733.xml
@@ -1272,7 +1272,7 @@ during capabilities exchange.)</p>
<p>
The frequency of reconnection attempts is configured with the
-&mod_transport_opt; <c>reconnect_timer</c> and
+&mod_transport_opt; <c>connect_timer</c> and
<c>watchdog_timer</c>.</p>
<pre>
diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameterc.xml
index 6630019e5c..039f4f9cdd 100644
--- a/lib/diameter/doc/src/diameter_compile.xml
+++ b/lib/diameter/doc/src/diameterc.xml
@@ -29,7 +29,7 @@ supplied.
<docno></docno>
<date></date>
<rev></rev>
-<file>diameter_compile.xml</file>
+<file>diameterc.xml</file>
</header>
<com>diameterc</com>
@@ -41,7 +41,7 @@ supplied.
The diameterc utility is used to compile a diameter
&dictionary; into Erlang source.
The resulting source implements the interface diameter required
-to encode and decode the dictionary's messages and AVP's.</p>
+to encode and decode the dictionary's messages and AVPs.</p>
<p>
The module &man_make; provides an alternate compilation interface.</p>
@@ -83,7 +83,7 @@ Defaults to the current working directory.</p>
<tag><![CDATA[-H]]></tag>
<item>
<p>
-Supress erl and hrl generation, respectively.</p>
+Suppress erl and hrl generation, respectively.</p>
</item>
<tag><![CDATA[--name <name>]]></tag>
diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk
index 510786a7fb..6e8b1f9068 100644
--- a/lib/diameter/doc/src/files.mk
+++ b/lib/diameter/doc/src/files.mk
@@ -21,7 +21,7 @@ XML_APPLICATION_FILES = \
ref_man.xml
XML_REF1_FILES = \
- diameter_compile.xml
+ diameterc.xml
XML_REF3_FILES = \
diameter.xml \
diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml
index 32082e565d..18c712ec3d 100644
--- a/lib/diameter/doc/src/notes.xml
+++ b/lib/diameter/doc/src/notes.xml
@@ -42,6 +42,78 @@ first.</p>
<!-- ===================================================================== -->
+<section><title>diameter 1.5</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Rename reconnect_timer to connect_timer.</p>
+ <p>
+ The former is still accepted for backwards compatibility,
+ but the name is misleading given the semantics of the
+ timer.</p>
+ <p>
+ Own Id: OTP-11168</p>
+ </item>
+ <item>
+ <p>
+ Extend diameter_make(3).</p>
+ <p>
+ Dictionaries can now be compiled from strings, not just
+ filesystem paths, and results can be returned instead of
+ written to the filesystem.</p>
+ <p>
+ Own Id: OTP-11348</p>
+ </item>
+ <item>
+ <p>
+ Remove hardcoding of diameter_base as @prefix on
+ dictionaries for application id 0.</p>
+ <p>
+ Own Id: OTP-11361</p>
+ </item>
+ <item>
+ <p>
+ Fix silent make rules (Thanks to Anthony Ramine)</p>
+ <p>
+ Own Id: OTP-11514</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>diameter 1.4.4</title>
+
+ <section><title>Known Bugs and Problems</title>
+ <list>
+ <item>
+ <p>
+ Fix setting of End-to-End and Hop-by-Hop Identifiers in
+ outgoing DWA.</p>
+ <p>
+ Broken by OTP-11184, which caused the identifiers to be
+ set anew, discarding the values from the incoming DWR.</p>
+ <p>
+ Own Id: OTP-11367</p>
+ </item>
+ <item>
+ <p>
+ Fix handling of 5014, DIAMETER_INVALID_AVP_LENGTH.</p>
+ <p>
+ The error was detected as 5004,
+ DIAMETER_INVALID_AVP_VALUE, for some Diameter types, in
+ which case an AVP length that pointed past the end of a
+ message resulted in encode failure.</p>
+ <p>
+ Own Id: OTP-11395</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>diameter 1.4.3</title>
<section><title>Fixed Bugs and Malfunctions</title>
diff --git a/lib/diameter/doc/src/ref_man.xml b/lib/diameter/doc/src/ref_man.xml
index 4b99fe716d..1095887144 100644
--- a/lib/diameter/doc/src/ref_man.xml
+++ b/lib/diameter/doc/src/ref_man.xml
@@ -6,7 +6,7 @@
<header>
<copyright>
<year>2011</year>
-<year>2012</year>
+<year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -39,7 +39,7 @@ applications on top of the Diameter protocol. </p>
</description>
<xi:include href="diameter.xml"/>
-<xi:include href="diameter_compile.xml"/>
+<xi:include href="diameterc.xml"/>
<xi:include href="diameter_app.xml"/>
<xi:include href="diameter_codec.xml"/>
<xi:include href="diameter_dict.xml"/>
diff --git a/lib/diameter/doc/src/seealso.ent b/lib/diameter/doc/src/seealso.ent
index 76b9823f79..7bf7460351 100644
--- a/lib/diameter/doc/src/seealso.ent
+++ b/lib/diameter/doc/src/seealso.ent
@@ -66,7 +66,7 @@ significant.
<!ENTITY disconnect_cb '<seealso marker="#disconnect_cb">disconnect_cb</seealso>'>
<!ENTITY transport_config '<seealso marker="#transport_config">transport_config</seealso>'>
<!ENTITY transport_module '<seealso marker="#transport_module">transport_module</seealso>'>
-<!ENTITY reconnect_timer '<seealso marker="#reconnect_timer">reconnect_timer</seealso>'>
+<!ENTITY connect_timer '<seealso marker="#connect_timer">connect_timer</seealso>'>
<!ENTITY watchdog_timer '<seealso marker="#watchdog_timer">watchdog_timer</seealso>'>
<!-- diameter_app -->
@@ -115,6 +115,8 @@ significant.
<!-- diameter_make -->
<!ENTITY make_codec '<seealso marker="diameter_make#codec-2">diameter_make:codec/2</seealso>'>
+<!ENTITY make_format '<seealso marker="diameter_make#format-1">diameter_make:format/1</seealso>'>
+<!ENTITY make_flatten '<seealso marker="diameter_make#flatten-1">diameter_make:flatten/1</seealso>'>
<!-- diameter_transport -->
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-22 01:42:43 +0000