1diameter(3)                Erlang Module Definition                diameter(3)
2
3
4

NAME

6       diameter - Main API of the diameter application.
7

DESCRIPTION

9       This  module  provides  the interface with which a user can implement a
10       Diameter node that sends and receives messages using the Diameter  pro‐
11       tocol as defined in RFC 6733.
12
13       Basic  usage  consists of creating a representation of a locally imple‐
14       mented Diameter node and its capabilities with start_service/2,  adding
15       transport   capability   using  add_transport/2  and  sending  Diameter
16       requests and receiving Diameter answers with call/4. Incoming  Diameter
17       requests  are  communicated  as callbacks to a diameter_app(3) callback
18       modules as specified in the service configuration.
19
20       Beware the difference between diameter (not capitalized)  and  Diameter
21       (capitalized). The former refers to the Erlang application named diame‐
22       ter whose main api is defined here, the latter to Diameter protocol  in
23       the sense of RFC 6733.
24
25       The  diameter application must be started before calling most functions
26       in this module.
27

DATA TYPES

29         Address():
30
31
32         DiameterIdentity():
33
34
35         Grouped():
36
37
38         OctetString():
39
40
41         Time():
42
43
44         Unsigned32():
45
46
47         UTF8String():
48           Types corresponding to RFC 6733 AVP Data Formats. Defined in diame‐
49           ter_dict(4).
50
51         application_alias() = term():
52           Name  identifying  a Diameter application in service configuration.
53           Passed to call/4 when sending requests defined by the application.
54
55         application_module() = Mod |  [Mod  |  ExtraArgs]  |  #diameter_call‐
56         back{}:
57
58
59         Mod = atom()
60         ExtraArgs = list()
61
62
63           Module  implementing  the  callback  interface  defined  in  diame‐
64           ter_app(3), along with any extra arguments to be appended to  those
65           documented.  Note  that  extra  arguments  specific  to an outgoing
66           request can be specified to call/4, in which  case  those  are  are
67           appended to any module-specific extra arguments.
68
69           Specifying  a  #diameter_callback{}  record allows individual func‐
70           tions to be configured in place of the usual diameter_app(3)  call‐
71           backs. See diameter_callback.erl for details.
72
73         application_opt():
74           Options  defining  a  Diameter  application.  Has one the following
75           types.
76
77           {alias, application_alias()}:
78             Unique identifier for the application in the scope  of  the  ser‐
79             vice. Defaults to the value of the dictionary option.
80
81           {dictionary, atom()}:
82             Name of an encode/decode module for the Diameter messages defined
83             by the application. These modules are generated from files  whose
84             format is documented in diameter_dict(4).
85
86           {module, application_module()}:
87             Callback module in which messages of the Diameter application are
88             handled. See  diameter_app(3)  for  the  required  interface  and
89             semantics.
90
91           {state, term()}:
92             Initial  callback  state.  The prevailing state is passed to some
93             diameter_app(3) callbacks, which can then  return  a  new  state.
94             Defaults to the value of the alias option.
95
96           {call_mutates_state, true|false}:
97             Whether  or  not  the pick_peer/4 application callback can modify
98             the application state. Defaults to false.
99
100       Warning:
101           pick_peer/4 callbacks are serialized  when  this  option  is  true,
102           which  is  a  potential  performance  bottleneck. A simple Diameter
103           client may suffer no ill effects from using  mutable  state  but  a
104           server  or  agent that responds to incoming request should probably
105           avoid it.
106
107
108           {answer_errors, callback|report|discard}:
109             Manner in which incoming answer messages containing decode errors
110             are handled.
111
112             If  callback  then errors result in a handle_answer/4 callback in
113             the same fashion as for handle_request/3,  with  errors  communi‐
114             cated in the errors field of the #diameter_packet{} passed to the
115             callback. If report then an answer containing errors is discarded
116             without a callback and a warning report is written to the log. If
117             discard then an answer containing errors  is  silently  discarded
118             without  a  callback.  In  both  the report and discard cases the
119             return value for the call/4 invocation in question  is  as  if  a
120             callback had taken place and returned {error, failure}.
121
122             Defaults to discard.
123
124           {request_errors, answer_3xxx|answer|callback}:
125             Manner in which incoming requests are handled when an error other
126             than  3007  (DIAMETER_APPLICATION_UNSUPPORTED,  which  cannot  be
127             associated with an application callback module), is detected.
128
129             If   answer_3xxx  then  requests  are  answered  without  a  han‐
130             dle_request/3 callback taking place. If  answer  then  even  5xxx
131             errors  are  answered without a callback unless the connection in
132             question has configured the RFC 3588 common dictionary  as  noted
133             below.  If callback then a handle_request/3 callback always takes
134             place and its return value determines  the  answer  sent  to  the
135             peer, if any.
136
137             Defaults to answer_3xxx.
138
139       Note:
140           Answers  sent  by  diameter  set  the E-bit in the Diameter Header.
141           Since RFC 3588 allows only 3xxx result codes in an  answer-message,
142           answer  has the same semantics as answer_3xxx when the transport in
143           question has been configured with diameter_gen_base_rfc3588 as  its
144           common  dictionary. Since RFC 6733 allows both 3xxx and 5xxx result
145           codes   in   an   answer-message,   a   transport    with    diame‐
146           ter_gen_base_rfc6733  as  its  common  dictionary  does distinguish
147           between answer_3xxx and answer.
148
149
150         call_opt():
151           Options available to  call/4  when  sending  an  outgoing  Diameter
152           request. Has one of the following types.
153
154           {extra, list()}:
155             Extra  arguments to append to callbacks to the callback module in
156             question. These are appended to any extra arguments configured on
157             the  callback  itself.  Multiple  options  append to the argument
158             list.
159
160           {filter, peer_filter()}:
161             Filter to apply to the list of available peers before passing  it
162             to the pick_peer/4 callback for the application in question. Mul‐
163             tiple options are equivalent a single all filter  on  the  corre‐
164             sponding list of filters. Defaults to none.
165
166           {peer, diameter_app:peer_ref()}:
167             Peer to which the request in question can be sent, preempting the
168             selection of peers having advertised  support  for  the  Diameter
169             application  in  question. Multiple options can be specified, and
170             their order is respected in the candidate lists passed to a  sub‐
171             sequent pick_peer/4 callback.
172
173           {timeout, Unsigned32()}:
174             Number  of  milliseconds  after which the request should timeout.
175             Defaults to 5000.
176
177           detach:
178             Cause call/4 to return ok as soon as the request in question  has
179             been  encoded,  instead  of  waiting for and returning the result
180             from a subsequent handle_answer/4 or handle_error/4 callback.
181
182           An invalid option will cause call/4 to fail.
183
184         capability():
185           AVP values sent in outgoing CER or CEA messages during capabilities
186           exchange. Can be configured both on a service and a transport, val‐
187           ues on the latter taking  precedence.  Has  one  of  the  following
188           types.
189
190           {'Origin-Host', DiameterIdentity()}:
191
192
193           {'Origin-Realm', DiameterIdentity()}:
194
195
196           {'Host-IP-Address', [Address()]}:
197             An address list is available to the start function of a transport
198             module, which can return a new list for use in the subsequent CER
199             or  CEA.  Host-IP-Address  need not be specified if the transport
200             module in question communicates an address list as  described  in
201             diameter_transport(3)
202
203           {'Vendor-Id', Unsigned32()}:
204
205
206           {'Product-Name', UTF8String()}:
207
208
209           {'Origin-State-Id', Unsigned32()}:
210             Origin-State-Id  is optional but, if configured, will be included
211             in outgoing CER/CEA and DWR/DWA messages. Setting a  value  of  0
212             (zero) is equivalent to not setting a value, as documented in RFC
213             6733. The function origin_state_id/0 can be used as to retrieve a
214             value that is computed when the diameter application is started.
215
216           {'Supported-Vendor-Id', [Unsigned32()]}:
217
218
219           {'Auth-Application-Id', [Unsigned32()]}:
220
221
222           {'Inband-Security-Id', [Unsigned32()]}:
223             Inband-Security-Id  defaults  to the empty list, which is equiva‐
224             lent to a list containing only 0 (NO_INBAND_SECURITY). If 1 (TLS)
225             is  specified  then  TLS is selected if the CER/CEA received from
226             the peer offers it.
227
228           {'Acct-Application-Id', [Unsigned32()]}:
229
230
231           {'Vendor-Specific-Application-Id', [Grouped()]}:
232
233
234           {'Firmware-Revision', Unsigned32()}:
235
236
237           Note that each tuple communicates one or more AVP values. It is  an
238           error to specify duplicate tuples.
239
240         eval() = {M,F,A} | fun() | [eval() | A]:
241           An  expression that can be evaluated as a function in the following
242           sense.
243
244         eval([{M,F,A} | T]) ->
245             apply(M, F, T ++ A);
246         eval([[F|A] | T]) ->
247             eval([F | T ++ A]);
248         eval([F|A]) ->
249             apply(F, A);
250         eval(F) ->
251             eval([F]).
252
253
254           Applying an eval() E to an argument list A is meant in the sense of
255           eval([E|A]).
256
257     Warning:
258         Beware  of using fun expressions of the form fun Name/Arity in situa‐
259         tions in which the fun is not short-lived and code is to be  upgraded
260         at  runtime since any processes retaining such a fun will have a ref‐
261         erence to old code. In particular, such a value is typically inappro‐
262         priate in configuration passed to start_service/2 or add_transport/2.
263
264
265         peer_filter() = term():
266           Filter  passed  to  call/4 in order to select candidate peers for a
267           pick_peer/4 callback. Has one of the following types.
268
269           none:
270             Matches any peer. This is a convenience that  provides  a  filter
271             equivalent to no filter.
272
273           host:
274             Matches  only those peers whose Origin-Host has the same value as
275             Destination-Host in the outgoing request in question, or any peer
276             if the request does not contain a Destination-Host AVP.
277
278           realm:
279             Matches only those peers whose Origin-Realm has the same value as
280             Destination-Realm in the outgoing request  in  question,  or  any
281             peer if the request does not contain a Destination-Realm AVP.
282
283           {host, any|DiameterIdentity()}:
284             Matches  only  those  peers  whose  Origin-Host has the specified
285             value, or all peers if the atom any.
286
287           {realm, any|DiameterIdentity()}:
288             Matches only those peers whose  Origin-Realm  has  the  specified
289             value, or all peers if the atom any.
290
291           {eval, eval()}:
292             Matches  only  those peers for which the specified eval() returns
293             true when applied to the connection's diameter_caps  record.  Any
294             other return value or exception is equivalent to false.
295
296           {neg, peer_filter()}:
297             Matches only those peers not matched by the specified filter.
298
299           {all, [peer_filter()]}:
300             Matches  only those peers matched by each filter in the specified
301             list.
302
303           {any, [peer_filter()]}:
304             Matches only those peers matched by at least one  filter  in  the
305             specified  list. The resulting list will be in match order, peers
306             matching the first  filter  of  the  list  sorting  before  those
307             matched by the second, and so on.
308
309           {first, [peer_filter()]}:
310             Like  any,  but  stops  at  the  first filter for which there are
311             matches, which can be much more efficient  when  there  are  many
312             peers.  For  example, the following filter causes only peers best
313             matching both the host and realm filters to be presented.
314
315           {first, [{all, [host, realm]}, realm]}
316
317
318           An invalid filter is equivalent to {any,[]}, a filter that  matches
319           no peer.
320
321     Note:
322         The  host  and  realm filters cause the Destination-Host and Destina‐
323         tion-Realm AVPs to be extracted from the outgoing  request,  assuming
324         it  to  be  a  record-  or  list-valued diameter_codec:message(), and
325         assuming at most one of each AVP. If this is not the  case  then  the
326         {host|realm,  DiameterIdentity()} filters must be used to achieve the
327         desired result. An empty DiameterIdentity() (which should not be typ‐
328         ical) matches all hosts/realms for the purposes of filtering.
329
330
331     Warning:
332         A  host  filter  is not typically desirable when setting Destination-
333         Host since it will remove peer agents from the candidates list.
334
335
336         service_event() = #diameter_event{service =  service_name(),  info  =
337         service_event_info()}:
338           An  event  message  sent to processes that have subscribed to these
339           using subscribe/1.
340
341         service_event_info() = term():
342           The info field of a service_event() record. Can  have  one  of  the
343           following types.
344
345           start:
346
347
348           stop:
349             The  service  is  being  started  or stopped. No event precedes a
350             start event. No event  follows  a  stop  event,  and  this  event
351             implies the termination of all transport processes.
352
353           {up, Ref, Peer, Config, Pkt}:
354
355
356           {up, Ref, Peer, Config}:
357
358
359           {down, Ref, Peer, Config}:
360
361
362           Ref    = transport_ref()
363           Peer   = diameter_app:peer()
364           Config = {connect|listen, [transport_opt()]}
365           Pkt    = #diameter_packet{}
366
367
368             The RFC 3539 watchdog state machine has transitioned into (up) or
369             out of (down) the OKAY state. If a #diameter_packet{} is  present
370             in  an  up event then there has been a capabilities exchange on a
371             newly established transport connection and  the  record  contains
372             the received CER or CEA.
373
374             Note  that a single up or down event for a given peer corresponds
375             to multiple peer_up/3 or peer_down/3 callbacks, one for  each  of
376             the   Diameter   applications   negotiated   during  capabilities
377             exchange. That is, the event communicates connectivity  with  the
378             peer as a whole while the callbacks communicate connectivity with
379             respect to individual Diameter applications.
380
381           {reconnect, Ref, Opts}:
382
383
384           Ref  = transport_ref()
385           Opts = [transport_opt()]
386
387
388             A connecting transport is attempting to  establish/reestablish  a
389             transport  connection  with  a  peer  following  connect_timer or
390             watchdog_timer expiry.
391
392           {closed, Ref, Reason, Config}:
393
394
395           Ref = transport_ref()
396           Config = {connect|listen, [transport_opt()]}
397
398
399             Capabilities exchange has failed. Reason can have one of the fol‐
400             lowing types.
401
402             {'CER', Result, Caps, Pkt}:
403
404
405             Result = ResultCode | {capabilities_cb, CB, ResultCode|discard}
406             Caps = #diameter_caps{}
407             Pkt  = #diameter_packet{}
408             ResultCode = integer()
409             CB = eval()
410
411
412               An  incoming  CER  has  been answered with the indicated result
413               code, or discarded. Caps contains  pairs  of  values,  for  the
414               local  node  and remote peer respectively. Pkt contains the CER
415               in question. In the case of rejection by a  capabilities  call‐
416               back, the tuple contains the rejecting callback.
417
418             {'CER', Caps, {ResultCode, Pkt}}:
419
420
421             ResultCode = integer()
422             Caps = #diameter_caps{}
423             Pkt  = #diameter_packet{}
424
425
426               An incoming CER contained errors and has been answered with the
427               indicated result code. Caps contains values for the local  node
428               only. Pkt contains the CER in question.
429
430             {'CER', timeout}:
431               An expected CER was not received within capx_timeout of connec‐
432               tion establishment.
433
434             {'CEA', Result, Caps, Pkt}:
435
436
437             Result = ResultCode | atom() | {capabilities_cb, CB, ResultCode|discard}
438             Caps = #diameter_caps{}
439             Pkt  = #diameter_packet{}
440             ResultCode = integer()
441
442
443               An incoming CEA has been rejected for the indicated reason.  An
444               integer-valued  Result  indicates  the  result code sent by the
445               peer. Caps contains pairs of values  for  the  local  node  and
446               remote  peer.  Pkt contains the CEA in question. In the case of
447               rejection by a capabilities callback, the  tuple  contains  the
448               rejecting callback.
449
450             {'CEA', Caps, Pkt}:
451
452
453             Caps = #diameter_caps{}
454             Pkt  = #diameter_packet{}
455
456
457               An  incoming  CEA  contained errors and has been rejected. Caps
458               contains only values for the local node. Pkt contains  the  CEA
459               in question.
460
461             {'CEA', timeout}:
462               An expected CEA was not received within capx_timeout of connec‐
463               tion establishment.
464
465           {watchdog, Ref, PeerRef, {From, To}, Config}:
466
467
468           Ref = transport_ref()
469           PeerRef = diameter_app:peer_ref()
470           From, To = initial | okay | suspect | down | reopen
471           Config = {connect|listen, [transport_opt()]}
472
473
474             An RFC 3539 watchdog state machine has changed state.
475
476           any():
477             For forward compatibility, a subscriber  should  be  prepared  to
478             receive info fields of forms other than the above.
479
480         service_name() = term():
481           Name  of  a service as passed to start_service/2 and with which the
482           service is identified. There can be at  most  one  service  with  a
483           given name on a given node. Note that erlang:make_ref/0 can be used
484           to generate a service name that is somewhat unique.
485
486         service_opt():
487           Option passed to start_service/2. Can be any capability()  as  well
488           as the following.
489
490           {application, [application_opt()]}:
491             A Diameter application supported by the service.
492
493             A  service must configure one tuple for each Diameter application
494             it intends to support. For  an  outgoing  request,  the  relevant
495             application_alias()  is  passed  to call/4, while for an incoming
496             request the application identifier in the message  header  deter‐
497             mines  the  application,  the  identifier  being specified in the
498             application's dictionary file.
499
500       Warning:
501           The capabilities advertised by a node  must  match  its  configured
502           applications.  In  particular,  application  configuration  must be
503           matched by corresponding capability() configuration, of  *-Applica‐
504           tion-Id AVPs in particular.
505
506
507           {decode_format, record | list | map | none}:
508             The  format of decoded messages and grouped AVPs in the msg field
509             of  diameter_packet  records  and  value  field  of  diameter_avp
510             records respectively. If record then a record whose definition is
511             generated from the dictionary file in question. If  list  or  map
512             then a [Name | Avps] pair where Avps is a list of AVP name/values
513             pairs or a map keyed on AVP names respectively. If none then  the
514             atom-value message name, or undefined for a Grouped AVP. See also
515             diameter_codec:message().
516
517             Defaults to record.
518
519       Note:
520           AVPs are decoded into a list of diameter_avp records in avps  field
521           of diameter_packet records independently of decode_format.
522
523
524           {restrict_connections, false | node | nodes | [node()] | eval()}:
525             The degree to which the service allows multiple transport connec‐
526             tions to the same peer, as identified by its Origin-Host at capa‐
527             bilities exchange.
528
529             If  [node()]  then  a  connection  is rejected if another already
530             exists on any of the specified nodes. Types  false,  node,  nodes
531             and  eval()  are equivalent to [], [node()], [node()|nodes()] and
532             the evaluated value respectively, evaluation of  each  expression
533             taking place whenever a new connection is to be established. Note
534             that false allows an unlimited number of connections to be estab‐
535             lished with the same peer.
536
537             Multiple  connections  are  independent and governed by their own
538             peer and watchdog state machines.
539
540             Defaults to nodes.
541
542           {sequence, {H,N} | eval()}:
543             A constant value H for the topmost 32-N bits of of 32-bit End-to-
544             End  and  Hop-by-Hop Identifiers generated by the service, either
545             explicitly or as a return value of a function to be evaluated  at
546             start_service/2.  In  particular, an identifier Id is mapped to a
547             new identifier as follows.
548
549           (H bsl N) bor (Id band ((1 bsl N) - 1))
550
551
552             Note that RFC 6733 requires that  End-to-End  Identifiers  remain
553             unique  for  a period of at least 4 minutes and that this and the
554             call rate places a lower bound on appropriate values of N:  at  a
555             rate  of R requests per second, an N-bit counter traverses all of
556             its values in (1 bsl N) div  (R*60)  minutes,  so  the  bound  is
557             4*R*60 =< 1 bsl N.
558
559             N  must lie in the range 0..32 and H must be a non-negative inte‐
560             ger less than 1 bsl (32-N).
561
562             Defaults to {0,32}.
563
564       Warning:
565           Multiple Erlang nodes implementing the same Diameter node should be
566           configured  with  different sequence masks to ensure that each node
567           uses a unique range of End-to-End and  Hop-by-Hop  Identifiers  for
568           outgoing requests.
569
570
571           {share_peers, boolean() | [node()] | eval()}:
572             Nodes  to  which peer connections established on the local Erlang
573             node are communicated.  Shared  peers  become  available  in  the
574             remote  candidates list passed to pick_peer/4 callbacks on remote
575             nodes  whose  services  are   configured   to   use   them:   see
576             use_shared_peers below.
577
578             If  false  then  peers are not shared. If [node()] then peers are
579             shared with the specified list of nodes. If eval() then peers are
580             shared  with the nodes returned by the specified function, evalu‐
581             ated whenever a peer connection becomes  available  or  a  remote
582             service  requests  information about local connections. The value
583             true is equivalent to fun erlang:nodes/0. The value node()  in  a
584             list  is  ignored, so a collection of services can all be config‐
585             ured to share with the same list of nodes.
586
587             Defaults to false.
588
589       Note:
590           Peers are only shared with services of the same name for  the  pur‐
591           pose  of sending outgoing requests. Since the value of the applica‐
592           tion_opt() alias, passed to call/4, is the handle for identifying a
593           peer  as  a  suitable candidate, services that share peers must use
594           the same aliases to identify  their  supported  applications.  They
595           should  typically also configure identical capabilities(), since by
596           sharing peer connections they are distributing  the  implementation
597           of a single Diameter node across multiple Erlang nodes.
598
599
600           {strict_arities, boolean() | encode | decode}:
601             Whether or not to require that the number of AVPs in a message or
602             grouped AVP agree with those specified in the dictionary in ques‐
603             tion  when passing messages to diameter_app(3) callbacks. If true
604             then mismatches in an outgoing messages cause message encoding to
605             fail,  while  mismatches  in  an incoming message are reported as
606             5005/5009 errors in  the  errors  field  of  the  diameter_packet
607             record  passed  to handle_request/3 or handle_answer/4 callbacks.
608             If false then neither error is enforced/detected.  If  encode  or
609             decode  then  errors  are  only  enforced/detected on outgoing or
610             incoming messages respectively.
611
612             Defaults to true.
613
614       Note:
615           Disabling  arity  checks  affects   the   form   of   messages   at
616           encode/decode. In particular, decoded AVPs are represented as lists
617           of values, regardless of the AVP's arity (ie.  expected  number  in
618           the message/AVP grammar in question), and values are expected to be
619           supplied as lists at encode. This differs from the historic  decode
620           behaviour  of  representing  AVPs  of  arity  1 as bare values, not
621           wrapped in a list.
622
623
624           {string_decode, boolean()}:
625             Whether or not to decode  AVPs  of  type  OctetString()  and  its
626             derived  types DiameterIdentity(), DiameterURI(), IPFilterRule(),
627             QoSFilterRule(), and UTF8String(). If true  then  AVPs  of  these
628             types  are decoded to string(). If false then values are retained
629             as binary().
630
631             Defaults to true.
632
633       Warning:
634           This option should be set to false since a  sufficiently  malicious
635           peer  can  otherwise  cause  large amounts of memory to be consumed
636           when decoded Diameter messages are passed  between  processes.  The
637           default value is for backwards compatibility.
638
639
640           {traffic_counters, boolean()}:
641             Whether  or not to count application-specific messages; those for
642             which diameter_app(3) callbacks take place. If  false  then  only
643             messages   handled  by  diameter  itself  are  counted:  CER/CEA,
644             DWR/DWA, DPR/DPA.
645
646             Defaults to true.
647
648       Note:
649           Disabling counters is a performance improvement, but means that the
650           omitted counters are not returned by service_info/2.
651
652
653           {use_shared_peers, boolean() | [node()] | eval()}:
654             Nodes  from  which  communicated  peers are made available in the
655             remote candidates list of pick_peer/4 callbacks.
656
657             If false then remote peers are not used. If  [node()]  then  only
658             peers  from  the specified list of nodes are used. If eval() then
659             only peers returned by the specified function are used, evaluated
660             whenever  a  remote  service  communicates  information  about an
661             available peer connection. The value true is  equivalent  to  fun
662             erlang:nodes/0. The value node() in a list is ignored.
663
664             Defaults to false.
665
666       Note:
667           A service that does not use shared peers will always pass the empty
668           list as the second argument of pick_peer/4 callbacks.
669
670
671       Warning:
672           Sending a request over a peer connection on a remote node  is  less
673           efficient  than  sending  it  over  a  local  connection. It may be
674           preferable to make use of  the  service_opt()  restrict_connections
675           and  maintain  a  dedicated  connection  on  each  node  from which
676           requests are sent.
677
678
679           transport_opt():
680             Any transport option except applications or capabilities. Used as
681             defaults for transport configuration, values passed to add_trans‐
682             port/2 overriding values configured on the service.
683
684         transport_opt():
685           Option passed to add_transport/2. Has one of the following types.
686
687           {applications, [application_alias()]}:
688             Diameter  applications  to  which   the   transport   should   be
689             restricted.  Defaults  to all applications configured on the ser‐
690             vice in question. Applications not configured on the  service  in
691             question are ignored.
692
693       Warning:
694           The  capabilities  advertised  by  a node must match its configured
695           applications. In particular, setting applications  on  a  transport
696           typically implies having to set matching *-Application-Id AVPs in a
697           capabilities() tuple.
698
699
700           {avp_dictionaries, [module()]}:
701             A  list  of  alternate   dictionary   modules   with   which   to
702             encode/decode  AVPs that are not defined by the dictionary of the
703             application in question. At decode, such AVPs are represented  as
704             diameter_avp  records  in the 'AVP' field of a decoded message or
705             Grouped AVP, the first alternate that succeeds  in  decoding  the
706             AVP  setting  the  record's  value field. At encode, values in an
707             'AVP' list can be passed as AVP name/value 2-tuples, and it is an
708             encode error for no alternate to define the AVP of such a tuple.
709
710             Defaults to the empty list.
711
712       Note:
713           The  motivation  for  alternate  dictionaries is RFC 7683, Diameter
714           Overload Indication Conveyance (DOIC), which  defines  AVPs  to  be
715           piggybacked onto existing application messages rather than defining
716           an application of its own. The DOIC dictionary is provided  by  the
717           diameter  application,  as  module  diameter_gen_doic_rfc7683,  but
718           alternate dictionaries can be used to encode/decode any set of AVPs
719           not known to an application dictionary.
720
721
722           {capabilities, [capability()]}:
723             AVPs  used  to  construct  outgoing CER/CEA messages. Values take
724             precedence over any specified on the service in question.
725
726             Specifying a capability as a transport option may be particularly
727             appropriate  for  Inband-Security-Id, in case TLS is desired over
728             TCP as implemented by diameter_tcp(3).
729
730           {capabilities_cb, eval()}:
731             Callback invoked upon reception of  CER/CEA  during  capabilities
732             exchange  in order to ask whether or not the connection should be
733             accepted. Applied to  the  transport_ref()  and  #diameter_caps{}
734             record of the connection.
735
736             The return value can have one of the following types.
737
738             ok:
739               Accept the connection.
740
741             integer():
742               Causes  an  incoming  CER  to  be  answered  with the specified
743               Result-Code.
744
745             discard:
746               Causes an incoming CER to be discarded without CEA being sent.
747
748             unknown:
749               Equivalent to returning 3010, DIAMETER_UNKNOWN_PEER.
750
751             Returning anything but ok or a 2xxx series result code causes the
752             transport  connection  to  be  broken.  Multiple  capabilities_cb
753             options can be specified, in which case the  corresponding  call‐
754             backs are applied until either all return ok or one does not.
755
756           {capx_timeout, Unsigned32()}:
757             Number  of milliseconds after which a transport process having an
758             established  transport  connection  will  be  terminated  if  the
759             expected  capabilities  exchange  message  (CER  or  CEA)  is not
760             received from the peer. For a connecting transport, the timing of
761             connection  attempts  is  governed  by  connect_timer  or  watch‐
762             dog_timer expiry. For a listening transport, the peer  determines
763             the timing.
764
765             Defaults to 10000.
766
767           {connect_timer, Tc}:
768
769
770           Tc = Unsigned32()
771
772
773             For  a  connecting transport, the RFC 6733 Tc timer, in millisec‐
774             onds. This timer determines the frequency with which a  transport
775             attempts to establish an initial connection with its peer follow‐
776             ing transport configuration. Once an initial connection has  been
777             established, watchdog_timer determines the frequency of reconnec‐
778             tion attempts, as required by RFC 3539.
779
780             For a listening transport, the timer  specifies  the  time  after
781             which a previously connected peer will be forgotten: a connection
782             after this time is regarded as an initial connection rather  than
783             reestablishment,  causing  the  RFC 3539 state machine to pass to
784             state OKAY rather than REOPEN. Note that these semantics are  not
785             governed  by  the  RFC  and  that  a  listening  transport's con‐
786             nect_timer should be greater than its peer's Tw plus jitter.
787
788             Defaults to 30000 for a connecting transport and 60000 for a lis‐
789             tening transport.
790
791           {disconnect_cb, eval()}:
792             Callback  invoked prior to terminating the transport process of a
793             transport connection  having  watchdog  state  OKAY.  Applied  to
794             application|service|transport  and the transport_ref() and diame‐
795             ter_app:peer() in question: application indicates that the diame‐
796             ter  application  is  being  stopped, service that the service in
797             question is being stopped by stop_service/1, and  transport  that
798             the transport in question is being removed by remove_transport/2.
799
800             The return value can have one of the following types.
801
802             {dpr, [option()]}:
803               Send Disconnect-Peer-Request to the peer, the transport process
804               being terminated following reception of  Disconnect-Peer-Answer
805               or timeout. An option() can be one of the following.
806
807               {cause, 0|rebooting|1|busy|2|goaway}:
808                 Disconnect-Cause     to    send,    REBOOTING,    BUSY    and
809                 DO_NOT_WANT_TO_TALK_TO_YOU respectively. Defaults to  reboot‐
810                 ing   for  Reason=service|application  and  goaway  for  Rea‐
811                 son=transport.
812
813               {timeout, Unsigned32()}:
814                 Number of milliseconds after which the transport  process  is
815                 terminated  if  DPA  has  not  been received. Defaults to the
816                 value of dpa_timeout.
817
818             dpr:
819               Equivalent to {dpr, []}.
820
821             close:
822               Terminate the transport process without Disconnect-Peer-Request
823               being sent to the peer.
824
825             ignore:
826               Equivalent to not having configured the callback.
827
828             Multiple  disconnect_cb  options  can be specified, in which case
829             the corresponding callbacks are applied until one of them returns
830             a  value  other  than  ignore.  All callbacks returning ignore is
831             equivalent to not having configured them.
832
833             Defaults to a single callback returning dpr.
834
835           {dpa_timeout, Unsigned32()}:
836             Number of milliseconds after which a transport connection is ter‐
837             minated following an outgoing DPR if DPA is not received.
838
839             Defaults to 1000.
840
841           {dpr_timeout, Unsigned32()}:
842             Number of milliseconds after which a transport connection is ter‐
843             minated following an incoming DPR if the peer does not close  the
844             connection.
845
846             Defaults to 5000.
847
848           {incoming_maxlen, 0..16777215}:
849             Bound  on  the  expected size of incoming Diameter messages. Mes‐
850             sages larger than the specified number of bytes are discarded.
851
852             Defaults to 16777215, the maximum value  of  the  24-bit  Message
853             Length field in a Diameter Header.
854
855           {length_errors, exit|handle|discard}:
856             How to deal with errors in the Message Length field of the Diame‐
857             ter Header in an incoming message. An error in  this  context  is
858             that  the  length  is  not  at  least  20  bytes (the length of a
859             Header), is not a multiple of 4 (a valid length) or  is  not  the
860             length of the message in question, as received over the transport
861             interface documented in diameter_transport(3).
862
863             If exit then the transport process in question exits.  If  handle
864             then  the  message  is  processed  as  usual,  a  resulting  han‐
865             dle_request/3 or handle_answer/4 callback (if  one  takes  place)
866             indicating  the  5015 error (DIAMETER_INVALID_MESSAGE_LENGTH). If
867             discard then the message in question is silently discarded.
868
869             Defaults to exit.
870
871       Note:
872           The default value reflects the fact that a transport module  for  a
873           stream-oriented  transport like TCP may not be able to recover from
874           a message length error since such a transport must use the  Message
875           Length  header  to  divide the incoming byte stream into individual
876           Diameter messages. An invalid length leaves it with no reliable way
877           to  rediscover  message boundaries, which may result in the failure
878           of subsequent messages. See diameter_tcp(3) for  the  behaviour  of
879           that module.
880
881
882           {pool_size, pos_integer()}:
883             Number  of  transport  processes to start. For a listening trans‐
884             port, determines the size of the pool of accepting transport pro‐
885             cesses,  a  larger number being desirable for processing multiple
886             concurrent peer connection attempts. For a connecting  transport,
887             determines the number of connections to the peer in question that
888             will  be  attempted  to   be   establshed:   the   service_opt():
889             restrict_connections  should also be configured on the service in
890             question to allow multiple connections to the same peer.
891
892           {spawn_opt, [term()]}:
893             Options passed to erlang:spawn_opt/2 when spawning a process  for
894             an  incoming  Diameter  request.  Options  monitor  and  link are
895             ignored.
896
897             Defaults to the empty list.
898
899           {strict_capx, boolean()]}:
900             Whether or not to enforce the RFC 6733 requirement that any  mes‐
901             sage  before  capabilities exchange should close the peer connec‐
902             tion. If false then unexpected messages are discarded.
903
904             Defaults to true. Changing this results  in  non-standard  behav‐
905             iour,  but  can  be  useful  in case peers are known to be behave
906             badly.
907
908           {strict_mbit, boolean()}:
909             Whether or not to regard an AVP setting the  M-bit  as  erroneous
910             when  the  command  grammar in question does not explicitly allow
911             the AVP. If true then such AVPs  are  regarded  as  5001  errors,
912             DIAMETER_AVP_UNSUPPORTED.  If false then the M-bit is ignored and
913             policing it becomes the receiver's responsibility.
914
915             Defaults to true.
916
917       Warning:
918           RFC 6733 is unclear about the semantics of the M-bit. One  the  one
919           hand,  the CCF specification in section 3.2 documents AVP in a com‐
920           mand grammar as meaning any arbitrary AVP; on the other hand, 1.3.4
921           states  that  AVPs setting the M-bit cannot be added to an existing
922           command: the modified command must instead be placed in a new Diam‐
923           eter application.
924
925           The  reason for the latter is presumably interoperability: allowing
926           arbitrary AVPs setting the M-bit in a command makes its interpreta‐
927           tion  implementation-dependent, since there's no guarantee that all
928           implementations will understand the same set of arbitrary  AVPs  in
929           the context of a given command. However, interpreting AVP in a com‐
930           mand grammar as any AVP, regardless of M-bit, renders  1.3.4  mean‐
931           ingless,  since  the  receiver  can simply ignore any AVP it thinks
932           isn't relevant, regardless of the sender's intent.
933
934           Beware of confusing mandatory in the sense of the M-bit with manda‐
935           tory  in the sense of the command grammar. The former is a semantic
936           requirement: that the receiver understand the semantics of the  AVP
937           in  the context in question. The latter is a syntactic requirement:
938           whether or not the AVP must occur in the message in question.
939
940
941           {transport_config, term()}:
942
943
944           {transport_config, term(), Unsigned32() | infinity}:
945             Term passed as the third argument to the start/3 function of  the
946             relevant  transport module in order to start a transport process.
947             Defaults to the empty list.
948
949             The 3-tuple form additionally specifies an interval, in millisec‐
950             onds,  after  which  a started transport process should be termi‐
951             nated if it has not yet established a  connection.  For  example,
952             the following options on a connecting transport request a connec‐
953             tion with one peer over SCTP or another (typically the same) over
954             TCP.
955
956           {transport_module, diameter_sctp}
957           {transport_config, SctpOpts, 5000}
958           {transport_module, diameter_tcp}
959           {transport_config, TcpOpts}
960
961
962             To listen on both SCTP and TCP, define one transport for each.
963
964           {transport_module, atom()}:
965             Module  implementing  a  transport  process  as defined in diame‐
966             ter_transport(3). Defaults to diameter_tcp.
967
968             Multiple  transport_module  and  transport_config   options   are
969             allowed. The order of these is significant in this case (and only
970             in this case), a transport_module being  paired  with  the  first
971             transport_config following it in the options list, or the default
972             value for trailing modules. Transport starts  will  be  attempted
973             with each of the modules in order until one establishes a connec‐
974             tion within the corresponding timeout (see below) or all fail.
975
976           {watchdog_config, [{okay|suspect, non_neg_integer()}]}:
977             Configuration that alters the behaviour  of  the  watchdog  state
978             machine.  On  key  okay,  the non-negative number of answered DWR
979             messages before transitioning from REOPEN to OKAY.  On  key  sus‐
980             pect,  the  number of watchdog timeouts before transitioning from
981             OKAY to SUSPECT when DWR is unanswered, or  0  to  not  make  the
982             transition.
983
984             Defaults  to  [{okay,  3}, {suspect, 1}]. Not specifying a key is
985             equivalent to specifying the default value for that key.
986
987       Warning:
988           The default value is as required by RFC 3539: changing  it  results
989           in non-standard behaviour that should only be used to simulate mis‐
990           behaving nodes during test.
991
992
993           {watchdog_timer, TwInit}:
994
995
996           TwInit = Unsigned32()
997                  | {M,F,A}
998
999
1000             The RFC 3539 watchdog timer. An integer value is  interpreted  as
1001             the RFC's TwInit in milliseconds, a jitter of +/- 2 seconds being
1002             added at each rearming of the timer to compute the RFC's  Tw.  An
1003             MFA  is  expected  to  return  the RFC's Tw directly, with jitter
1004             applied, allowing the jitter calculation to be performed  by  the
1005             callback.
1006
1007             An  integer  value must be at least 6000 as required by RFC 3539.
1008             Defaults to 30000.
1009
1010           Unrecognized options are silently ignored but are returned  unmodi‐
1011           fied  by  service_info/2  and can be referred to in predicate func‐
1012           tions passed to remove_transport/2.
1013
1014         transport_ref() = reference():
1015           Reference returned by add_transport/2 that identifies the  configu‐
1016           ration.
1017

EXPORTS

1019       add_transport(SvcName,  {connect|listen, [Opt]}) -> {ok, Ref} | {error,
1020       Reason}
1021
1022              Types:
1023
1024                 SvcName = service_name()
1025                 Opt = transport_opt()
1026                 Ref = transport_ref()
1027                 Reason = term()
1028
1029              Add transport capability to a service.
1030
1031              The service will start transport processes as required in  order
1032              to establish a connection with the peer, either by connecting to
1033              the peer (connect) or by accepting incoming connection  requests
1034              (listen).  A  connecting transport establishes transport connec‐
1035              tions with at most one peer, an listening transport  potentially
1036              with many.
1037
1038              The  diameter  application  takes  responsibility for exchanging
1039              CER/CEA with the peer. Upon successful completion  of  capabili‐
1040              ties  exchange  the service calls each relevant application mod‐
1041              ule's peer_up/3 callback after which  the  caller  can  exchange
1042              Diameter  messages with the peer over the transport. In addition
1043              to CER/CEA, the service takes responsibility for the handling of
1044              DWR/DWA and required by RFC 3539, as well as for DPR/DPA.
1045
1046              The  returned reference uniquely identifies the transport within
1047              the scope of the service. Note that the function returns  before
1048              a transport connection has been established.
1049
1050          Note:
1051              It  is not an error to add a transport to a service that has not
1052              yet been configured: a service can be started after  configuring
1053              its transports.
1054
1055
1056       call(SvcName, App, Request, [Opt]) -> Answer | ok | {error, Reason}
1057
1058              Types:
1059
1060                 SvcName = service_name()
1061                 App = application_alias()
1062                 Request = diameter_codec:message()
1063                 Answer = term()
1064                 Opt = call_opt()
1065
1066              Send a Diameter request message.
1067
1068              App  specifies  the Diameter application in which the request is
1069              defined and callbacks to the corresponding callback module  will
1070              follow  as  described  below  and in diameter_app(3). Unless the
1071              detach option is specified, the  call  returns  either  when  an
1072              answer  message is received from the peer or an error occurs. In
1073              the answer case, the return value  is  as  returned  by  a  han‐
1074              dle_answer/4  callback.  In  the  error case, whether or not the
1075              error is returned directly by diameter or from a  handle_error/4
1076              callback  depends on whether or not the outgoing request is suc‐
1077              cessfully encoded for transmission to the peer, the cases  being
1078              documented below.
1079
1080              If  there  are no suitable peers, or if pick_peer/4 rejects them
1081              by returning false, then {error,no_connection} is returned. Oth‐
1082              erwise  pick_peer/4 is followed by a prepare_request/3 callback,
1083              the message is encoded and then sent.
1084
1085              There are several error cases which may prevent an  answer  from
1086              being received and passed to a handle_answer/4 callback:
1087
1088                * If  the  initial  encode of the outgoing request fails, then
1089                  the request process fails and {error,encode} is returned.
1090
1091                * If the request is successfully  encoded  and  sent  but  the
1092                  answer  times out then a handle_error/4 callback takes place
1093                  with Reason = timeout.
1094
1095                * If the request is successfully encoded and sent but the ser‐
1096                  vice  in  question  is  stopped before an answer is received
1097                  then a handle_error/4 callback takes  place  with  Reason  =
1098                  cancel.
1099
1100                * If  the  transport  connection with the peer goes down after
1101                  the request has been sent but  before  an  answer  has  been
1102                  received then an attempt is made to resend the request to an
1103                  alternate peer. If no such peer is available, or if the sub‐
1104                  sequent  pick_peer/4 callback rejects the candidates, then a
1105                  handle_error/4 callback takes place with Reason =  failover.
1106                  If  a  peer is selected then a prepare_retransmit/3 callback
1107                  takes place, after which the semantics are the same as  fol‐
1108                  lowing an initial prepare_request/3 callback.
1109
1110                * If  an  encode  error takes place during retransmission then
1111                  the request process fails and {error,failure} is returned.
1112
1113                * If an application callback made in  processing  the  request
1114                  fails  (pick_peer, prepare_request, prepare_retransmit, han‐
1115                  dle_answer or handle_error) then  either  {error,encode}  or
1116                  {error,failure}  is  returned  depending  on  whether or not
1117                  there has been an attempt  to  send  the  request  over  the
1118                  transport.
1119
1120              Note  that {error,encode} is the only return value which guaran‐
1121              tees that the request has not been sent over the transport  con‐
1122              nection.
1123
1124       origin_state_id() -> Unsigned32()
1125
1126              Return a reasonable value for use as Origin-State-Id in outgoing
1127              messages.
1128
1129              The  value   returned   is   the   number   of   seconds   since
1130              19680120T031408Z, the first value that can be encoded as a Diam‐
1131              eter Time(), at the time the diameter application was started.
1132
1133       remove_transport(SvcName, Pred) -> ok | {error, Reason}
1134
1135              Types:
1136
1137                 SvcName = service_name()
1138                 Pred = Fun | MFA | transport_ref() | list() | true | false
1139
1140                 Fun = fun((transport_ref(), connect|listen, list()) ->  bool‐
1141                 ean())
1142                  | fun((transport_ref(), list()) -> boolean())
1143                  | fun((list()) -> boolean())
1144                 MFA = {atom(), atom(), list()}
1145                 Reason = term()
1146
1147              Remove previously added transports.
1148
1149              Pred  determines  which  transports to remove. An arity-3-valued
1150              Pred removes all transports  for  which  Pred(Ref,  Type,  Opts)
1151              returns  true,  where  Type and Opts are as passed to add_trans‐
1152              port/2 and Ref is as returned by it.  The  remaining  forms  are
1153              equivalent to an arity-3 fun as follows.
1154
1155              Pred = fun(transport_ref(), list()):  fun(Ref, _, Opts) -> Pred(Ref, Opts) end
1156              Pred = fun(list()):                   fun(_, _, Opts) -> Pred(Opts) end
1157              Pred = transport_ref():               fun(Ref, _, _)  -> Pred == Ref end
1158              Pred = list():                        fun(_, _, Opts) -> [] == Pred -- Opts end
1159              Pred = true:                          fun(_, _, _) -> true end
1160              Pred = false:                         fun(_, _, _) -> false end
1161              Pred = {M,F,A}:  fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end
1162
1163
1164              Removing  a  transport  causes  the corresponding transport pro‐
1165              cesses to be terminated. Whether or not a DPR message is sent to
1166              a peer is controlled by value of disconnect_cb configured on the
1167              transport.
1168
1169       service_info(SvcName, Info) -> term()
1170
1171              Types:
1172
1173                 SvcName = service_name()
1174                 Info = Item | [Info]
1175                 Item = atom()
1176
1177              Return information about a started service. Requesting info  for
1178              an unknown service causes undefined to be returned. Requesting a
1179              list of items causes a tagged list to be returned.
1180
1181              Item can be one of the following.
1182
1183                'Origin-Host':
1184
1185
1186                'Origin-Realm':
1187
1188
1189                'Vendor-Id':
1190
1191
1192                'Product-Name':
1193
1194
1195                'Origin-State-Id':
1196
1197
1198                'Host-IP-Address':
1199
1200
1201                'Supported-Vendor':
1202
1203
1204                'Auth-Application-Id':
1205
1206
1207                'Inband-Security-Id':
1208
1209
1210                'Acct-Application-Id':
1211
1212
1213                'Vendor-Specific-Application-Id':
1214
1215
1216                'Firmware-Revision':
1217                  Return a capability  value  as  configured  with  start_ser‐
1218                  vice/2.
1219
1220                applications:
1221                  Return   the   list   of  applications  as  configured  with
1222                  start_service/2.
1223
1224                capabilities:
1225                  Return a tagged list of all capabilities values  as  config‐
1226                  ured with start_service/2.
1227
1228                transport:
1229                  Return a list containing one entry for each of the service's
1230                  transport as configured with add_transport/2. Each entry  is
1231                  a  tagged list containing both configuration and information
1232                  about established peer connections. An example return  value
1233                  with  for  a  client  service with Origin-Host "client.exam‐
1234                  ple.com" configured with a  single  transport  connected  to
1235                  "server.example.com" might look as follows.
1236
1237                [[{ref,#Ref<0.0.0.93>},
1238                  {type,connect},
1239                  {options,[{transport_module,diameter_tcp},
1240                            {transport_config,[{ip,{127,0,0,1}},
1241                                               {raddr,{127,0,0,1}},
1242                                               {rport,3868},
1243                                               {reuseaddr,true}]}]},
1244                  {watchdog,{<0.66.0>,-576460736368485571,okay}},
1245                  {peer,{<0.67.0>,-576460736357885808}},
1246                  {apps,[{0,common}]},
1247                  {caps,[{origin_host,{"client.example.com","server.example.com"}},
1248                         {origin_realm,{"example.com","example.com"}},
1249                         {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}},
1250                         {vendor_id,{0,193}},
1251                         {product_name,{"Client","Server"}},
1252                         {origin_state_id,{[],[]}},
1253                         {supported_vendor_id,{[],[]}},
1254                         {auth_application_id,{[0],[0]}},
1255                         {inband_security_id,{[],[0]}},
1256                         {acct_application_id,{[],[]}},
1257                         {vendor_specific_application_id,{[],[]}},
1258                         {firmware_revision,{[],[]}},
1259                         {avp,{[],[]}}]},
1260                  {port,[{owner,<0.69.0>},
1261                         {module,diameter_tcp},
1262                         {socket,{{127,0,0,1},48758}},
1263                         {peer,{{127,0,0,1},3868}},
1264                         {statistics,[{recv_oct,656},
1265                                      {recv_cnt,6},
1266                                      {recv_max,148},
1267                                      {recv_avg,109},
1268                                      {recv_dvi,19},
1269                                      {send_oct,836},
1270                                      {send_cnt,6},
1271                                      {send_max,184},
1272                                      {send_avg,139},
1273                                      {send_pend,0}]}]},
1274                  {statistics,[{{{0,258,0},recv},3},
1275                               {{{0,258,1},send},3},
1276                               {{{0,258,0},recv,{'Result-Code',2001}},3},
1277                               {{{0,257,0},recv},1},
1278                               {{{0,257,1},send},1},
1279                               {{{0,257,0},recv,{'Result-Code',2001}},1},
1280                               {{{0,280,1},recv},2},
1281                               {{{0,280,0},send},2},
1282                               {{{0,280,0},send,{'Result-Code',2001}},2}]}]]
1283
1284
1285                  Here  ref is a transport_ref() and options the corresponding
1286                  transport_opt() list passed to add_transport/2. The watchdog
1287                  entry  shows  the  state of a connection's RFC 3539 watchdog
1288                  state  machine.  The  peer  entry  identifies   the   diame‐
1289                  ter_app:peer_ref()  for which there will have been peer_up/3
1290                  callbacks for the Diameter applications  identified  by  the
1291                  apps  entry,  common being the application_alias(). The caps
1292                  entry identifies the capabilities sent by the local node and
1293                  received  from  the  peer  during capabilities exchange. The
1294                  port  entry  displays  socket-level  information  about  the
1295                  transport  connection.  The statistics entry presents Diame‐
1296                  ter-level counters, an entry like {{{0,280,1},recv},2}  say‐
1297                  ing that the client has received 2 DWR messages: {0,280,1} =
1298                  {Application_Id, Command_Code, R_Flag}.
1299
1300                  Note that watchdog, peer, apps, caps and port entries depend
1301                  on  connectivity  with the peer and may not be present. Note
1302                  also that the statistics entry presents  values  accumulated
1303                  during the lifetime of the transport configuration.
1304
1305                  A listening transport presents its information slightly dif‐
1306                  ferently since there may be  multiple  accepted  connections
1307                  for the same transport_ref(). The transport info returned by
1308                  a server with a single client connection might look as  fol‐
1309                  lows.
1310
1311                [[{ref,#Ref<0.0.0.61>},
1312                  {type,listen},
1313                  {options,[{transport_module,diameter_tcp},
1314                            {transport_config,[{reuseaddr,true},
1315                                               {ip,{127,0,0,1}},
1316                                               {port,3868}]}]},
1317                  {accept,[[{watchdog,{<0.56.0>,-576460739249514012,okay}},
1318                            {peer,{<0.58.0>,-576460638229179167}},
1319                            {apps,[{0,common}]},
1320                            {caps,[{origin_host,{"server.example.com","client.example.com"}},
1321                                   {origin_realm,{"example.com","example.com"}},
1322                                   {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}},
1323                                   {vendor_id,{193,0}},
1324                                   {product_name,{"Server","Client"}},
1325                                   {origin_state_id,{[],[]}},
1326                                   {supported_vendor_id,{[],[]}},
1327                                   {auth_application_id,{[0],[0]}},
1328                                   {inband_security_id,{[],[]}},
1329                                   {acct_application_id,{[],[]}},
1330                                   {vendor_specific_application_id,{[],[]}},
1331                                   {firmware_revision,{[],[]}},
1332                                   {avp,{[],[]}}]},
1333                            {port,[{owner,<0.62.0>},
1334                                   {module,diameter_tcp},
1335                                   {socket,{{127,0,0,1},3868}},
1336                                   {peer,{{127,0,0,1},48758}},
1337                                   {statistics,[{recv_oct,1576},
1338                                                {recv_cnt,16},
1339                                                {recv_max,184},
1340                                                {recv_avg,98},
1341                                                {recv_dvi,26},
1342                                                {send_oct,1396},
1343                                                {send_cnt,16},
1344                                                {send_max,148},
1345                                                {send_avg,87},
1346                                                {send_pend,0}]}]}],
1347                           [{watchdog,{<0.72.0>,-576460638229717546,initial}}]]},
1348                  {statistics,[{{{0,280,0},recv},7},
1349                               {{{0,280,1},send},7},
1350                               {{{0,280,0},recv,{'Result-Code',2001}},7},
1351                               {{{0,258,1},recv},3},
1352                               {{{0,258,0},send},3},
1353                               {{{0,258,0},send,{'Result-Code',2001}},3},
1354                               {{{0,280,1},recv},5},
1355                               {{{0,280,0},send},5},
1356                               {{{0,280,0},send,{'Result-Code',2001}},5},
1357                               {{{0,257,1},recv},1},
1358                               {{{0,257,0},send},1},
1359                               {{{0,257,0},send,{'Result-Code',2001}},1}]}]]
1360
1361
1362                  The  information  presented  here  is as in the connect case
1363                  except that the client  connections  are  grouped  under  an
1364                  accept tuple.
1365
1366                  Whether  or  not the transport_opt() pool_size has been con‐
1367                  figured affects the format of the listing in the case  of  a
1368                  connecting  transport,  since a value greater than 1 implies
1369                  multiple transport processes for the  same  transport_ref(),
1370                  as in the listening case. The format in this case is similar
1371                  to the listening case, with a pool  tuple  in  place  of  an
1372                  accept tuple.
1373
1374                connections:
1375                  Return  a  list  containing  one entry for every established
1376                  transport connection whose watchdog state machine is not  in
1377                  the  down state. This is a flat view of transport info which
1378                  lists only active connections and for  which  Diameter-level
1379                  statistics  are  accumulated  only  for  the lifetime of the
1380                  transport connection. A return value for  the  server  above
1381                  might look as follows.
1382
1383                [[{ref,#Ref<0.0.0.61>},
1384                  {type,accept},
1385                  {options,[{transport_module,diameter_tcp},
1386                            {transport_config,[{reuseaddr,true},
1387                                               {ip,{127,0,0,1}},
1388                                               {port,3868}]}]},
1389                  {watchdog,{<0.56.0>,-576460739249514012,okay}},
1390                  {peer,{<0.58.0>,-576460638229179167}},
1391                  {apps,[{0,common}]},
1392                  {caps,[{origin_host,{"server.example.com","client.example.com"}},
1393                         {origin_realm,{"example.com","example.com"}},
1394                         {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}},
1395                         {vendor_id,{193,0}},
1396                         {product_name,{"Server","Client"}},
1397                         {origin_state_id,{[],[]}},
1398                         {supported_vendor_id,{[],[]}},
1399                         {auth_application_id,{[0],[0]}},
1400                         {inband_security_id,{[],[]}},
1401                         {acct_application_id,{[],[]}},
1402                         {vendor_specific_application_id,{[],[]}},
1403                         {firmware_revision,{[],[]}},
1404                         {avp,{[],[]}}]},
1405                  {port,[{owner,<0.62.0>},
1406                         {module,diameter_tcp},
1407                         {socket,{{127,0,0,1},3868}},
1408                         {peer,{{127,0,0,1},48758}},
1409                         {statistics,[{recv_oct,10124},
1410                                      {recv_cnt,132},
1411                                      {recv_max,184},
1412                                      {recv_avg,76},
1413                                      {recv_dvi,9},
1414                                      {send_oct,10016},
1415                                      {send_cnt,132},
1416                                      {send_max,148},
1417                                      {send_avg,75},
1418                                      {send_pend,0}]}]},
1419                  {statistics,[{{{0,280,0},recv},62},
1420                               {{{0,280,1},send},62},
1421                               {{{0,280,0},recv,{'Result-Code',2001}},62},
1422                               {{{0,258,1},recv},3},
1423                               {{{0,258,0},send},3},
1424                               {{{0,258,0},send,{'Result-Code',2001}},3},
1425                               {{{0,280,1},recv},66},
1426                               {{{0,280,0},send},66},
1427                               {{{0,280,0},send,{'Result-Code',2001}},66},
1428                               {{{0,257,1},recv},1},
1429                               {{{0,257,0},send},1},
1430                               {{{0,257,0},send,{'Result-Code',2001}},1}]}]]
1431
1432
1433                  Note  that  there may be multiple entries with the same ref,
1434                  in contrast to transport info.
1435
1436                statistics:
1437                  Return a {{Counter, Ref}, non_neg_integer()} list of counter
1438                  values.  Ref  can  be  either  a transport_ref() or a diame‐
1439                  ter_app:peer_ref(). Entries for the latter are  folded  into
1440                  corresponding  entries for the former as peer connections go
1441                  down. Entries for both are  removed  at  remove_transport/2.
1442                  The Diameter-level statistics returned by transport and con‐
1443                  nections info are based upon these entries.
1444
1445                diameter_app:peer_ref():
1446                  Return transport  configuration  associated  with  a  single
1447                  peer,  as  passed  to  add_transport/2. The returned list is
1448                  empty if the peer is unknown. Otherwise it contains the ref,
1449                  type and options tuples as in transport and connections info
1450                  above. For example:
1451
1452                [{ref,#Ref<0.0.0.61>},
1453                 {type,accept},
1454                 {options,[{transport_module,diameter_tcp},
1455                           {transport_config,[{reuseaddr,true},
1456                                              {ip,{127,0,0,1}},
1457                                              {port,3868}]}]}]
1458
1459
1460       services() -> [SvcName]
1461
1462              Types:
1463
1464                 SvcName = service_name()
1465
1466              Return the list of started services.
1467
1468       session_id(Ident) -> OctetString()
1469
1470              Types:
1471
1472                 Ident = DiameterIdentity()
1473
1474              Return a value for a Session-Id AVP.
1475
1476              The value has the form required by  section  8.8  of  RFC  6733.
1477              Ident  should be the Origin-Host of the peer from which the mes‐
1478              sage containing the returned value will be sent.
1479
1480       start() -> ok | {error, Reason}
1481
1482              Start the diameter application.
1483
1484              The diameter application must be started before starting a  ser‐
1485              vice. In a production system this is typically accomplished by a
1486              boot file, not by calling start/0 explicitly.
1487
1488       start_service(SvcName, Options) -> ok | {error, Reason}
1489
1490              Types:
1491
1492                 SvcName = service_name()
1493                 Options = [service_opt()]
1494                 Reason = term()
1495
1496              Start a diameter service.
1497
1498              A service defines a locally-implemented Diameter node,  specify‐
1499              ing  the  capabilities  to  be  advertised  during  capabilities
1500              exchange. Transports are added to  a  service  using  add_trans‐
1501              port/2.
1502
1503          Note:
1504              A  transport  can  both  override its service's capabilities and
1505              restrict its supported Diameter applications so "service = Diam‐
1506              eter  node  as identified by Origin-Host" is not necessarily the
1507              case.
1508
1509
1510       stop() -> ok | {error, Reason}
1511
1512              Stop the diameter application.
1513
1514       stop_service(SvcName) -> ok | {error, Reason}
1515
1516              Types:
1517
1518                 SvcName = service_name()
1519                 Reason = term()
1520
1521              Stop a diameter service.
1522
1523              Stopping a service causes all associated  transport  connections
1524              to  be  broken.  A  DPR  message  with be sent as in the case of
1525              remove_transport/2.
1526
1527          Note:
1528              Stopping a service does not remove  any  associated  transports:
1529              remove_transport/2 must be called to remove transport configura‐
1530              tion.
1531
1532
1533       subscribe(SvcName) -> true
1534
1535              Types:
1536
1537                 SvcName = service_name()
1538
1539              Subscribe to service_event() messages from a service.
1540
1541              It is not an error to subscribe to events from  a  service  that
1542              does  not  yet  exist.  Doing  so  before  adding  transports is
1543              required to guarantee the  reception  of  all  transport-related
1544              events.
1545
1546       unsubscribe(SvcName) -> true
1547
1548              Types:
1549
1550                 SvcName = service_name()
1551
1552              Unsubscribe to event messages from a service.
1553

SEE ALSO

1555       diameter_app(3), diameter_transport(3), diameter_dict(4)
1556
1557
1558
1559Ericsson AB                    diameter 2.1.4.1                    diameter(3)
Impressum