aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/diameter/doc')
-rw-r--r--lib/diameter/doc/.gitignore4
-rw-r--r--lib/diameter/doc/src/Makefile10
-rw-r--r--lib/diameter/doc/src/diameter.xml103
-rw-r--r--lib/diameter/doc/src/diameter_transport.xml42
4 files changed, 123 insertions, 36 deletions
diff --git a/lib/diameter/doc/.gitignore b/lib/diameter/doc/.gitignore
new file mode 100644
index 0000000000..b634bdd7ba
--- /dev/null
+++ b/lib/diameter/doc/.gitignore
@@ -0,0 +1,4 @@
+
+/html/
+/man*/
+/pdf/
diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile
index 59ca660797..d1d5e8f869 100644
--- a/lib/diameter/doc/src/Makefile
+++ b/lib/diameter/doc/src/Makefile
@@ -16,13 +16,8 @@
#
# %CopyrightEnd%
-ifneq ($(ERL_TOP),)
include $(ERL_TOP)/make/target.mk
include $(ERL_TOP)/make/$(TARGET)/otp.mk
-else
-include $(DIAMETER_TOP)/make/target.mk
-include $(DIAMETER_TOP)/make/$(TARGET)/rules.mk
-endif
include ../../vsn.mk
@@ -155,11 +150,8 @@ info:
# ----------------------------------------------------
# Release Target
# ----------------------------------------------------
-ifneq ($(ERL_TOP),)
+
include $(ERL_TOP)/make/otp_release_targets.mk
-else
-include $(DIAMETER_TOP)/make/release_targets.mk
-endif
release_docs_spec: $(LOCAL)docs
$(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf"
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index b8652a7482..80863f8eff 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -375,10 +375,15 @@ is meant in the sense of <c>eval([E|A])</c>.</p>
<warning>
<p>
-Beware of using fun expressions of the form <c>fun Name/Arity</c> (not
-fun Mod:Name/Arity) in situations in which the fun is not short-lived
+Beware of using fun expressions of the form <c>fun Name/Arity</c> in
+situations in which the fun is not short-lived
and code is to be upgraded at runtime since any processes retaining
-such a fun will have a reference to old code.</p>
+such a fun will have a reference to old code.
+In particular, such a value is typically inappropriate in
+configuration passed to <seealso
+marker="#start_service">start_service/2</seealso> or
+<seealso
+marker="#add_transport">add_transport/2</seealso>.</p>
</warning>
<marker id="peer_filter"/>
@@ -699,6 +704,64 @@ the application's <seealso marker="diameter_dict">dictionary</seealso>
file.</p>
</item>
+<tag><c>{restrict_connections, false
+ | node
+ | nodes
+ | [node()]
+ | diameter:evaluable()}</c></tag>
+<item>
+<p>
+Specifies the degree to which multiple transport connections to the
+same peer are accepted by the service.</p>
+
+<p>
+If type <c>[node()]</c> then a connection is rejected if another already
+exists on any of the specified nodes.
+Values of type <c>false</c>, <c>node</c>, <c>nodes</c> or
+<c>diameter:evaluable()</c> are equivalent to values <c>[]</c>,
+<c>[node()]</c>, <c>[node()|nodes()]</c> and the evaluated value,
+respectively, evaluation of each expression taking place whenever a
+new connection is to be established.
+Note that <c>false</c> allows an unlimited number of connections to be
+established with the same peer.</p>
+
+<p>
+Multiple connections are independent and governed
+by their own peer and watchdog state machines.</p>
+
+<p>
+Defaults to <c>nodes</c>.</p>
+</item>
+
+<tag><c>{sequence, {H,N} | <seealso
+ marker="diameter#evaluable">diameter:evaluable()</seealso>}</c></tag>
+<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
+to be evaluated at <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>.
+In particular, an identifier <c>Id</c> is mapped to a new identifier
+as follows.</p>
+<code>
+(H bsl N) bor (Id band ((1 bsl N) - 1))
+</code>
+<p>
+Note that RFC 3588 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
+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
+non-negative integer less than <c>1 bsl (32-N)</c>.</p>
+
+<p>
+Defaults to <c>{0,32}</c>.</p>
+</item>
+
</taglist>
<marker id="transport_opt"/>
@@ -850,7 +913,7 @@ reconnection attempts, as required by RFC 3539.</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 OPEN rather than
+causing the RFC 3539 state machine to pass to state OKAY rather than
REOPEN.
Note that these semantics are not goverened by the RFC and
that a listening transport's <c>reconnect_timer</c> should be greater
@@ -1149,6 +1212,12 @@ DPA or timeout.</p>
<desc>
<p>
Return information about a started service.
+Requesting info for an unknown service causes <c>undefined</c> to be
+returned.
+Requesting a list of items causes a tagged list to be
+returned.</p>
+
+<p>
<c>Item</c> can be one of the following.</p>
<taglist>
@@ -1419,13 +1488,27 @@ The Diameter-level statistics returned by <c>transport</c> and
<c>connections</c> info are based upon these entries.</p>
</item>
-</taglist>
-
+<tag><c><seealso marker="diameter_app#peer_ref">diameter_app:peer_ref()</seealso></c></tag>
+<item>
<p>
-Requesting info for an unknown service causes <c>undefined</c> to be
-returned.
-Requesting a list of items causes a tagged list to be
-returned.</p>
+Return transport configuration associated with a single peer, as
+passed to <seealso marker="#add_transport">add_transport/2</seealso>.
+The returned list is empty if the peer is unknown.
+Otherwise it contains the <c>ref</c>, <c>type</c> and <c>options</c>
+tuples as in <c>transport</c> and <c>connections</c> info above.
+For example:</p>
+
+<code>
+[{ref,#Ref&lt;0.0.0.61>},
+ {type,accept},
+ {options,[{transport_module,diameter_tcp},
+ {transport_config,[{reuseaddr,true},
+ {ip,{127,0,0,1}},
+ {port,3868}]}]}]
+</code>
+</item>
+
+</taglist>
<marker id="services"/>
</desc>
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 9ab750e560..d9b36a1e09 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -54,14 +54,14 @@ parent).</p>
<funcs>
<func>
-<name>Mod:start({Type, Ref}, Svc, Opts)
+<name>Mod:start({Type, Ref}, Svc, Config)
-> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason}</name>
<fsummary>Start a transport process.</fsummary>
<type>
<v>Type = connect | accept</v>
<v>Ref = <seealso marker="diameter#transport_ref">diameter:transport_ref()</seealso></v>
<v>Svc = #diameter_service{}</v>
-<v>Opts = term()</v>
+<v>Config = term()</v>
<v>Pid = pid()</v>
<v>LAddrs = [<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>]</v>
<v>Reason = term()</v>
@@ -75,38 +75,46 @@ order to establish or accept a transport connection respectively.
A transport process maintains a connection with a single remote peer.</p>
<p>
-The first argument indicates whether the transport process in question
+<c>Type</c> indicates whether the transport process in question
is being started for a connecting (<c>connect</c>) or listening
(<c>accept</c>) transport.
In the latter case, transport processes are started as required to
-accept connections from multiple peers.
-Ref is in each case the same value that was returned from the
-call to <seealso
-marker="diameter#add_transport">diameter:add_transport/2</seealso>
-that has lead to starting of a transport process.</p>
+accept connections from multiple peers.</p>
<p>
-A transport process must implement the message interface documented below.
-It should retain the pid of its parent, monitor the parent and terminate if
-it dies.
-It should not link to the parent.
-It should exit if its transport connection with its peer is lost.</p>
+Ref is the value that was returned from the call to <seealso
+marker="diameter#add_transport">diameter:add_transport/2</seealso>
+that has lead to starting of a transport process.</p>
<p>
-The capabilities in the <c>#diameter_service{}</c> record are as
-passed to <seealso
+<c>Svc</c> contains the capabilities passed to <seealso
marker="diameter#start_service">diameter:start_service/2</seealso> and
<seealso
marker="diameter#add_transport">diameter:add_transport/2</seealso>,
-values passed to the latter overriding those passed to the former.
+values passed to the latter overriding those passed to the former.</p>
+
+<p>
+<c>Config</c> is as passed in <c>transport_config</c> tuple in the
+<seealso marker="diameter#transport_opt">diameter:transport_opt()</seealso>
+list passed to <seealso
+marker="diameter#add_transport">diameter:add_transport/2</seealso>.</p>
+
+<p>
The start function should use the <c>Host-IP-Address</c> list and/or
-<c>Opts</c> to select an appropriate list of local IP addresses,
+<c>Config</c> to select an appropriate list of local IP addresses,
and should return this list if different from the
<c>#diameter_service{}</c> addresses.
The returned list is used to populate <c>Host-IP-Address</c> AVPs in
outgoing capabilities exchange messages, the
<c>#diameter_service{}</c> addresses being used otherwise.</p>
+<p>
+A transport process must implement the message interface documented below.
+It should retain the pid of its parent, monitor the parent and terminate if
+it dies.
+It should not link to the parent.
+It should exit if its transport connection with its peer is lost.</p>
+
<marker id="MESSAGES"/>
</desc>
</func>