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

EXPORTS

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

SEE ALSO

1561       diameter_app(3), diameter_transport(3), diameter_dict(4)
1562
1563
1564
1565Ericsson AB                     diameter 2.2.7                     diameter(3)
Impressum