From 8317fec82dc677f299e3772d3d644639f936857a Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Thu, 11 Oct 2012 02:17:56 +0200 Subject: -> 
 in documentation

The former doesn't allow seealso content, which erl_docgen doesn't
enforce, resulting in mangled PDF.
---
 lib/diameter/doc/src/diameter.xml      | 76 ++++++++++++++---------------
 lib/diameter/doc/src/diameter_app.xml  |  8 ++--
 lib/diameter/doc/src/diameter_dict.xml | 88 +++++++++++++++++-----------------
 3 files changed, 86 insertions(+), 86 deletions(-)

(limited to 'lib/diameter/doc')

diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index c93a7b2c67..ea540562af 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -110,10 +110,10 @@ defined by the application.

                              | [Mod | ExtraArgs]
                              | #diameter_callback{}
 
-
+
 Mod = atom()
 ExtraArgs = list()
-
+

 
 

 A module implementing the callback interface defined in 
 An expression that can be evaluated as a function in the following
 sense.

 
-
+
 eval([{M,F,A} | T]) ->
     apply(M, F, T ++ A);
 eval([[F|A] | T]) ->
@@ -366,7 +366,7 @@ eval([F|A]) ->
     apply(F, A);
 eval(F) ->
     eval([F]).
-
+

 
 

 Applying an evaluable()
@@ -527,12 +527,12 @@ implies the termination of all transport processes.

 {up, Ref, Peer, Config}
 {down, Ref, Peer, Config}
 
-
+
 Ref    = transport_ref()
 Peer   = diameter_app:peer()
 Config = {connect|listen, [transport_opt()]}
 Pkt    = #diameter_packet{}
-
+

 
 

 The RFC 3539 watchdog state machine has
@@ -556,10 +556,10 @@ respect to individual Diameter applications.

 
 {reconnect, Ref, Opts}
 
-
+
 Ref  = transport_ref()
 Opts = [transport_opt()]
-
+

 
 

 A connecting transport is attempting to establish/reestablish a
@@ -571,10 +571,10 @@ expiry.

 
 {closed, Ref, Reason, Config}
 
-
+
 Ref = transport_ref()
 Config = {connect|listen, [transport_opt()]}
-
+

 
 

 Capabilities exchange has failed.
@@ -584,13 +584,13 @@ Capabilities exchange has failed.
 
 {'CER', Result, Caps, Pkt}
 
-
+
 Result = ResultCode | {capabilities_cb, CB, ResultCode|discard}
 Caps = #diameter_caps{}
 Pkt  = #diameter_packet{}
 ResultCode = integer()
 CB = evaluable()
-
+

 
 

 An incoming CER has been answered with the indicated result code or
@@ -604,11 +604,11 @@ contains the rejecting callback.

 
 {'CER', Caps, {ResultCode, Pkt}}
 
-
+
 ResultCode = integer()
 Caps = #diameter_caps{}
 Pkt  = #diameter_packet{}
-
+

 
 

 An incoming CER contained errors and has been answered with the
@@ -627,12 +627,12 @@ connection establishment.

 
 {'CEA', Result, Caps, Pkt}
 
-
+
 Result = integer() | atom() | {capabilities_cb, CB, ResultCode|discard}
 Caps = #diameter_caps{}
 Pkt  = #diameter_packet{}
 ResultCode = integer()
-
+

 
 

 An incoming CEA has been rejected for the indicated reason.
@@ -647,10 +647,10 @@ contains the rejecting callback.

 
 {'CEA', Caps, Pkt}
 
-
+
 Caps = #diameter_caps{}
 Pkt  = #diameter_packet{}
-
+

 
 

 An incoming CEA contained errors and has been rejected.
@@ -671,12 +671,12 @@ of connection establishment.

 
 {watchdog, Ref, PeerRef, {From, To}, Config}
 
-
+
 Ref = transport_ref()
 PeerRef  = diameter_app:peer_ref()
 From, To = initial | okay | suspect | down | reopen
 Config = {connect|listen, [transport_opt()]}
-
+

 
 

 An RFC 3539 watchdog state machine has changed state.

@@ -772,9 +772,9 @@ to be evaluated at start_service/2.
 In particular, an identifier Id is mapped to a new identifier
 as follows.

-
+
 (H bsl N) bor (Id band ((1 bsl N) - 1))
-
+

 

 Note that RFC 3588 requires that End-to-End identifiers remain unique
 for a period of at least 4 minutes and that this and the call rate
@@ -980,9 +980,9 @@ Defaults to a single callback returning dpr.

 
 {reconnect_timer, Tc}
 
-
+
 Tc = Unsigned32()
-
+

 
 

 For a connecting transport, the RFC 3588 Tc timer, in milliseconds.
@@ -1029,12 +1029,12 @@ For example, the following options on a connecting transport
 request a connection with one peer over SCTP or another
 (typically the same) over TCP.

 
-
+
 {transport_module, diameter_sctp}
 {transport_config, SctpOpts, 5000}
 {transport_module, diameter_tcp}
 {transport_config, TcpOpts}
-
+

 
 

 To listen on both SCTP and TCP, define one transport for each.

@@ -1065,10 +1065,10 @@ corresponding timeout (see below) or all fail.

 
 {watchdog_timer, TwInit}
 
-
+
 TwInit = Unsigned32()
        | {M,F,A}
-
+

 
 

 The RFC 3539 watchdog timer.
@@ -1334,7 +1334,7 @@ marker="#add_transport">add_transport/2 and Ref is
 as returned by it.
 The remaining forms are equivalent to an arity-3 fun as follows.

 
-
+
 Pred = fun(transport_ref(), list()):  fun(Ref, _, Opts) -> Pred(Ref, Opts) end
 Pred = fun(list()):                   fun(_, _, Opts) -> Pred(Opts) end
 Pred = transport_ref():               fun(Ref, _, _)  -> Pred == Ref end
@@ -1342,7 +1342,7 @@ Pred = list():                        fun(_, _, Opts) -> [] == Pred -- Opts end
 Pred = true:                          fun(_, _, _) -> true end
 Pred = false:                         fun(_, _, _) -> false end
 Pred = {M,F,A}:  fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end
-
+

 
 

 Removing a transport causes the corresponding transport processes to
@@ -1425,7 +1425,7 @@ An example return value with for a client service with Origin-Host
 "client.example.com" configured with a single transport connected to
 "server.example.com" might look as follows.

 
-
+
 [[{ref,#Ref<0.0.0.93>},
   {type,connect},
   {options,[{transport_module,diameter_tcp},
@@ -1470,7 +1470,7 @@ An example return value with for a client service with Origin-Host
                {{{0,258,0},recv,{'Result-Code',2001}},3},
                {{{0,280,1},recv},2},
                {{{0,280,0},send},2}]}]]
-
+

 
 

 Here ref is a transport_ref().
 The transport info returned by a server with a single client
 connection might look as follows.

 
-
+
 [[{ref,#Ref<0.0.0.61>},
   {type,listen},
   {options,[{transport_module,diameter_tcp},
@@ -1557,7 +1557,7 @@ connection might look as follows.

                {{{0,280,0},send},5},
                {{{0,257,1},recv},1},
                {{{0,257,0},send},1}]}]]
-
+

 
 

 The information presented here is as in the connect case except
@@ -1576,7 +1576,7 @@ connections and for which Diameter-level statistics are accumulated
 only for the lifetime of the transport connection.
 A return value for the server above might look as follows.

 
-
+
 [[{ref,#Ref<0.0.0.61>},
   {type,accept},
   {options,[{transport_module,diameter_tcp},
@@ -1622,7 +1622,7 @@ A return value for the server above might look as follows.

                {{{0,280,0},send},66},
                {{{0,257,1},recv},1},
                {{{0,257,0},send},1}]}]]
-
+

 
 

 Note that there may be multiple entries with the same ref, in
@@ -1655,14 +1655,14 @@ Otherwise it contains the ref, type and options
 tuples as in transport and connections info above.
 For example:

 
-
+
 [{ref,#Ref<0.0.0.61>},
  {type,accept},
  {options,[{transport_module,diameter_tcp},
            {transport_config,[{reuseaddr,true},
                               {ip,{127,0,0,1}},
                               {port,3868}]}]}]
-
+

 
 
 
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index b6870f7c28..290b8a3984 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -559,14 +559,14 @@ application.

 

 The argument packet() has the following signature.

 
-
+
 #diameter_packet{header = #diameter_header{},
                  avps   = [#diameter_avp{}],
                  msg    = record() | undefined,
                  errors = [Unsigned32() | {Unsigned32(), #diameter_avp{}}],
                  bin    = binary(),
                  transport_data = term()}
-
+

 
 

 The msg field will be undefined in case the request has
@@ -619,9 +619,9 @@ being set by diameter.

 Send an answer message to the peer containing the specified
 protocol error.
 Equivalent to

-
+
 {reply, ['answer-message' | Avps]
-
+

 

 where Avps sets the Origin-Host, Origin-Realm, the specified
 Result-Code and (if the request sent one) Session-Id AVP's.

diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml
index 98adebf145..9d6a6a8f38 100644
--- a/lib/diameter/doc/src/diameter_dict.xml
+++ b/lib/diameter/doc/src/diameter_dict.xml
@@ -125,9 +125,9 @@ is used to identify the relevant dictionary module.

 

 Example:

 
-
+
 @id 16777231
-
+

 
 
 
@@ -146,9 +146,9 @@ with existing modules in the system.

 

 Example:

 
-
+
 @name etsi_e2
-
+

 
 
 
@@ -169,9 +169,9 @@ different Diameter applications.

 

 Example:

 
-
+
 @prefix etsi_e2
-
+

 
 
 
@@ -189,9 +189,9 @@ The section has empty content.

 

 Example:

 
-
+
 @vendor 13019 ETSI
-
+

 
 
 
@@ -205,13 +205,13 @@ The section content consists of AVP names.

 

 Example:

 
-
+
 @avp_vendor_id 2937
 
 WWW-Auth
 Domain-Index
 Region-Set
-
+

 
 
 
@@ -244,9 +244,9 @@ All dictionaries should typically inherit RFC3588 AVPs from
 

 Example:

 
-
+
 @inherits diameter_gen_base_rfc3588
-
+

 
 
 
@@ -268,12 +268,12 @@ none are to be set.

 

 Example:

 
-
+
 @avp_types
 
 Location-Information   350  Grouped     MV
 Requested-Information  353  Enumerated   V
-
+

 
 
 

@@ -298,11 +298,11 @@ encode/decode.

 

 Example:

 
-
+
 @custom_types rfc4005_avps
 
 Framed-IP-Address
-
+

 
 
 @codecs Mod
@@ -315,11 +315,11 @@ Like @custom_types but requires the specified module to export
 

 Example:

 
-
+
 @codecs rfc4005_avps
 
 Framed-IP-Address
-
+

 
 
 @messages
@@ -330,7 +330,7 @@ The section content consists of definitions of the form specified in
 section 3.2 of RFC 3588, "Command Code ABNF specification".

 
 
-
+
 @messages
 
 RTR ::= < Diameter Header: 287, REQ, PXY >
@@ -363,7 +363,7 @@ RTA ::= < Diameter Header: 287, PXY >
       * [ Proxy-Info ]
       * [ Route-Record ]
       * [ AVP ]
-
+

 
 
 
@@ -378,14 +378,14 @@ section 4.4 of RFC 3588, "Grouped AVP Values".

 

 Example:

 
-
+
 @grouped
 
 SIP-Deregistration-Reason ::= < AVP Header: 383 >
                               { SIP-Reason-Code }
                               [ SIP-Reason-Info ]
                             * [ AVP ]
-
+

 
 

 Specifying a Vendor-Id in the definition of a grouped AVP is
@@ -408,14 +408,14 @@ otherwise defined in another dictionary.

 

 Example:

 
-
+
 @enum SIP-Reason-Code
 
 PERMANENT_TERMINATION    0
 NEW_SIP_SERVER_ASSIGNED  1
 SIP_SERVER_CHANGE        2
 REMOVE_SIP_SERVER        3
-
+

 
 
 @end
@@ -450,22 +450,22 @@ contained in the message or grouped AVP in the order specified in the
 definition in question.
 For example, the grouped AVP

 
-
+
 SIP-Deregistration-Reason ::= < AVP Header: 383 >
                               { SIP-Reason-Code }
                               [ SIP-Reason-Info ]
                             * [ AVP ]
-
+

 
 

 will result in the following record definition given an empty
 prefix.

 
-
+
 -record('SIP-Deregistration-Reason' {'SIP-Reason-Code',
                                      'SIP-Reason-Info',
                                      'AVP'}).
-
+

 
 

 The values encoded in the fields of generated records depends on the
@@ -507,7 +507,7 @@ callback upon reception of an incoming request.

 
 
 
-
+
 OctetString() = [0..255]
 Integer32()   = -2147483647..2147483647
 Integer64()   = -9223372036854775807..9223372036854775807
@@ -516,7 +516,7 @@ Unsigned64()  = 0..18446744073709551615
 Float32()     = '-infinity' | float() | infinity
 Float64()     = '-infinity' | float() | infinity
 Grouped()     = record()
-
+

 
 

 On encode, an OctetString() can be specified as an iolist(),
@@ -530,10 +530,10 @@ section.

 Derived AVP Data Formats

 
 
-
+
 Address() = OctetString()
           | tuple()
-
+

 
 

 On encode, an OctetString() IPv4 address is parsed in the usual
@@ -545,7 +545,7 @@ An IPv6 tuple() has length 8 and contains values of type 0..65535.
 The tuple representation is used on decode.

 
 
-
+
 Time() = {date(), time()}
 
 where
@@ -559,7 +559,7 @@ where
   Hour   = 0..23
   Minute = 0..59
   Second = 0..59
-
+

 
 

 Additionally, values that can be encoded are
@@ -569,9 +569,9 @@ In particular, only values between {{1968,1,20},{3,14,8}}
 and {{2104,2,26},{9,42,23}} (both inclusive) can be encoded.

 
 
-
+
 UTF8String() = [integer()]
-
+

 
 

 List elements are the UTF-8 encodings of the individual characters
@@ -579,15 +579,15 @@ in the string.
 Invalid codepoints will result in encode/decode failure.

 
 
-
+
 DiameterIdentity() = OctetString()
-
+

 
 

 A value must have length at least 1.

 
 
-
+
 DiameterURI() = OctetString()
               | #diameter_URI{type = Type,
                               fqdn = FQDN,
@@ -602,7 +602,7 @@ where
   Port = integer()
   Transport = sctp | tcp
   Protocol  = diameter | radius | 'tacacs+'
-
+

 
 

 On encode, fields port, transport and protocol default to 3868, sctp
@@ -612,9 +612,9 @@ section 4.3 of RFC 3588.
 The record representation is used on decode.

 
 
-
+
 Enumerated() = Integer32()
-
+

 
 

 On encode, values can be specified using the macros defined in a
@@ -622,10 +622,10 @@ dictionary's hrl file.

 
 
 
-
+
 IPFilterRule()  = OctetString()
 QoSFilterRule() = OctetString()
-
+

 
 

 Values of these types are not currently parsed by diameter.

-- 
cgit v1.2.3


From 511e47080a0dade00cc973e9d79e7a70da198c43 Mon Sep 17 00:00:00 2001
From: Anders Svensson 
Date: Thu, 11 Oct 2012 12:56:29 +0200
Subject: Add entities file for cross-references (mostly)

Saves typing, more readable, less error prone.
---
 lib/diameter/doc/src/Makefile     |   3 +-
 lib/diameter/doc/src/diameter.ent | 196 ++++++++++++++++++++++++++++++++++++++
 lib/diameter/doc/src/files.mk     |   5 +-
 3 files changed, 202 insertions(+), 2 deletions(-)
 create mode 100644 lib/diameter/doc/src/diameter.ent

(limited to 'lib/diameter/doc')

diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile
index d1d5e8f869..6e91181c6c 100644
--- a/lib/diameter/doc/src/Makefile
+++ b/lib/diameter/doc/src/Makefile
@@ -34,7 +34,8 @@ XML_REF_FILES = $(XML_REF1_FILES) $(XML_REF3_FILES) $(XML_REF4_FILES)
 
 XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) \
             $(XML_REF_FILES) \
-            $(XML_PART_FILES) $(XML_CHAPTER_FILES) 
+            $(XML_PART_FILES) $(XML_CHAPTER_FILES) \
+            $(XML_ENTITY_FILES)
 
 INTERNAL_HTML_FILES = $(TECHNICAL_DESCR_FILES:%.xml=$(HTMLDIR)/%.html)
 
diff --git a/lib/diameter/doc/src/diameter.ent b/lib/diameter/doc/src/diameter.ent
new file mode 100644
index 0000000000..81f1b01239
--- /dev/null
+++ b/lib/diameter/doc/src/diameter.ent
@@ -0,0 +1,196 @@
+
+
+
+
+
+
+add_transport/2'>
+call/4'>
+origin_state_id/0'>
+remove_transport/2'>
+service_info/2'>
+services/0'>
+diameter:start_service/2'>
+stop_service/1'>
+subscribe/1'>
+
+application_alias()'>
+application_module()'>
+application_opt()'>
+call_opt()'>
+capability()'>
+evaluable()'>
+peer_filter()'>
+service_event()'>
+service_name()'>
+service_opt()'>
+transport_opt()'>
+transport_ref()'>
+
+application'>
+capabilities_cb'>
+capx_timeout'>
+disconnect_cb'>
+transport_config'>
+transport_module'>
+reconnect_timer'>
+watchdog_timer'>
+
+diameter:add_transport/2'>
+diameter:call/4'>
+diameter:remove_transport/2'>
+diameter:start_service/2'>
+
+diameter:call_opt()'>
+diameter:application_opt()'>
+diameter:evaluable()'>
+diameter:service_name()'>
+diameter:transport_opt()'>
+diameter:transport_ref()'>
+
+
+
+handle_answer/4'>
+handle_request/3'>
+handle_error/4'>
+peer_down/3'>
+peer_up/3'>
+pick_peer/4'>
+prepare_retransmit/3'>
+prepare_request/3'>
+
+capabilities()'>
+message()'>
+packet()'>
+peer()'>
+peer_ref()'>
+state()'>
+
+handle_answer/4'>
+handle_request/3'>
+handle_error/4'>
+peer_up/3'>
+pick_peer/4'>
+prepare_retransmit/3'>
+prepare_request/3'>
+
+diameter_app:message()'>
+diameter_app:peer()'>
+diameter_app:peer_ref()'>
+
+
+
+diameter_dict(4)'>
+
+Address()'>
+DiameterIdentity()'>
+Grouped()'>
+OctetString()'>
+Time()'>
+UTF8String()'>
+Unsigned32()'>
+
+
+
+start/3'>
+
+
+
+diameterc(1)'>
+diameter(3)'>
+diameter_app(3)'>
+diameter_dict(4)'>
+diameter_transport(3)'>
+diameter_sctp(3)'>
+diameter_tcp(3)'>
diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk
index 79d53abceb..48f604c98f 100644
--- a/lib/diameter/doc/src/files.mk
+++ b/lib/diameter/doc/src/files.mk
@@ -2,7 +2,7 @@
 
 # %CopyrightBegin%
 #
-# Copyright Ericsson AB 2010-2011. All Rights Reserved.
+# Copyright Ericsson AB 2010-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
@@ -17,6 +17,9 @@
 #
 # %CopyrightEnd%
 
+XML_ENTITY_FILES = \
+	diameter.ent
+
 XML_APPLICATION_FILES = \
 	ref_man.xml
 
-- 
cgit v1.2.3


From 439dd4b95017a9966dd0cf1f090a9b00da831fe4 Mon Sep 17 00:00:00 2001
From: Anders Svensson 
Date: Fri, 16 Nov 2012 00:41:34 +0100
Subject: Use entities for cross references

---
 lib/diameter/doc/src/diameter.xml           | 442 +++++++++++-----------------
 lib/diameter/doc/src/diameter_app.xml       | 256 +++++++---------
 lib/diameter/doc/src/diameter_compile.xml   |   7 +-
 lib/diameter/doc/src/diameter_dict.xml      |  21 +-
 lib/diameter/doc/src/diameter_sctp.xml      |  29 +-
 lib/diameter/doc/src/diameter_tcp.xml       |  25 +-
 lib/diameter/doc/src/diameter_transport.xml |  30 +-
 7 files changed, 339 insertions(+), 471 deletions(-)

(limited to 'lib/diameter/doc')

diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index ea540562af..0392bd9bb7 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -1,5 +1,8 @@
 
-
+
+  %ents;
+]>
 
 
 

@@ -49,15 +52,12 @@ Diameter protocol as defined in RFC 3588.

 
 

 Basic usage consists of creating a representation of a
-locally implemented Diameter node and its capabilities with start_service/2, adding transport
-capability using add_transport/2 and sending Diameter
-requests and receiving Diameter answers with call/4.
+locally implemented Diameter node and its capabilities with
+&start_service;, adding transport capability using
+&add_transport; and sending Diameter
+requests and receiving Diameter answers with &call;.
 Incoming Diameter requests are communicated as callbacks to a
-diameter_app(3) callback modules as
+&man_app; callback modules as
 specified in the service configuration.

 
 

@@ -90,7 +90,7 @@ in this module.

 
 

 Types corresponding to RFC 3588 AVP Data Formats.
-Defined in diameter_dict(4).

+Defined in &dict_data_types;.

 
 
 
@@ -100,7 +100,7 @@ Defined in diameter_dict(4)
 

 A name identifying a Diameter application in
 service configuration.
-Passed to call/4 when sending requests
+Passed to &call; when sending requests
 defined by the application.

 
 
@@ -116,17 +116,16 @@ ExtraArgs = list()

-A module implementing the callback interface defined in diameter_app(3), along with any +A module implementing the callback interface defined in &man_app;, +along with any extra arguments to be appended to those documented for the interface. Note that extra arguments specific to an outgoing request can be -specified to call/4, in which case +specified to &call;, in which case those are are appended to any module-specific extra arguments.

Specifying a #diameter_callback{} record allows individual -functions to be configured in place of the usual diameter_app(3) callbacks. +functions to be configured in place of the usual &man_app; callbacks. See that module for details.

@@ -141,7 +140,7 @@ Has one the following types.

-{alias, application_alias()} +{alias, &application_alias;}

An unique identifier for the application in the scope of the @@ -156,17 +155,15 @@ unspecified.

The name of an encode/decode module for the Diameter messages defined by the application. These modules are generated from a specification file whose format is -documented in diameter_dict(4).

+documented in &man_dict;.

 -{module, application_module()} +{module, &application_module;}

The callback module with which messages of the Diameter application are handled. -See diameter_app(3) for -the required interface and semantics.

+See &man_app; for the required interface and semantics.

 {state, term()} @@ -174,7 +171,7 @@ the required interface and semantics.

The initial callback state. The prevailing state is passed to some -diameter_app(3) +&man_app; callbacks, which can then return a new state. Defaults to the value of the alias option if unspecified.

@@ -182,14 +179,13 @@ Defaults to the value of the alias option if unspecified.

{call_mutates_state, true|false}

-Specifies whether or not the pick_peer/4 +Specifies whether or not the &app_pick_peer; application callback can modify the application state, Defaults to false if unspecified.

-pick_peer callbacks +&app_pick_peer; callbacks are serialized when these are allowed to modify state, which is a potential performance bottleneck. A simple Diameter client may suffer no ill effects from using mutable @@ -203,10 +199,8 @@ probably avoid it.

Determines the manner in which incoming answer messages containing decode errors are handled. -If callback then errors result in a handle_answer/4 -callback in the same fashion as for handle_request/3, with +If callback then errors result in a &app_handle_answer; +callback in the same fashion as for &app_handle_request;, with errors communicated in the errors field of the #diameter_packet{} record passed to the callback. If report then an answer containing errors is discarded @@ -214,7 +208,7 @@ without a callback and a warning report is written to the log. If discard then an answer containing errors is silently discarded without a callback. In both the report and discard cases the return value -for the call/4 invocation in +for the &call; invocation in question is as if a callback had taken place and returned {error, failure}.

@@ -231,7 +225,7 @@ Defaults to report if unspecified.

-Options available to call/4 when +Options available to &call; when sending an outgoing Diameter request. Has one of the following types.

@@ -247,18 +241,18 @@ itself. Multiple options append to the argument list.

 -{filter, peer_filter()} +{filter, &peer_filter;}

A filter to apply to the list of available peers before passing them to -the pick_peer/4 +the &app_pick_peer; callback for the application in question. Multiple options are equivalent a single all filter on the corresponding list of filters. Defaults to none.

 -{timeout, Unsigned32()} +{timeout, &dict_Unsigned32;}

The number of milliseconds after which the request should @@ -269,21 +263,17 @@ Defaults to 5000.

detach

-Causes call/4 to return ok as +Causes &call; to return ok as soon as the request in question has been encoded instead of waiting for and returning -the result from a subsequent -handle_answer/4 -or handle_error/4 -callback.

+the result from a subsequent &app_handle_answer; or +&app_handle_error; callback.

-An invalid option will cause call/4 -to fail.

+An invalid option will cause &call; to fail.

@@ -300,9 +290,9 @@ Has one of the following types.

-{'Origin-Host', DiameterIdentity()} -{'Origin-Realm', DiameterIdentity()} -{'Host-IP-Address', [Address()]} +{'Origin-Host', &dict_DiameterIdentity;} +{'Origin-Realm', &dict_DiameterIdentity;} +{'Host-IP-Address', [&dict_Address;]}

An address list is available to the start function of a @@ -312,24 +302,23 @@ Host-IP-Address need not be specified if the transport start function returns an address list.

 -{'Vendor-Id', Unsigned32()} -{'Product-Name', UTF8String()} -{'Origin-State-Id', Unsigned32()} +{'Vendor-Id', &dict_Unsigned32;} +{'Product-Name', &dict_UTF8String;} +{'Origin-State-Id', &dict_Unsigned32;}

Origin-State-Id is optional but will be included in outgoing messages sent by diameter itself: CER/CEA, DWR/DWA and DPR/DPA. Setting a value of 0 (zero) is equivalent to not setting a value as documented in RFC 3588. -The function origin_state_id/0 +The function &origin_state_id; can be used as to retrieve a value that is computed when the diameter application is started.

 -{'Supported-Vendor-Id', [Unsigned32()]} -{'Auth-Application-Id', [Unsigned32()]} -{'Inband-Security-Id', [Unsigned32()]} +{'Supported-Vendor-Id', [&dict_Unsigned32;]} +{'Auth-Application-Id', [&dict_Unsigned32;]} +{'Inband-Security-Id', [&dict_Unsigned32;]}

Inband-Security-Id defaults to the empty list, which is equivalent to a @@ -338,9 +327,9 @@ If 1 (= TLS) is specified then TLS is selected if the CER/CEA received from the peer offers it.

 -{'Acct-Application-Id', [Unsigned32()]} -{'Vendor-Specific-Application-Id', [Grouped()]} -{'Firmware-Revision', Unsigned32()} +{'Acct-Application-Id', [&dict_Unsigned32;]} +{'Vendor-Specific-Application-Id', [&dict_Grouped;]} +{'Firmware-Revision', &dict_Unsigned32;} @@ -369,7 +358,7 @@ eval(F) ->

-Applying an evaluable() +Applying an &evaluable; E to an argument list A is meant in the sense of eval([E|A]).

@@ -380,10 +369,7 @@ situations in which the fun is not short-lived and code is to be upgraded at runtime since any processes retaining such a fun will have a reference to old code. In particular, such a value is typically inappropriate in -configuration passed to start_service/2 or -add_transport/2.

+configuration passed to &start_service; or &add_transport;.

@@ -392,10 +378,8 @@ marker="#add_transport">add_transport/2.

peer_filter() = term()

-A filter passed to call/4 -in order to select candidate peers for a -pick_peer/4 -callback. +A filter passed to &call; in order to select candidate peers for a +&app_pick_peer; callback. Has one of the following types.

@@ -426,42 +410,42 @@ or any peer if the request does not contain a Destination-Realm AVP.

 -{host, any|DiameterIdentity()} +{host, any|&dict_DiameterIdentity;}

Matches only those peers whose Origin-Host has the specified value, or all peers if the atom any.

 -{realm, any|DiameterIdentity() +{realm, any|&dict_DiameterIdentity;

Matches only those peers whose Origin-Realm has the specified value, or all peers if the atom any.

 -{eval, evaluable()} +{eval, &evaluable;}

-Matches only those peers for which the specified evaluable() returns +Matches only those peers for which the specified +&evaluable; returns true on the connection's diameter_caps record. Any other return value or exception is equivalent to false.

 -{neg, peer_filter()} +{neg, &peer_filter;}

Matches only those peers not matched by the specified filter.

 -{all, [peer_filter()]} +{all, [&peer_filter;]}

Matches only those peers matched by each filter in the specified list.

 -{any, [peer_filter()]} +{any, [&peer_filter;]}

Matches only those peers matched by at least one filter in the @@ -477,15 +461,12 @@ that matches no peer.

The host and realm filters examine the -outgoing request as passed to call/4, -assuming that this is a record- or list-valued diameter_app:message(), +outgoing request as passed to &call;, +assuming that this is a record- or list-valued &app_message;, and that the message contains at most one of each AVP. -If this is not the case then the {host|realm, DiameterIdentity()} +If this is not the case then the {host|realm, &dict_DiameterIdentity;} filters must be used to achieve the desired result. -An empty DiameterIdentity() +An empty &dict_DiameterIdentity; (which should not be typical) matches all hosts/realms for the purposes of filtering.

 @@ -504,7 +485,7 @@ candidates list.

An event message sent to processes that have subscribed to these using -subscribe/1.

+&subscribe;.

The info field of the event record can have one of the @@ -528,9 +509,9 @@ implies the termination of all transport processes.

{down, Ref, Peer, Config} 
-Ref    = transport_ref()
-Peer   = diameter_app:peer()
-Config = {connect|listen, [transport_opt()]}
+Ref    = &transport_ref;
+Peer   = &app_peer;
+Config = {connect|listen, [&transport_opt;]}
 Pkt    = #diameter_packet{}
@@ -546,7 +527,8 @@ connectivity.

Note that a single up/down event for a given peer -corresponds to one peer_up/peer_down +corresponds to one +peer_up/peer_down callback for each of the Diameter applications negotiated during capablilities exchange. That is, the event communicates connectivity with the @@ -557,23 +539,21 @@ respect to individual Diameter applications.

{reconnect, Ref, Opts} 
-Ref  = transport_ref()
-Opts = [transport_opt()]
+Ref  = &transport_ref;
+Opts = [&transport_opt;]

A connecting transport is attempting to establish/reestablish a -transport connection with a peer following reconnect_timer or -watchdog_timer -expiry.

+transport connection with a peer following &reconnect_timer; or +&watchdog_timer; expiry.

 {closed, Ref, Reason, Config} 
-Ref = transport_ref()
-Config = {connect|listen, [transport_opt()]}
+Ref = &transport_ref;
+Config = {connect|listen, [&transport_opt;]}

@@ -589,7 +569,7 @@ Result = ResultCode | {capabilities_cb, CB, ResultCode|discard} Caps = #diameter_caps{} Pkt = #diameter_packet{} ResultCode = integer() -CB = evaluable() +CB = &evaluable;

@@ -620,8 +600,7 @@ indicated result code. {'CER', timeout}

-An expected CER was not received within capx_timeout of +An expected CER was not received within &capx_timeout; of connection establishment.

 @@ -661,8 +640,7 @@ An incoming CEA contained errors and has been rejected. {'CEA', timeout}

-An expected CEA was not received within capx_timeout +An expected CEA was not received within &capx_timeout; of connection establishment.

 @@ -672,8 +650,8 @@ of connection establishment.

{watchdog, Ref, PeerRef, {From, To}, Config} 
-Ref = transport_ref()
-PeerRef  = diameter_app:peer_ref()
+Ref = &transport_ref;
+PeerRef = &app_peer_ref;
 From, To = initial | okay | suspect | down | reopen
 Config = {connect|listen, [transport_opt()]}
@@ -694,8 +672,7 @@ info fields of forms other than the above.

service_name() = term()

-The name of a service as passed to start_service/2 and with which the +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 erlang:make_ref/0 @@ -707,25 +684,21 @@ can be used to generate a service name that is somewhat unique.

service_opt()

-An option passed to start_service/2. -Can be any capability() as -well as the following.

+An option passed to &start_service;. +Can be any &capability; as well as the following.

-{application, [application_opt()]} +{application, [&application_opt;]}

Defines a Diameter application supported by the service.

-A service must configure one application for each Diameter +A service must configure one &application; for each Diameter application it intends to support. -For an outgoing Diameter request, the relevant application_alias() is -passed to call/4, while for an +For an outgoing Diameter request, the relevant &application_alias; is +passed to &call;, while for an incoming request the application identifier in the message header determines the application, the identifier being specified in the application's dictionary @@ -746,7 +719,7 @@ same peer are accepted by the service.

If type [node()] then a connection is rejected if another already exists on any of the specified nodes. Values of type false, node, nodes or -evaluable() are equivalent to +&evaluable; are equivalent to values [], [node()], [node()|nodes()] and the evaluated value, respectively, evaluation of each expression taking place whenever a new connection is to be established. @@ -761,15 +734,13 @@ by their own peer and watchdog state machines.

Defaults to nodes.

 -{sequence, {H,N} | evaluable()} +{sequence, {H,N} | &evaluable;}

Specifies a constant value H for the topmost 32-N bits of of 32-bit End-to-End and Hop-by-Hop identifiers generated by the service, either explicity or as a return value of a function -to be evaluated at start_service/2. +to be evaluated at &start_service;. In particular, an identifier Id is mapped to a new identifier as follows.

@@ -798,13 +769,12 @@ Defaults to {0,32}.

 transport_opt()
 
 

-An option passed to add_transport/2.
+An option passed to &add_transport;.
 Has one of the following types.

 
 
 
-{applications, [application_alias()]}
+{applications, [&application_alias;]}
 
 

 The list of Diameter applications to which the transport should be
@@ -814,7 +784,7 @@ Applications not configured on the service in question are ignored.

 
 
 
-{capabilities, [capability()]}
+{capabilities, [&capability;]}
 
 

 AVP's used to construct outgoing CER/CEA messages.
@@ -824,19 +794,17 @@ question.

 

 Specifying a capability as a transport option
 may be particularly appropriate for Inband-Security-Id, in case
-TLS is desired over TCP as implemented by
-diameter_tcp(3).

+TLS is desired over TCP as implemented by &man_tcp;.

 
 
 
-{capabilities_cb, evaluable()}
+{capabilities_cb, &evaluable;}
 
 

 A 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 transport_ref() and
+Applied to the &transport_ref; and
 #diameter_caps{} record of the connection.

 
 

@@ -871,23 +839,22 @@ Equivalent to returning 3010, DIAMETER_UNKNOWN_PEER.

 

 Returning anything but ok or a 2xxx series result
 code causes the transport connection to be broken.
-Multiple capabilities_cb
+Multiple &capabilities_cb;
 options can be specified, in which
 case the corresponding callbacks are applied until either all return
 ok or one does not.

 
 
 
-{capx_timeout,
-  Unsigned32()}
+{capx_timeout, &dict_Unsigned32;}
 
 

 The number of milliseconds after which a transport process having an
 established transport connection will be terminated if the expected
 capabilities exchange message (CER or CEA) is not received from the peer.
 For a connecting transport, the timing reconnection attempts is
-governed by watchdog_timer or
-reconnect_timer expiry.
+governed by &watchdog_timer; or
+&reconnect_timer; expiry.
 For a listening transport, the peer determines the timing.

 
 

@@ -895,21 +862,19 @@ Defaults to 10000.

 
 
 
-{disconnect_cb, evaluable()}
+{disconnect_cb, &evaluable;}
 
 
 

 A callback invoked prior to terminating the transport process of a
 transport connection having watchdog state OKAY.
 Applied to Reason=transport|service|application and the
-transport_ref() and
-diameter_app:peer()
+&transport_ref; and
+&app_peer;
 in question, Reason indicating whether the the diameter
 application is being stopped, the service in question is being stopped
-at stop_service/1 or
-the transport in question is being removed at remove_transport/2,
+at &stop_service; or
+the transport in question is being removed at &remove_transport;,
 respectively.

 
 

@@ -934,8 +899,7 @@ Defaults to rebooting for Reason=service|application and
 goaway for Reason=transport.

 
 
-{timeout,
-  Unsigned32()}
+{timeout, &dict_Unsigned32;}
 
 

 The number of milliseconds after which the transport process is
@@ -966,7 +930,7 @@ Equivalent to not having configured the callback.

 
 
 

-Multiple disconnect_cb
+Multiple &disconnect_cb;
 options can be specified, in which
 case the corresponding callbacks are applied until one of them returns
 a value other than ignore.
@@ -981,7 +945,7 @@ Defaults to a single callback returning dpr.

 {reconnect_timer, Tc}
 
 
-Tc = Unsigned32()
+Tc = &dict_Unsigned32;
 

 
 

@@ -989,8 +953,7 @@ For a connecting transport, the RFC 3588 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 before
 an initial connection is established: once there is an initial
-connection it's watchdog_timer that determines the
+connection it's &watchdog_timer; that determines the
 frequency of reconnection attempts, as required by RFC 3539.

 
 

@@ -1000,8 +963,7 @@ 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
+that a listening transport's &reconnect_timer; should be greater
 than its peer's Tw plus jitter.

 
 

@@ -1011,13 +973,11 @@ transport.

 
 
 {transport_config, term()}
-{transport_config, term(), Unsigned32()}
+{transport_config, term(), &dict_Unsigned32;}
 
 

-A term passed as the third argument to the start/3 function of
-the relevant transport_module in order to
+A 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.

 
@@ -1044,17 +1004,15 @@ To listen on both SCTP and TCP, define one transport for each.

 {transport_module, atom()}
 
 

-A module implementing a transport process as defined in diameter_transport(3).
+A module implementing a transport process as defined in &man_transport;.
 Defaults to diameter_tcp if unspecified.

 
 

-Multiple transport_module and transport_config
+Multiple transport_module and &transport_config;
 options are allowed.
 The order of these is significant in this case (and only in this case),
 a transport_module being paired with the first
-transport_config
+&transport_config;
 following it in the options list, or the default value for trailing
 modules.
 Transport starts will be attempted with each of the
@@ -1066,7 +1024,7 @@ corresponding timeout (see below) or all fail.

 {watchdog_timer, TwInit}
 
 
-TwInit = Unsigned32()
+TwInit = &dict_Unsigned32;
        | {M,F,A}
 

 
@@ -1088,10 +1046,8 @@ Defaults to 30000 if unspecified.

 
 

 Unrecognized options are silently ignored but are returned unmodified
-by service_info/2 and can be referred to
-in predicate functions passed to remove_transport/2.

+by &service_info; and can be referred to
+in predicate functions passed to &remove_transport;.

 
 
 
@@ -1099,8 +1055,7 @@ marker="#remove_transport">remove_transport/2.

 transport_ref() = reference()
 
 

-An reference returned by add_transport/2 that
+An reference returned by &add_transport; that
 identifies the configuration.

 
 
@@ -1118,9 +1073,9 @@ identifies the configuration.

         -> {ok, Ref} | {error, Reason}
 Add transport capability to a service.
 
-SvcName = service_name()
-Opt = transport_opt()
-Ref = transport_ref()
+SvcName = &service_name;
+Opt = &transport_opt;
+Ref = &transport_ref;
 Reason = term()
 
 
@@ -1139,8 +1094,7 @@ one peer, an listening transport potentially with many.

 The diameter application takes responsibility for exchanging
 CER/CEA with the peer.
 Upon successful completion of capabilities exchange the service
-calls each relevant application module's peer_up/3 callback
+calls each relevant application module's &app_peer_up; callback
 after which the caller can exchange Diameter messages with the peer over
 the transport.
 In addition to CER/CEA, the service takes responsibility for the
@@ -1169,11 +1123,11 @@ its transports.

 call(SvcName, App, Request, [Opt]) -> Answer | ok | {error, Reason}
 Send a Diameter request message.
 
-SvcName = service_name()
-App = application_alias()
-Request = diameter_app:message()
+SvcName = &service_name;
+App = &application_alias;
+Request = &app_message;
 Answer = term()
-Opt = call_opt()
+Opt = &call_opt;
 
 
 

@@ -1182,37 +1136,29 @@ Send a Diameter request message.

 

 App specifies the Diameter application in which the request is
 defined and callbacks to the corresponding callback module
-will follow as described below and in diameter_app(3).
+will follow as described below and in &man_app;.
 Unless the detach option is specified, the call returns either
 when an answer message is received from the peer or an error occurs.
 In the answer case, the return value is as returned by a
-handle_answer/4
-callback.
+&app_handle_answer; callback.
 In the error case, whether or not the error is returned directly
-by diameter or from a handle_error/4
+by diameter or from a &app_handle_error;
 callback depends on whether or not the outgoing request is
 successfully encoded for transmission to the peer, the cases being
 documented below.

 
 

 If there are no suitable peers, or if
-pick_peer/4
+&app_pick_peer;
 rejects them by returning false, then {error,no_connection}
 is returned.
-Otherwise pick_peer/4
-is followed by a
-prepare_request/3
-callback, the message is encoded and then sent.

+Otherwise &app_pick_peer; is followed by a
+&app_prepare_request; callback, the message is encoded and then sent.

 
 

 There are several error cases which may prevent an
 answer from being received and passed to a
-handle_answer/4
-callback:

+&app_handle_answer; callback:

 
 
 
@@ -1227,16 +1173,14 @@ is returned.

 

 If the request is successfully encoded and sent but
 the answer times out then a
-handle_error/4
-callback takes place with Reason = timeout.

+&app_handle_error; callback takes place with Reason = timeout.

 
 
 
 

 If the request is successfully encoded and sent but the service in
 question is stopped before an answer is received then a
-handle_error/4
-callback takes place with Reason = cancel.

+&app_handle_error; callback takes place with Reason = cancel.

 
 
 
@@ -1245,18 +1189,11 @@ If the transport connection with the peer goes down after the request
 has been sent but before an answer has been received then an attempt
 is made to resend the request to an alternate peer.
 If no such peer is available, or if the subsequent
-pick_peer/4
-callback rejects the candidates, then a
-handle_error/4
-callback takes place with Reason = failover.
-If a peer is selected then a
-prepare_retransmit/3
+&app_pick_peer; callback rejects the candidates, then a
+&app_handle_error; callback takes place with Reason = failover.
+If a peer is selected then a &app_prepare_retransmit;
 callback takes place, after which the semantics are the same as
-following an initial
-
-prepare_request/3
-callback.

+following an initial &app_prepare_request; callback.

 
 
 
@@ -1290,7 +1227,7 @@ transport connection.

 
 
 
-origin_state_id() -> Unsigned32()
+origin_state_id() -> &dict_Unsigned32;
 Returns a reasonable Origin-State-Id.
 
 

@@ -1299,7 +1236,7 @@ outgoing messages.

 
 

 The value returned is the number of seconds since 19680120T031408Z,
-the first value that can be encoded as a Diameter Time(),
+the first value that can be encoded as a Diameter &dict_Time;,
 at the time the diameter application was started.

 
 
@@ -1312,11 +1249,11 @@ at the time the diameter application was started.

 remove_transport(SvcName, Pred) -> ok | {error, Reason}
 Remove previously added transports.
 
-SvcName = service_name()
-Pred = Fun | MFA | transport_ref() | list() | true | false
+SvcName = &service_name;
+Pred = Fun | MFA | &transport_ref; | list() | true | false
 
-Fun = fun((transport_ref(), connect|listen, list()) -> boolean())
-    | fun((transport_ref(), list()) -> boolean())
+Fun = fun((&transport_ref;, connect|listen, list()) -> boolean())
+    | fun((&transport_ref;, list()) -> boolean())
     | fun((list()) -> boolean())
 MFA = {atom(), atom(), list()}
 Reason = term()
@@ -1329,8 +1266,7 @@ Remove previously added transports.

 Pred determines which transports to remove.
 An arity-3-valued Pred removes all transports for which
 Pred(Ref, Type, Opts) returns true, where Type and
-Opts are as passed to add_transport/2 and Ref is
+Opts are as passed to &add_transport; and Ref is
 as returned by it.
 The remaining forms are equivalent to an arity-3 fun as follows.

 
@@ -1348,8 +1284,7 @@ Pred = {M,F,A}:  fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end
 Removing a transport causes the corresponding transport processes to
 be terminated.
 Whether or not a DPR message is sent to a peer is
-controlled by
-value of disconnect_cb
+controlled by value of &disconnect_cb;
 configured on the transport.

 
 
@@ -1362,7 +1297,7 @@ configured on the transport.

 service_info(SvcName, Info) -> term()
 Return information about a started service.
 
-SvcName = service_name()
+SvcName = &service_name;
 Info = Item | [Info]
 Item = atom()
 
@@ -1393,15 +1328,13 @@ returned.

 'Firmware-Revision'
 
 

-Return a capability value as configured with start_service/2.

+Return a capability value as configured with &start_service;.

 
 
 applications
 
 

-Return the list of applications as configured with start_service/2.
+Return the list of applications as configured with &start_service;.
 

 
 
@@ -1409,16 +1342,14 @@ marker="#start_service">start_service/2.
 
 

 Return a tagged list of all capabilities values as configured with
-start_service/2.

+&start_service;.

 
 
 transport
 
 

 Return a list containing one entry for each of the service's transport
-as configured with add_transport/2.
+as configured with &add_transport;.
 Each entry is a tagged list containing both configuration and
 information about established peer connections.
 An example return value with for a client service with Origin-Host
@@ -1473,20 +1404,15 @@ An example return value with for a client service with Origin-Host

-Here ref is a transport_ref() and options -the corresponding transport_opt() list passed to add_transport/2. +Here ref is a &transport_ref; and options +the corresponding &transport_opt; list passed to +&add_transport;. The watchdog entry shows the state of a connection's RFC 3539 watchdog state machine. -The peer entry identifies the diameter_app:peer_ref() for -which there will have been peer_up callbacks for the +The peer entry identifies the &app_peer_ref; for +which there will have been &app_peer_up; callbacks for the Diameter applications identified by the apps entry, -common being the application_alias(). +common being the &application_alias;. The caps entry identifies the capabilities sent by the local node and received from the peer during capabilities exchange. The port entry displays socket-level information about the @@ -1505,8 +1431,8 @@ during the lifetime of the transport configuration.

A listening transport presents its information slightly differently -since there may be multiple accepted connections for the same transport_ref(). +since there may be multiple accepted connections for the same +&transport_ref;. The transport info returned by a server with a single client connection might look as follows.

@@ -1633,23 +1559,20 @@ contrast to transport info.

Return a {{Counter, Ref}, non_neg_integer()} list of counter values. -Ref can be either a transport_ref() -or a diameter_app:peer_ref(). +Ref can be either a &transport_ref; +or a &app_peer_ref;. Entries for the latter are folded into corresponding entries for the former as peer connections go down. -Entries for both are removed at remove_transport/2. +Entries for both are removed at &remove_transport;. The Diameter-level statistics returned by transport and connections info are based upon these entries.

 -diameter_app:peer_ref() +&app_peer_ref;

Return transport configuration associated with a single peer, as -passed to add_transport/2. +passed to &add_transport;. The returned list is empty if the peer is unknown. Otherwise it contains the ref, type and options tuples as in transport and connections info above. @@ -1677,7 +1600,7 @@ For example:

services() -> [SvcName] Return the list of started services. -SvcName = service_name() +SvcName = &service_name;

@@ -1690,10 +1613,10 @@ Return the list of started services.

-session_id(Ident) -> OctetString() +session_id(Ident) -> &dict_OctetString; Return a value for a Session-Id AVP. -Ident = DiameterIdentity() +Ident = &dict_DiameterIdentity;

@@ -1730,8 +1653,8 @@ file, not by calling start/0 explicitly.

start_service(SvcName, Options) -> ok | {error, Reason} Start a Diameter service. -SvcName = service_name() -Options = [service_opt()] +SvcName = &service_name; +Options = [&service_opt;] Reason = term() @@ -1741,8 +1664,7 @@ Start a diameter service.

A service defines a locally-implemented Diameter node, specifying the capabilities to be advertised during capabilities exchange. -Transports are added to a service using add_transport/2. +Transports are added to a service using &add_transport;.

@@ -1777,7 +1699,7 @@ Stop the diameter application.

stop_service(SvcName) -> ok | {error, Reason} Stop a Diameter service. -SvcName = service_name() +SvcName = &service_name; Reason = term() @@ -1787,13 +1709,12 @@ Stop a diameter service.

Stopping a service causes all associated transport connections to be broken. -A DPR message with be sent as in the case of remove_transport/2.

+A DPR message with be sent as in the case of &remove_transport;.

-Stopping a transport does not remove any associated transports: -remove_transport/2 must +Stopping a service does not remove any associated transports: +&remove_transport; must be called to remove transport configuration.

 @@ -1807,12 +1728,11 @@ be called to remove transport configuration.

subscribe(SvcName) -> true Subscribe to event messages. -SvcName = service_name() +SvcName = &service_name;

-Subscribe to service_event() messages from +Subscribe to &service_event; messages from a service.

@@ -1831,7 +1751,7 @@ reception of all related events.

unsubscribe(SvcName) -> true Unsubscribe to event messages. -SvcName = service_name() +SvcName = &service_name;

@@ -1848,9 +1768,7 @@ Unsubscribe to event messages from a service.

SEE ALSO

-diameter_app(3), -diameter_transport(3), -diameter_dict(4)

+&man_app;, &man_transport;, &man_dict;

diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index 290b8a3984..c0aa2518af 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -1,5 +1,8 @@ - + + %ents; +]>
@@ -41,15 +44,13 @@ Callback module of a Diameter application.

-A diameter service as started by diameter:start_service/2 +A diameter service as started by &mod_start_service; configures one of more Diameter applications, each of whose configuration specifies a callback that handles messages specific to the application. The messages and AVPs of the application are defined in a dictionary file whose format is documented in -diameter_dict(4) -while the callback module is documented here. +&man_dict; while the callback module is documented here. The callback module implements the Diameter application-specific functionality of a service.

@@ -60,26 +61,24 @@ The functions themselves are of three distinct flavours:

-peer_up/3 and -peer_down/3 signal the +&peer_up; and &peer_down; signal the attainment or loss of connectivity with a Diameter peer.

-pick_peer/4, -prepare_request/3, -prepare_retransmit/3, -handle_answer/4 -and handle_error/4 are (or may -be) called as a consequence of a call to diameter:call/4 to send an outgoing +&pick_peer;, +&prepare_request;, +&prepare_retransmit;, +&handle_answer; +and &handle_error; are (or may be) called as a consequence of a call +to &mod_call; to send an outgoing Diameter request message.

-handle_request/3 +&handle_request; is called in response to an incoming Diameter request message.

 @@ -92,10 +91,9 @@ is called in response to an incoming Diameter request message.

The arities given for the the callback functions here assume no extra arguments. All functions will also be passed any extra arguments configured with -the callback module itself when calling diameter:start_service/2 +the callback module itself when calling &mod_start_service; and, for the call-specific callbacks, any extra arguments passed to -diameter:call/4.

+&mod_call;.

@@ -128,7 +126,7 @@ mandatory values as the bare value.

The representation of a Diameter message as passed to -diameter:call/4. +&mod_call;. The record representation is as outlined in diameter_dict(4): @@ -145,7 +143,7 @@ whose head is a #diameter_header{} record and whose tail is a list of #diameter_avp{} records. This representation is used by diameter itself when relaying requests as directed by the return value of a -handle_request/3 +&handle_request; callback. It differs from the other other two in that it bypasses the checks for messages that do not agree with their definitions in the dictionary in @@ -174,9 +172,7 @@ A term identifying a transport connection with a Diameter peer.

-peer() = - {peer_ref(), - capabilities()} +peer() = {&peer_ref;, &capabilities;}

A tuple representing a Diameter peer connection.

@@ -188,13 +184,9 @@ A tuple representing a Diameter peer connection.

The state maintained by the application callback functions -peer_up/3, -peer_down/3 and (optionally) -pick_peer/4. +&peer_up;, &peer_down; and (optionally) &pick_peer;. The initial state is configured in the call to -diameter:start_service/2 -that configures the application on a service. +&mod_start_service; that configures the application on a service. Callback functions returning a state are evaluated in a common service-specific process while those not returning state are evaluated in a request-specific @@ -215,9 +207,9 @@ process.

Mod:peer_up(SvcName, Peer, State) -> NewState Invoked when a transport connection has been established -SvcName = diameter:service_name() -Peer = peer() -State = NewState = state() +SvcName = &mod_service_name; +Peer = &peer; +State = NewState = &state;

@@ -238,11 +230,8 @@ new peer_ref().

There is no requirement that a callback return before incoming -requests are received: handle_request/3 callbacks must be -handled independently of peer_up/3 and peer_down/3.

+requests are received: &handle_request; callbacks must be +handled independently of &peer_up; and &peer_down;.

 @@ -253,19 +242,17 @@ marker="#peer_down">peer_down/3.

Mod:peer_down(SvcName, Peer, State) -> NewState Invoked when a transport connection has been lost. -SvcName = diameter:service_name() -Peer = peer() -State = NewState = state() +SvcName = &mod_service_name; +Peer = &peer; +State = NewState = &state;

Invoked to signal that a peer connection is no longer available -following a previous call to peer_up/3. +following a previous call to &peer_up;. In particular, that the RFC 3539 watchdog state machine for the connection has left state OKAY and the peer will no longer be a -candidate in pick_peer() -callbacks.

+candidate in &pick_peer; callbacks.

 @@ -276,16 +263,15 @@ callbacks.

-> Selection | false Select a target peer for an outgoing request. -Candidates = [peer()] -SvcName = diameter:service_name() -State = NewState = state() +Candidates = [&peer;] +SvcName = &mod_service_name; +State = NewState = &state; Selection = {ok, Peer} | {Peer, NewState} -Peer = peer() | false +Peer = &peer; | false

-Invoked as a consequence of a call to diameter:call/4 to select a destination +Invoked as a consequence of a call to &mod_call; to select a destination peer for an outgoing request. The return value indicates the selected peer.

@@ -293,39 +279,34 @@ The return value indicates the selected peer.

The candidate list contains only those peers that have advertised support for the Diameter application in question during capabilities exchange, that have not be excluded by a filter option in -the call to diameter:call/4 +the call to &mod_call; and whose watchdog state machine is in the OKAY state. 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 {filter, {all, [host, realm]}} -option to diameter:call/4) +option to &mod_call;) will be placed at the head of the list.

A callback that returns a peer() will be followed by a -prepare_request/3 +&prepare_request; callback and, if the latter indicates that the request should be sent, -by either handle_answer/4 -or handle_error/4 depending +by either &handle_answer; +or &handle_error; depending on whether or not an answer message is received from the peer. -If the transport becomes unavailable after prepare_request/3 then a new pick_peer/4 callback may take place to -failover to an alternate peer, after which prepare_retransmit/3 takes the -place of prepare_request/3 in resending the +If the transport becomes unavailable after &prepare_request; then a +new &pick_peer; callback may take place to +failover to an alternate peer, after which &prepare_retransmit; takes the +place of &prepare_request; in resending the request. -There is no guarantee that a pick_peer/4 callback to select +There is no guarantee that a &pick_peer; callback to select an alternate peer will be followed by any additional callbacks since a retransmission to an alternate peer is abandoned if an answer is received from a previously selected peer.

Returning false or {false, NewState} causes {error, -no_connection} to be returned from diameter:call/4.

+no_connection} to be returned from &mod_call;.

The return values false and {false, State} (that is, @@ -335,13 +316,12 @@ The return values false and {false, State} (that is,

The return value {Peer, NewState} is only allowed if -the Diameter application in question was configured with the diameter:application_opt() -{call_mutates_state, true}. +the Diameter application in question was configured with the +&mod_application_opt; {call_mutates_state, true}. Otherwise, the State argument is always the intial value as configured on the application, not any subsequent -value returned by a peer_up/3 -or peer_down/3 callback.

+value returned by a &peer_up; +or &peer_down; callback.

@@ -353,15 +333,13 @@ or peer_down/3 callback.

Mod:prepare_request(Packet, SvcName, Peer) -> Action Return a request for encoding and transport. -Packet = packet() -SvcName = diameter:service_name() -Peer = peer() +Packet = &packet; +SvcName = &mod_service_name; +Peer = &peer; Action = Send | Discard | {eval_packet, Action, PostF} -Send = {send, packet() - | message()} +Send = {send, &packet; | &message;} Discard = {discard, Reason} | discard -PostF = - diameter:evaluable()} +PostF = &mod_evaluable;}

@@ -371,16 +349,15 @@ to modify the outgoing request. Many implementations may simply want to return {send, Packet}

-A returned packet() should set the +A returned &packet; should set the request to be encoded in its msg field and can set the transport_data field in order to pass information to the transport process. -Extra arguments passed to diameter:call/4 can be used to +Extra arguments passed to &mod_call; can be used to communicate transport (or any other) data to the callback.

-A returned packet() can set +A returned &packet; can set the header field to a #diameter_header{} to specify values that should be preserved in the outgoing request, values otherwise being those in @@ -396,8 +373,7 @@ The return value is ignored.

Returning {discard, Reason} causes the request to be aborted -and the diameter:call/4 for which the +and the &mod_call; for which the callback has taken place to return {error, Reason}. Returning discard is equivalent to returning {discard, discarded}.

@@ -410,30 +386,25 @@ discarded}.

Mod:prepare_retransmit(Packet, SvcName, Peer) -> Action Return a request for encoding and retransmission. -Packet = packet() -SvcName = diameter:service_name() -Peer = peer() +Packet = &packet; +SvcName = &mod_service_name; +Peer = &peer; Action = Send | Discard | {eval_packet, Action, PostF} -Send = {send, packet() - | message()} +Send = {send, &packet; | &message;} Discard = {discard, Reason} | discard -PostF = - diameter:evaluable()} +PostF = &mod_evaluable;}

Invoked to return a request for encoding and retransmission. -Has the same role as prepare_request/3 in the case that +Has the same role as &prepare_request; in the case that a peer connection is lost an an alternate peer selected but the -argument packet() is as returned -by the initial prepare_request/3.

+argument &packet; is as returned +by the initial &prepare_request;.

Returning {discard, Reason} causes the request to be aborted -and a handle_error/4 callback to +and a &handle_error; callback to take place with Reason as initial argument. Returning discard is equivalent to returning {discard, discarded}.

@@ -446,49 +417,41 @@ discarded}.

Mod:handle_answer(Packet, Request, SvcName, Peer) -> Result Receive an answer message from a peer. -Packet = packet() -Request = message() -SvcName = diameter:service_name() -Peer = peer() +Packet = &packet; +Request = &message; +SvcName = &mod_service_name; +Peer = &peer; Result = term()

Invoked when an answer message is received from a peer. -The return value is returned from diameter:call/4 unless the +The return value is returned from &mod_call; unless the detach option was specified.

The decoded answer record and undecoded binary are in the msg and bin fields of the argument -packet() respectively. +&packet; respectively. Request is the outgoing request message as was returned from -prepare_request/3 or -prepare_retransmit/3.

+&prepare_request; or &prepare_retransmit;.

-For any given call to diameter:call/4 there is at most one -handle_answer/4 callback: any +For any given call to &mod_call; there is at most one +&handle_answer; callback: any duplicate answer (due to retransmission or otherwise) is discarded. -Similarly, only one of handle_answer/4 or -handle_error/4 is -called.

+Similarly, only one of &handle_answer; or +&handle_error; is called.

By default, an incoming answer message that cannot be successfully decoded causes the request process to fail, causing -diameter:call/4 +&mod_call; to return {error, failure} unless the detach option was specified. -In particular, there is no handle_error/4 callback in this +In particular, there is no &handle_error; callback in this case. -The diameter:application_opt() +The &mod_application_opt; answer_errors can be set to change this behaviour.

@@ -500,23 +463,21 @@ marker="diameter#application_opt">diameter:application_opt() Return an error from a outgoing request. Reason = timeout | failover | term() -Request = message() -SvcName = diameter:service_name() -Peer = peer() +Request = &message; +SvcName = &mod_service_name; +Peer = &peer; Result = term()

Invoked when an error occurs before an answer message is received in response to an outgoing request. -The return value is returned from diameter:call/4 unless the +The return value is returned from &mod_call; unless the detach option was specified.

Reason timeout indicates that an answer message has not been -received within the time specified with the corresponding diameter:call_opt(). +received within the time specified with the corresponding &mod_call_opt;. Reason failover indicates that the transport connection to the peer to which the request has been sent has become unavailable and that not alternate peer was @@ -530,25 +491,23 @@ not selected.

Mod:handle_request(Packet, SvcName, Peer) -> Action Receive an incoming request. -Packet = packet() +Packet = &packet; SvcName = term() -Peer = peer() +Peer = &peer; Action = Reply | {relay, [Opt]} | discard | {eval|eval_packet, Action, PostF} -Reply = {reply, packet() - | message()} +Reply = {reply, &packet; | &message;} | {protocol_error, 3000..3999} -Opt = diameter:call_opt() -PostF = diameter:evaluable() +Opt = &mod_call_opt; +PostF = &mod_evaluable;

Invoked when a request message is received from a peer. The application in which the callback takes place (that is, the -callback module as configured with diameter:start_service/2) +callback module as configured with &mod_start_service;) is determined by the Application Identifier in the header of the incoming request message, the selected module being the one whose corresponding

-The argument packet() has the following signature.

+The argument &packet; has the following signature.

 #diameter_packet{header = #diameter_header{},
                  avps   = [#diameter_avp{}],
                  msg    = record() | undefined,
-                 errors = [Unsigned32() | {Unsigned32(), #diameter_avp{}}],
+                 errors = [&dict_Unsigned32; | {&dict_Unsigned32;, #diameter_avp{}}],
                  bin    = binary(),
                  transport_data = term()}
@@ -580,8 +539,8 @@ The errors field specifies any Result-Code's identifying errors that were encountered in decoding the request. In this case diameter will set both Result-Code and Failed-AVP AVP's in a returned -answer message() before sending it to the peer: -the returned message() need only set any other required AVP's. +answer &message; before sending it to the peer: +the returned &message; need only set any other required AVP's. Note that the errors detected by diameter are all of the 5xxx series (Permanent Failures). The errors list is empty if the request has been received in @@ -591,21 +550,19 @@ the relay application.

The transport_data field contains an arbitrary term passed into diameter from the transport module in question, or the atom undefined if the transport specified no data. -The term is preserved if a message() is returned but must be set -explicitly in a returned packet().

+The term is preserved if a &message; is returned but must be set +explicitly in a returned &packet;.

The semantics of each of the possible return values are as follows.

-{reply, packet() - | message()} +{reply, &packet; | &message;}

Send the specified answer message to the peer. -In the case of a packet(), the +In the case of a &packet;, the message to be sent must be set in the msg field and the header field can be set to a #diameter_header{} to specify values that should be @@ -640,23 +597,22 @@ Relay a request to another peer in the role of a Diameter relay agent. If a routing loop is detected then the request is answered with 3005 (DIAMETER_LOOP_DETECTED). Otherwise a Route-Record AVP (containing the sending peer's Origin-Host) is -added to the request and pick_peer/4 -and subsequent callbacks take place just as if diameter:call/4 had been called +added to the request and &pick_peer; +and subsequent callbacks take place just as if &mod_call; had been called explicitly. The End-to-End Identifier of the incoming request is preserved in the header of the relayed request.

The returned Opts should not specify detach. -A subsequent handle_answer/4 +A subsequent &handle_answer; callback for the relayed request must return its first argument, the #diameter_packet{} record containing the answer message. Note that the extra option can be specified to supply arguments that can distinguish the relay case from others if so desired. Any other return value (for example, from a -handle_error/4 callback) +&handle_error; callback) causes the request to be answered with 3002 (DIAMETER_UNABLE_TO_DELIVER).

 diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameter_compile.xml index 7a6ca48798..5ca8126b83 100644 --- a/lib/diameter/doc/src/diameter_compile.xml +++ b/lib/diameter/doc/src/diameter_compile.xml @@ -1,5 +1,8 @@ - + + %ents; +]>
@@ -122,7 +125,7 @@ Returns 0 on success, non-zero on failure.

SEE ALSO

-diameter_dict(4)

+&man_dict;

diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 9d6a6a8f38..4956ff4be0 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -1,5 +1,8 @@ - + + %ents; +]>
@@ -40,8 +43,7 @@ under the License.

-A diameter service as configured with diameter:start_service/2 +A diameter service as configured with &mod_start_service; specifies one or more supported Diameter applications. Each Diameter application specifies a dictionary module that knows how to encode and decode its messages and AVPs. @@ -58,8 +60,7 @@ resulting dictionaries modules on a service.

The codec generation also results in a hrl file that defines records for the messages and grouped AVPs defined for the application, these records being what a user of the diameter application sends and receives. -(Modulo other available formats as discussed in diameter_app(3).) +(Modulo other available formats as discussed in &man_app;.) These records and the underlying Erlang data types corresponding to Diameter data formats are discussed in MESSAGE RECORDS and The data formats defined in sections 4.2 ("Basic AVP Data Formats") and 4.3 ("Derived AVP Data Formats") of RFC 3588 are encoded as values of the types defined here. -Values are passed to diameter:call/4 +Values are passed to &mod_call; in a request record when sending a request, returned in a resulting -answer record and passed to a handle_request +answer record and passed to a &app_handle_request; callback upon reception of an incoming request.

@@ -639,9 +638,7 @@ Values of these types are not currently parsed by diameter.

SEE ALSO

-diameterc(1), -diameter(3), -diameter_app(3)

+&man_compile;, &man_main;, &man_app;

diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml index 709b17c0d2..053c305978 100644 --- a/lib/diameter/doc/src/diameter_sctp.xml +++ b/lib/diameter/doc/src/diameter_sctp.xml @@ -1,5 +1,8 @@ - + + %ents; +]>
@@ -41,10 +44,9 @@ under the License. This module implements diameter transport over SCTP using gen_sctp. It can be specified as the value of a transport_module option to -diameter:add_transport/2 +&mod_add_transport; and implements the behaviour documented in -diameter_transport(3).

+&man_transport;.

@@ -59,7 +61,7 @@ and implements the behaviour documented in Start a transport process. Type = connect | accept -Ref = diameter:transport_ref() +Ref = &mod_transport_ref; Svc = #diameter_service{} Opt = {raddr, inet:ip_address()} | {rport, integer()} | term() Pid = pid() @@ -69,8 +71,7 @@ and implements the behaviour documented in

-The start function required by diameter_transport(3).

+The start function required by &man_transport;.

The only diameter_sctp-specific argument is the options list. @@ -115,16 +116,13 @@ diameter_sctp uses the transport_data field of the #diameter_packet{} 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 {stream, Id} -on an inbound message passed to a handle_request or handle_answer callback. +on an inbound message passed to a &app_handle_request; or +&app_handle_answer; callback. For an outbound message, either undefined (explicitly or by receiving the outbound message as a binary()) or a tuple -should be set in the return value of handle_request +should be set in the return value of &app_handle_request; (typically by retaining the value passed into this function) -or prepare_request. +or &app_prepare_request;. The value undefined uses a "next outbound stream" id and increments this modulo the total number outbound streams. That is, successive values of undefined cycle through all @@ -145,7 +143,8 @@ outbound streams.

SEE ALSO

-diameter_transport(3), +&man_main;, +&man_transport;, gen_sctp(3), inet(3)

diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml index 3ffcebfd90..1d4196ed61 100644 --- a/lib/diameter/doc/src/diameter_tcp.xml +++ b/lib/diameter/doc/src/diameter_tcp.xml @@ -1,5 +1,8 @@ - + + %ents; +]>
@@ -41,10 +44,9 @@ under the License. This module implements diameter transport over TCP using gen_tcp. It can be specified as the value of a transport_module option to -diameter:add_transport/2 +&mod_add_transport; and implements the behaviour documented in -diameter_transport(3). +&man_transport;. TLS security is supported, both as an upgrade following capabilities exchange as specified by RFC 3588 and at connection establishment as in the current draft standard.

@@ -66,7 +68,7 @@ before configuring TLS capability on diameter transports.

Start a transport process. Type = connect | accept -Ref = diameter:transport_ref() +Ref = &mod_transport_ref; Svc = #diameter_service{} Opt = OwnOpt | SslOpt | TcpOpt Pid = pid() @@ -81,8 +83,7 @@ before configuring TLS capability on diameter transports.

-The start function required by diameter_transport(3).

+The start function required by &man_transport;.

The only diameter_tcp-specific argument is the options list. @@ -115,10 +116,8 @@ Note that the option ip specifies the local address.

An ssl_options list must be specified if and only if the transport in question has set Inband-Security-Id to 1 (TLS), as -specified to either start_service/2 or -add_transport/2, +specified to either &mod_start_service; or +&mod_add_transport;, so that the transport process will receive notification of whether or not to commence with a TLS handshake following capabilities exchange. @@ -149,8 +148,8 @@ The returned local address list has length one.

SEE ALSO

-diameter(3), -diameter_transport(3), +&man_main;, +&man_transport;, gen_tcp(3), inet(3), ssl(3)

diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index 0c8b41397a..a06d8a348b 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -1,5 +1,8 @@ - + + %ents; +]>
@@ -38,8 +41,7 @@ under the License.

-A module specified as a transport_module to diameter:add_transport/2 +A module specified as a transport_module to &mod_add_transport; must implement the interface documented here. The interface consists of a function with which diameter starts a transport process and a message interface with which @@ -59,7 +61,7 @@ parent).

Start a transport process. Type = connect | accept -Ref = diameter:transport_ref() +Ref = &mod_transport_ref; Svc = #diameter_service{} Config = term() Pid = pid() @@ -69,8 +71,7 @@ parent).

Start a transport process. -Called by diameter as a consequence of a call to diameter:add_transport/2 in +Called by diameter as a consequence of a call to &mod_add_transport; in order to establish or accept a transport connection respectively. A transport process maintains a connection with a single remote peer.

@@ -82,22 +83,18 @@ In the latter case, transport processes are started as required to accept connections from multiple peers.

-Ref is the value that was returned from the call to diameter:add_transport/2 +Ref is the value that was returned from the call to &mod_add_transport; that has lead to starting of a transport process.

-Svc contains the capabilities passed to diameter:start_service/2 and -diameter:add_transport/2, +Svc contains the capabilities passed to &mod_start_service; and +&mod_add_transport;, values passed to the latter overriding those passed to the former.

Config is as passed in transport_config tuple in the -diameter:transport_opt() -list passed to diameter:add_transport/2.

+&mod_transport_opt; +list passed to &mod_add_transport;.

The start function should use the Host-IP-Address list and/or @@ -245,8 +242,7 @@ A transport must exit if a handshake is not successful.

SEE ALSO

-diameter_tcp(3), -diameter_sctp(3)

+&man_tcp;, &man_sctp;

-- cgit v1.2.3 From febfe74f6a32c04756c2c12de53136e75f813e3b Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 16 Nov 2012 03:48:41 +0100 Subject: Remove superfluous function markers --- lib/diameter/doc/src/diameter.ent | 58 +++++++++++++++++------------------ lib/diameter/doc/src/diameter.xml | 15 +-------- lib/diameter/doc/src/diameter_app.xml | 7 ----- 3 files changed, 30 insertions(+), 50 deletions(-) (limited to 'lib/diameter/doc') diff --git a/lib/diameter/doc/src/diameter.ent b/lib/diameter/doc/src/diameter.ent index 81f1b01239..fbfbe817a9 100644 --- a/lib/diameter/doc/src/diameter.ent +++ b/lib/diameter/doc/src/diameter.ent @@ -23,23 +23,23 @@ add_transport/2'> + 'add_transport/2'> call/4'> + 'call/4'> origin_state_id/0'> + 'origin_state_id/0'> remove_transport/2'> + 'remove_transport/2'> service_info/2'> + 'service_info/2'> services/0'> + 'services/0'> diameter:start_service/2'> + 'start_service/2'> stop_service/1'> + 'stop_service/1'> subscribe/1'> + 'subscribe/1'> application_alias()'> @@ -84,13 +84,13 @@ 'watchdog_timer'> diameter:add_transport/2'> + 'diameter:add_transport/2'> diameter:call/4'> + 'diameter:call/4'> diameter:remove_transport/2'> + 'diameter:remove_transport/2'> diameter:start_service/2'> + 'diameter:start_service/2'> diameter:call_opt()'> @@ -108,21 +108,21 @@ handle_answer/4'> + 'handle_answer/4'> handle_request/3'> + 'handle_request/3'> handle_error/4'> + 'handle_error/4'> peer_down/3'> + 'peer_down/3'> peer_up/3'> + 'peer_up/3'> pick_peer/4'> + 'pick_peer/4'> prepare_retransmit/3'> + 'prepare_retransmit/3'> prepare_request/3'> + 'prepare_request/3'> capabilities()'> @@ -138,19 +138,19 @@ 'state()'> handle_answer/4'> + 'handle_answer/4'> handle_request/3'> + 'handle_request/3'> handle_error/4'> + 'handle_error/4'> peer_up/3'> + 'peer_up/3'> pick_peer/4'> + 'pick_peer/4'> prepare_retransmit/3'> + 'prepare_retransmit/3'> prepare_request/3'> + 'prepare_request/3'> diameter_app:message()'> @@ -182,7 +182,7 @@ start/3'> + 'start/3'> diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 0392bd9bb7..2a2fff86a9 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -528,7 +528,7 @@ connectivity.

Note that a single up/down event for a given peer corresponds to one -peer_up/peer_down +peer_up/peer_down callback for each of the Diameter applications negotiated during capablilities exchange. That is, the event communicates connectivity with the @@ -1063,7 +1063,6 @@ identifies the configuration.

- @@ -1113,7 +1112,6 @@ been configured: a service can be started after configuring its transports.

- @@ -1220,7 +1218,6 @@ Note that {error,encode} is the only return value which guarantees that the request has not been sent over the transport connection.

- @@ -1239,7 +1236,6 @@ The value returned is the number of seconds since 19680120T031408Z, the first value that can be encoded as a Diameter &dict_Time;, at the time the diameter application was started.

- @@ -1287,7 +1283,6 @@ Whether or not a DPR message is sent to a peer is controlled by value of &disconnect_cb; configured on the transport.

- @@ -1590,7 +1585,6 @@ For example:

- @@ -1606,7 +1600,6 @@ For example:

Return the list of started services.

- @@ -1627,7 +1620,6 @@ The value has the form required by section 8.8 of RFC 3588. Ident should be the Origin-Host of the peer from which the message containing the returned value will be sent.

- @@ -1644,7 +1636,6 @@ The diameter application must be started before starting a service. In a production system this is typically accomplished by a boot file, not by calling start/0 explicitly.

- @@ -1675,7 +1666,6 @@ capabilities and restrict its supported Diameter applications so necessarily the case.

- @@ -1690,7 +1680,6 @@ Stop the diameter application.

- @@ -1718,7 +1707,6 @@ Stopping a service does not remove any associated transports: be called to remove transport configuration.

- @@ -1741,7 +1729,6 @@ that does not yet exist. Doing so before adding transports is required to guarantee the reception of all related events.

- diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index c0aa2518af..826b28aaac 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -234,7 +234,6 @@ requests are received: &handle_request; callbacks must be handled independently of &peer_up; and &peer_down;.

- @@ -254,7 +253,6 @@ In particular, that the RFC 3539 watchdog state machine for the connection has left state OKAY and the peer will no longer be a candidate in &pick_peer; callbacks.

- @@ -324,7 +322,6 @@ value returned by a &peer_up; or &peer_down; callback.

- @@ -378,7 +375,6 @@ callback has taken place to return {error, Reason}. Returning discard is equivalent to returning {discard, discarded}.

- @@ -409,7 +405,6 @@ take place with Reason as initial argument. Returning discard is equivalent to returning {discard, discarded}.

- @@ -454,7 +449,6 @@ case. The &mod_application_opt; answer_errors can be set to change this behaviour.

- @@ -483,7 +477,6 @@ that the transport connection to the peer to which the request has been sent has become unavailable and that not alternate peer was not selected.

- -- cgit v1.2.3 From 0295e6350bc344ce443c80e7251c6e5fc48159ba Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 16 Nov 2012 11:12:07 +0100 Subject: Generate intra-document references --- lib/diameter/doc/src/.gitignore | 1 + lib/diameter/doc/src/Makefile | 8 +- lib/diameter/doc/src/diameter.ent | 196 ---------------------------- lib/diameter/doc/src/diameter.xml | 6 +- lib/diameter/doc/src/diameter_app.xml | 6 +- lib/diameter/doc/src/diameter_compile.xml | 6 +- lib/diameter/doc/src/diameter_dict.xml | 6 +- lib/diameter/doc/src/diameter_sctp.xml | 6 +- lib/diameter/doc/src/diameter_tcp.xml | 6 +- lib/diameter/doc/src/diameter_transport.xml | 6 +- lib/diameter/doc/src/files.mk | 3 - lib/diameter/doc/src/seealso.ent | 113 ++++++++++++++++ lib/diameter/doc/src/seehere.sed | 35 +++++ 13 files changed, 182 insertions(+), 216 deletions(-) delete mode 100644 lib/diameter/doc/src/diameter.ent create mode 100644 lib/diameter/doc/src/seealso.ent create mode 100644 lib/diameter/doc/src/seehere.sed (limited to 'lib/diameter/doc') diff --git a/lib/diameter/doc/src/.gitignore b/lib/diameter/doc/src/.gitignore index feeb378fd8..5776e1cc76 100644 --- a/lib/diameter/doc/src/.gitignore +++ b/lib/diameter/doc/src/.gitignore @@ -1,2 +1,3 @@ /depend.mk +/seehere.ent diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile index 6e91181c6c..8ad38ba0d5 100644 --- a/lib/diameter/doc/src/Makefile +++ b/lib/diameter/doc/src/Makefile @@ -35,7 +35,7 @@ XML_REF_FILES = $(XML_REF1_FILES) $(XML_REF3_FILES) $(XML_REF4_FILES) XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) \ $(XML_REF_FILES) \ $(XML_PART_FILES) $(XML_CHAPTER_FILES) \ - $(XML_ENTITY_FILES) + seealso.ent INTERNAL_HTML_FILES = $(TECHNICAL_DESCR_FILES:%.xml=$(HTMLDIR)/%.html) @@ -94,7 +94,7 @@ html: gifs $(HTML_REF_MAN_FILE) clean clean_docs: clean_pdf clean_html clean_man rm -f errs core *~ - rm -f depend.mk + rm -f depend.mk seehere.ent clean_pdf: rm -f $(PDFDIR)/* @@ -171,7 +171,9 @@ release_docs_spec: $(LOCAL)docs release_spec: -depend.mk: depend.sed $(XML_REF_FILES) $(XML_CHAPTER_FILES) Makefile +depend.mk: depend.sed Makefile seealso.ent \ + $(XML_REF_FILES) $(XML_CHAPTER_FILES) + sed -f seehere.sed seealso.ent > seehere.ent (for f in $(XML_REF_FILES) $(XML_CHAPTER_FILES); do \ sed -f $< $$f | sed "s@%FILE%@`basename $$f .xml`@g"; \ done) \ diff --git a/lib/diameter/doc/src/diameter.ent b/lib/diameter/doc/src/diameter.ent deleted file mode 100644 index fbfbe817a9..0000000000 --- a/lib/diameter/doc/src/diameter.ent +++ /dev/null @@ -1,196 +0,0 @@ - - - - - - -add_transport/2'> -call/4'> -origin_state_id/0'> -remove_transport/2'> -service_info/2'> -services/0'> -start_service/2'> -stop_service/1'> -subscribe/1'> - -application_alias()'> -application_module()'> -application_opt()'> -call_opt()'> -capability()'> -evaluable()'> -peer_filter()'> -service_event()'> -service_name()'> -service_opt()'> -transport_opt()'> -transport_ref()'> - -application'> -capabilities_cb'> -capx_timeout'> -disconnect_cb'> -transport_config'> -transport_module'> -reconnect_timer'> -watchdog_timer'> - -diameter:add_transport/2'> -diameter:call/4'> -diameter:remove_transport/2'> -diameter:start_service/2'> - -diameter:call_opt()'> -diameter:application_opt()'> -diameter:evaluable()'> -diameter:service_name()'> -diameter:transport_opt()'> -diameter:transport_ref()'> - - - -handle_answer/4'> -handle_request/3'> -handle_error/4'> -peer_down/3'> -peer_up/3'> -pick_peer/4'> -prepare_retransmit/3'> -prepare_request/3'> - -capabilities()'> -message()'> -packet()'> -peer()'> -peer_ref()'> -state()'> - -handle_answer/4'> -handle_request/3'> -handle_error/4'> -peer_up/3'> -pick_peer/4'> -prepare_retransmit/3'> -prepare_request/3'> - -diameter_app:message()'> -diameter_app:peer()'> -diameter_app:peer_ref()'> - - - -diameter_dict(4)'> - -Address()'> -DiameterIdentity()'> -Grouped()'> -OctetString()'> -Time()'> -UTF8String()'> -Unsigned32()'> - - - -start/3'> - - - -diameterc(1)'> -diameter(3)'> -diameter_app(3)'> -diameter_dict(4)'> -diameter_transport(3)'> -diameter_sctp(3)'> -diameter_tcp(3)'> diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 2a2fff86a9..b47ca56b10 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -1,7 +1,9 @@ - %ents; + + + %also; + %here; ]> diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index 826b28aaac..304c69ebda 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -1,7 +1,9 @@ - %ents; + + + %also; + %here; ]> diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameter_compile.xml index 5ca8126b83..eb6de80c11 100644 --- a/lib/diameter/doc/src/diameter_compile.xml +++ b/lib/diameter/doc/src/diameter_compile.xml @@ -1,7 +1,9 @@ - %ents; + + + %also; + %here; ]> diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 4956ff4be0..4a6cccc276 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -1,7 +1,9 @@ - %ents; + + + %also; + %here; ]> diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml index 053c305978..a023a9bc08 100644 --- a/lib/diameter/doc/src/diameter_sctp.xml +++ b/lib/diameter/doc/src/diameter_sctp.xml @@ -1,7 +1,9 @@ - %ents; + + + %also; + %here; ]> diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml index 1d4196ed61..be8a938115 100644 --- a/lib/diameter/doc/src/diameter_tcp.xml +++ b/lib/diameter/doc/src/diameter_tcp.xml @@ -1,7 +1,9 @@ - %ents; + + + %also; + %here; ]> diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index a06d8a348b..0507af63a8 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -1,7 +1,9 @@ - %ents; + + + %also; + %here; ]> diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk index 48f604c98f..89ec1031e6 100644 --- a/lib/diameter/doc/src/files.mk +++ b/lib/diameter/doc/src/files.mk @@ -17,9 +17,6 @@ # # %CopyrightEnd% -XML_ENTITY_FILES = \ - diameter.ent - XML_APPLICATION_FILES = \ ref_man.xml diff --git a/lib/diameter/doc/src/seealso.ent b/lib/diameter/doc/src/seealso.ent new file mode 100644 index 0000000000..a0143fd6d6 --- /dev/null +++ b/lib/diameter/doc/src/seealso.ent @@ -0,0 +1,113 @@ + + + + + + + + +diameter:add_transport/2'> +diameter:call/4'> +diameter:origin_state_id/0'> +diameter:remove_transport/2'> +diameter:service_info/2'> +diameter:services/0'> +diameter:start_service/2'> +diameter:stop_service/1'> +diameter:subscribe/1'> + +diameter:application_alias()'> +diameter:application_module()'> +diameter:application_opt()'> +diameter:call_opt()'> +diameter:capability()'> +diameter:evaluable()'> +diameter:peer_filter()'> +diameter:service_event()'> +diameter:service_name()'> +diameter:service_opt()'> +diameter:transport_opt()'> +diameter:transport_ref()'> + +application'> +capabilities_cb'> +capx_timeout'> +disconnect_cb'> +transport_config'> +transport_module'> +reconnect_timer'> +watchdog_timer'> + + + +handle_answer/4'> +handle_request/3'> +handle_error/4'> +peer_up/3'> +peer_up/3'> +pick_peer/4'> +prepare_retransmit/3'> +prepare_request/3'> + +diameter_app:capabilities()'> +diameter_app:message()'> +diameter_app:packet()'> +diameter_app:peer()'> +diameter_app:peer_ref()'> +diameter_app:state()'> + + + +diameter_dict(4)'> + +Address()'> +DiameterIdentity()'> +Grouped()'> +OctetString()'> +Time()'> +UTF8String()'> +Unsigned32()'> + + + +start/3'> + + + +diameterc(1)'> +diameter(3)'> +diameter_app(3)'> +diameter_dict(4)'> +diameter_transport(3)'> +diameter_sctp(3)'> +diameter_tcp(3)'> diff --git a/lib/diameter/doc/src/seehere.sed b/lib/diameter/doc/src/seehere.sed new file mode 100644 index 0000000000..c62a783d40 --- /dev/null +++ b/lib/diameter/doc/src/seehere.sed @@ -0,0 +1,35 @@ +# +# %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. +# +# %CopyrightEnd% + +# +# Map entities for inter-document references to ones for +# intra-document references like this: +# +# ccc:zzz'> +# +# ===> +# +# zzz'> +# + +/[^:]*:@>@ -- cgit v1.2.3 From d4530aae03e1b8a3a47ed6693d36c9f2536df8a8 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Sun, 18 Nov 2012 19:35:07 +0100 Subject: Fix broken doc links --- lib/diameter/doc/src/diameter.xml | 2 +- lib/diameter/doc/src/notes.xml | 14 +++++++++----- lib/diameter/doc/src/seealso.ent | 1 - 3 files changed, 10 insertions(+), 7 deletions(-) (limited to 'lib/diameter/doc') diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index b47ca56b10..bc42b75c7a 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -697,7 +697,7 @@ Can be any &capability; as well as the following.

Defines a Diameter application supported by the service.

-A service must configure one &application; for each Diameter +A service must configure one tuple for each Diameter application it intends to support. For an outgoing Diameter request, the relevant &application_alias; is passed to &call;, while for an diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml index e57958ac09..aad86b966b 100644 --- a/lib/diameter/doc/src/notes.xml +++ b/lib/diameter/doc/src/notes.xml @@ -1,11 +1,17 @@ - + + + %also; + %here; +]>

2011 +2012 Ericsson AB. All Rights Reserved. @@ -395,8 +401,7 @@ Known issues or limitations:

Some agent-related functionality is not entirely complete. In particular, support for proxy agents, that advertise specific Diameter applications but otherwise relay messages in much the same -way as relay agents (for which a handle_request/3 +way as relay agents (for which a &handle_request; callback can return a relay tuple), will be completed in an upcoming release. There may also be more explicit support for redirect agents, although @@ -428,8 +433,7 @@ could likely be expanded upon.

-The function diameter:service_info/2 +The function &service_info; can be used to retrieve information about a started service (statistics, information about connected peers, etc) but this is not yet documented and both the input and output may change diff --git a/lib/diameter/doc/src/seealso.ent b/lib/diameter/doc/src/seealso.ent index a0143fd6d6..6f67630220 100644 --- a/lib/diameter/doc/src/seealso.ent +++ b/lib/diameter/doc/src/seealso.ent @@ -57,7 +57,6 @@ significant. diameter:transport_opt()'> diameter:transport_ref()'> -application'> capabilities_cb'> capx_timeout'> disconnect_cb'> -- cgit v1.2.3