1diameter_transport(3) Erlang Module Definition diameter_transport(3)
2
6 diameter_transport - Diameter transport interface.
7
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
16 message() = binary() | diameter_codec:packet():
17 A Diameter message as passed over the transport interface.
18 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 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
31 Mod:start({Type, Ref}, Svc, Config) -> {ok, Pid} | {ok, Pid, LAddrs} |
32 {error, Reason}
33 Types:
35 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 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 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 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 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 Config is as passed in transport_config tuple in the diame‐
64 ter:transport_opt() list passed to diameter:add_transport/2.
65 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 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
82 All messages sent over the transport interface are of the form {diame‐
83 ter, term()}.
84 A transport process can expect messages of the following types from its
86 parent.
87 {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 {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 {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 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 This message is only sent to a transport process over whose Inband-
114 Security-Id configuration has indicated support for TLS.
115 A transport process should send messages of the following types to its
117 parent.
118 {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 {diameter, {self(), connected, Remote}}:
125 {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 {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 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 {diameter, {recv, message()}}:
152 An inbound Diameter message.
153 {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
161 diameter_tcp(3), diameter_sctp(3)
162Ericsson AB diameter 2.2.3 diameter_transport(3)