diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter_transport.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter_transport.xml | 114 |
1 files changed, 67 insertions, 47 deletions
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index d9b36a1e09..55b531155f 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -1,5 +1,13 @@ <?xml version="1.0" encoding="latin1" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> +<!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY message '<seealso marker="#message">message()</seealso>'> + <!ENTITY ip_address + '<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>'> + <!ENTITY % also SYSTEM "seealso.ent" > + <!ENTITY % here SYSTEM "seehere.ent" > + %also; + %here; +]> <erlref> <header> @@ -38,66 +46,92 @@ under the License. <description> <p> -A module specified as a <c>transport_module</c> to <seealso -marker="diameter#add_transport">diameter:add_transport/2</seealso> +A module specified as a <c>transport_module</c> to &mod_add_transport; must implement the interface documented here. The interface consists of a function with which diameter starts a transport process and a message interface with which the transport process communicates with the process that starts it (aka its parent).</p> -<marker id="start"/> </description> <!-- ===================================================================== --> +<section> +<title>DATA TYPES</title> + +<taglist> + +<marker id="message"/> + +<tag><c>message() = binary() | &codec_packet;</c></tag> +<item> +<p> +A Diameter message as passed over the transport interface.</p> + +<p> +For an inbound message from a transport process, a &codec_packet; must +contain the received message in its <c>bin</c> field. +In the case of an inbound request, any value set in the +<c>transport_data</c> field will passed back to the transport module +in the corresponding answer message, unless the sender supplies +another value.</p> + +<p> +For an outbound message to a transport process, a &codec_packet; has a +value other than <c>undefined</c> in its <c>transport_data</c> field +and has the binary() to send in its <c>bin</c> field.</p> +</item> + +</taglist> + +</section> + +<!-- ===================================================================== --> + <funcs> <func> <name>Mod:start({Type, Ref}, Svc, Config) - -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason}</name> + -> {ok, Pid} + | {ok, Pid, LAddrs} + | {error, Reason}</name> <fsummary>Start a transport process.</fsummary> <type> <v>Type = connect | accept</v> -<v>Ref = <seealso marker="diameter#transport_ref">diameter:transport_ref()</seealso></v> +<v>Ref = &mod_transport_ref;</v> <v>Svc = #diameter_service{}</v> <v>Config = term()</v> <v>Pid = pid()</v> -<v>LAddrs = [<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>]</v> +<v>LAddrs = [&ip_address;]</v> <v>Reason = term()</v> </type> <desc> <p> Start a transport process. -Called by diameter as a consequence of a call to <seealso -marker="diameter#add_transport">diameter:add_transport/2</seealso> in +Called by diameter as a consequence of a call to &mod_add_transport; in order to establish or accept a transport connection respectively. A transport process maintains a connection with a single remote peer.</p> <p> <c>Type</c> indicates whether the transport process in question -is being started for a connecting (<c>connect</c>) or listening -(<c>accept</c>) transport. +is being started for a connecting (<c>Type=connect</c>) or listening +(<c>Type=accept</c>) transport. In the latter case, transport processes are started as required to accept connections from multiple peers.</p> <p> -Ref is the value that was returned from the call to <seealso -marker="diameter#add_transport">diameter:add_transport/2</seealso> +Ref is the value that was returned from the call to &mod_add_transport; that has lead to starting of a transport process.</p> <p> -<c>Svc</c> contains the capabilities passed to <seealso -marker="diameter#start_service">diameter:start_service/2</seealso> and -<seealso -marker="diameter#add_transport">diameter:add_transport/2</seealso>, -values passed to the latter overriding those passed to the former.</p> +<c>Svc</c> contains the capabilities passed to &mod_start_service; and +&mod_add_transport;, values passed to the latter overriding those +passed to the former.</p> <p> <c>Config</c> is as passed in <c>transport_config</c> tuple in the -<seealso marker="diameter#transport_opt">diameter:transport_opt()</seealso> -list passed to <seealso -marker="diameter#add_transport">diameter:add_transport/2</seealso>.</p> +&mod_transport_opt; list passed to &mod_add_transport;.</p> <p> The start function should use the <c>Host-IP-Address</c> list and/or @@ -115,13 +149,13 @@ it dies. It should not link to the parent. It should exit if its transport connection with its peer is lost.</p> -<marker id="MESSAGES"/> </desc> </func> </funcs> <!-- ===================================================================== --> +<marker id="MESSAGES"/> <section> <title>MESSAGES</title> @@ -131,27 +165,23 @@ All messages sent over the transport interface are of the form <c>{diameter, term()}</c>.</p> <p> -A transport process can expect the following messages from -diameter.</p> +A transport process can expect messages of the following types from +its parent.</p> <taglist> -<tag><c>{diameter, {send, Packet}}</c></tag> +<tag><c>{diameter, {send, &message;}}</c></tag> <item> <p> -An outbound Diameter message. -<c>Packet</c> can be either binary() (the message to be sent) -or a <c>#diameter_packet{}</c> record whose <c>transport_data</c> -field contains a value other than undefined and whose <c>bin</c> field -contains the binary to send.</p> +An outbound Diameter message.</p> </item> <tag><c>{diameter, {close, Pid}}</c></tag> <item> <p> -A request to close the transport connection. -The transport process should terminate after closing the -connection. +A request to terminate the transport process after having received DPA +in response to DPR. +The transport process should exit. <c>Pid</c> is the pid() of the parent process.</p> </item> @@ -186,7 +216,7 @@ TLS.</p> </taglist> <p> -A transport process should send the following messages +A transport process should send messages of the following types to its parent.</p> <taglist> @@ -209,19 +239,10 @@ Not sent if the transport process has <c>Type=accept</c>. endpoint to which the transport has connected.</p> </item> -<tag><c>{diameter, {recv, Packet}}</c></tag> +<tag><c>{diameter, {recv, &message;}}</c></tag> <item> <p> -An inbound Diameter message. -<c>Packet</c> can be either binary() (the received message) -or a <c>#diameter_packet{}</c> record -whose <c>bin</c> field contains the received binary(). -Any value (other than <c>undefined</c>) set in -the <c>transport_data</c> field will be passed back with a -corresponding answer message in the case that the inbound message is a -request unless the sender sets another value. -How <c>transport_data</c> is used/interpreted is up to the -transport module.</p> +An inbound Diameter message.</p> </item> <tag><c>{diameter, {tls, Ref}}</c></tag> @@ -245,8 +266,7 @@ A transport must exit if a handshake is not successful.</p> <title>SEE ALSO</title> <p> -<seealso marker="diameter_tcp">diameter_tcp(3)</seealso>, -<seealso marker="diameter_sctp">diameter_sctp(3)</seealso></p> +&man_tcp;, &man_sctp;</p> </section> |