aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc
diff options
context:
space:
mode:
authorAnders Svensson <[email protected]>2011-09-27 11:41:33 +0200
committerAnders Svensson <[email protected]>2011-09-27 11:41:33 +0200
commit578d53ae4ae3ecc1e8f3d05ad78d16a6a19ea890 (patch)
treeec8bd0c751463f4a889ab79045cfe002df270f89 /lib/diameter/doc
parent1e24333833f49e52ab3235148acf85cfd2c044b3 (diff)
parent7d38b593e8b1624e1ce2cda8fa57a42cdf2d3068 (diff)
downloadotp-578d53ae4ae3ecc1e8f3d05ad78d16a6a19ea890.tar.gz
otp-578d53ae4ae3ecc1e8f3d05ad78d16a6a19ea890.tar.bz2
otp-578d53ae4ae3ecc1e8f3d05ad78d16a6a19ea890.zip
Merge branch 'anders/diameter/peer_filters/OTP-9580' into dev
* anders/diameter/peer_filters/OTP-9580: Fix and clarify semantics of peer filters
Diffstat (limited to 'lib/diameter/doc')
-rw-r--r--lib/diameter/doc/src/diameter.xml37
-rw-r--r--lib/diameter/doc/src/diameter_app.xml7
2 files changed, 35 insertions, 9 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index 36b6cbf0cf..2cad70e3bc 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -277,6 +277,10 @@ callback.</p>
</taglist>
+<p>
+An invalid option will cause <seealso marker="#call">call/4</seealso>
+to fail.</p>
+
<marker id="capability"/>
</item>
@@ -405,6 +409,8 @@ sense.</p>
<code>
eval([{M,F,A} | T]) ->
apply(M, F, T ++ A);
+eval([[F|A] | T]) ->
+ eval([F | T ++ A]);
eval([F|A]) ->
apply(F, A);
eval(F) ->
@@ -461,14 +467,14 @@ or any peer if the request does not contain
a <c>Destination-Realm</c> AVP.</p>
</item>
-<tag><c>{host, any|UTF8String()}</c></tag>
+<tag><c>{host, any|DiameterIdentity()}</c></tag>
<item>
<p>
Matches only those peers whose <c>Origin-Host</c> has the
specified value, or all peers if the atom <c>any</c>.</p>
</item>
-<tag><c>{realm, any|UTF8String()</c></tag>
+<tag><c>{realm, any|DiameterIdentity()</c></tag>
<item>
<p>
Matches only those peers whose <c>Origin-Realm</c> has the
@@ -478,8 +484,9 @@ value, or all peers if the atom <c>any</c>.</p>
<tag><c>{eval, evaluable()}</c></tag>
<item>
<p>
-Matches only those peers for which the specified evaluable() evaluates
-to true on the peer's <c>diameter_caps</c> record.</p>
+Matches only those peers for which the specified evaluable() returns
+<c>true</c> on the connection's <c>diameter_caps</c> record.
+Any other return value or exception is equivalent to <c>false</c>.</p>
</item>
<tag><c>{neg, peer_filter()}</c></tag>
@@ -503,6 +510,21 @@ specified list.</p>
</taglist>
+<p>
+Note that the <c>host</c> and <c>realm</c> filters examine the
+outgoing request as passed to <seealso marker="#call">call/4</seealso>,
+assuming that this is a record- or list-valued message() as documented
+in <seealso marker="diameter_app">diameter_app(3)</seealso>, and that
+the message contains at most one of each AVP.
+If this is not the case then the <c>{host|realm, DiameterIdentity()}</c>
+filters must be used to achieve the desired result.
+Note also that an empty host/realm (which should not be typical)
+is equivalent to an unspecified one for the purposes of filtering.</p>
+
+<p>
+An invalid filter is equivalent to <c>{any, []}</c>, a filter
+that matches no peer.</p>
+
<marker id="service_event"/>
</item>
@@ -787,7 +809,7 @@ transports.</p>
<type>
<v>SvcName = service_name()</v>
<v>App = application_alias()</v>
-<v>Request = diameter_app:message()</v>
+<v>Request = diameter_app:message() | term()</v>
<v>Answer = term()</v>
<v>Options = [call_opt()]</v>
</type>
@@ -819,9 +841,8 @@ If there are no suitable peers, or if
<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
rejects them by returning 'false', then <c>{error, no_connection}</c>
is returned.
-If <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
-selects a candidate peer then a request process is spawned for the
-outgoing request, in which there is a
+Otherwise <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
+is followed by a
<seealso
marker="diameter_app#prepare_request">prepare_request/3</seealso>
callback, the message is encoded and sent.</p>
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index fc359b9d1d..f2bada84ae 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -269,7 +269,12 @@ The candidate peers list will only include those
which are selected by any <c>filter</c> option specified in the call to
<seealso marker="diameter#call">diameter:call/4</seealso>, and only
those which have indicated support for the Diameter application in
-question.</p>
+question.
+The order of the elements is unspecified except that any
+peers whose Origin-Host and Origin-Realm matches that of the
+outgoing request (in the sense of a <c>{filter, {all, [host, realm]}}</c>
+option to <seealso marker="diameter#call">diameter:call/4</seealso>)
+will be placed at the head of the list.</p>
<p>
The return values <c>false</c> and <c>{false, State}</c> are