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

NAME

6       diameter_transport - Diameter transport interface.
7

DESCRIPTION

9       A  module  specified  as a transport_module to diameter:add_transport/2
10       must implement the interface documented here. The interface consists of
11       a function with which diameter starts a transport process and a message
12       interface with  which  the  transport  process  communicates  with  the
13       process that starts it (aka its parent).
14

DATA TYPES

16         message() = binary() | diameter_codec:packet():
17           A Diameter message as passed over the transport interface.
18
19           For   an  inbound  message  from  a  transport  process,  a  diame‐
20           ter_codec:packet() must contain the received  message  in  its  bin
21           field.  In  the  case  of  an inbound request, any value set in the
22           transport_data field will passed back to the  transport  module  in
23           the  corresponding  answer  message,  unless  the  sender  supplies
24           another value.
25
26           For  an  outbound  message  to  a  transport  process,   a   diame‐
27           ter_codec:packet()  has  a value other than undefined in its trans‐
28           port_data field and has the binary() to send in its bin field.
29

EXPORTS

31       Mod:start({Type, Ref}, Svc, Config) -> {ok, Pid} | {ok, Pid, LAddrs}  |
32       {error, Reason}
33
34              Types:
35
36                 Type = connect | accept
37                 Ref = diameter:transport_ref()
38                 Svc = #diameter_service{}
39                 Config = term()
40                 Pid = pid()
41                 LAddrs = [inet:ip_address()]
42                 Reason = term()
43
44              Start  a  transport process. Called by diameter as a consequence
45              of a call to diameter:add_transport/2 in order to  establish  or
46              accept  a transport connection respectively. A transport process
47              maintains a connection with a single remote peer.
48
49              Type indicates whether the  transport  process  in  question  is
50              being  started  for  a  connecting  (Type=connect)  or listening
51              (Type=accept) transport. In the latter case, transport processes
52              are  started  as  required  to  accept connections from multiple
53              peers.
54
55              Ref is the value that was  returned  from  the  call  to  diame‐
56              ter:add_transport/2  that  has  lead  to starting of a transport
57              process.
58
59              Svc contains capabilities passed to diameter:start_service/2 and
60              diameter:add_transport/2, values passed to the latter overriding
61              those passed to the former.
62
63              Config is as passed in  transport_config  tuple  in  the  diame‐
64              ter:transport_opt() list passed to diameter:add_transport/2.
65
66              The  start  function  should use the Host-IP-Address list in Svc
67              and/or Config to select and return an appropriate list of  local
68              IP addresses. In the connecting case, the local address list can
69              instead be communicated in a  connected  message  (see  MESSAGES
70              below)  following  connection establishment. In either case, the
71              local address list is used to populate Host-IP-Address  AVPs  in
72              outgoing  capabilities  exchange  messages if Host-IP-Address is
73              unspecified.
74
75              A transport process must implement the message  interface  docu‐
76              mented  below.  It  should retain the pid of its parent, monitor
77              the parent and terminate if it dies. It should not link  to  the
78              parent. It should exit if its transport connection with its peer
79              is lost.
80

MESSAGES

82       All messages sent over the transport interface are of the form  {diame‐
83       ter, term()}.
84
85       A transport process can expect messages of the following types from its
86       parent.
87
88         {diameter, {send, message() | false}}:
89           An outbound Diameter message. The atom false can only  be  received
90           when  request acknowledgements have been requests: see the ack mes‐
91           sage below.
92
93         {diameter, {close, Pid}}:
94           A request to terminate the transport process after having  received
95           DPA  in  response to DPR. The transport process should exit. Pid is
96           the pid() of the parent process.
97
98         {diameter, {tls, Ref, Type, Bool}}:
99           Indication of whether or not  capabilities  exchange  has  selected
100           inband  security  using  TLS.  Ref  is  a  reference() that must be
101           included in the {diameter, {tls, Ref}} reply message to the  trans‐
102           port's parent process (see below). Type is either connect or accept
103           depending on whether the process has been started for a  connecting
104           or listening transport respectively. Bool is a boolean() indicating
105           whether or not the transport connection should be upgraded to TLS.
106
107           If TLS is requested (Bool=true) then a  connecting  process  should
108           initiate  a  TLS  handshake  with the peer and an accepting process
109           should prepare to accept a handshake. A successful handshake should
110           be  followed  by  a  {diameter,  {tls,  Ref}} message to the parent
111           process. A failed handshake should cause the process to exit.
112
113           This message is only sent to a transport process over whose Inband-
114           Security-Id configuration has indicated support for TLS.
115
116       A  transport process should send messages of the following types to its
117       parent.
118
119         {diameter, {self(), connected}}:
120           Inform the parent that the transport process with  Type=accept  has
121           established  a  connection with the peer. Not sent if the transport
122           process has Type=connect.
123
124         {diameter, {self(), connected, Remote}}:
125
126
127         {diameter, {self(), connected, Remote, [LocalAddr]}}:
128           Inform the parent that the transport process with Type=connect  has
129           established  a  connection  with  a peer. Not sent if the transport
130           process has Type=accept. Remote is an arbitrary term that  uniquely
131           identifies  the  remote  endpoint  to  which the transport has con‐
132           nected. A LocalAddr list has the same  semantics  as  one  returned
133           from start/3.
134
135         {diameter, ack}:
136           Request   acknowledgements  of  unanswered  requests.  A  transport
137           process should send this once before passing incoming Diameter mes‐
138           sages  into  diameter.  As  a result, every Diameter request passed
139           into diameter with a recv message (below) will be answered  with  a
140           send  message (above), either a message() for the transport process
141           to send or the atom false if the request has been discarded or oth‐
142           erwise not answered.
143
144           This is to allow a transport process to keep count of the number of
145           incoming request messages that have not yet been answered  or  dis‐
146           carded,  to  allow  it  to regulate the amount of incoming traffic.
147           Both diameter_tcp and diameter_sctp request acknowledgements when a
148           message_cb  is configured, turning send/recv message into callbacks
149           that can be used to regulate traffic.
150
151         {diameter, {recv, message()}}:
152           An inbound Diameter message.
153
154         {diameter, {tls, Ref}}:
155           Acknowledgment of a successful TLS handshake.  Ref  is  the  refer‐
156           ence()  received  in the {diameter, {tls, Ref, Type, Bool}} message
157           in response to which the reply is sent. A transport must exit if  a
158           handshake is not successful.
159

SEE ALSO

161       diameter_tcp(3), diameter_sctp(3)
162
163
164
165Ericsson AB                     diameter 2.2.3           diameter_transport(3)
Impressum