diff options
Diffstat (limited to 'lib/diameter/doc')
-rw-r--r-- | lib/diameter/doc/.gitignore | 4 | ||||
-rw-r--r-- | lib/diameter/doc/src/Makefile | 10 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter.xml | 103 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_transport.xml | 42 |
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 =< 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<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> |