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 +++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 lib/diameter/doc/src/diameter_codec.xml (limited to 'lib/diameter/doc/src/diameter_codec.xml') 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;

+ +
+ + -- 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_codec.xml | 271 ++++++++++++++++++++++++++++++-- 1 file changed, 259 insertions(+), 12 deletions(-) (limited to 'lib/diameter/doc/src/diameter_codec.xml') 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;

-- 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/diameter_codec.xml') 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