diff options
Diffstat (limited to 'lib/diameter/doc/src')
23 files changed, 1788 insertions, 463 deletions
diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile index bd2b6b103a..7a7546fc4d 100644 --- a/lib/diameter/doc/src/Makefile +++ b/lib/diameter/doc/src/Makefile @@ -1,18 +1,19 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2010-2013. All Rights Reserved. +# Copyright Ericsson AB 2010-2016. All Rights Reserved. # -# The contents of this file are subject to the Erlang Public License, -# Version 1.1, (the "License"); you may not use this file except in -# compliance with the License. You should have received a copy of the -# Erlang Public License along with this software. If not, it can be -# retrieved online at http://www.erlang.org/. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at # -# Software distributed under the License is distributed on an "AS IS" -# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -# the License for the specific language governing rights and limitations -# under the License. +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% @@ -82,6 +83,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 +142,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/book.xml b/lib/diameter/doc/src/book.xml index 960296528b..b6cbcbc560 100644 --- a/lib/diameter/doc/src/book.xml +++ b/lib/diameter/doc/src/book.xml @@ -1,24 +1,25 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE book SYSTEM "book.dtd"> <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> -<year>2011</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> diff --git a/lib/diameter/doc/src/depend.sed b/lib/diameter/doc/src/depend.sed index 42de597f15..9c0a417be2 100644 --- a/lib/diameter/doc/src/depend.sed +++ b/lib/diameter/doc/src/depend.sed @@ -1,18 +1,19 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2011. All Rights Reserved. -# -# The contents of this file are subject to the Erlang Public License, -# Version 1.1, (the "License"); you may not use this file except in -# compliance with the License. You should have received a copy of the -# Erlang Public License along with this software. If not, it can be -# retrieved online at http://www.erlang.org/. -# -# Software distributed under the License is distributed on an "AS IS" -# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -# the License for the specific language governing rights and limitations -# under the License. +# Copyright Ericsson AB 2011-2016. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index db19fbb271..d68a78ed6d 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ <!ENTITY spawn_opt '<seealso marker="erts:erlang#spawn_opt-2">erlang:spawn_opt/2</seealso>'> @@ -20,20 +20,22 @@ <header> <copyright> -<year>2011</year><year>2013</year> +<year>2011</year> +<year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -110,7 +112,7 @@ Defined in &dict_data_types;.</p> <tag><c>application_alias() = term()</c></tag> <item> <p> -A name identifying a Diameter application in +Name identifying a Diameter application in service configuration. Passed to &call; when sending requests defined by the application.</p> @@ -128,9 +130,9 @@ ExtraArgs = list() </pre> <p> -A module implementing the callback interface defined in &man_app;, +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 +140,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 +157,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 +Unique identifier for the application in the scope of the service. Defaults to the value of the <c>dictionary</c> option if unspecified.</p> @@ -164,16 +166,16 @@ unspecified.</p> <tag><c>{dictionary, atom()}</c></tag> <item> <p> -The name of an encode/decode module for the Diameter +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> <item> <p> -The callback module with which messages of the Diameter application are +Callback module in which messages of the Diameter application are handled. See &man_app; for the required interface and semantics.</p> </item> @@ -181,7 +183,7 @@ See &man_app; for the required interface and semantics.</p> <tag><c>{state, term()}</c></tag> <item> <p> -The initial callback state. +Initial callback state. The prevailing state is passed to some &man_app; callbacks, which can then return a new state. @@ -191,25 +193,24 @@ Defaults to the value of the <c>alias</c> option if unspecified.</p> <tag><c>{call_mutates_state, true|false}</c></tag> <item> <p> -Specifies whether or not the &app_pick_peer; +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> <item> <p> -Determines the manner in which incoming answer messages containing +Manner in which incoming answer messages containing decode errors are handled.</p> <p> @@ -227,14 +228,14 @@ question is as if a callback had taken place and returned <c>{error, failure}</c>.</p> <p> -Defaults to <c>report</c> if unspecified.</p> +Defaults to <c>discard</c> if unspecified.</p> </item> <tag><c>{request_errors, answer_3xxx|answer|callback}</c></tag> <item> <p> -Determines the manner in which incoming requests are handled when an -error other than 3007, DIAMETER_APPLICATION_UNSUPPORTED (which cannot +Manner in which incoming requests are handled when an +error other than 3007 (DIAMETER_APPLICATION_UNSUPPORTED, which cannot be associated with an application callback module), is detected.</p> <p> @@ -244,7 +245,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 +254,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 +294,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. +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> @@ -302,7 +304,7 @@ Defaults to <c>none</c>.</p> <tag><c>{timeout, &dict_Unsigned32;}</c></tag> <item> <p> -The number of milliseconds after which the request should +Number of milliseconds after which the request should timeout. Defaults to 5000.</p> </item> @@ -310,9 +312,9 @@ Defaults to 5000.</p> <tag><c>detach</c></tag> <item> <p> -Causes &call; to return <c>ok</c> as +Cause &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 +333,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> @@ -355,10 +357,10 @@ question communicates an address list as described in <tag><c>{'Origin-State-Id', &dict_Unsigned32;}</c></tag> <item> <p> -Origin-State-Id is optional but will be included in outgoing messages -sent by diameter itself: CER/CEA, DWR/DWA and DPR/DPA. +Origin-State-Id is optional but, if configured, will be included in +outgoing CER/CEA and DWR/DWA messages. 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 +372,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> @@ -426,7 +428,7 @@ configuration passed to &start_service; or &add_transport;.</p> <tag><c>peer_filter() = term()</c></tag> <item> <p> -A filter passed to &call; in order to select candidate peers for a +Filter passed to &call; in order to select candidate peers for a &app_pick_peer; callback. Has one of the following types.</p> @@ -437,38 +439,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> +<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 +479,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> @@ -497,7 +500,23 @@ Matches only those peers matched by each filter in the specified list.</p> <item> <p> Matches only those peers matched by at least one filter in the -specified list.</p> +specified list. +The resulting list will be in match order, peers matching the +first filter of the list sorting before those matched by the second, +and so on.</p> +</item> + +<tag><c>{first, [&peer_filter;]}</c></tag> +<item> +<p> +Like <c>any</c>, but stops at the first filter for which there are +matches, which can be much more efficient when there are many peers. +For example, the following filter causes only peers best matching +both the host and realm filters to be presented.</p> + +<pre> +{first, [{all, [host, realm]}, realm]} +</pre> </item> </taglist> @@ -508,10 +527,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 +574,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 +594,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 +617,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 +645,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 +665,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> @@ -661,7 +679,7 @@ connection establishment.</p> <tag><c>{'CEA', Result, Caps, Pkt}</c></tag> <item> <pre> -Result = integer() | atom() | {capabilities_cb, CB, ResultCode|discard} +Result = ResultCode | atom() | {capabilities_cb, CB, ResultCode|discard} Caps = #diameter_caps{} Pkt = #diameter_packet{} ResultCode = integer() @@ -729,7 +747,7 @@ info fields of forms other than the above.</p> <tag><c>service_name() = term()</c></tag> <item> <p> -The name of a service as passed to &start_service; and with which the +Name of a service as passed to &start_service; and with which the service is identified. There can be at most one service with a given name on a given node. Note that &make_ref; @@ -741,7 +759,7 @@ can be used to generate a service name that is somewhat unique.</p> <tag><c>service_opt()</c></tag> <item> <p> -An option passed to &start_service;. +Option passed to &start_service;. Can be any <c>&capability;</c> as well as the following.</p> <taglist> @@ -749,12 +767,12 @@ Can be any <c>&capability;</c> as well as the following.</p> <tag><c>{application, [&application_opt;]}</c></tag> <item> <p> -Defines a Diameter application supported by the service.</p> +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,11 +783,24 @@ 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> +<marker id="incoming_maxlen"/> +<tag><c>{incoming_maxlen, 0..16777215}</c></tag> +<item> +<p> +Bound on the expected size of incoming Diameter messages. +Messages larger than the specified number of bytes are discarded.</p> + +<p> +Defaults to <c>16777215</c>, the maximum value of the 24-bit Message +Length field in a Diameter Header.</p> + +</item> + <tag><c>{restrict_connections, false | node | nodes @@ -777,11 +808,12 @@ Application-Id AVP's in particular.</p> | evaluable()}</c></tag> <item> <p> -Specifies the degree to which the service allows multiple transport -connections to the same peer.</p> +The degree to which the service allows multiple transport +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 @@ -802,9 +834,9 @@ Defaults to <c>nodes</c>.</p> <tag><c>{sequence, {H,N} | &evaluable;}</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 +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 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 +844,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 =< 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 +861,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> @@ -837,7 +869,7 @@ outgoing requests.</p> <tag><c>{share_peers, boolean() | [node()] | evaluable()}</c></tag> <item> <p> -Specifies nodes to which peer connections established on the local +Nodes to which peer connections established on the local Erlang node are communicated. Shared peers become available in the remote candidates list passed to &app_pick_peer; callbacks on remote nodes whose services are @@ -852,7 +884,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> @@ -876,7 +908,7 @@ of a single Diameter node across multiple Erlang nodes.</p> <tag><c>{spawn_opt, [term()]}</c></tag> <item> <p> -An options list passed to &spawn_opt; when spawning a process for an +Options list passed to &spawn_opt; when spawning a process for an incoming Diameter request, unless the transport in question specifies another value. Options <c>monitor</c> and <c>link</c> are ignored.</p> @@ -885,10 +917,77 @@ Options <c>monitor</c> and <c>link</c> are ignored.</p> Defaults to the empty list.</p> </item> +<marker id="strict_mbit"/> +<tag><c>{strict_mbit, boolean()}</c></tag> +<item> +<p> +Whether or not to regard an AVP setting the M-bit as erroneous when +the command grammar in question does not explicitly allow the AVP. +If <c>true</c> then such AVPs are regarded as 5001 errors, +DIAMETER_AVP_UNSUPPORTED. +If <c>false</c> then the M-bit is ignored and policing +it becomes the receiver's responsibility.</p> + +<p> +Defaults to <c>true</c>.</p> + +<warning> +<p> +RFC 6733 is unclear about the semantics of the M-bit. +One the one hand, the CCF specification in section 3.2 documents AVP +in a command grammar as meaning <b>any</b> arbitrary AVP; on the +other hand, 1.3.4 states that AVPs setting the M-bit cannot be added +to an existing command: the modified command must instead be +placed in a new Diameter application.</p> +<p> +The reason for the latter is presumably interoperability: +allowing arbitrary AVPs setting the M-bit in a command makes its +interpretation implementation-dependent, since there's no +guarantee that all implementations will understand the same set of +arbitrary AVPs in the context of a given command. +However, interpreting <c>AVP</c> in a command grammar as <b>any</b> +AVP, regardless of M-bit, renders 1.3.4 meaningless, since the receiver +can simply ignore any AVP it thinks isn't relevant, regardless of the +sender's intent.</p> +<p> +Beware of confusing mandatory in the sense of the M-bit with mandatory +in the sense of the command grammar. +The former is a semantic requirement: that the receiver understand the +semantics of the AVP in the context in question. +The latter is a syntactic requirement: whether or not the AVP must +occur in the message in question.</p> +</warning> + +</item> + +<marker id="string_decode"/> +<tag><c>{string_decode, boolean()}</c></tag> +<item> +<p> +Whether or not to decode AVPs of type &dict_OctetString; and its +derived types &dict_DiameterIdentity;, &dict_DiameterURI;, +&dict_IPFilterRule;, &dict_QoSFilterRule;, and &dict_UTF8String;. +If <c>true</c> then AVPs of these types are decoded to string(). +If <c>false</c> then values are retained as binary().</p> + +<p> +Defaults to <c>true</c>.</p> + +<warning> +<p> +This option should be set to <c>false</c> +since a sufficiently malicious peer can otherwise cause large amounts +of memory to be consumed when decoded Diameter messages are passed +between processes. +The default value is for backwards compatibility.</p> +</warning> + +</item> + <tag><c>{use_shared_peers, boolean() | [node()] | evaluable()}</c></tag> <item> <p> -Specifies nodes from which communicated peers are made available in +Nodes from which communicated peers are made available in the remote candidates list of &app_pick_peer; callbacks.</p> <p> @@ -899,7 +998,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> @@ -928,7 +1027,7 @@ each node from which requests are sent.</p> <tag><c>transport_opt()</c></tag> <item> <p> -An option passed to &add_transport;. +Option passed to &add_transport;. Has one of the following types.</p> <taglist> @@ -936,8 +1035,7 @@ Has one of the following types.</p> <tag><c>{applications, [&application_alias;]}</c></tag> <item> <p> -The list of Diameter applications to which the transport should be -restricted. +Diameter applications to which the transport should be restricted. Defaults to all applications configured on the service in question. Applications not configured on the service in question are ignored.</p> @@ -946,7 +1044,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 +1054,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> @@ -970,7 +1068,7 @@ TLS is desired over TCP as implemented by &man_tcp;.</p> <tag><c>{capabilities_cb, &evaluable;}</c></tag> <item> <p> -A callback invoked upon reception of CER/CEA during capabilities +Callback invoked upon reception of CER/CEA during capabilities exchange in order to ask whether or not the connection should be accepted. Applied to the <c>&transport_ref;</c> and @@ -1018,32 +1116,61 @@ case the corresponding callbacks are applied until either all return <tag><c>{capx_timeout, &dict_Unsigned32;}</c></tag> <item> <p> -The number of milliseconds after which a transport process having an +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> <item> <p> -A callback invoked prior to terminating the transport process of 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> @@ -1052,7 +1179,7 @@ The return value can have one of the following types.</p> <tag><c>{dpr, [option()]}</c></tag> <item> <p> -Causes Disconnect-Peer-Request to be sent to the peer, the transport +Send Disconnect-Peer-Request to the peer, the transport process being terminated following reception of Disconnect-Peer-Answer or timeout. An <c>option()</c> can be one of the following.</p> @@ -1061,7 +1188,7 @@ An <c>option()</c> can be one of the following.</p> <tag><c>{cause, 0|rebooting|1|busy|2|goaway}</c></tag> <item> <p> -The Disconnect-Cause to send, <c>REBOOTING</c>, <c>BUSY</c> and +Disconnect-Cause to send, <c>REBOOTING</c>, <c>BUSY</c> and <c>DO_NOT_WANT_TO_TALK_TO_YOU</c> respectively. Defaults to <c>rebooting</c> for <c>Reason=service|application</c> and <c>goaway</c> for <c>Reason=transport</c>.</p> @@ -1070,9 +1197,9 @@ Defaults to <c>rebooting</c> for <c>Reason=service|application</c> and <tag><c>{timeout, &dict_Unsigned32;}</c></tag> <item> <p> -The number of milliseconds after which the transport process is +Number of milliseconds after which the transport process is terminated if DPA has not been received. -Defaults to 1000.</p> +Defaults to the value of &dpa_timeout;.</p> </item> </taglist> </item> @@ -1086,7 +1213,7 @@ Equivalent to <c>{dpr, []}</c>.</p> <tag><c>close</c></tag> <item> <p> -Causes the transport process to be terminated without +Terminate the transport process without Disconnect-Peer-Request being sent to the peer.</p> </item> @@ -1109,11 +1236,34 @@ configured them.</p> Defaults to a single callback returning <c>dpr</c>.</p> </item> +<marker id="dpa_timeout"/> +<tag><c>{dpa_timeout, &dict_Unsigned32;}</c></tag> +<item> +<p> +Number of milliseconds after which a transport connection is +terminated following an outgoing DPR if DPA is not received.</p> + +<p> +Defaults to 1000.</p> +</item> + +<marker id="dpr_timeout"/> +<tag><c>{dpr_timeout, &dict_Unsigned32;}</c></tag> +<item> +<p> +Number of milliseconds after which a transport connection is +terminated following an incoming DPR if the peer does not close the +connection.</p> + +<p> +Defaults to 5000.</p> +</item> + <marker id="length_errors"/> <tag><c>{length_errors, exit|handle|discard}</c></tag> <item> <p> -Specifies how to deal with errors in the Message Length field of the +How to deal with errors in the Message Length field of the Diameter Header in an incoming message. An error in this context is that the length is not at least 20 bytes (the length of a Header), is not a multiple of 4 (a valid length) or @@ -1121,9 +1271,7 @@ is not the length of the message in question, as received over the transport interface documented in &man_transport;.</p> <p> -If <c>exit</c> then a warning report is emitted and the parent of the -transport process in question exits, which causes the transport -process itself to exit as described in &man_transport;. +If <c>exit</c> then the transport process in question exits. If <c>handle</c> then the message is processed as usual, a resulting &app_handle_request; or &app_handle_answer; callback (if one takes place) indicating the <c>5015</c> error (DIAMETER_INVALID_MESSAGE_LENGTH). @@ -1145,41 +1293,26 @@ See &man_tcp; for the behaviour of that module.</p> </note> </item> -<marker id="reconnect_timer"/> -<tag><c>{reconnect_timer, Tc}</c></tag> +<tag><c>{pool_size, pos_integer()}</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> +Number of transport processes to start. +For a listening transport, determines the size of the pool of +accepting transport processes, a larger number being desirable for +processing multiple concurrent peer connection attempts. +For a connecting transport, determines the number of connections to +the peer in question that will be attempted to be establshed: +the &service_opt;: <c>restrict_connections</c> should also be +configured on the service in question to allow multiple connections to +the same peer.</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> <p> -An options list passed to &spawn_opt; when spawning a process for an +Options passed to &spawn_opt; when spawning a process for an incoming Diameter request. Options <c>monitor</c> and <c>link</c> are ignored.</p> @@ -1192,7 +1325,7 @@ Defaults to the list configured on the service if not specified.</p> <tag><c>{transport_config, term(), &dict_Unsigned32; | infinity}</c></tag> <item> <p> -A term passed as the third argument to the &transport_start; function of +Term passed as the third argument to the &transport_start; function of the relevant &transport_module; in order to start a transport process. Defaults to the empty list if unspecified.</p> @@ -1220,7 +1353,7 @@ To listen on both SCTP and TCP, define one transport for each.</p> <tag><c>{transport_module, atom()}</c></tag> <item> <p> -A module implementing a transport process as defined in &man_transport;. +Module implementing a transport process as defined in &man_transport;. Defaults to <c>diameter_tcp</c> if unspecified.</p> <p> @@ -1240,7 +1373,7 @@ corresponding timeout (see below) or all fail.</p> <tag><c>{watchdog_config, [{okay|suspect, non_neg_integer()}]}</c></tag> <item> <p> -Specifies configuration that alters the behaviour of the watchdog +Configuration that alters the behaviour of the watchdog state machine. On key <c>okay</c>, the non-negative number of answered DWR messages before transitioning from REOPEN to OKAY. @@ -1295,7 +1428,7 @@ in predicate functions passed to &remove_transport;.</p> <tag><c>transport_ref() = reference()</c></tag> <item> <p> -An reference returned by &add_transport; that +Reference returned by &add_transport; that identifies the configuration.</p> </item> @@ -1631,11 +1764,13 @@ An example return value with for a client service with Origin-Host {send_pend,0}]}]}, {statistics,[{{{0,258,0},recv},3}, {{{0,258,1},send},3}, + {{{0,258,0},recv,{'Result-Code',2001}},3}, {{{0,257,0},recv},1}, {{{0,257,1},send},1}, - {{{0,258,0},recv,{'Result-Code',2001}},3}, + {{{0,257,0},recv,{'Result-Code',2001}},1}, {{{0,280,1},recv},2}, - {{{0,280,0},send},2}]}]] + {{{0,280,0},send},2}, + {{{0,280,0},send,{'Result-Code',2001}},2}]}]] </pre> <p> @@ -1661,7 +1796,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> @@ -1711,19 +1846,31 @@ connection might look as follows.</p> [{watchdog,{<0.72.0>,{1346,171491,998404},initial}}]]}, {statistics,[{{{0,280,0},recv},7}, {{{0,280,1},send},7}, - {{{0,258,0},send,{'Result-Code',2001}},3}, + {{{0,280,0},recv,{'Result-Code',2001}},7}, {{{0,258,1},recv},3}, {{{0,258,0},send},3}, + {{{0,258,0},send,{'Result-Code',2001}},3}, {{{0,280,1},recv},5}, {{{0,280,0},send},5}, + {{{0,280,0},send,{'Result-Code',2001}},5}, {{{0,257,1},recv},1}, - {{{0,257,0},send},1}]}]] + {{{0,257,0},send},1}, + {{{0,257,0},send,{'Result-Code',2001}},1}]}]] </pre> <p> The information presented here is as in the <c>connect</c> case except that the client connections are grouped under an <c>accept</c> tuple.</p> +<p> +Whether or not the &transport_opt; <c>pool_size</c> has been +configured affects the format +of the listing in the case of a connecting transport, since a value +greater than 1 implies multiple transport processes for the same +<c>&transport_ref;</c>, as in the listening case. +The format in this case is similar to the listening case, with a +<c>pool</c> tuple in place of an <c>accept</c> tuple.</p> + </item> <tag><c>connections</c></tag> @@ -1776,13 +1923,16 @@ A return value for the server above might look as follows.</p> {send_pend,0}]}]}, {statistics,[{{{0,280,0},recv},62}, {{{0,280,1},send},62}, - {{{0,258,0},send,{'Result-Code',2001}},3}, + {{{0,280,0},recv,{'Result-Code',2001}},62}, {{{0,258,1},recv},3}, {{{0,258,0},send},3}, + {{{0,258,0},send,{'Result-Code',2001}},3}, {{{0,280,1},recv},66}, {{{0,280,0},send},66}, + {{{0,280,0},send,{'Result-Code',2001}},66}, {{{0,257,1},recv},1}, - {{{0,257,0},send},1}]}]] + {{{0,257,0},send},1}, + {{{0,257,0},send,{'Result-Code',2001}},1}]}]] </pre> <p> diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index e6c9cc9a90..973b6eb732 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ <!ENTITY message '<seealso marker="#message">message()</seealso>'> <!ENTITY dict @@ -13,20 +13,21 @@ <header> <copyright> -<year>2011</year><year>2013</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -308,7 +309,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 +566,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..a0313e2877 100644 --- a/lib/diameter/doc/src/diameter_codec.xml +++ b/lib/diameter/doc/src/diameter_codec.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ <!ENTITY records '<seealso marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>'> @@ -13,20 +13,21 @@ <erlref> <header> <copyright> -<year>2012</year> +<year>2012</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -73,7 +74,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 +123,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 +223,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 4fcde495b3..ae40f99aee 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "fileref.dtd" [ <!ENTITY format '<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso>'> @@ -16,20 +16,21 @@ <header> <copyright> -<year>2011</year><year>2013</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -431,7 +432,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 @@ -529,6 +530,11 @@ answer record and passed to a &app_handle_request; callback upon reception of an incoming request.</p> <p> +In cases in which there is a choice between string() and binary() types +for OctetString() and derived types, the representation is determined +by the value of &mod_string_decode;.</p> + +<p> <em>Basic AVP Data Formats</em></p> <marker id="OctetString"/> @@ -541,7 +547,7 @@ callback upon reception of an incoming request.</p> <marker id="Grouped"/> <pre> -OctetString() = [0..255] +OctetString() = string() | binary() Integer32() = -2147483647..2147483647 Integer64() = -9223372036854775807..9223372036854775807 Unsigned32() = 0..4294967295 @@ -603,13 +609,15 @@ and <c>{{2104,2,26},{9,42,23}}</c> (both inclusive) can be encoded.</p> <marker id="UTF8String"/> <pre> -UTF8String() = [integer()] +UTF8String() = [integer()] | binary() </pre> <p> List elements are the UTF-8 encodings of the individual characters in the string. -Invalid codepoints will result in encode/decode failure.</p> +Invalid codepoints will result in encode/decode failure. +On encode, a UTF8String() can be specified as a binary, or as a nested +list of binaries and codepoints.</p> <marker id="DiameterIdentity"/> <pre> diff --git a/lib/diameter/doc/src/diameter_examples.xml b/lib/diameter/doc/src/diameter_examples.xml index 1fd7755695..853ef96bb3 100644 --- a/lib/diameter/doc/src/diameter_examples.xml +++ b/lib/diameter/doc/src/diameter_examples.xml @@ -1,25 +1,26 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> -<year>2011</year><year>2012</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> diff --git a/lib/diameter/doc/src/diameter_intro.xml b/lib/diameter/doc/src/diameter_intro.xml index 288ebc0c7c..cb0aa3de2a 100644 --- a/lib/diameter/doc/src/diameter_intro.xml +++ b/lib/diameter/doc/src/diameter_intro.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd" [ <!ENTITY % also SYSTEM "seealso.ent"> %also; @@ -7,21 +7,22 @@ <chapter> <header> <copyright> -<year>2011</year><year>2013</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -40,7 +41,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 +70,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..112355816f 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" ?> +<?xml version="1.0" encoding="utf-8" ?> <!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 @@ -14,20 +16,21 @@ <header> <copyright> <year>2012</year> -<year>2013</year> +<year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -50,8 +53,8 @@ under the License. <p> 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> +The resulting source implements the interface diameter requires +to encode and decode the dictionary's messages and AVPs.</p> <p> The utility &man_compile; provides an alternate compilation @@ -64,16 +67,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 +124,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 +150,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 +169,57 @@ 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> + +<p> +A returned error reason can be converted into a readable string using +&format_error;.</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> + +<!-- ===================================================================== --> + +<func> +<name>format_error(Reason) -> string()</name> +<fsummary>Turn an error reason into a readable string.</fsummary> +<desc> + +<p> +Turn an error reason returned by &codec; into a readable string.</p> </desc> </func> @@ -138,11 +231,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..9b6d629f79 100644 --- a/lib/diameter/doc/src/diameter_sctp.xml +++ b/lib/diameter/doc/src/diameter_sctp.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ <!ENTITY gen_sctp '<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>'> <!ENTITY gen_sctp_open1 @@ -15,20 +15,22 @@ <erlref> <header> <copyright> -<year>2011</year><year>2013</year> +<year>2011</year> +<year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -90,7 +92,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> @@ -113,7 +115,7 @@ and port respectively.</p> <p> Multiple <c>ip</c> options can be specified for a multihomed peer. If none are specified then the values of <c>Host-IP-Address</c> -in the <c>#diameter_service{}</c> record are used. +in the <c>diameter_service</c> record are used. (In particular, one of these must be specified.) Option <c>port</c> defaults to 3868 for a listening transport and 0 for a connecting transport.</p> @@ -131,25 +133,18 @@ the buffer size.</p> </warning> <p> -diameter_sctp uses the <c>transport_data</c> field of -the <c>#diameter_packet{}</c> record 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> -on an inbound message passed to a &app_handle_request; or -&app_handle_answer; callback. -For an outbound message, either <c>undefined</c> (explicitly or -by receiving the outbound message as a <c>binary()</c>) or a tuple -should be set in the return value of &app_handle_request; -(typically by retaining the value passed into this function) -or &app_prepare_request;. -The value <c>undefined</c> uses a "next outbound stream" id and -increments this modulo the total number outbound streams. -That is, successive values of <c>undefined</c> cycle through all -outbound streams.</p> - -<!-- TODO: Some way of getting at the number of available outbound --> -<!-- streams. --> - +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> diff --git a/lib/diameter/doc/src/diameter_soc.xml b/lib/diameter/doc/src/diameter_soc.xml index 4f5419122f..ae404fcda4 100644 --- a/lib/diameter/doc/src/diameter_soc.xml +++ b/lib/diameter/doc/src/diameter_soc.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd" [ <!ENTITY % also SYSTEM "seealso.ent" > %also; @@ -9,21 +9,22 @@ <header> <copyright> <year>2011</year> -<year>2013</year> +<year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> diff --git a/lib/diameter/doc/src/diameter_soc_rfc6733.xml b/lib/diameter/doc/src/diameter_soc_rfc6733.xml index 8d85569650..2098965706 100644 --- a/lib/diameter/doc/src/diameter_soc_rfc6733.xml +++ b/lib/diameter/doc/src/diameter_soc_rfc6733.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!-- <copyright> -<year>2013</year> +<year>2013</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -1272,7 +1273,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_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml index ce4d6cfd0f..00ccc39c15 100644 --- a/lib/diameter/doc/src/diameter_tcp.xml +++ b/lib/diameter/doc/src/diameter_tcp.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ <!ENTITY start '<seealso marker="#start-3">start/3</seealso>'> <!ENTITY gen_tcp_connect3 @@ -27,20 +27,21 @@ <erlref> <header> <copyright> -<year>2011</year><year>2013</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index 9161bd1f48..736d4cbfbd 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ <!ENTITY message '<seealso marker="#message">message()</seealso>'> <!ENTITY MESSAGES '<seealso marker="#MESSAGES">MESSAGES</seealso>'> @@ -14,20 +14,21 @@ <erlref> <header> <copyright> -<year>2011</year><year>2013</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> diff --git a/lib/diameter/doc/src/diameter_using.xml b/lib/diameter/doc/src/diameter_using.xml index c487d94a16..dbdb1be284 100644 --- a/lib/diameter/doc/src/diameter_using.xml +++ b/lib/diameter/doc/src/diameter_using.xml @@ -1,25 +1,26 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> -<year>2011</year><year>2013</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameterc.xml index 6630019e5c..5bffe9a771 100644 --- a/lib/diameter/doc/src/diameter_compile.xml +++ b/lib/diameter/doc/src/diameterc.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE comref SYSTEM "comref.dtd" [ <!ENTITY dictionary '<seealso marker="diameter_dict">dictionary file</seealso>'> @@ -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..cb4f88a375 100644 --- a/lib/diameter/doc/src/files.mk +++ b/lib/diameter/doc/src/files.mk @@ -2,18 +2,19 @@ # %CopyrightBegin% # -# Copyright Ericsson AB 2010-2013. All Rights Reserved. +# Copyright Ericsson AB 2010-2016. All Rights Reserved. # -# The contents of this file are subject to the Erlang Public License, -# Version 1.1, (the "License"); you may not use this file except in -# compliance with the License. You should have received a copy of the -# Erlang Public License along with this software. If not, it can be -# retrieved online at http://www.erlang.org/. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at # -# Software distributed under the License is distributed on an "AS IS" -# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -# the License for the specific language governing rights and limitations -# under the License. +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% @@ -21,7 +22,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 e750b56f1e..b1be7bdcf7 100644 --- a/lib/diameter/doc/src/notes.xml +++ b/lib/diameter/doc/src/notes.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd" [ <!ENTITY % also SYSTEM "seealso.ent" > <!ENTITY % here SYSTEM "seehere.ent" > @@ -11,20 +11,21 @@ <header> <copyright> <year>2011</year> -<year>2013</year> +<year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -42,6 +43,1058 @@ first.</p> <!-- ===================================================================== --> +<section><title>diameter 1.12</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Ensure listening socket is closed at transport removal.</p> + <p> + Transport removal did not immediately close a + <c>diameter_tcp/sctp</c> listening socket, and a + subsequent peer connection caused it to remain open.</p> + <p> + Own Id: OTP-13611</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add <c>diameter:peer_info/1</c>.</p> + <p> + That retrieves information in the style of + <c>diameter:service_info/2</c>, but for a single peer + connection.</p> + <p> + Own Id: OTP-13508</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.11.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Make peer handling more efficient.</p> + <p> + Inefficient lookup and manipulation of peer lists could + result in poor performance when many outgoing requests + were sent simultaneously, or when many peers connected + simultaneously. Filtering peer lists on realm/host is now + also more efficient in many cases.</p> + <p> + Own Id: OTP-13164</p> + </item> + <item> + <p> + Fix handling of shared peer connections in watchdog state + SUSPECT.</p> + <p> + A peer connection shared from a remote node was regarded + as being up for the lifetime of the connection, ignoring + watchdog transitions into state SUSPECT.</p> + <p> + Own Id: OTP-13342</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.11.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix request table leaks</p> + <p> + The End-to-End and Hop-by-Hop identifiers of outgoing + Diameter requests are stored in a table in order for the + caller to be located when the corresponding answer + message is received. Entries were orphaned if the handler + was terminated by an exit signal as a consequence of + actions taken by callback functions, or if callbacks + modified identifiers in retransmission cases.</p> + <p> + Own Id: OTP-13137</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.11</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix relay encode of nested, Grouped AVPs.</p> + <p> + A fault in OTP-12475 caused encode to fail if the first + AVP in a Grouped AVP was itself Grouped.</p> + <p> + Own Id: OTP-12879 Aux Id: OTP-12475 </p> + </item> + <item> + <p> + Match acceptable peer addresses case insensitively.</p> + <p> + Regular expressions passed in an 'accept' tuple to + diameter_tcp or diameter_sctp inappropriately matched + case.</p> + <p> + Own Id: OTP-12902</p> + </item> + <item> + <p> + Fix diameter_watchdog function clause.</p> + <p> + OTP-12912 introduced an error with accepting transports + setting <c>{restrict_connections, false}</c>, causing + processes to fail when peer connections were terminated.</p> + <p> + Own Id: OTP-12969</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Don't report 5005 (DIAMETER_AVP_MISSING) errors + unnecessarily.</p> + <p> + An AVP whose decode failed was reported as missing, + despite having been reported with another error as a + consequence of the failure.</p> + <p> + Own Id: OTP-12871</p> + </item> + <item> + <p> + Improve decode performance.</p> + <p> + The time required to decode a message increased + quadratically with the number of AVPs in the worst case, + leading to extremely long execution times.</p> + <p> + Own Id: OTP-12891</p> + </item> + <item> + <p> + Improve watchdog and statistics performance.</p> + <p> + Inefficient use of timers contributed to poor performance + at high load, as did ordering of the table statistics are + written to.</p> + <p> + Own Id: OTP-12912</p> + </item> + <item> + <p> + Add service_opt() strict_mbit.</p> + <p> + There are differing opinions on whether or not reception + of an arbitrary AVP setting the M-bit is an error. The + default interpretation is strict: if a command grammar + doesn't explicitly allow an AVP setting the M-bit then + reception of such an AVP is regarded as an error. Setting + <c>{strict_mbit, false}</c> disables this check.</p> + <p> + Own Id: OTP-12947</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.10</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix decode of Grouped AVPs containing errors.</p> + <p> + RFC 6733 says this of Failed-AVP in 7.5:</p> + <p> + <taglist><item><p><c> In the case where the offending AVP + is embedded within a Grouped AVP, the Failed-AVP MAY + contain the grouped AVP, which in turn contains the + single offending AVP. The same method MAY be employed if + the grouped AVP itself is embedded in yet another grouped + AVP and so on. In this case, the Failed-AVP MAY contain + the grouped AVP hierarchy up to the single offending AVP. + This enables the recipient to detect the location of the + offending AVP when embedded in a + group.</c></p></item></taglist></p> + <p> + It says this of DIAMETER_INVALID_AVP_LENGTH in 7.1.5:</p> + <p> + <taglist><item><p><c> The request contained an AVP with + an invalid length. A Diameter message indicating this + error MUST include the offending AVPs within a Failed-AVP + AVP. In cases where the erroneous AVP length value + exceeds the message length or is less than the minimum + AVP header length, it is sufficient to include the + offending AVP header and a zero filled payload of the + minimum required length for the payloads data type. If + the AVP is a Grouped AVP, the Grouped AVP header with an + empty payload would be sufficient to indicate the + offending AVP. In the case where the offending AVP header + cannot be fully decoded when the AVP length is less than + the minimum AVP header length, it is sufficient to + include an offending AVP header that is formulated by + padding the incomplete AVP header with zero up to the + minimum AVP header length.</c></p></item></taglist></p> + <p> + The AVPs placed in the errors field of a diameter_packet + record are intended to be appropriate for inclusion in a + Failed-AVP, but neither of the above paragraphs has been + followed in the Grouped case: the entire faulty AVP + (non-faulty components and all) has been included. This + made it difficult to identify the actual faulty AVP in + all but simple cases.</p> + <p> + The decode is now adapted to the RFC, and implements the + suggested single faulty AVP, nested in as many Grouped + containers as required.</p> + <p> + Own Id: OTP-12721</p> + </item> + <item> + <p> + Fix SCTP problems on Solaris.</p> + <p> + The allocation of association ids in Solaris was in + conflict with an assumption made in diameter_sctp, + resulting in failures when accepting multiple peer + connections.</p> + <p> + Own Id: OTP-12768</p> + </item> + <item> + <p> + Fix start order of alternate transports.</p> + <p> + A transport configured with diameter:add_transport/2 can + be passed multiple transport_module/transport_config + tuples in order to specify alternate configuration, + modules being attempted in order until one succeeds. This + is primarily for the connecting case; for example, to + allow a transport to be configured to first attempt + connection over SCTP, and then TCP in case SCTP fails. + Multiple module tuples can be paired with a single config + tuple, but in this case the start order was reversed + relative to the order in which the modules were specifed.</p> + <p> + Own Id: OTP-12851</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Change license text from Erlang Public License to Apache + Public License v2.</p> + <p> + Own Id: OTP-12845</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.9.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix broken relay counters.</p> + <p> + OTP-12654 in OTP 17.5.3 broke counters in the case of + answer messages received in the relay application. + Counters were accumulated as unknown messages or + no_result_code instead of as relayed messages on the + intended Result-Code and 'Experimental-Result' tuples.</p> + <p> + Own Id: OTP-12741</p> + </item> + <item> + <p> + Fix diameter_sctp listener race.</p> + <p> + An oversight in OTP-12428 made it possible to start a + transport process that could not establish associations.</p> + <p> + Own Id: OTP-12744</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.9.1</title> + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p> + Don't leave extra bit in decoded AVP data.</p> + <p> + OTP-12074 in OTP 17.3 missed one case: a length error on + a trailing AVP unknown to the dictionary in question.</p> + <p> + Own Id: OTP-12642</p> + </item> + <item> + <p> + Don't confuse Result-Code and Experimental-Result.</p> + <p> + The errors field of a decoded diameter_packet record was + populated with a Result-Code AVP when an + Experimental-Result containing a 3xxx Result-Code was + received in an answer not setting the E-bit. The correct + AVP is now extracted from the incoming message.</p> + <p> + Own Id: OTP-12654</p> + </item> + <item> + <p> + Don't count on unknown Application Id.</p> + <p> + OTP-11721 in OTP 17.1 missed the case of an Application + Id not agreeing with that of the dictionary in question, + causing counters to be accumulated on keys containing the + unknown id.</p> + <p> + Own Id: OTP-12701</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.9</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Don't discard outgoing answers unnecessarily.</p> + <p> + Answers missing a Result-Code AVP or setting an E-bit + inappropriately were discarded even if encode was + successful.</p> + <p> + Own Id: OTP-11492</p> + </item> + <item> + <p> + Increase supervision timeouts.</p> + <p> + At diameter application shutdown, DPR could be omitted on + open peer connections because of short supervision + timeouts.</p> + <p> + Own Id: OTP-12412</p> + </item> + <item> + <p> + Fix retransmission of messages sent as header/avps list.</p> + <p> + Extracting End-to-End and Hop-by-Hop Identifiers resulted + in a function clause error, resulting in a handle_error + callback.</p> + <p> + Own Id: OTP-12415</p> + </item> + <item> + <p> + Fix diameter_avp decode of Grouped AVPs having decode + errors.</p> + <p> + Components of such an AVP were not extracted, causing it + to be represented by a single diameter_avp record instead + of the intended list.</p> + <p> + Dictionary files must be recompiled for the fix to have + effect.</p> + <p> + Own Id: OTP-12475</p> + </item> + <item> + <p> + Fix ordering of AVPs in relayed messages.</p> + <p> + The order was reversed relative to the received order, + with a Route-Record AVP prepended.</p> + <p> + Thanks to Andrzej Trawiński.</p> + <p> + Own Id: OTP-12551</p> + </item> + <item> + <p> + Fix issues with DiameterURI encode/decode.</p> + <p> + RFC 6773 changed the default port and transport, but the + RFC 3588 defaults were used even if the RFC 6733 common + dictionary was in use. The RFC 3588 defaults are now only + used when the common dictionary is + diameter_gen_base_rfc3588.</p> + <p> + Both RFC 3588 and 6733 disallow + transport=udp;protocol=diameter. Encode of the + combination now fails.</p> + <p> + Decode of ports numbers outside the range 0-65535 and + fully qualified domain names longer than 255 octets now + fails.</p> + <p> + Note that RFC 3588 is obsolete, and that there is a + diameter_gen_base_rfc6733. The change in defaults is a + potential interoperability problem when moving to RFC + 6733 with peers that do not send all URI components. The + fact that 6733 allows 5xxx result codes in answer + messages setting the E-bit, which RFC 3588 doesn't, is + another.</p> + <p> + Own Id: OTP-12589</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add service_opt() string_decode.</p> + <p> + To disable the decode of potentially large binaries to + string. This prevents large strings from being copied + when incoming Diameter messages are passed between + processes, a vulnerability that can lead to memory being + exhausted given sufficiently malicious peers.</p> + <p> + The value is a boolean(), true being the default for + backwards compatibility. Setting false causes both + diameter_caps records and decoded messages to contain + binary() in relevant places that previously had string(): + diameter_app(3) callbacks need to be prepared for the + change.</p> + <p> + The Diameter types affected are OctetString and the + derived types UTF8String, DiameterIdentity, DiameterURI, + IPFilterRule, and QoSFilterRule. Time and Address are + unaffected.</p> + <p> + Own Id: OTP-11952</p> + </item> + <item> + <p> + Add transport_opt() pool_size.</p> + <p> + To allow for pools of accepting transport processes, + which can better service multiple simultaneous peer + connections. The option can also be used with connecting + transports, to establish multiple connections to the same + peer without having to configure multiple transports.</p> + <p> + Own Id: OTP-12428</p> + </item> + <item> + <p> + Allow DPR to be sent with diameter:call/4.</p> + <p> + It has been possible to send, but the answer was regarded + as unsolicited and discarded. DPA now causes the + transport process in question to be terminated, as for + DPR that diameter itself sends.</p> + <p> + Own Id: OTP-12542</p> + </item> + <item> + <p> + Discard requests after DPR.</p> + <p> + RFC 6733 is imprecise, but the tone is that messages + received after DPR are an exception to be dealt with only + because of the possibility of unordered delivery over + SCTP. As a consequence, and because a request following + DPR is unlikely to be answered due to the impending loss + of the peer connection, discard outgoing requests + following an outgoing or incoming DPR. Incoming requests + are also discarded, with the exception of DPR itself. + Answers are sent and received as usual.</p> + <p> + Own Id: OTP-12543</p> + </item> + <item> + <p> + Add transport_opt() dpr_timeout.</p> + <p> + To cause a peer connection to be closed following an + outgoing DPA when the peer fails to do so. It is the + recipient of DPA that should close the connection + according to RFC 6733.</p> + <p> + Own Id: OTP-12609</p> + </item> + <item> + <p> + Add service_opt() incoming_maxlen.</p> + <p> + To bound the expected size of incoming Diameter messages. + Messages larger than the specified number of bytes are + discarded, to prevent a malicious peer from generating + excessive load.</p> + <p> + Own Id: OTP-12628</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix remote diameter_request table leak.</p> + <p> + An outgoing request whose pick_peer callback selected a + transport on another node resulted in an orphaned table + entry on that node.</p> + <p> + Own Id: OTP-12196</p> + </item> + <item> + <p> + Fix handling of 3xxx Result-Code without E-bit.</p> + <p> + OTP-12233 broke the population of the errors field of the + diameter_packet record when an incoming request with an + E-bit/Result-Code mismatch was detected, causing a + 4-tuple to be inserted as Result-Code in a diameter_avp + record.</p> + <p> + Own Id: OTP-12233</p> + </item> + <item> + <p> + Fix ignored connect timer.</p> + <p> + There are two timers governing the establishment of peer + connections: connect_timer and watchdog_timer. The former + is the RFC 6733 Tc timer, and is used at initial + connection establishment. The latter is RFC 3539 TwInit, + and is used for connection reestablishment. A connecting + transport erroneously used watchdog_timer in both cases.</p> + <p> + Own Id: OTP-12281 Aux Id: seq12728 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Order candidate peers in pick_peer callbacks.</p> + <p> + The order of candidate peers presented to a + diameter_app(3) pick_peer callback has previously not + been documented, but there are use cases that are + simplified by an ordering. The order is now determined by + the filter.</p> + <p> + Own Id: OTP-12308</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.7.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Don't leave extra bit in decoded AVP data.</p> + <p> + An extra bit could be communicated in the data field of a + diameter_avp record in the case of length errors. Of no + consequence for code using the record encoding of + Diameter messages, but code examining diameter_avp + records would see this bit.</p> + <p> + Dictionary files must be recompiled for the fix to have + effect.</p> + <p> + Own Id: OTP-12074</p> + </item> + <item> + <p> + Fix counting of outgoing requests and answers setting the + E-bit.</p> + <p> + OTP-11721 broke these counters for all outgoing requests + except DWR, and caused answers setting the E-bit to be + counted as unknown messages.</p> + <p> + Own Id: OTP-12080</p> + </item> + <item> + <p> + Fix Failed-AVP decode.</p> + <p> + The best-effort decode only worked for AVPs in the common + dictionary, not for those in the dictionary of the + application identified in the Diameter Header of the + answer message in question.</p> + <p> + Failed-AVP in an answer decoded with the RFC 3588 common + dictionary (diameter_gen_base_rfc3588) was regarded as an + error. The RFC 6733 dictionary was unaffected.</p> + <p> + Dictionary files must be recompiled for the fix to have + effect.</p> + <p> + Own Id: OTP-12094</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Improve robustness.</p> + <p> + Counters returned by diameter:service_info/2 now only + count messages known to the dictionary in question, so + that an attacker cannot cause arbitrarily many counters + to be created.</p> + <p> + Messages to the Erlang log have been minimized, and those + related to traffic have been removed entirely since an + attacker could cause a node to be logged to death. + Consequently, the default answer_errors configuration has + been changed from report to discard. A service needs to + be restarted for the change in default to take effect.</p> + <p> + Own Id: OTP-11721</p> + </item> + <item> + <p> + Fix request table leak.</p> + <p> + Outgoing Diameter requests are stored in a table until an + answer is received or times out. Calling + diameter:stop_service/1 before this took place would + orphan the entries, resulting in a memory leak.</p> + <p> + Own Id: OTP-11893</p> + </item> + <item> + <p> + Fix broken SCTP transport.</p> + <p> + OTP-11593 caused the sending of answer messages over SCTP + to fail.</p> + <p> + Own Id: OTP-11901 Aux Id: OTP-11593 </p> + </item> + <item> + <p> + Fix watchdog process leak.</p> + <p> + A failed capabilities exchange on a listening transport + would orphan a process, causing a memory leak.</p> + <p> + Own Id: OTP-11934</p> + </item> + <item> + <p> + Fix incorrect handling of incoming DPR.</p> + <p> + In the case of a listening transport, a reconnection by a + peer following DPR could transition the watchdog state to + REOPEN instead of OKAY.</p> + <p> + Own Id: OTP-11938</p> + </item> + <item> + <p> + Fix handling of AVP length errors on unknown AVPs.</p> + <p> + An AVP (Header) length that pointed past the end of the + message was not flagged as a 5014 error in this case. + Moreover, encoding such an AVP in the Failed-AVP of an + answer message as a consequence of other errors (eg. + M-bit, resulting in 5001) failed if the AVP contained a + complete header.</p> + <p> + Dictionary files must be recompiled for the fix to have + effect.</p> + <p> + Own Id: OTP-11946</p> + </item> + <item> + <p> + Fix broken check in dictionary compilation.</p> + <p> + That an AVP specified in the content of a @codecs or + @custom_types section was undefined went undetected, + causing compilation to fail when attempting to lookup the + AVP's type.</p> + <p> + Own Id: OTP-11958</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add result code counters for CEA, DWA, and DPA.</p> + <p> + In addition to the existing result code counters on other + answer messages.</p> + <p> + Own Id: OTP-11891</p> + </item> + <item> + <p> + Add best-effort decode of AVPs within Failed-AVP.</p> + <p> + OTP-11007 disabled the decode of AVPs in Failed-AVP since + errors could cause the decode of Failed-AVP itself to + fail. Component AVPs are now decoded if possible, + otherwise not. AVPs of type Grouped are decoded as much + as possible, as deeply as possible.</p> + <p> + Dictionary files must be recompiled for the fix to have + effect.</p> + <p> + Own Id: OTP-11936 Aux Id: OTP-11007 </p> + </item> + <item> + <p> + Add counters for encode errors in outgoing Diameter + messages.</p> + <p> + In addition to the existing counters on decode errors. + The latter now count independently of result codes in + answer messages since decode errors do not preclude the + presence of a result code.</p> + <p> + Own Id: OTP-11937</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Add missing check at dictionary compilation.</p> + <p> + In particular, that an AVP defined as having type Grouped + in an @avp_types section has a corresponding definition + in a @grouped section.</p> + <p> + Own Id: OTP-11561</p> + </item> + <item> + <p> + Correct documentation on the setting of Origin-State-Id</p> + <p> + It was incorrectly stated that the AVP would be set in an + outgoing DPR/DPA.</p> + <p> + Own Id: OTP-11583</p> + </item> + <item> + <p> + Change interface for communicating outbound stream id to + diameter_sctp</p> + <p> + The module uses the transport_data field of record + diameter_packet to communicate the stream on which the an + incoming message is received and on which an outgoing + message should be sent, the previous interface being that + both are communicated as a tuple of the form {stream, + Id}. However, since diameter retains the value of an + incoming request's transport_data unless the + corresponding answer message specifies otherwise, the + behaviour in this case is to send an answer on the + outbound stream with the same identifier as the that of + the inbound stream on which the request was received. If + the inbound stream id is greater than or equal to the + number of outbound streams then this is guaranteed to + fail, causing the transport process in question to + terminate. There is no relationship between inbound and + outbound stream identifiers so diameter_sctp's imposition + of one is simply wrong.</p> + <p> + Outbound stream ids are now communicated with a different + tuple: {outstream, Id}, interpreted modulo the number of + outbound streams. Thus, retention of an inbound request's + transport_data has no effect on the selection of an + outbound stream.</p> + <p> + The change in interface is not strictly backwards + compatible because of the new atom for the outbound + stream. However, as there is currently no documented way + of obtaining the available number of outbound streams for + a peer connection, there is no way for a client to have + known the range of ids from which it could reliably have + chosen with the previous interface, so any setting of the + outbound stream has probably been unintentional. Not + explicitly specifying an outbound stream now results in a + round-robin selection.</p> + <p> + Thanks to Sharmila Pillai for reporting the problem.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11593</p> + </item> + <item> + <p> + Fix unicode path failure in diameter_make:codec/2.</p> + <p> + A dictionary path containing a unicode codepoint > 255 + caused the function to fail.</p> + <p> + Own Id: OTP-11655</p> + </item> + <item> + <p> + Fix 'accept' config to diameter_sctp.</p> + <p> + OTP-10893 added support for {accept, Match} tuples to + specify addresses or regexps that should be matched + against peer addresses to decide whether or not a newly + established association should be retained, but this + hasn't been functional in the SCTP case because of + missing support in inet(3).</p> + <p> + The display of both local and peer addresses in + diameter:service_info/2 output has also been corrected.</p> + <p> + Own Id: OTP-11661 Aux Id: OTP-10229 </p> + </item> + <item> + <p> + Be lenient with the M-bit in Grouped AVPs.</p> + <p> + RFC 6733 says this, in 4.4:</p> + <p> + <taglist><item><p><c>Receivers of a Grouped AVP that does + not have the 'M' (mandatory) bit set and one or more of + the encapsulated AVPs within the group has the 'M' + (mandatory) bit set MAY simply be ignored if the Grouped + AVP itself is unrecognized. The rule applies even if the + encapsulated AVP with its 'M' (mandatory) bit set is + further encapsulated within other sub-groups, i.e., other + Grouped AVPs embedded within the Grouped + AVP.</c></p></item></taglist></p> + <p> + The first sentence is mangled but take it to mean this:</p> + <p> + <taglist><item><p><c>An unrecognized AVP of type Grouped + that does not set the 'M' bit MAY be ignored even if one + of its encapsulated AVPs sets the 'M' + bit.</c></p></item></taglist></p> + <p> + This is a bit of a non-statement since if the AVP is + unrecognized then its type is unknown. We therefore don't + know that its data bytes contain encapsulated AVPs, so + can't but ignore any of those that set the M-bit. Doing + anything else when the type *is* known would be + inconsistent.</p> + <p> + OTP-11087 (R16B03) caused the M-bit on any unrecognized + AVP to be regarded as an error, unrecognized being taken + to mean "not explicitly defined as a member of its + container". (That is, an AVP that can't be packed into a + dedicated record field, which is slightly stronger than + "not defined".) This fixed the original intention for + top-level AVPs but broke the required leniency for + Grouped AVPs whose type is known. This leniency is now + restored.</p> + <p> + Note that dictionary files need to be recompiled for the + change to have effect.</p> + <p> + Thanks to Rory McKeown for reporting the problem.</p> + <p> + Own Id: OTP-11675 Aux Id: OTP-11087 </p> + </item> + <item> + <p> + Fix pick_peer case clause failure.</p> + <p> + In the case of {call_mutates_state, true} configuration + on the service in question, any peer selection that + failed to select a peer resulted in a case clause + failure. This was noticed in the case of a peer failover + in which an alternate peer wasn't available.</p> + <p> + Own Id: OTP-11789</p> + </item> + </list> + </section> + +</section> + +<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> + </list> + </section> + +</section> + +<section><title>diameter 1.4.4</title> + + <section><title>Fixed Bugs and Malfunctions</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> + <list> + <item> + <p> + Fix UTF8String encode.</p> + <p> + Encode now accepts any nested list of codepoints and + binaries. A list containing a binary was previously + misinterpreted and the documentation was incomplete.</p> + <p> + Own Id: OTP-11172</p> + </item> + <item> + <p> + Ensure DWR isn't sent immediately after DWA.</p> + <p> + This was possible if the timing was unfortunate. An + incoming DWR now properly resets the watchdog timer.</p> + <p> + Own Id: OTP-11184</p> + </item> + <item> + <p> + Fix faulty encode of Failed-AVP</p> + <p> + Reception of a CER, DWR or DPR that has decode failures + caused encode of the corresponding answer message to + fail.</p> + <p> + Own Id: OTP-11293</p> + </item> + <item> + <p> + Fix broken service_opt() spawn_opt.</p> + <p> + The option was ignored.</p> + <p> + Own Id: OTP-11299</p> + </item> + </list> + </section> + +</section> + <section><title>diameter 1.4.2</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..a0ef28844d 100644 --- a/lib/diameter/doc/src/ref_man.xml +++ b/lib/diameter/doc/src/ref_man.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE application SYSTEM "application.dtd"> <application xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -6,20 +6,21 @@ <header> <copyright> <year>2011</year> -<year>2012</year> +<year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> @@ -39,7 +40,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..e5c284c6e8 100644 --- a/lib/diameter/doc/src/seealso.ent +++ b/lib/diameter/doc/src/seealso.ent @@ -4,18 +4,19 @@ %CopyrightBegin% -Copyright Ericsson AB 2012-2013. All Rights Reserved. +Copyright Ericsson AB 2012-2015. All Rights Reserved. -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. %CopyrightEnd% @@ -64,11 +65,14 @@ significant. <!ENTITY capabilities_cb '<seealso marker="#capabilities_cb">capabilities_cb</seealso>'> <!ENTITY capx_timeout '<seealso marker="#capx_timeout">capx_timeout</seealso>'> <!ENTITY disconnect_cb '<seealso marker="#disconnect_cb">disconnect_cb</seealso>'> +<!ENTITY dpa_timeout '<seealso marker="#dpa_timeout">dpa_timeout</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>'> +<!ENTITY mod_string_decode '<seealso marker="diameter#service_opt">diameter:service_opt()</seealso> <seealso marker="diameter#string_decode">string_decode</seealso>'> + <!-- diameter_app --> <!ENTITY app_handle_answer '<seealso marker="diameter_app#Mod:handle_answer-4">handle_answer/4</seealso>'> @@ -102,6 +106,9 @@ significant. <!ENTITY dict_Address '<seealso marker="diameter_dict#DATA_TYPES">Address()</seealso>'> <!ENTITY dict_DiameterIdentity '<seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>'> +<!ENTITY dict_DiameterURI '<seealso marker="diameter_dict#DATA_TYPES">DiameterURI()</seealso>'> +<!ENTITY dict_IPFilterRule '<seealso marker="diameter_dict#DATA_TYPES">IPFilterRule()</seealso>'> +<!ENTITY dict_QoSFilterRule '<seealso marker="diameter_dict#DATA_TYPES">QoSFilterRule()</seealso>'> <!ENTITY dict_Grouped '<seealso marker="diameter_dict#DATA_TYPES">Grouped()</seealso>'> <!ENTITY dict_OctetString '<seealso marker="diameter_dict#DATA_TYPES">OctetString()</seealso>'> <!ENTITY dict_Time '<seealso marker="diameter_dict#DATA_TYPES">Time()</seealso>'> @@ -115,6 +122,9 @@ 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>'> +<!ENTITY make_format_error '<seealso marker="diameter_make#format_error-1">diameter_make:format_error/1</seealso>'> <!-- diameter_transport --> diff --git a/lib/diameter/doc/src/seehere.sed b/lib/diameter/doc/src/seehere.sed index c62a783d40..10eca9258e 100644 --- a/lib/diameter/doc/src/seehere.sed +++ b/lib/diameter/doc/src/seehere.sed @@ -1,18 +1,19 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2012. All Rights Reserved. -# -# The contents of this file are subject to the Erlang Public License, -# Version 1.1, (the "License"); you may not use this file except in -# compliance with the License. You should have received a copy of the -# Erlang Public License along with this software. If not, it can be -# retrieved online at http://www.erlang.org/. -# -# Software distributed under the License is distributed on an "AS IS" -# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -# the License for the specific language governing rights and limitations -# under the License. +# Copyright Ericsson AB 2012-2016. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% diff --git a/lib/diameter/doc/src/user_man.xml b/lib/diameter/doc/src/user_man.xml index a6416c7e23..adfc8de880 100644 --- a/lib/diameter/doc/src/user_man.xml +++ b/lib/diameter/doc/src/user_man.xml @@ -1,24 +1,25 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> -<year>2011</year> +<year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. </legalnotice> |