aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc/src/diameter_app.xml
blob: 36a560b33c8c1028fbe88d32df3c1accbf85be48 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd" [
  <!ENTITY message '<seealso marker="#message">message()</seealso>'>
  <!ENTITY dict
  '<seealso marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>'>
  <!ENTITY % also SYSTEM "seealso.ent" >
  <!ENTITY % here SYSTEM "seehere.ent" >
  %also;
  %here;
]>

<erlref>
<header>

<copyright>
<year>2011</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.

Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.

</legalnotice>

<title>diameter_app(3)</title>
<prepared>Anders Svensson</prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date></date>
<rev></rev>
<file>diameter_app.xml</file>

</header>

<module>diameter_app</module>
<modulesummary>
Callback module of a Diameter application.</modulesummary>

<description>

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

<p>
A callback module must export all of the functions documented below.
The functions themselves are of three distinct flavours:</p>

<list>
<item>
<p>
&peer_up; and &peer_down; signal the
attainment or loss of connectivity with a Diameter peer.</p>
</item>

<item>
<p>
&pick_peer;,
&prepare_request;,
&prepare_retransmit;,
&handle_answer;
and &handle_error; are (or may be) called as a consequence of a call
to &mod_call; to send an outgoing
Diameter request message.</p>
</item>

<item>
<p>
&handle_request;
is called in response to an incoming Diameter request message.</p>
</item>

</list>

</description>

<note>
<p>
The arities given for the the callback functions here assume no extra
arguments.
All functions will also be passed any extra arguments configured with
the callback module itself when calling &mod_start_service;
and, for the call-specific callbacks, any extra arguments passed to
&mod_call;.</p>
</note>

<!-- ===================================================================== -->
<!-- ===================================================================== -->

<section>
<title>DATA TYPES</title>

<taglist>

<marker id="capabilities"/>

<tag><c>capabilities() = #diameter_caps{}</c></tag>
<item>
<p>
A record containing the identities of
the local Diameter node and the remote Diameter peer having an
established transport
connection, as well as the capabilities as
determined by capabilities exchange.
Each field of the record is a 2-tuple consisting of
values for the (local) host and (remote) peer.
Optional or possibly multiple values are encoded as lists of values,
mandatory values as the bare value.</p>
</item>

<marker id="message"/>

<tag><c>message() = &codec_message;</c></tag>
<item>
<p>
The representation of a Diameter message as passed to
&mod_call; or returned from a &handle_request; callback.</p>

</item>

<marker id="packet"/>

<tag><c>packet() = &codec_packet;</c></tag>
<item>
<p>
A container for incoming and outgoing Diameter messages that's passed
through encode/decode and transport.
Fields should not be set in return values except as documented.</p>
</item>

<marker id="peer_ref"/>

<tag><c>peer_ref() = term()</c></tag>
<item>
<p>
A term identifying a transport connection with a Diameter peer.</p>
</item>

<marker id="peer"/>

<tag><c>peer() = {&peer_ref;, &capabilities;}</c></tag>
<item>
<p>
A tuple representing a Diameter peer connection.</p>
</item>

<marker id="state"/>

<tag><c>state() = term()</c></tag>
<item>
<p>
The state maintained by the application callback functions
&peer_up;, &peer_down; and (optionally) &pick_peer;.
The initial state is configured in the call to
&mod_start_service; that configures the application on a service.
Callback functions returning a state are evaluated in a common
service-specific process while
those not returning state are evaluated in a request-specific
process.</p>
</item>

</taglist>

<marker id="peer_up"/>
</section>

<!-- ===================================================================== -->
<!-- ===================================================================== -->

<funcs>

<func>
<name>Mod:peer_up(SvcName, Peer, State) -> NewState</name>
<fsummary>Invoked when a transport connection has been established</fsummary>
<type>
<v>SvcName = &mod_service_name;</v>
<v>Peer    = &peer;</v>
<v>State   = NewState = &state;</v>
</type>
<desc>
<p>
Invoked to signal the availability of a peer connection on the local
Erlang node.
In particular, capabilities exchange with the peer has indicated
support for the application in question, the RFC 3539 watchdog state
machine for the connection has reached state <c>OKAY</c> and Diameter
messages can be both sent and received.</p>

<note>
<p>
A watchdog state machine can reach state <c>OKAY</c> from state
<c>SUSPECT</c> without a new capabilities exchange taking place.
A new transport connection (and capabilities exchange) results in a
new peer_ref().</p>
</note>

<note>
<p>
There is no requirement that a callback return before incoming
requests are received: &handle_request; callbacks must be
handled independently of &peer_up; and &peer_down;.</p>
</note>

</desc>
</func>

<func>
<name>Mod:peer_down(SvcName, Peer, State) -> NewState</name>
<fsummary>Invoked when a transport connection has been lost.</fsummary>
<type>
<v>SvcName = &mod_service_name;</v>
<v>Peer    = &peer;</v>
<v>State   = NewState = &state;</v>
</type>
<desc>
<p>
Invoked to signal that a peer connection on the local Erlang node is
no longer available following a previous call to &peer_up;.
In particular, that the RFC 3539 watchdog state machine for the
connection has left state <c>OKAY</c> and the peer will no longer be a
candidate in &pick_peer; callbacks.</p>

</desc>
</func>

<func>
<name>Mod:pick_peer(LocalCandidates, RemoteCandidates, SvcName, State)
      -> Selection | false</name>
<fsummary>Select a target peer for an outgoing request.</fsummary>
<type>
<v>LocalCandidates = RemoteCandidates = [&peer;]</v>
<v>SvcName = &mod_service_name;</v>
<v>State = NewState = &state;</v>
<v>Selection = {ok, Peer} | {Peer, NewState}</v>
<v>Peer = &peer; | false</v>
</type>
<desc>
<p>
Invoked as a consequence of a call to &mod_call; to select a destination
peer for an outgoing request.
The return value indicates the selected peer.</p>

<p>
The candidate lists contain only those peers that have advertised
support for the Diameter application in question during capabilities
exchange, that have not be excluded by a <c>filter</c> option in
the call to &mod_call;
and whose watchdog state machine is in the <c>OKAY</c> state.
The order of the elements is unspecified except that any
peers whose Origin-Host and Origin-Realm matches that of the
outgoing request (in the sense of a <c>{filter, {all, [host, realm]}}</c>
option to &mod_call;)
will be placed at the head of the list.
<c>LocalCandidates</c> contains peers whose transport process resides
on the local Erlang node while
<c>RemoteCandidates</c> contains peers that have been communicated
from other nodes by services of the same name.</p>

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

<p>
The return values <c>false</c> and <c>{false, State}</c> (that is,
<c>NewState = State</c>) are equivalent, as are <c>{ok, Peer}</c> and
<c>{Peer, State}</c>.</p>

<note>
<p>
The &mod_service_opt; <c>use_shared_peers</c> determines whether or
not a service uses peers shared from other nodes.
If not then <c>RemoteCandidates</c> is the empty list.</p>
</note>

<warning>
<p>
The return value <c>{Peer, NewState}</c> is only allowed if
the Diameter application in question was configured with the
&mod_application_opt; <c>{call_mutates_state, true}</c>.
Otherwise, the <c>State</c> argument is always
the intial value as configured on the application, not any subsequent
value returned by a &peer_up;
or &peer_down; callback.</p>
</warning>

</desc>

</func>

<func>
<name>Mod:prepare_request(Packet, SvcName, Peer) -> Action</name>
<fsummary>Return a request for encoding and transport.</fsummary>
<type>
<v>Packet = &packet;</v>
<v>SvcName = &mod_service_name;</v>
<v>Peer = &peer;</v>
<v>Action = Send | Discard | {eval_packet, Action, PostF}</v>
<v>Send = {send, &packet; | &message;}</v>
<v>Discard = {discard, Reason} | discard</v>
<v>PostF = &mod_evaluable;}</v>
</type>
<desc>
<p>
Invoked to return a request for encoding and transport.
Allows the sender to use the selected peer's capabilities
to modify the outgoing request.
Many implementations may simply want to return <c>{send, Packet}</c></p>

<p>
A returned &packet; should set the
request to be encoded in its
<c>msg</c> field and can set the <c>transport_data</c> field in order
to pass information to the transport process.
Extra arguments passed to &mod_call; can be used to
communicate transport (or any other) data to the callback.</p>

<p>
A returned &packet; can set
the <c>header</c> field to a
<c>#diameter_header{}</c> to specify values that should
be preserved in the outgoing request, values otherwise being those in
the header record contained in <c>Packet</c>.
A returned <c>length</c>, <c>cmd_code</c> or <c>application_id</c> is
ignored.</p>

<p>
A returned <c>PostF</c> will be evaluated on any encoded
<c>#diameter_packet{}</c> prior to transmission, the <c>bin</c> field
containing the encoded binary.
The return value is ignored.</p>

<p>
Returning <c>{discard, Reason}</c> causes the request to be aborted
and the &mod_call; for which the
callback has taken place to return <c>{error, Reason}</c>.
Returning <c>discard</c> is equivalent to returning <c>{discard,
discarded}</c>.</p>

</desc>
</func>

<func>
<name>Mod:prepare_retransmit(Packet, SvcName, Peer) -> Action</name>
<fsummary>Return a request for encoding and retransmission.</fsummary>
<type>
<v>Packet  = &packet;</v>
<v>SvcName = &mod_service_name;</v>
<v>Peer = &peer;</v>
<v>Action = Send | Discard | {eval_packet, Action, PostF}</v>
<v>Send = {send, &packet; | &message;}</v>
<v>Discard = {discard, Reason} | discard</v>
<v>PostF = &mod_evaluable;}</v>
</type>
<desc>
<p>
Invoked to return a request for encoding and retransmission.
Has the same role as &prepare_request; in the case that
a peer connection is lost an an alternate peer selected but the
argument &packet; is as returned
by the initial &prepare_request;.</p>

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

</desc>
</func>

<func>
<name>Mod:handle_answer(Packet, Request, SvcName, Peer) -> Result</name>
<fsummary>Receive an answer message from a peer.</fsummary>
<type>
<v>Packet  = &packet;</v>
<v>Request = &message;</v>
<v>SvcName = &mod_service_name;</v>
<v>Peer    = &peer;</v>
<v>Result  = term()</v>
</type>
<desc>
<p>
Invoked when an answer message is received from a peer.
The return value is returned from &mod_call; unless the
<c>detach</c> option was specified.</p>

<p>
The decoded answer record and undecoded binary are in the <c>msg</c>
and <c>bin</c> fields of the argument
&packet; respectively.
<c>Request</c> is the outgoing request message as was returned from
&prepare_request; or &prepare_retransmit;.</p>

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

<p>
By default, an incoming answer message that cannot be successfully
decoded causes the request process to fail, causing
&mod_call;
to return <c>{error, failure}</c> unless the <c>detach</c> option was
specified.
In particular, there is no &handle_error; callback in this
case.
The &mod_application_opt;
<c>answer_errors</c> can be set to change this behaviour.</p>

</desc>
</func>

<func>
<name>Mod:handle_error(Reason, Request, SvcName, Peer) -> Result</name>
<fsummary>Return an error from a outgoing request.</fsummary>
<type>
<v>Reason  = timeout | failover | term()</v>
<v>Request = &message;</v>
<v>SvcName = &mod_service_name;</v>
<v>Peer    = &peer;</v>
<v>Result  = term()</v>
</type>
<desc>
<p>
Invoked when an error occurs before an answer message is received
in response to an outgoing request.
The return value is returned from &mod_call; unless the
<c>detach</c> option was specified.</p>

<p>
Reason <c>timeout</c> indicates that an answer message has not been
received within the time specified with the corresponding &mod_call_opt;.
Reason <c>failover</c> indicates
that the transport connection to the peer to which the request has
been sent has become unavailable and that not alternate peer was
not selected.</p>

</desc>
</func>

<func>
<name>Mod:handle_request(Packet, SvcName, Peer) -> Action</name>
<fsummary>Receive an incoming request.</fsummary>
<type>
<v>Packet  = &packet;</v>
<v>SvcName = term()</v>
<v>Peer    = &peer;</v>
<v>Action  = Reply
           | {relay, [Opt]}
           | discard
           | {eval|eval_packet, Action, PostF}</v>
<v>Reply   = {reply, &packet; | &message;}
           | {answer_message, 3000..3999|5000..5999}
           | {protocol_error, 3000..3999}</v>
<v>Opt     = &mod_call_opt;</v>
<v>PostF   = &mod_evaluable;</v>
</type>
<desc>
<p>
Invoked when a request message is received from a peer.
The application in which the callback takes place (that is, the
callback module as configured with &mod_start_service;)
is determined by the Application Identifier in the header of the
incoming request message, the selected module being the one
whose corresponding dictionary declares
itself as defining either the application in question or the Relay
application.</p>

<p>
The argument &packet; has the following signature.</p>

<pre>
#diameter_packet{header = #diameter_header{},
                 avps   = [#diameter_avp{}],
                 msg    = record() | undefined,
                 errors = [&dict_Unsigned32; | {&dict_Unsigned32;, #diameter_avp{}}],
                 bin    = binary(),
                 transport_data = term()}
</pre>

<p>
The <c>msg</c> field will be <c>undefined</c> in case the request has
been received in the relay application.
Otherwise it contains the record representing the request as outlined
in &dict;.</p>

<p>
The <c>errors</c> field specifies any results codes identifying errors
found while decoding the request.
This is used to set Result-Code and/or Failed-AVP in a returned
answer unless the callback returns a <c>#diameter_packet{}</c>
whose <c>errors</c> field is set to either a non-empty list of its
own, in which case this list is used instead, or the atom <c>false</c>
to disable any setting of Result-Code and Failed-AVP.
Note that the errors detected by diameter are of the 3xxx
and 5xxx series, Protocol Errors and Permanent Failures respectively.
The <c>errors</c> list is empty if the request has been received in
the relay application.</p>

<p>
The <c>transport_data</c> field contains an arbitrary term passed into
diameter from the transport module in question, or the atom
<c>undefined</c> if the transport specified no data.
The term is preserved if a &message; is returned but must be set
explicitly in a returned &packet;.</p>

<p>
The semantics of each of the possible return values are as follows.</p>

<taglist>

<tag><c>{reply, &packet; | &message;}</c></tag>
<item>
<p>
Send the specified answer message to the peer.
In the case of a &packet;, the
message to be sent must be set in the
<c>msg</c> field and the <c>header</c> field can be set to a
<c>#diameter_header{}</c> to specify values that should be
preserved in the outgoing answer, appropriate values otherwise
being set by diameter.</p>
</item>

<tag><c>{answer_message, 3000..3999|5000..5999}</c></tag>
<item>
<p>
Send an answer message to the peer containing the specified
Result-Code.
Equivalent to</p>
<pre>
{reply, ['answer-message' | Avps]
</pre>
<p>
where <c>Avps</c> sets the Origin-Host, Origin-Realm, the specified
Result-Code and (if the request contained one) Session-Id AVP's.</p>

<p>
Returning a value other than 3xxx or 5xxx will cause the request
process in question to fail, as will returning a 5xxx value if the
peer connection in question has been configured with the RFC 3588
common dictionary <c>diameter_gen_base_rfc3588</c>.
(Since RFC 3588 only allows 3xxx values in an answer-message.)</p>
</item>

<tag><c>{relay, Opts}</c></tag>
<item>
<p>
Relay a request to another peer in the role of a Diameter relay agent.
If a routing loop is detected then the request is answered with
3005 (DIAMETER_LOOP_DETECTED).
Otherwise a Route-Record AVP (containing the sending peer's Origin-Host) is
added to the request and &pick_peer;
and subsequent callbacks take place just as if &mod_call; had been called
explicitly.
The End-to-End Identifier of the incoming request is preserved in the
header of the relayed request.</p>

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

<tag><c>discard</c></tag>
<item>
<p>
Discard the request.
No answer message is sent to the peer.</p>
</item>

<tag><c>{eval, Action, PostF}</c></tag>
<item>
<p>
Handle the request as if <c>Action</c> has been returned and then
evaluate <c>PostF</c> in the request process.
The return value is ignored.</p>
</item>

<tag><c>{eval_packet, Action, PostF}</c></tag>
<item>
<p>
Like <c>eval</c> but evaluate <c>PostF</c> on any encoded
<c>#diameter_packet{}</c> prior to transmission, the <c>bin</c> field
containing the encoded binary.
The return value is ignored.</p>
</item>

<tag><c>{protocol_error, 3000..3999}</c></tag>
<item>
<p>
Equivalent to <c>{answer_message, 3000..3999}</c>.</p>
</item>

</taglist>

<note>
<p>
Requests containing errors may be answered by diameter, without a
callback taking place, depending on the value of the
&mod_application_opt; <c>request_errors</c>.</p>
</note>

</desc>
</func>

</funcs>

</erlref>