<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- diameter_codec(3)</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/diameter-1.3.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Diameter</strong><br><strong>Reference Manual</strong><br><small>Version 1.3</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Table of Contents</strong></small></p>
<ul class="flipMenu">
<li id="no" title="diameter " expanded="false">diameter<ul>
<li><a href="diameter.html">
Top of manual page
</a></li>
<li title="add_transport-2"><a href="diameter.html#add_transport-2">add_transport/2</a></li>
<li title="call-4"><a href="diameter.html#call-4">call/4</a></li>
<li title="origin_state_id-0"><a href="diameter.html#origin_state_id-0">origin_state_id/0</a></li>
<li title="remove_transport-2"><a href="diameter.html#remove_transport-2">remove_transport/2</a></li>
<li title="service_info-2"><a href="diameter.html#service_info-2">service_info/2</a></li>
<li title="services-0"><a href="diameter.html#services-0">services/0</a></li>
<li title="session_id-1"><a href="diameter.html#session_id-1">session_id/1</a></li>
<li title="start-0"><a href="diameter.html#start-0">start/0</a></li>
<li title="start_service-2"><a href="diameter.html#start_service-2">start_service/2</a></li>
<li title="stop-0"><a href="diameter.html#stop-0">stop/0</a></li>
<li title="stop_service-1"><a href="diameter.html#stop_service-1">stop_service/1</a></li>
<li title="subscribe-1"><a href="diameter.html#subscribe-1">subscribe/1</a></li>
<li title="unsubscribe-1"><a href="diameter.html#unsubscribe-1">unsubscribe/1</a></li>
</ul>
</li>
<li title="diameterc"><a href="diameterc.html">diameterc</a></li>
<li id="no" title="diameter_app " expanded="false">diameter_app<ul>
<li><a href="diameter_app.html">
Top of manual page
</a></li>
<li title="Mod:peer_up-3"><a href="diameter_app.html#Mod:peer_up-3">Mod:peer_up/3</a></li>
<li title="Mod:peer_down-3"><a href="diameter_app.html#Mod:peer_down-3">Mod:peer_down/3</a></li>
<li title="Mod:pick_peer-4"><a href="diameter_app.html#Mod:pick_peer-4">Mod:pick_peer/4</a></li>
<li title="Mod:prepare_request-3"><a href="diameter_app.html#Mod:prepare_request-3">Mod:prepare_request/3</a></li>
<li title="Mod:prepare_retransmit-3"><a href="diameter_app.html#Mod:prepare_retransmit-3">Mod:prepare_retransmit/3</a></li>
<li title="Mod:handle_answer-4"><a href="diameter_app.html#Mod:handle_answer-4">Mod:handle_answer/4</a></li>
<li title="Mod:handle_error-4"><a href="diameter_app.html#Mod:handle_error-4">Mod:handle_error/4</a></li>
<li title="Mod:handle_request-3"><a href="diameter_app.html#Mod:handle_request-3">Mod:handle_request/3</a></li>
</ul>
</li>
<li id="loadscrollpos" title="diameter_codec " expanded="true">diameter_codec<ul>
<li><a href="diameter_codec.html">
Top of manual page
</a></li>
<li title="decode-2"><a href="diameter_codec.html#decode-2">decode/2</a></li>
<li title="encode-2"><a href="diameter_codec.html#encode-2">encode/2</a></li>
</ul>
</li>
<li title="diameter_dict"><a href="diameter_dict.html">diameter_dict</a></li>
<li id="no" title="diameter_make " expanded="false">diameter_make<ul>
<li><a href="diameter_make.html">
Top of manual page
</a></li>
<li title="codec-2"><a href="diameter_make.html#codec-2">codec/2</a></li>
</ul>
</li>
<li id="no" title="diameter_transport " expanded="false">diameter_transport<ul>
<li><a href="diameter_transport.html">
Top of manual page
</a></li>
<li title="Mod:start-3"><a href="diameter_transport.html#Mod:start-3">Mod:start/3</a></li>
</ul>
</li>
<li id="no" title="diameter_tcp " expanded="false">diameter_tcp<ul>
<li><a href="diameter_tcp.html">
Top of manual page
</a></li>
<li title="start-3"><a href="diameter_tcp.html#start-3">start/3</a></li>
</ul>
</li>
<li id="no" title="diameter_sctp " expanded="false">diameter_sctp<ul>
<li><a href="diameter_sctp.html">
Top of manual page
</a></li>
<li title="start-3"><a href="diameter_sctp.html#start-3">start/3</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<!-- refpage --><center><h1>diameter_codec</h1></center>
<h3>MODULE</h3>
<div class="REFBODY">diameter_codec</div>
<h3>MODULE SUMMARY</h3>
<div class="REFBODY">Decode and encode of Diameter messages.</div>
<h3>DESCRIPTION</h3>
<div class="REFBODY"><p>
<p>
Incoming Diameter messages are decoded from binary() before being
communicated to <span class="bold_code"><a href="diameter_app.html">diameter_app(3)</a></span> callbacks.
Similarly, outgoing Diameter messages are encoded into binary() before
being passed to the appropriate <span class="bold_code"><a href="diameter_transport.html">diameter_transport(3)</a></span> module for
transmission.
The functions in this module implement this encode/decode.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>
Calls to this module are made by diameter itself as a consequence of
configuration passed to <span class="bold_code"><a href="diameter.html#start_service-2">diameter:start_service/2</a></span>.
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 <span class="bold_code"><a href="diameter.html#call-4">diameter:call/4</a></span> and the callback
interface documented in <span class="bold_code"><a href="diameter_app.html">diameter_app(3)</a></span>.</p>
</p></div>
</div>
<p>
The <span class="bold_code"><a href="#header">header()</a></span> and <span class="bold_code"><a href="#packet">packet()</a></span> records below
are defined in diameter.hrl, which can be included as follows.</p>
<div class="example"><pre>
-include_lib("diameter/include/diameter.hrl").
</pre></div>
<p>
Application-specific records are definied in the hrl
files resulting from dictionary file compilation.</p>
</p></div>
<h3><a name="id75816">DATA TYPES</a></h3>
<div class="REFBODY">
<p></p>
<dl>
<a name="integers"></a>
<dt><strong><span class="code">uint8() = 0..255</span></strong></dt>
<dt><strong><span class="code">uint24() = 0..16777215</span></strong></dt>
<dt><strong><span class="code">uint32() = 0..4294967295</span></strong></dt>
<dd>
<p>
8-bit, 24-bit and 32-bit integers occurring in Diameter and AVP
headers.</p>
</dd>
<a name="avp"></a>
<dt><strong><span class="code">avp() = #diameter_avp{}</span></strong></dt>
<dd>
<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
<span class="bold_code"><a href="#message">message()</a></span> instead.</p>
<p>
Fields have the following types.</p>
<dl>
<dt><strong><span class="code">code = uint32()</span></strong></dt>
<dt><strong><span class="code">is_mandatory = boolean()</span></strong></dt>
<dt><strong><span class="code">need_encryption = boolean()</span></strong></dt>
<dt><strong><span class="code">vendor_id = uint32() | undefined</span></strong></dt>
<dd>
<p>
Values in the AVP header, corresponding to AVP Code, the M flag, P
flags and Vendor-ID respectivelty.
A Vendor-ID other than <span class="code">undefined</span> implies a set V flag.</p>
</dd>
<dt><strong><span class="code">data = iolist()</span></strong></dt>
<dd>
<p>
The data bytes of the AVP.</p>
</dd>
<dt><strong><span class="code">name = atom()</span></strong></dt>
<dd>
<p>
The name of the AVP as defined in the dictionary file in question, or
<span class="code">undefined</span> if the AVP is unknown to the dictionary file in
question.</p>
</dd>
<dt><strong><span class="code">value = term()</span></strong></dt>
<dd>
<p>
The decoded value of an AVP.
Will be <span class="code">undefined</span> 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 <span class="bold_code"><a href="diameter_dict.html#DATA_TYPES">diameter_dict(4)</a></span>.</p>
</dd>
<dt><strong><span class="code">type = atom()</span></strong></dt>
<dd>
<p>
The type of the AVP as specified in the dictionary file in question
(or one it inherits).
Possible types are <span class="code">undefined</span> and the Diameter types:
<span class="code">OctetString</span>, <span class="code">Integer32</span>, <span class="code">Integer64</span>,
<span class="code">Unsigned32</span>, <span class="code">Unsigned64</span>, <span class="code">Float32</span>, <span class="code">Float64</span>,
<span class="code">Grouped</span>, <span class="code">Enumerated</span>, <span class="code">Address</span>, <span class="code">Time</span>,
<span class="code">UTF8String</span>, <span class="code">DiameterIdentity</span>, <span class="code">DiameterURI</span>,
<span class="code">IPFilterRule</span> and <span class="code">QoSFilterRule</span>.</p>
</dd>
</dl>
</dd>
<a name="dictionary"></a>
<dt><strong><span class="code">dictionary() = module()</span></strong></dt>
<dd>
<p>
The name of a generated dictionary module as generated by <span class="bold_code"><a href="diameterc.html">diameterc(1)</a></span>
or <span class="bold_code"><a href="diameter_make.html#codec-2">diameter_make:codec/2</a></span>.
The interface provided by a dictionary module is an
implementation detail that may change.</p>
</dd>
<a name="header"></a>
<dt><strong><span class="code">header() = #diameter_header{}</span></strong></dt>
<dd>
<p>
The record representation of the Diameter header.
Values in a <span class="bold_code"><a href="#packet">packet()</a></span> returned by <span class="bold_code"><a href="#decode-2">decode/2</a></span> are as extracted from the
incoming message.
Values set in an <span class="bold_code"><a href="#packet">packet()</a></span> passed to <span class="bold_code"><a href="#encode-2">encode/2</a></span> are preserved in the
encoded binary(), with the exception of <span class="code">length</span>, <span class="code">cmd_code</span>
and <span class="code">application_id</span>, all of which are determined by the
<span class="bold_code"><a href="#dictionary">dictionary()</a></span> in question.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<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>
</p></div>
</div>
<p>
Fields have the following types.</p>
<dl>
<dt><strong><span class="code">version = uint8()</span></strong></dt>
<dt><strong><span class="code">length = uint24()</span></strong></dt>
<dt><strong><span class="code">cmd_code = uint24()</span></strong></dt>
<dt><strong><span class="code">application_id = uint32()</span></strong></dt>
<dt><strong><span class="code">hop_by_hop_id = uint32()</span></strong></dt>
<dt><strong><span class="code">end_to_end_id = uint32()</span></strong></dt>
<dd>
<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>
</dd>
<dt><strong><span class="code">is_request = boolean()</span></strong></dt>
<dt><strong><span class="code">is_proxiable = boolean()</span></strong></dt>
<dt><strong><span class="code">is_error = boolean()</span></strong></dt>
<dt><strong><span class="code">is_retransmitted = boolean()</span></strong></dt>
<dd>
<p>
Values correspoding to the R(equest), P(roxiable), E(rror)
and T(Potentially re-transmitted message) flags of the Diameter
header.</p>
</dd>
</dl>
</dd>
<a name="message"></a>
<dt><strong><span class="code">message() = record() | list()</span></strong></dt>
<dd>
<p>
The representation of a Diameter message as passed to
<span class="bold_code"><a href="diameter.html#call-4">diameter:call/4</a></span> or returned from a <span class="bold_code"><a href="diameter_app.html#Mod:handle_request-3">handle_request/3</a></span> callback.
The record representation is as outlined in <span class="bold_code"><a href="diameter_dict.html#MESSAGE_RECORDS">diameter_dict(4)</a></span>:
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 <span class="code">{AvpName, AvpValue}</span> pairs.</p>
<p>
Another list-valued representation allows a message to be specified
as a list whose head is a <span class="bold_code"><a href="#header">header()</a></span> and whose tail is an <span class="bold_code"><a href="#avp">avp()</a></span> list.
This representation is used by diameter itself when relaying requests
as directed by the return value of a <span class="bold_code"><a href="diameter_app.html#Mod:handle_request-3">handle_request/3</a></span> 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>
</dd>
<a name="packet"></a>
<dt><strong><span class="code">packet() = #diameter_packet{}</span></strong></dt>
<dd>
<p>
A container for incoming and outgoing Diameter messages.
Fields have the following types.</p>
<dl>
<dt><strong><span class="code">header = <span class="bold_code"><a href="#header">header()</a></span> | undefined</span></strong></dt>
<dd>
<p>
The Diameter header of the message.
Can be (and typically should be) <span class="code">undefined</span> for an outgoing
message in a non-relay application, in which case diameter provides
appropriate values.</p>
</dd>
<dt><strong><span class="code">avps = [<span class="bold_code"><a href="#avp">avp()</a></span>] | undefined</span></strong></dt>
<dd>
<p>
The AVPs of the message.
Ignored for an outgoing message if the <span class="code">msg</span> field is set to a
value other than <span class="code">undefined</span>.</p>
</dd>
<dt><strong><span class="code">msg = <span class="bold_code"><a href="#message">message()</a></span> | undefined</span></strong></dt>
<dd>
<p>
The incoming/outgoing message.
For an incoming message, a record if the message can be
decoded in a non-relay application, <span class="code">undefined</span> otherwise.
For an outgoing message, setting a <span class="code">[<span class="bold_code"><a href="#header">header()</a></span> | <span class="bold_code"><a href="#avp">avp()</a></span>]</span> list is
equivalent to setting the <span class="code">header</span> and <span class="code">avps</span> fields to the
corresponding values.</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p>
<p>
A record-valued <span class="code">msg</span> field does <strong>not</strong> imply an absence of
decode errors.
The <span class="code">errors</span> field should also be examined.</p>
</p></div>
</div>
</dd>
<dt><strong><span class="code">bin = binary()</span></strong></dt>
<dd>
<p>
The incoming message prior to encode or the outgoing message after
encode.</p>
</dd>
<dt><strong><span class="code">errors = [5000..5999 | {5000..5999, avp()}]</span></strong></dt>
<dd>
<p>
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 <span class="bold_code"><a href="diameter_app.html#Mod:handle_request-3">handle_request/3</a></span>
callback in <span class="bold_code"><a href="diameter_app.html">diameter_app(3)</a></span>.
For an incoming answer, the <span class="bold_code"><a href="diameter.html#application_opt">diameter:application_opt()</a></span>
<span class="code">answer_errors</span> determines the behaviour.</p>
</dd>
<dt><strong><span class="code">transport_data = term()</span></strong></dt>
<dd>
<p>
An arbitrary term of meaning only to the transport process in
question, as documented in <span class="bold_code"><a href="diameter_transport.html">diameter_transport(3)</a></span>.</p>
</dd>
</dl>
</dd>
</dl>
</div>
<h3>EXPORTS</h3>
<p><a name="decode-2"><span class="bold_code">decode(Mod, Bin) -> Pkt</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Mod = <span class="bold_code"><a href="#dictionary">dictionary()</a></span></span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Bin = binary()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Pkt = <span class="bold_code"><a href="#packet">packet()</a></span></span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>
Decode a Diameter message.</p>
</p></div>
<p><a name="encode-2"><span class="bold_code">encode(Mod, Msg) -> Pkt</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Mod = <span class="bold_code"><a href="#dictionary">dictionary()</a></span></span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Msg = <span class="bold_code"><a href="#message">message()</a></span> | <span class="bold_code"><a href="#packet">packet()</a></span></span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Pkt = <span class="bold_code"><a href="#packet">packet()</a></span></span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>
Encode a Diameter message.
</p>
</p></div>
<h3><a name="id76604">SEE ALSO</a></h3>
<div class="REFBODY">
<p>
<span class="bold_code"><a href="diameterc.html">diameterc(1)</a></span>, <span class="bold_code"><a href="diameter_app.html">diameter_app(3)</a></span>, <span class="bold_code"><a href="diameter_dict.html">diameter_dict(4)</a></span>, <span class="bold_code"><a href="diameter_make.html">diameter_make(3)</a></span></p>
</div>
</div>
<div class="footer">
<hr>
<p>Copyright © 2011-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
522
