diff options
Diffstat (limited to 'lib/diameter/doc/src')
-rw-r--r-- | lib/diameter/doc/src/diameter.xml | 20 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_app.xml | 37 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_codec.xml | 271 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_compile.xml | 55 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_dict.xml | 63 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_make.xml | 81 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_sctp.xml | 27 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_tcp.xml | 44 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_transport.xml | 82 | ||||
-rw-r--r-- | lib/diameter/doc/src/notes.xml | 4 | ||||
-rw-r--r-- | lib/diameter/doc/src/seealso.ent | 26 |
11 files changed, 541 insertions, 169 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index bc42b75c7a..3ad06156a2 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -1,5 +1,11 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY make_ref + '<seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso>'> + <!ENTITY transport_module + '<seealso marker="diameter_transport">transport module</seealso>'> + <!ENTITY dictionary + '<seealso marker="diameter_dict">dictionary</seealso>'> <!ENTITY % also SYSTEM "seealso.ent" > <!ENTITY % here SYSTEM "seehere.ent" > %also; @@ -298,7 +304,7 @@ Has one of the following types.</p> <item> <p> An address list is available to the start function of a -<seealso marker="diameter_transport">transport module</seealso>, which +&transport_module;, which can return a new list for use in the subsequent CER or CEA. Host-IP-Address need not be specified if the transport start function returns an address list.</p> @@ -464,7 +470,7 @@ that matches no peer.</p> <p> The <c>host</c> and <c>realm</c> filters examine the outgoing request as passed to &call;, -assuming that this is a record- or list-valued <c>&app_message;</c>, +assuming that this is a record- or list-valued <c>&codec_message;</c>, and that the message contains at most one of each AVP. If this is not the case then the <c>{host|realm, &dict_DiameterIdentity;}</c> filters must be used to achieve the desired result. @@ -529,8 +535,7 @@ connectivity.</p> <p> Note that a single <c>up</c>/<c>down</c> event for a given peer -corresponds to one -<seealso marker="diameter_app#Mod:peer_up-3">peer_up/peer_down</seealso> +corresponds to one &app_peer_up;/&app_peer_down; callback for each of the Diameter applications negotiated during capablilities exchange. That is, the event communicates connectivity with the @@ -677,7 +682,7 @@ info fields of forms other than the above.</p> The name of a service as passed to &start_service; and with which the service is identified. There can be at most one service with a given name on a given node. -Note that <seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso> +Note that &make_ref; can be used to generate a service name that is somewhat unique.</p> <marker id="service_opt"/> @@ -703,8 +708,7 @@ For an outgoing Diameter request, the relevant <c>&application_alias;</c> is passed to &call;, while for an incoming request the application identifier in the message header determines the application, the identifier being specified in -the application's <seealso marker="diameter_dict">dictionary</seealso> -file.</p> +the application's &dictionary; file.</p> </item> <tag><c>{restrict_connections, false @@ -1125,7 +1129,7 @@ its transports.</p> <type> <v>SvcName = &service_name;</v> <v>App = &application_alias;</v> -<v>Request = &app_message;</v> +<v>Request = &codec_message;</v> <v>Answer = term()</v> <v>Opt = &call_opt;</v> </type> diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index 304c69ebda..d1fbb9ba31 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -1,5 +1,8 @@ <?xml version="1.0" encoding="latin1" ?> <!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; @@ -124,39 +127,17 @@ mandatory values as the bare value.</p> <marker id="message"/> -<tag><c>message() = record() | list()</c></tag> +<tag><c>message() = &codec_message;</c></tag> <item> <p> The representation of a Diameter message as passed to -&mod_call;. -The record representation is as outlined in -<seealso -marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>: -a message as defined in a dictionary file is encoded as a record with -one field for each component AVP. -Equivalently, a message can also be encoded as a list whose head is -the atom-valued message name (the record name minus any -prefix specified in the relevant dictionary file) and whose tail is a -list of <c>{FieldName, FieldValue}</c> pairs.</p> - -<p> -A third representation allows a message to be specified as a list -whose head is a <c>#diameter_header{}</c> record and whose tail is a list -of <c>#diameter_avp{}</c> records. -This representation is used by diameter itself when relaying requests -as directed by the return value of a -&handle_request; -callback. -It differs from the other other two in that it bypasses the checks for -messages that do not agree with their definitions in the dictionary in -question (since relays agents must handle arbitrary request): messages -are sent exactly as specified.</p> +&mod_call; or returned from a &handle_request; callback.</p> </item> <marker id="packet"/> -<tag><c>packet() = #diameter_packet{}</c></tag> +<tag><c>packet() = &codec_packet;</c></tag> <item> <p> A container for incoming and outgoing Diameter messages that's passed @@ -505,8 +486,7 @@ 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 <seealso -marker="diameter_dict#MESSAGE_RECORDS">dictionary</seealso> declares +whose corresponding dictionary declares itself as defining either the application in question or the Relay application.</p> @@ -526,8 +506,7 @@ The argument &packet; has the following signature.</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 <seealso -marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>.</p> +in &dict;.</p> <p> The <c>errors</c> field specifies any Result-Code's identifying errors diff --git a/lib/diameter/doc/src/diameter_codec.xml b/lib/diameter/doc/src/diameter_codec.xml index 041616e54b..fb245936cf 100644 --- a/lib/diameter/doc/src/diameter_codec.xml +++ b/lib/diameter/doc/src/diameter_codec.xml @@ -1,5 +1,9 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY records + '<seealso marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>'> + <!ENTITY types + '<seealso marker="diameter_dict#DATA_TYPES">diameter_dict(4)</seealso>'> <!ENTITY % also SYSTEM "seealso.ent" > <!ENTITY % here SYSTEM "seehere.ent" > %also; @@ -38,44 +42,288 @@ under the License. </header> <module>diameter_codec</module> -<modulesummary>Diameter encode/decode.</modulesummary> +<modulesummary>Decode and encode of Diameter messages.</modulesummary> <description> <p> -</p> +Incoming Diameter messages are decoded from binary() before being +communicated to &man_app; callbacks. +Similarly, outgoing Diameter messages are encoded into binary() before +being passed to the appropriate &man_transport; module for +transmission. +The functions in this module implement this encode/decode.</p> + +<note> +<p> +Calls to this module are made by diameter itself as a consequence of +configuration passed to &mod_start_service;. +The encode/decode functions may also be useful for other purposes (eg. +test) but the diameter user does not need to call them explicitly when +sending and receiving messages using &mod_call; and the callback +interface documented in &man_app;.</p> +</note> + +<p> +The &header; and &packet; records below +are defined in diameter.hrl, which can be included as follows.</p> + +<pre> +-include_lib("diameter/include/diameter.hrl"). +</pre> + +<p> +Application-specific records are definied in the hrl +files resulting from dictionary file compilation.</p> </description> <!-- ===================================================================== --> +<section> +<title>DATA TYPES</title> + +<p></p> + +<taglist> + +<marker id="integers"/> + +<tag><c>uint8() = 0..255</c></tag> +<tag><c>uint24() = 0..16777215</c></tag> +<tag><c>uint32() = 0..4294967295</c></tag> +<item> +<p> +8-bit, 24-bit and 32-bit integers occurring in Diameter and AVP +headers.</p> +</item> + +<marker id="avp"/> + +<tag><c>avp() = #diameter_avp{}</c></tag> +<item> +<p> +The application-neutral representation of an AVP. +Primarily intended for use by relay applications that need to handle +arbitrary Diameter applications. +A service implementing a specific Diameter application +(for which it configures a dictionary) can manipulate values of type +&message; instead.</p> + +<p> +Fields have the following types.</p> + +<taglist> + +<tag><c>code = uint32()</c></tag> +<tag><c>is_mandatory = boolean()</c></tag> +<tag><c>need_encryption = boolean()</c></tag> +<tag><c>vendor_id = uint32() | undefined</c></tag> +<item> +<p> +Values in the AVP header, corresponding to AVP Code, the M flag, P +flags and Vendor-ID respectivelty. +A Vendor-ID other than <c>undefined</c> implies a set V flag.</p> +</item> + +<tag><c>data = iolist()</c></tag> +<item> +<p> +The data bytes of the AVP.</p> +</item> + +<tag><c>name = atom()</c></tag> +<item> +<p> +The name of the AVP as defined in the dictionary file in question, or +<c>undefined</c> if the AVP is unknown to the dictionary file in +question.</p> +</item> + +<tag><c>value = term()</c></tag> +<item> +<p> +The decoded value of an AVP. +Will be <c>undefined</c> on decode if the data bytes could +not be decoded or the AVP is unknown. +The type of a decoded value is as document in &types;.</p> +</item> + +<tag><c>type = atom()</c></tag> +<item> +<p> +The type of the AVP as specified in the dictionary file in question +(or one it inherits). +Possible types are <c>undefined</c> and the Diameter types: +<c>OctetString</c>, <c>Integer32</c>, <c>Integer64</c>, +<c>Unsigned32</c>, <c>Unsigned64</c>, <c>Float32</c>, <c>Float64</c>, +<c>Grouped</c>, <c>Enumerated</c>, <c>Address</c>, <c>Time</c>, +<c>UTF8String</c>, <c>DiameterIdentity</c>, <c>DiameterURI</c>, +<c>IPFilterRule</c> and <c>QoSFilterRule</c>.</p> +</item> + +</taglist> + +</item> + +<marker id="dictionary"/> + +<tag><c>dictionary() = module()</c></tag> +<item> + +<p> +The name of a generated dictionary module as generated by &man_compile; +or &make_codec;. +The interface provided by a dictionary module is an +implementation detail that may change.</p> +</item> + +<marker id="header"/> + +<tag><c>header() = #diameter_header{}</c></tag> +<item> +<p> +The record representation of the Diameter header. +Values in a &packet; returned by &decode; are as extracted from the +incoming message. +Values set in an &packet; passed to &encode; are preserved in the +encoded binary(), with the exception of <c>length</c>, <c>cmd_code</c> +and <c>application_id</c>, all of which are determined by the +&dictionary; in question.</p> + +<note> +<p> +It is not necessary to set header fields explicitly in outgoing +messages as diameter itself will set appropriate values. +Setting inappropriate values can be useful for test purposes.</p> +</note> + +<p> +Fields have the following types.</p> + +<taglist> + +<tag><c>version = uint8()</c></tag> +<tag><c>length = uint24()</c></tag> +<tag><c>cmd_code = uint24()</c></tag> +<tag><c>application_id = uint32()</c></tag> +<tag><c>hop_by_hop_id = uint32()</c></tag> +<tag><c>end_to_end_id = uint32()</c></tag> +<item> +<p> +Values of the Version, Message Length, Command-Code, Application-ID, +Hop-by-Hop Identifier and End-to-End Identifier fields of the Diameter +header.</p> +</item> + +<tag><c>is_request = boolean()</c></tag> +<tag><c>is_proxiable = boolean()</c></tag> +<tag><c>is_error = boolean()</c></tag> +<tag><c>is_retransmitted = boolean()</c></tag> +<item> +<p> +Values correspoding to the R(equest), P(roxiable), E(rror) +and T(Potentially re-transmitted message) flags of the Diameter +header.</p> +</item> + +</taglist> + +</item> + +<marker id="message"/> + +<tag><c>message() = record() | list()</c></tag> +<item> +<p> +The representation of a Diameter message as passed to +&mod_call; or returned from a &app_handle_request; callback. +The record representation is as outlined in &records;: +a message as defined in a dictionary file is encoded as a record with +one field for each component AVP. +Equivalently, a message can also be encoded as a list whose head is +the atom-valued message name (as specified in the relevant dictionary +file) and whose tail is a list of <c>{AvpName, AvpValue}</c> pairs.</p> + +<p> +Another list-valued representation allows a message to be specified +as a list whose head is a &header; and whose tail is an &avp; list. +This representation is used by diameter itself when relaying requests +as directed by the return value of a &app_handle_request; callback. +It differs from the other other two in that it bypasses the checks for +messages that do not agree with their definitions in the dictionary in +question: messages are sent exactly as specified.</p> + +</item> + +<marker id="packet"/> + +<tag><c>packet() = #diameter_packet{}</c></tag> +<item> +<p> +A container for incoming and outgoing Diameter messages. +Fields have the following types.</p> + +<taglist> + +<tag><c>header = &header;</c></tag> +<item> +</item> + +<tag><c>msg = &message;</c></tag> +<item> +</item> + +<tag><c>bin = binary()</c></tag> +<item> +</item> + +<tag><c>errors = [&dict_Unsigned32; | {&dict_Unsigned32;, avp()}]</c></tag> +<item> +</item> + +<tag><c>transport_data = term()</c></tag> +<item> +</item> + +</taglist> + +</item> + +</taglist> + +</section> + +<!-- ===================================================================== --> + <funcs> <func> -<name>decode(Mod, Bin) -> #diameter_packet{}</name> -<fsummary>Decode an incoming Diameter message.</fsummary> +<name>decode(Mod, Bin) -> &packet;</name> +<fsummary>Decode a Diameter message.</fsummary> <type> -<v></v> -<v></v> +<v>Mod = &dictionary;</v> +<v>Bin = binary()</v> </type> <desc> <p> -</p> +Decode a Diameter message.</p> </desc> </func> <func> <name>encode(Mod, Msg) -> binary()</name> -<fsummary>Encode an outgoing Diameter message.</fsummary> +<fsummary>Encode a Diameter message.</fsummary> <type> -<v></v> -<v></v> +<v>Mod = &dictionary;</v> +<v>Msg = &message; | &packet;</v> </type> <desc> <p> +Encode a Diameter message. </p> </desc> @@ -90,8 +338,7 @@ under the License. <title>SEE ALSO</title> <p> -&man_main;, -&man_dict;</p> +&man_compile;, &man_app;, &man_dict;, &man_make;</p> </section> diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameter_compile.xml index eb6de80c11..0bd7ad1789 100644 --- a/lib/diameter/doc/src/diameter_compile.xml +++ b/lib/diameter/doc/src/diameter_compile.xml @@ -1,5 +1,7 @@ <?xml version="1.0" encoding="iso-8859-1" ?> <!DOCTYPE comref SYSTEM "comref.dtd" [ + <!ENTITY dictionary + '<seealso marker="diameter_dict">dictionary file</seealso>'> <!ENTITY % also SYSTEM "seealso.ent" > <!ENTITY % here SYSTEM "seehere.ent" > %also; @@ -36,12 +38,14 @@ supplied. <description> <p> -The diameterc utility is used to compile diameter -<seealso marker="diameter_dict">dictionary files</seealso> -into Erlang source. -The resulting source implements the interface diameter requires +The diameterc utility is used to compile a diameter +&dictionary; into Erlang source. +The resulting source implements the interface diameter required to encode and decode the dictionary's messages and AVP's.</p> +<p> +The module &man_make; provides an alternate compilation interface.</p> + </description> <section> @@ -52,53 +56,52 @@ to encode and decode the dictionary's messages and AVP's.</p> <tag><![CDATA[diameterc [<options>] <file>]]></tag> <item> <p> -Compiles a single dictionary file. Valid options are as follows.</p> - -<!-- Leave -h/d/v undocumented, except for the usage message from the - utility itself. --> - -<taglist> -<tag><![CDATA[-o <dir>]]></tag> -<item> -<p> -Specifies the directory into which the generated source should be written. -Defaults to the current working directory.</p> -</item> +Compile a single dictionary file to Erlang source. +Valid options are as follows.</p> <tag><![CDATA[-i <dir>]]></tag> <item> <p> -Specifies a directory to add to the code path. +Prepend the specified directory to the code path. Use to point at beam files compiled from inherited dictionaries, -<c>@inherits</c> in a dictionary file creating a beam dependency, not -an erl/hrl dependency.</p> +<c>&dict_inherits;</c> in a dictionary file creating a beam +dependency, not an erl/hrl dependency.</p> <p> Multiple <c>-i</c> options can be specified.</p> </item> +<taglist> +<tag><![CDATA[-o <dir>]]></tag> +<item> +<p> +Write generated source to the specified directory. +Defaults to the current working directory.</p> +</item> + <tag><![CDATA[-E]]></tag> <tag><![CDATA[-H]]></tag> <item> <p> -Supresses erl and hrl generation, respectively.</p> +Supress erl and hrl generation, respectively.</p> </item> <tag><![CDATA[--name <name>]]></tag> <tag><![CDATA[--prefix <prefix>]]></tag> <item> <p> -Set <c>@name</c> and <c>@prefix</c> in the dictionary, -respectively. +Set <c>&dict_name;</c> or <c>&dict_prefix;</c> to the specified +string. Overrides any setting in the file itself.</p> </item> <tag><![CDATA[--inherits <dict>]]></tag> <item> <p> -Append an <c>@inherits</c> to the dictionary before compiling. -Specifying <c>'-'</c> as the dictionary has the effect of clearing any -previous inherits, causing them to be ignored.</p> +Append &dict_inherits; of the specified module. +Specifying <c>"-"</c> has the effect of discarding clearing any +previous inherits, both in the dictionary file and on the options +list.</p> <p> Multiple <c>--inherits</c> options can be specified.</p> @@ -127,7 +130,7 @@ Returns 0 on success, non-zero on failure.</p> <title>SEE ALSO</title> <p> -&man_dict;</p> +&man_make;, &man_dict;</p> </section> diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 4a6cccc276..eb6cf9ba86 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -1,5 +1,11 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "fileref.dtd" [ + <!ENTITY format + '<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso>'> + <!ENTITY records + '<seealso marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso>'> + <!ENTITY types + '<seealso marker="#DATA_TYPES">DATA TYPES</seealso>'> <!ENTITY % also SYSTEM "seealso.ent" > <!ENTITY % here SYSTEM "seehere.ent" > %also; @@ -45,29 +51,28 @@ under the License. <description> <p> -A diameter service as configured with &mod_start_service; +A diameter service, as configured with &mod_start_service;, specifies one or more supported Diameter applications. Each Diameter application specifies a dictionary module that knows how to encode and decode its messages and AVPs. The dictionary module is in turn generated from a file that defines these messages and AVPs. -The format of such a file is defined in -<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso> below. +The format of such a file is defined in &format; below. Users add support for their specific applications by creating dictionary files, compiling them to Erlang modules using -<seealso marker="diameterc">diameterc</seealso> and configuring the +either &man_compile; or &man_make; and configuring the resulting dictionaries modules on a service.</p> <p> -The codec generation also results in a hrl file that defines records -for the messages and grouped AVPs defined for the application, these -records being what a user of the diameter application sends and receives. -(Modulo other available formats as discussed in &man_app;.) +Dictionary module generation also results in a hrl file that defines +records for the messages and Grouped AVPs defined by the +dictionary, these records being what a user of the diameter +application sends and receives, modulo other possible formats as +discussed in &man_app;. These records and the underlying Erlang data types corresponding to -Diameter data formats are discussed in <seealso -marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso> and <seealso -marker="#DATA_TYPES">DATA TYPES</seealso> respectively. -The generated hrl also contains defines for the possible values of +Diameter data formats are discussed in &records; and &types; +respectively. +The generated hrl also contains macro definitions for the possible values of AVPs of type Enumerated.</p> <p> @@ -111,6 +116,8 @@ The order in which sections are specified is unimportant.</p> <taglist> +<marker id="id"/> + <tag><c>@id Number</c></tag> <item> <p> @@ -134,6 +141,8 @@ Example:</p> </item> +<marker id="name"/> + <tag><c>@name Mod</c></tag> <item> <p> @@ -155,6 +164,8 @@ Example:</p> </item> +<marker id="prefix"/> + <tag><c>@prefix Name</c></tag> <item> <p> @@ -178,6 +189,8 @@ Example:</p> </item> +<marker id="vendor"/> + <tag><c>@vendor Number Name</c></tag> <item> <p> @@ -198,6 +211,8 @@ Example:</p> </item> +<marker id="avp_vendor_id"/> + <tag><c>@avp_vendor_id Number</c></tag> <item> <p> @@ -218,6 +233,8 @@ Region-Set </item> +<marker id="inherits"/> + <tag><c>@inherits Mod</c></tag> <item> <p> @@ -253,6 +270,8 @@ Example:</p> </item> +<marker id="avp_types"/> + <tag><c>@avp_types</c></tag> <item> <p> @@ -263,7 +282,7 @@ The section consists of definitions of the form</p> <p> where Code is the integer AVP code, Type identifies an AVP Data Format -as defined in <seealso marker="#DATA_TYPES">DATA TYPES</seealso> below, +as defined in section &types; below, and Flags is a string of V, M and P characters indicating the flags to be set on an outgoing AVP or a single <c>'-'</c> (minus) character if none are to be set.</p> @@ -287,6 +306,8 @@ to conform to the current draft standard.</p> </item> +<marker id="custom_types"/> + <tag><c>@custom_types Mod</c></tag> <item> <p> @@ -308,6 +329,8 @@ Framed-IP-Address </pre> </item> +<marker id="codecs"/> + <tag><c>@codecs Mod</c></tag> <item> <p> @@ -325,6 +348,8 @@ Framed-IP-Address </pre> </item> +<marker id="messages"/> + <tag><c>@messages</c></tag> <item> <p> @@ -370,6 +395,8 @@ RTA ::= < Diameter Header: 287, PXY > </item> +<marker id="grouped"/> + <tag><c>@grouped</c></tag> <item> <p> @@ -395,6 +422,8 @@ Specifying a Vendor-Id in the definition of a grouped AVP is equivalent to specifying it with <c>@avp_vendor_id</c>.</p> </item> +<marker id="enum"/> + <tag><c>@enum Name</c></tag> <item> <p> @@ -421,6 +450,8 @@ REMOVE_SIP_SERVER 3 </pre> </item> +<marker id="end"/> + <tag><c>@end</c></tag> <item> <p> @@ -447,8 +478,8 @@ The hrl generated from a dictionary specification defines records for the messages and grouped AVPs defined in <c>@messages</c> and <c>@grouped</c> sections. For each message or grouped AVP definition, a record is defined whose -name is the message or AVP name prefixed with any dictionary prefix -defined with <c>@prefix</c> and whose fields are the names of the AVPs +name is the message or AVP name, prefixed with any dictionary prefix +defined with <c>@prefix</c>, and whose fields are the names of the AVPs contained in the message or grouped AVP in the order specified in the definition in question. For example, the grouped AVP</p> @@ -640,7 +671,7 @@ Values of these types are not currently parsed by diameter.</p> <title>SEE ALSO</title> <p> -&man_compile;, &man_main;, &man_app;</p> +&man_compile;, &man_main;, &man_app;, &man_codec;, &man_make;</p> </section> diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml index aee98d62d2..da6124310e 100644 --- a/lib/diameter/doc/src/diameter_make.xml +++ b/lib/diameter/doc/src/diameter_make.xml @@ -1,5 +1,9 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY filename + '<seealso marker="kernel:file#type-name">file:name()</seealso>'> + <!ENTITY dictionary + '<seealso marker="diameter_dict">dictionary file</seealso>'> <!ENTITY % also SYSTEM "seealso.ent" > <!ENTITY % here SYSTEM "seehere.ent" > %also; @@ -43,7 +47,14 @@ under the License. <description> <p> -</p> +The function &codec; is used to compile a diameter +&dictionary; into Erlang source. +The resulting source implements the interface diameter required +to encode and decode the dictionary's messages and AVP's.</p> + +<p> +The utility &man_compile; provides an alternate compilation +interface.</p> </description> @@ -52,16 +63,56 @@ under the License. <funcs> <func> -<name>codec(Name) -> ok</name> -<fsummary>Compile a dictionary into a codec module.</fsummary> -<type> -<v></v> -<v></v> -</type> +<name>codec(Path::string(), [Opt]) -> ok | {error, Reason}</name> +<fsummary>Compile a dictionary file into Erlang source.</fsummary> <desc> <p> -</p> +Compile a single dictionary file to Erlang source. +<c>Opt</c> can have the following types.</p> + +<taglist> + +<tag><c>{include, Dir::string()}</c></tag> +<item> +<p> +Prepend the specified directory to the code path. +Use to point at beam files compiled from inherited dictionaries, +<c>&dict_inherits;</c> in a dictionary file creating a beam +dependency, not an erl/hrl dependency.</p> + +<p> +Multiple <c>include</c> options can be specified.</p> +</item> + +<tag><c>{outdir, Dir::string()}</c></tag> +<item> +<p> +Write generated source to the specified directory. +Defaults to the current working directory.</p> +</item> + +<tag><c>{name|prefix, string()}</c></tag> +<item> +<p> +Set <c>&dict_name;</c> or <c>&dict_prefix;</c> to the specified +string. +Overrides any setting in the file itself.</p> +</item> + +<tag><c>{inherits, Mod::string()}</c></tag> +<item> +<p> +Append &dict_inherits; of the specified module. +Specifying <c>"-"</c> has the effect of discarding clearing any +previous inherits, both in the dictionary file and on the options +list.</p> + +<p> +Multiple <c>inherits</c> options can be specified.</p> +</item> + +</taglist> </desc> </func> @@ -69,14 +120,24 @@ under the License. </funcs> <!-- ===================================================================== --> + +<section> +<title>BUGS</title> + +<p> +All options are string-valued. +In particular, it is not currently possible to +an &dict_inherits; module as an atom() or a path as a &filename;</p> + +</section> + <!-- ===================================================================== --> <section> <title>SEE ALSO</title> <p> -&man_main;, -&man_dict;</p> +&man_compile;, &man_dict;</p> </section> diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml index a023a9bc08..5e3fd5eaf1 100644 --- a/lib/diameter/doc/src/diameter_sctp.xml +++ b/lib/diameter/doc/src/diameter_sctp.xml @@ -1,5 +1,11 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY gen_sctp '<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>'> + <!ENTITY gen_sctp_open1 + '<seealso marker="kernel:gen_sctp#open-1">gen_sctp:open/1</seealso>'> + <!ENTITY ip_address + '<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>'> + <!ENTITY inet '<seealso marker="kernel:inet">inet(3)</seealso>'> <!ENTITY % also SYSTEM "seealso.ent" > <!ENTITY % here SYSTEM "seehere.ent" > %also; @@ -43,8 +49,7 @@ under the License. <description> <p> -This module implements diameter transport over SCTP using <seealso -marker="kernel:gen_sctp">gen_sctp</seealso>. +This module implements diameter transport over SCTP using &gen_sctp;. It can be specified as the value of a transport_module option to &mod_add_transport; and implements the behaviour documented in @@ -65,9 +70,9 @@ and implements the behaviour documented in <v>Type = connect | accept</v> <v>Ref = &mod_transport_ref;</v> <v>Svc = #diameter_service{}</v> -<v>Opt = {raddr, <seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>} | {rport, integer()} | term()</v> +<v>Opt = {raddr, &ip_address;} | {rport, integer()} | term()</v> <v>Pid = pid()</v> -<v>LAddr = <seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso></v> +<v>LAddr = &ip_address;</v> <v>Reason = term()</v> </type> <desc> @@ -84,8 +89,7 @@ unspecified. More than one <c>raddr</c> option can be specified, in which case the connecting transport in question attempts each in sequence until an association is established. -Remaining options are any accepted by <seealso -marker="kernel:gen_sctp#open-1">gen_sctp:open/1</seealso>, with the exception +Remaining options are any accepted by &gen_sctp_open1;, with the exception of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c> and <c>sctp_events</c>. Note that options <c>ip</c> and <c>port</c> specify the local address @@ -102,14 +106,12 @@ connecting transport.</p> <warning> <p> An insufficiently large receive buffer may result in a peer having to -resend incoming messages: set the <seealso -marker="kernel:inet">inet(3)</seealso> option <c>recbuf</c> to increase +resend incoming messages: set the &inet; option <c>recbuf</c> to increase the buffer size.</p> <p> An insufficiently large send buffer may result in outgoing messages -being discarded: set the <seealso -marker="kernel:inet">inet(3)</seealso> option <c>sndbuf</c> to increase +being discarded: set the &inet; option <c>sndbuf</c> to increase the buffer size.</p> </warning> @@ -145,10 +147,7 @@ outbound streams.</p> <title>SEE ALSO</title> <p> -&man_main;, -&man_transport;, -<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>, -<seealso marker="kernel:inet">inet(3)</seealso></p> +&man_main;, &man_transport;, &gen_sctp;, &inet;</p> </section> diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml index be8a938115..901fce32c3 100644 --- a/lib/diameter/doc/src/diameter_tcp.xml +++ b/lib/diameter/doc/src/diameter_tcp.xml @@ -1,5 +1,22 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY gen_tcp_connect3 + '<seealso marker="kernel:gen_tcp#connect-3">gen_tcp:connect/3</seealso>'> + <!ENTITY gen_tcp_listen2 + '<seealso marker="kernel:gen_tcp#listen-2">gen_tcp:listen/2</seealso>'> + <!ENTITY ip_address + '<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>'> + <!ENTITY ssl_connect2 + '<seealso marker="ssl:ssl#connect-2">ssl:connect/2</seealso>'> + <!ENTITY ssl_connect3 + '<seealso marker="ssl:ssl#connect-3">ssl:connect/3</seealso>'> + <!ENTITY ssl_accept2 + '<seealso marker="ssl:ssl#ssl_accept-2">ssl:ssl_accept/2</seealso>'> + <!ENTITY ssl_listen2 + '<seealso marker="ssl:ssl#listen-2">ssl:listen/2</seealso>'> + <!ENTITY gen_tcp '<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>'> + <!ENTITY inet '<seealso marker="kernel:inet">inet(3)</seealso>'> + <!ENTITY ssl '<seealso marker="ssl:ssl">ssl(3)</seealso>'> <!ENTITY % also SYSTEM "seealso.ent" > <!ENTITY % here SYSTEM "seehere.ent" > %also; @@ -43,8 +60,7 @@ under the License. <description> <p> -This module implements diameter transport over TCP using <seealso -marker="kernel:gen_tcp">gen_tcp</seealso>. +This module implements diameter transport over TCP using &gen_tcp;. It can be specified as the value of a <c>transport_module</c> option to &mod_add_transport; and implements the behaviour documented in @@ -74,9 +90,9 @@ before configuring TLS capability on diameter transports.</p> <v>Svc = #diameter_service{}</v> <v>Opt = OwnOpt | SslOpt | TcpOpt</v> <v>Pid = pid()</v> -<v>LAddr = <seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso></v> +<v>LAddr = &ip_address;</v> <v>Reason = term()</v> -<v>OwnOpt = {raddr, <seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>} +<v>OwnOpt = {raddr, &ip_address;} | {rport, integer()} | {port, integer()}</v> <v>SslOpt = {ssl_options, true | list()}</v> @@ -95,16 +111,12 @@ transport. Option <c>ssl_options</c> must be specified for a transport that should support TLS: a value of <c>true</c> results in a TLS handshake immediately upon connection establishment while -<c>list()</c> specifies options to be passed to <seealso -marker="ssl:ssl#connect-2">ssl:connect/2</seealso> or -<seealso marker="ssl:ssl#ssl_accept-2">ssl:ssl_accept/2</seealso> +<c>list()</c> specifies options to be passed to &ssl_connect2; or +&ssl_accept2; after capabilities exchange if TLS is negotiated. -Remaining options are any accepted by <seealso -marker="ssl:ssl#connect-3">ssl:connect/3</seealso> or <seealso -marker="kernel:gen_tcp#connect-3">gen_tcp:connect/3</seealso> for -a connecting transport, or <seealso -marker="ssl:ssl#listen-2">ssl:listen/2</seealso> or <seealso -marker="kernel:gen_tcp#listen-2">gen_tcp:listen/2</seealso> for +Remaining options are any accepted by &ssl_connect3; or +&gen_tcp_connect3; for +a connecting transport, or &ssl_listen2; or &gen_tcp_listen2; for a listening transport, depending on whether or not <c>{ssl_options, true}</c> has been specified. Options <c>binary</c>, @@ -150,11 +162,7 @@ The returned local address list has length one.</p> <title>SEE ALSO</title> <p> -&man_main;, -&man_transport;, -<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>, -<seealso marker="kernel:inet">inet(3)</seealso>, -<seealso marker="ssl:ssl">ssl(3)</seealso></p> +&man_main;, &man_transport;, &gen_tcp;, &inet;, &ssl;</p> </section> diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index 0507af63a8..55b531155f 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -1,5 +1,8 @@ <?xml version="1.0" encoding="latin1" ?> <!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; @@ -50,16 +53,49 @@ 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> @@ -67,7 +103,7 @@ parent).</p> <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> @@ -79,8 +115,8 @@ 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> @@ -90,13 +126,12 @@ that has lead to starting of a transport process.</p> <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> +&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 -&mod_transport_opt; -list passed to &mod_add_transport;.</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 @@ -114,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> @@ -130,19 +165,15 @@ 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> @@ -185,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> @@ -208,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> diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml index b89d84a4f6..7f3cdab075 100644 --- a/lib/diameter/doc/src/notes.xml +++ b/lib/diameter/doc/src/notes.xml @@ -428,7 +428,7 @@ Known issues or limitations:</p> Some agent-related functionality is not entirely complete. In particular, support for proxy agents, that advertise specific Diameter applications but otherwise relay messages in much the same -way as relay agents (for which a &handle_request; +way as relay agents (for which a handle_request callback can return a <c>relay</c> tuple), will be completed in an upcoming release. There may also be more explicit support for redirect agents, although @@ -460,7 +460,7 @@ could likely be expanded upon.</p> <item> <p> -The function &service_info; +The function diameter:service_info/2 can be used to retrieve information about a started service (statistics, information about connected peers, etc) but this is not yet documented and both the input and output may change diff --git a/lib/diameter/doc/src/seealso.ent b/lib/diameter/doc/src/seealso.ent index 6f67630220..435dfda326 100644 --- a/lib/diameter/doc/src/seealso.ent +++ b/lib/diameter/doc/src/seealso.ent @@ -77,12 +77,21 @@ significant. <!ENTITY app_prepare_request '<seealso marker="diameter_app#Mod:prepare_request-3">prepare_request/3</seealso>'> <!ENTITY app_capabilities '<seealso marker="diameter_app#capabilities">diameter_app:capabilities()</seealso>'> -<!ENTITY app_message '<seealso marker="diameter_app#message">diameter_app:message()</seealso>'> -<!ENTITY app_packet '<seealso marker="diameter_app#packet">diameter_app:packet()</seealso>'> <!ENTITY app_peer '<seealso marker="diameter_app#peer">diameter_app:peer()</seealso>'> <!ENTITY app_peer_ref '<seealso marker="diameter_app#peer_ref">diameter_app:peer_ref()</seealso>'> <!ENTITY app_state '<seealso marker="diameter_app#state">diameter_app:state()</seealso>'> +<!-- diameter_codec --> + +<!ENTITY codec_encode '<seealso marker="diameter_codec#encode-2">diameter_codec:encode/2</seealso>'> +<!ENTITY codec_decode '<seealso marker="diameter_codec#decode-2">diameter_codec:decode/2</seealso>'> + +<!ENTITY codec_avp '<seealso marker="diameter_codec#avp">diameter_codec:avp()</seealso>'> +<!ENTITY codec_header '<seealso marker="diameter_codec#header">diameter_codec:header()</seealso>'> +<!ENTITY codec_dictionary '<seealso marker="diameter_codec#dictionary">diameter_codec:dictionary()</seealso>'> +<!ENTITY codec_message '<seealso marker="diameter_codec#message">diameter_codec:message()</seealso>'> +<!ENTITY codec_packet '<seealso marker="diameter_codec#packet">diameter_codec:packet()</seealso>'> + <!-- diameter_dict --> <!ENTITY dict_data_types '<seealso marker="diameter_dict#DATA_TYPES">diameter_dict(4)</seealso>'> @@ -95,6 +104,14 @@ significant. <!ENTITY dict_UTF8String '<seealso marker="diameter_dict#DATA_TYPES">UTF8String()</seealso>'> <!ENTITY dict_Unsigned32 '<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>'> +<!ENTITY dict_name '<seealso marker="diameter_dict#name">@name</seealso>'> +<!ENTITY dict_prefix '<seealso marker="diameter_dict#prefix">@prefix</seealso>'> +<!ENTITY dict_inherits '<seealso marker="diameter_dict#inherits">@inherits</seealso>'> + +<!-- diameter_make --> + +<!ENTITY make_codec '<seealso marker="diameter_make#codec-2">diameter_make:codec/2</seealso>'> + <!-- diameter_transport --> <!ENTITY transport_start @@ -105,8 +122,9 @@ significant. <!ENTITY man_compile '<seealso marker="diameterc">diameterc(1)</seealso>'> <!ENTITY man_main '<seealso marker="diameter">diameter(3)</seealso>'> <!ENTITY man_app '<seealso marker="diameter_app">diameter_app(3)</seealso>'> +<!ENTITY man_codec '<seealso marker="diameter_codec">diameter_codec(3)</seealso>'> <!ENTITY man_dict '<seealso marker="diameter_dict">diameter_dict(4)</seealso>'> -<!ENTITY man_transport - '<seealso marker="diameter_transport">diameter_transport(3)</seealso>'> +<!ENTITY man_make '<seealso marker="diameter_make">diameter_make(3)</seealso>'> +<!ENTITY man_transport '<seealso marker="diameter_transport">diameter_transport(3)</seealso>'> <!ENTITY man_sctp '<seealso marker="diameter_sctp">diameter_sctp(3)</seealso>'> <!ENTITY man_tcp '<seealso marker="diameter_tcp">diameter_tcp(3)</seealso>'> |