From f1ffd33240b982ec2ed80231a3a10f14cf5e3fc9 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Sun, 18 Nov 2012 20:14:34 +0100 Subject: Add reference pages diameter_codec(3) and diameter_make(3) Not yet any content to speak of. --- lib/diameter/doc/src/diameter_codec.xml | 98 +++++++++++++++++++++++++++++++++ lib/diameter/doc/src/diameter_make.xml | 83 ++++++++++++++++++++++++++++ lib/diameter/doc/src/files.mk | 2 + lib/diameter/doc/src/ref_man.xml | 3 + 4 files changed, 186 insertions(+) create mode 100644 lib/diameter/doc/src/diameter_codec.xml create mode 100644 lib/diameter/doc/src/diameter_make.xml (limited to 'lib/diameter/doc/src') diff --git a/lib/diameter/doc/src/diameter_codec.xml b/lib/diameter/doc/src/diameter_codec.xml new file mode 100644 index 0000000000..041616e54b --- /dev/null +++ b/lib/diameter/doc/src/diameter_codec.xml @@ -0,0 +1,98 @@ + + + + %also; + %here; +]> + + +
+ +2012 +Ericsson AB. All Rights Reserved. + + +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. + + + +diameter_codec(3) +Anders Svensson + + + + + + +diameter_codec.xml +
+ +diameter_codec +Diameter encode/decode. + + + +

+

+ + + + + + + + +decode(Mod, Bin) -> #diameter_packet{} +Decode an incoming Diameter message. + + + + + + +

+

+ + + + + +encode(Mod, Msg) -> binary() +Encode an outgoing Diameter message. + + + + + + +

+

+ + + + + + + + + +
+SEE ALSO + +

+&man_main;, +&man_dict;

+ +
+ + diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml new file mode 100644 index 0000000000..aee98d62d2 --- /dev/null +++ b/lib/diameter/doc/src/diameter_make.xml @@ -0,0 +1,83 @@ + + + + %also; + %here; +]> + + +
+ +2012 +Ericsson AB. All Rights Reserved. + + +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. + + + +diameter_make(3) +Anders Svensson + + + + + + +diameter_make.xml +
+ +diameter_make +Diameter dictionary compilation. + + + +

+

+ + + + + + + + +codec(Name) -> ok +Compile a dictionary into a codec module. + + + + + + +

+

+ + + + + + + + + +
+SEE ALSO + +

+&man_main;, +&man_dict;

+ +
+ + diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk index 89ec1031e6..00ced3d91e 100644 --- a/lib/diameter/doc/src/files.mk +++ b/lib/diameter/doc/src/files.mk @@ -26,6 +26,8 @@ XML_REF1_FILES = \ XML_REF3_FILES = \ diameter.xml \ diameter_app.xml \ + diameter_codec.xml \ + diameter_make.xml \ diameter_transport.xml \ diameter_tcp.xml \ diameter_sctp.xml diff --git a/lib/diameter/doc/src/ref_man.xml b/lib/diameter/doc/src/ref_man.xml index 137ce79094..4b99fe716d 100644 --- a/lib/diameter/doc/src/ref_man.xml +++ b/lib/diameter/doc/src/ref_man.xml @@ -6,6 +6,7 @@
2011 +2012 Ericsson AB. All Rights Reserved. @@ -40,7 +41,9 @@ applications on top of the Diameter protocol.

+ + -- cgit v1.2.3 From 67ffc483c80d29334c6c7739bcf1be756f374dfb Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Tue, 20 Nov 2012 13:11:19 +0100 Subject: Add content to diameter_codec(3) and diameter_make(3) --- lib/diameter/doc/src/diameter.xml | 20 +- lib/diameter/doc/src/diameter_app.xml | 37 +--- lib/diameter/doc/src/diameter_codec.xml | 271 ++++++++++++++++++++++++++-- lib/diameter/doc/src/diameter_compile.xml | 55 +++--- lib/diameter/doc/src/diameter_dict.xml | 63 +++++-- lib/diameter/doc/src/diameter_make.xml | 81 ++++++++- lib/diameter/doc/src/diameter_sctp.xml | 27 ++- lib/diameter/doc/src/diameter_tcp.xml | 44 +++-- lib/diameter/doc/src/diameter_transport.xml | 82 ++++++--- lib/diameter/doc/src/notes.xml | 4 +- lib/diameter/doc/src/seealso.ent | 26 ++- 11 files changed, 541 insertions(+), 169 deletions(-) (limited to 'lib/diameter/doc/src') 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 @@ erlang:make_ref/0'> + transport module'> + dictionary'> %also; @@ -298,7 +304,7 @@ Has one of the following types.

An address list is available to the start function of a -transport module, 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.

@@ -464,7 +470,7 @@ that matches no peer.

The host and realm filters examine the outgoing request as passed to &call;, -assuming that this is a record- or list-valued &app_message;, +assuming that this is a record- or list-valued &codec_message;, and that the message contains at most one of each AVP. If this is not the case then the {host|realm, &dict_DiameterIdentity;} filters must be used to achieve the desired result. @@ -529,8 +535,7 @@ connectivity.

Note that a single up/down event for a given peer -corresponds to one -peer_up/peer_down +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.

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 erlang:make_ref/0 +Note that &make_ref; can be used to generate a service name that is somewhat unique.

@@ -703,8 +708,7 @@ For an outgoing Diameter request, the relevant &application_alias; 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 dictionary -file.

+the application's &dictionary; file.

 {restrict_connections, false @@ -1125,7 +1129,7 @@ its transports.

SvcName = &service_name; App = &application_alias; -Request = &app_message; +Request = &codec_message; Answer = term() Opt = &call_opt; 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 @@ message()'> + diameter_dict(4)'> %also; @@ -124,39 +127,17 @@ mandatory values as the bare value.

-message() = record() | list() +message() = &codec_message;

The representation of a Diameter message as passed to -&mod_call;. -The record representation is as outlined in -diameter_dict(4): -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 {FieldName, FieldValue} pairs.

- -

-A third representation allows a message to be specified as a list -whose head is a #diameter_header{} record and whose tail is a list -of #diameter_avp{} 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.

+&mod_call; or returned from a &handle_request; callback.

 -packet() = #diameter_packet{} +packet() = &codec_packet;

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 dictionary declares +whose corresponding dictionary declares itself as defining either the application in question or the Relay application.

@@ -526,8 +506,7 @@ The argument &packet; has the following signature.

The msg field will be undefined in case the request has been received in the relay application. Otherwise it contains the record representing the request as outlined -in diameter_dict(4).

+in &dict;.

The errors 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 @@ diameter_dict(4)'> + diameter_dict(4)'> %also; @@ -38,44 +42,288 @@ under the License.

diameter_codec -Diameter encode/decode. +Decode and encode of Diameter messages.

-

+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.

+ + +

+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;.

+ + +

+The &header; and &packet; records below +are defined in diameter.hrl, which can be included as follows.

+ +
+-include_lib("diameter/include/diameter.hrl").
+
+ +

+Application-specific records are definied in the hrl +files resulting from dictionary file compilation.

 +
+DATA TYPES + +

+ + + + + +uint8()  = 0..255 +uint24() = 0..16777215 +uint32() = 0..4294967295 + +

+8-bit, 24-bit and 32-bit integers occurring in Diameter and AVP +headers.

+ + + + +avp() = #diameter_avp{} + +

+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.

+ +

+Fields have the following types.

+ + + +code = uint32() +is_mandatory = boolean() +need_encryption = boolean() +vendor_id = uint32() | undefined + +

+Values in the AVP header, corresponding to AVP Code, the M flag, P +flags and Vendor-ID respectivelty. +A Vendor-ID other than undefined implies a set V flag.

+ + +data = iolist() + +

+The data bytes of the AVP.

+ + +name = atom() + +

+The name of the AVP as defined in the dictionary file in question, or +undefined if the AVP is unknown to the dictionary file in +question.

+ + +value = term() + +

+The decoded value of an AVP. +Will be undefined 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;.

+ + +type = atom() + +

+The type of the AVP as specified in the dictionary file in question +(or one it inherits). +Possible types are undefined and the Diameter types: +OctetString, Integer32, Integer64, +Unsigned32, Unsigned64, Float32, Float64, +Grouped, Enumerated, Address, Time, +UTF8String, DiameterIdentity, DiameterURI, +IPFilterRule and QoSFilterRule.

+ + + + + + + + +dictionary() = module() + + +

+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.

+ + + + +header() = #diameter_header{} + +

+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 length, cmd_code +and application_id, all of which are determined by the +&dictionary; in question.

+ + +

+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.

+ + +

+Fields have the following types.

+ + + +version = uint8() +length = uint24() +cmd_code = uint24() +application_id = uint32() +hop_by_hop_id = uint32() +end_to_end_id = uint32() + +

+Values of the Version, Message Length, Command-Code, Application-ID, +Hop-by-Hop Identifier and End-to-End Identifier fields of the Diameter +header.

+ + +is_request = boolean() +is_proxiable = boolean() +is_error = boolean() +is_retransmitted = boolean() + +

+Values correspoding to the R(equest), P(roxiable), E(rror) +and T(Potentially re-transmitted message) flags of the Diameter +header.

+ + + + + + + + +message() = record() | list() + +

+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 {AvpName, AvpValue} pairs.

+ +

+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.

+ + + + + +packet() = #diameter_packet{} + +

+A container for incoming and outgoing Diameter messages. +Fields have the following types.

+ + + +header = &header; + + + +msg = &message; + + + +bin = binary() + + + +errors = [&dict_Unsigned32; | {&dict_Unsigned32;, avp()}] + + + +transport_data = term() + + + + + + + + + +
+ + + -decode(Mod, Bin) -> #diameter_packet{} -Decode an incoming Diameter message. +decode(Mod, Bin) -> &packet; +Decode a Diameter message. - - +Mod = &dictionary; +Bin = binary()

-

+Decode a Diameter message.

 encode(Mod, Msg) -> binary() -Encode an outgoing Diameter message. +Encode a Diameter message. - - +Mod = &dictionary; +Msg = &message; | &packet;

+Encode a Diameter message.

@@ -90,8 +338,7 @@ under the License. SEE ALSO

-&man_main;, -&man_dict;

+&man_compile;, &man_app;, &man_dict;, &man_make;

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 @@ dictionary file'> %also; @@ -36,12 +38,14 @@ supplied.

-The diameterc utility is used to compile diameter -dictionary files -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.

+

+The module &man_make; provides an alternate compilation interface.

+
@@ -52,53 +56,52 @@ to encode and decode the dictionary's messages and AVP's.

] ]]>

-Compiles a single dictionary file. Valid options are as follows.

- - - - -]]> - -

-Specifies the directory into which the generated source should be written. -Defaults to the current working directory.

- +Compile a single dictionary file to Erlang source. +Valid options are as follows.

]]>

-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, -@inherits in a dictionary file creating a beam dependency, not -an erl/hrl dependency.

+&dict_inherits; in a dictionary file creating a beam +dependency, not an erl/hrl dependency.

Multiple -i options can be specified.

 + +]]> + +

+Write generated source to the specified directory. +Defaults to the current working directory.

+ +

-Supresses erl and hrl generation, respectively.

+Supress erl and hrl generation, respectively.

 ]]> ]]>

-Set @name and @prefix in the dictionary, -respectively. +Set &dict_name; or &dict_prefix; to the specified +string. Overrides any setting in the file itself.

 ]]>

-Append an @inherits to the dictionary before compiling. -Specifying '-' as the dictionary has the effect of clearing any -previous inherits, causing them to be ignored.

+Append &dict_inherits; of the specified module. +Specifying "-" has the effect of discarding clearing any +previous inherits, both in the dictionary file and on the options +list.

Multiple --inherits options can be specified.

@@ -127,7 +130,7 @@ Returns 0 on success, non-zero on failure.

SEE ALSO

-&man_dict;

+&man_make;, &man_dict;

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 @@ FILE FORMAT'> + MESSAGE RECORDS'> + DATA TYPES'> %also; @@ -45,29 +51,28 @@ under the License.

-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 -FILE FORMAT 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 -diameterc and configuring the +either &man_compile; or &man_make; and configuring the resulting dictionaries modules on a service.

-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 MESSAGE RECORDS and DATA TYPES 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.

@@ -111,6 +116,8 @@ The order in which sections are specified is unimportant.

+ + @id Number

@@ -134,6 +141,8 @@ Example:

 + + @name Mod

@@ -155,6 +164,8 @@ Example:

 + + @prefix Name

@@ -178,6 +189,8 @@ Example:

 + + @vendor Number Name

@@ -198,6 +211,8 @@ Example:

 + + @avp_vendor_id Number

@@ -218,6 +233,8 @@ Region-Set + + @inherits Mod

@@ -253,6 +270,8 @@ Example:

 + + @avp_types

@@ -263,7 +282,7 @@ The section consists of definitions of the form

where Code is the integer AVP code, Type identifies an AVP Data Format -as defined in DATA TYPES 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 '-' (minus) character if none are to be set.

@@ -287,6 +306,8 @@ to conform to the current draft standard.

 + + @custom_types Mod

@@ -308,6 +329,8 @@ Framed-IP-Address + + @codecs Mod

@@ -325,6 +348,8 @@ Framed-IP-Address + + @messages

@@ -370,6 +395,8 @@ RTA ::= < Diameter Header: 287, PXY > + + @grouped

@@ -395,6 +422,8 @@ Specifying a Vendor-Id in the definition of a grouped AVP is equivalent to specifying it with @avp_vendor_id.

 + + @enum Name

@@ -421,6 +450,8 @@ REMOVE_SIP_SERVER 3 + + @end

@@ -447,8 +478,8 @@ The hrl generated from a dictionary specification defines records for the messages and grouped AVPs defined in @messages and @grouped 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 @prefix and whose fields are the names of the AVPs +name is the message or AVP name, prefixed with any dictionary prefix +defined with @prefix, 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

@@ -640,7 +671,7 @@ Values of these types are not currently parsed by diameter.

SEE ALSO

-&man_compile;, &man_main;, &man_app;

+&man_compile;, &man_main;, &man_app;, &man_codec;, &man_make;

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 @@ file:name()'> + dictionary file'> %also; @@ -43,7 +47,14 @@ under the License.

-

+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.

+ +

+The utility &man_compile; provides an alternate compilation +interface.

 @@ -52,16 +63,56 @@ under the License. -codec(Name) -> ok -Compile a dictionary into a codec module. - - - - +codec(Path::string(), [Opt]) -> ok | {error, Reason} +Compile a dictionary file into Erlang source.

-

+Compile a single dictionary file to Erlang source. +Opt can have the following types.

+ + + +{include, Dir::string()} + +

+Prepend the specified directory to the code path. +Use to point at beam files compiled from inherited dictionaries, +&dict_inherits; in a dictionary file creating a beam +dependency, not an erl/hrl dependency.

+ +

+Multiple include options can be specified.

+ + +{outdir, Dir::string()} + +

+Write generated source to the specified directory. +Defaults to the current working directory.

+ + +{name|prefix, string()} + +

+Set &dict_name; or &dict_prefix; to the specified +string. +Overrides any setting in the file itself.

+ + +{inherits, Mod::string()} + +

+Append &dict_inherits; of the specified module. +Specifying "-" has the effect of discarding clearing any +previous inherits, both in the dictionary file and on the options +list.

+ +

+Multiple inherits options can be specified.

+ + + @@ -69,14 +120,24 @@ under the License. + +
+BUGS + +

+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;

+ +
+
SEE ALSO

-&man_main;, -&man_dict;

+&man_compile;, &man_dict;

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 @@ gen_sctp(3)'> + gen_sctp:open/1'> + inet:ip_address()'> + inet(3)'> %also; @@ -43,8 +49,7 @@ under the License.

-This module implements diameter transport over SCTP using gen_sctp. +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 Type = connect | accept Ref = &mod_transport_ref; Svc = #diameter_service{} -Opt = {raddr, inet:ip_address()} | {rport, integer()} | term() +Opt = {raddr, &ip_address;} | {rport, integer()} | term() Pid = pid() -LAddr = inet:ip_address() +LAddr = &ip_address; Reason = term() @@ -84,8 +89,7 @@ unspecified. More than one raddr 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 gen_sctp:open/1, with the exception +Remaining options are any accepted by &gen_sctp_open1;, with the exception of options mode, binary, list, active and sctp_events. Note that options ip and port specify the local address @@ -102,14 +106,12 @@ connecting transport.

An insufficiently large receive buffer may result in a peer having to -resend incoming messages: set the inet(3) option recbuf to increase +resend incoming messages: set the &inet; option recbuf to increase the buffer size.

An insufficiently large send buffer may result in outgoing messages -being discarded: set the inet(3) option sndbuf to increase +being discarded: set the &inet; option sndbuf to increase the buffer size.

 @@ -145,10 +147,7 @@ outbound streams.

SEE ALSO

-&man_main;, -&man_transport;, -gen_sctp(3), -inet(3)

+&man_main;, &man_transport;, &gen_sctp;, &inet;

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 @@ gen_tcp:connect/3'> + gen_tcp:listen/2'> + inet:ip_address()'> + ssl:connect/2'> + ssl:connect/3'> + ssl:ssl_accept/2'> + ssl:listen/2'> + gen_tcp(3)'> + inet(3)'> + ssl(3)'> %also; @@ -43,8 +60,7 @@ under the License.

-This module implements diameter transport over TCP using gen_tcp. +This module implements diameter transport over TCP using &gen_tcp;. It can be specified as the value of a transport_module option to &mod_add_transport; and implements the behaviour documented in @@ -74,9 +90,9 @@ before configuring TLS capability on diameter transports.

Svc = #diameter_service{} Opt = OwnOpt | SslOpt | TcpOpt Pid = pid() -LAddr = inet:ip_address() +LAddr = &ip_address; Reason = term() -OwnOpt = {raddr, inet:ip_address()} +OwnOpt = {raddr, &ip_address;} | {rport, integer()} | {port, integer()} SslOpt = {ssl_options, true | list()} @@ -95,16 +111,12 @@ transport. Option ssl_options must be specified for a transport that should support TLS: a value of true results in a TLS handshake immediately upon connection establishment while -list() specifies options to be passed to ssl:connect/2 or -ssl:ssl_accept/2 +list() specifies options to be passed to &ssl_connect2; or +&ssl_accept2; after capabilities exchange if TLS is negotiated. -Remaining options are any accepted by ssl:connect/3 or gen_tcp:connect/3 for -a connecting transport, or ssl:listen/2 or gen_tcp:listen/2 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 {ssl_options, true} has been specified. Options binary, @@ -150,11 +162,7 @@ The returned local address list has length one.

SEE ALSO

-&man_main;, -&man_transport;, -gen_tcp(3), -inet(3), -ssl(3)

+&man_main;, &man_transport;, &gen_tcp;, &inet;, &ssl;

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 @@ message()'> + inet:ip_address()'> %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).

- +
+DATA TYPES + + + + + +message() = binary() | &codec_packet; + +

+A Diameter message as passed over the transport interface.

+ +

+For an inbound message from a transport process, a &codec_packet; must +contain the received message in its bin field. +In the case of an inbound request, any value set in the +transport_data field will passed back to the transport module +in the corresponding answer message, unless the sender supplies +another value.

+ +

+For an outbound message to a transport process, a &codec_packet; has a +value other than undefined in its transport_data field +and has the binary() to send in its bin field.

+ + + + +
+ + + Mod:start({Type, Ref}, Svc, Config) - -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason} + -> {ok, Pid} + | {ok, Pid, LAddrs} + | {error, Reason} Start a transport process. Type = connect | accept @@ -67,7 +103,7 @@ parent).

Svc = #diameter_service{} Config = term() Pid = pid() -LAddrs = [inet:ip_address()] +LAddrs = [&ip_address;] Reason = term() @@ -79,8 +115,8 @@ A transport process maintains a connection with a single remote peer.

Type indicates whether the transport process in question -is being started for a connecting (connect) or listening -(accept) transport. +is being started for a connecting (Type=connect) or listening +(Type=accept) transport. In the latter case, transport processes are started as required to accept connections from multiple peers.

@@ -90,13 +126,12 @@ that has lead to starting of a transport process.

Svc contains the capabilities passed to &mod_start_service; and -&mod_add_transport;, -values passed to the latter overriding those passed to the former.

+&mod_add_transport;, values passed to the latter overriding those +passed to the former.

Config is as passed in transport_config tuple in the -&mod_transport_opt; -list passed to &mod_add_transport;.

+&mod_transport_opt; list passed to &mod_add_transport;.

The start function should use the Host-IP-Address 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.

- +
MESSAGES @@ -130,19 +165,15 @@ All messages sent over the transport interface are of the form {diameter, term()}.

-A transport process can expect the following messages from -diameter.

+A transport process can expect messages of the following types from +its parent.

-{diameter, {send, Packet}} +{diameter, {send, &message;}}

-An outbound Diameter message. -Packet can be either binary() (the message to be sent) -or a #diameter_packet{} record whose transport_data -field contains a value other than undefined and whose bin field -contains the binary to send.

+An outbound Diameter message.

 {diameter, {close, Pid}} @@ -185,7 +216,7 @@ TLS.

-A transport process should send the following messages +A transport process should send messages of the following types to its parent.

@@ -208,19 +239,10 @@ Not sent if the transport process has Type=accept. endpoint to which the transport has connected.

-{diameter, {recv, Packet}} +{diameter, {recv, &message;}}

-An inbound Diameter message. -Packet can be either binary() (the received message) -or a #diameter_packet{} record -whose bin field contains the received binary(). -Any value (other than undefined) set in -the transport_data 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 transport_data is used/interpreted is up to the -transport module.

+An inbound Diameter message.

 {diameter, {tls, Ref}} 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:

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 relay 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.

-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. prepare_request/3'> diameter_app:capabilities()'> -diameter_app:message()'> -diameter_app:packet()'> diameter_app:peer()'> diameter_app:peer_ref()'> diameter_app:state()'> + + +diameter_codec:encode/2'> +diameter_codec:decode/2'> + +diameter_codec:avp()'> +diameter_codec:header()'> +diameter_codec:dictionary()'> +diameter_codec:message()'> +diameter_codec:packet()'> + diameter_dict(4)'> @@ -95,6 +104,14 @@ significant. UTF8String()'> Unsigned32()'> +@name'> +@prefix'> +@inherits'> + + + +diameter_make:codec/2'> + diameterc(1)'> diameter(3)'> diameter_app(3)'> +diameter_codec(3)'> diameter_dict(4)'> -diameter_transport(3)'> +diameter_make(3)'> +diameter_transport(3)'> diameter_sctp(3)'> diameter_tcp(3)'> -- cgit v1.2.3 From 3b8adac9179ea32c2f78860c621289cb4b2bb57e Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 23 Nov 2012 14:58:39 +0100 Subject: Add missing diameter_codec(3) content --- lib/diameter/doc/src/diameter_codec.xml | 54 ++++++++++++++++++++++++++++++--- 1 file changed, 49 insertions(+), 5 deletions(-) (limited to 'lib/diameter/doc/src') diff --git a/lib/diameter/doc/src/diameter_codec.xml b/lib/diameter/doc/src/diameter_codec.xml index fb245936cf..4a77d5435b 100644 --- a/lib/diameter/doc/src/diameter_codec.xml +++ b/lib/diameter/doc/src/diameter_codec.xml @@ -266,24 +266,66 @@ Fields have the following types.

-header = &header; +header = &header; | undefined +

+The Diameter header of the message. +Can be (and typically should be) undefined for an outgoing +message in a non-relay application, in which case diameter provides +appropriate values.

 -msg = &message; +avps = [&avp;] | undefined +

+The AVPs of the message. +Ignored for an outgoing message if the msg field is set to a +value other than undefined.

+ + +msg = &message; | undefined + +

+The incoming/outgoing message. +For an incoming message, a record if the message can be +decoded in a non-relay application, undefined otherwise. +For an outgoing message, setting a [&header; | &avp;] list is +equivalent to setting the header and avps fields to the +corresponding values.

+ + +

+A record-valued msg field does not imply an absence of +decode errors. +The errors field should also be examined.

+ + bin = binary() +

+The incoming message prior to encode or the outgoing message after +encode.

 -errors = [&dict_Unsigned32; | {&dict_Unsigned32;, avp()}] +errors = [5000..5999 | {5000..5999, avp()}] +

+Errors detected at decode of an incoming message, as identified by +a corresponding 5xxx series Result-Code (Permanent Failures). +For an incoming request, these should be used to formulate an +appropriate answer as documented for the &app_handle_request; +callback in &man_app;. +For an incoming answer, the &mod_application_opt; +answer_errors determines the behaviour.

 transport_data = term() +

+An arbitrary term of meaning only to the transport process in +question, as documented in &man_transport;.

 @@ -299,11 +341,12 @@ Fields have the following types.

-decode(Mod, Bin) -> &packet; +decode(Mod, Bin) -> Pkt Decode a Diameter message. Mod = &dictionary; Bin = binary() +Pkt = &packet; @@ -314,11 +357,12 @@ Decode a Diameter message.

 -encode(Mod, Msg) -> binary() +encode(Mod, Msg) -> Pkt Encode a Diameter message. Mod = &dictionary; Msg = &message; | &packet; +Pkt = &packet; -- cgit v1.2.3