/protocols/asn/docs/sources/src/main/resources/en-US/Chapter-Protocol.xml

  1<?xml version='1.0'?>
  2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  3<!ENTITY % BOOK_ENTITIES SYSTEM "SS7_Stack_User_Guide.ent">
  4%BOOK_ENTITIES;
  5]>
  6
  7<chapter id="protocol">
  8
  9	<title>Protocol</title>
 10
 11	<section>
 12		<title>Supported encoding rules</title>
 13		<para>&THIS.PLATFORM; &THIS.APPLICATION; supports following the encoding rules:</para>
 14		<itemizedlist>
 15			<listitem>
 16				<para>BER</para>
 17			</listitem>
 18		</itemizedlist>
 19	</section>
 20	<section>
 21		<title>API</title>
 22		<para>
 23    &THIS.PLATFORM; &THIS.APPLICATION; is stream oriented. The user accesses ASN primitives by means of stream objects capable of proper decoding and encoding.
 24		</para>
 25
 26		<para>The following classes deserve explanation:</para>
 27    <variablelist>
 28      <varlistentry>
 29        <term><literal>org.mobicents.protocols.asn.Tag</literal></term>
 30        <listitem>
 31          <para>
 32          This class defines static values that are part of header(Tag). Example values are tag values for Integer, BitString, etc.
 33          </para>
 34        </listitem>
 35      </varlistentry>
 36      <varlistentry>
 37        <term><literal>org.mobicents.protocols.asn.BERStatics</literal></term>
 38        <listitem>
 39          <para>
 40          This class defines some static values that are specific for BER
 41					encoding, such as real encoding schemes(NR1,NR2...).
 42          </para>
 43        </listitem>
 44      </varlistentry>
 45      <varlistentry>
 46        <term><literal>org.mobicents.protocols.asn.External</literal></term>
 47        <listitem>
 48          <para>
 49          This is a special class that is used to represent the "External" type.
 50					It is a special ASN type where "anything" can be used.
 51          </para>
 52        </listitem>
 53      </varlistentry>
 54      <varlistentry>
 55        <term>Input and Output stream</term>
 56        <listitem>
 57          <para>
 58          Simple classes that are the core of this library. They allow for chunks of data to be read/written.
 59          </para>
 60        </listitem>
 61      </varlistentry>
 62    </variablelist>
 63	</section>
 64	<section>
 65		<title>Examples</title>
 66		<para>
 67			Simple decode integer primitive example:
 68		</para>
 69		<programlisting lang="JAVA" role="JAVA">
 70		
 71// integer -128
 72byte[] data = new byte[] { 0x2, 0x1, (byte) 0x80 }; //encoded form
 73ByteArrayInputStream baIs = new ByteArrayInputStream(data);
 74AsnInputStream asnIs = new AsnInputStream(baIs);
 75int tag = asnIs.readTag();
 76if(Tag.INTEGER==tag)
 77{
 78	long value = asnIs.readInteger();
 79	//do somethin
 80}
 81
 82			</programlisting>
 83		<para>
 84			Simple encode Real primitive example:
 85		</para>
 86		<programlisting lang="JAVA" role="JAVA">
 87		
 88AsnOutputStream output = new AsnOutputStream();
 89output.writeReal(-3145.156d, BERStatics.REAL_NR1);	
 90		</programlisting>
 91		<para>
 92			Complex example - how to decode some constructed data structure:
 93		</para>
 94		<programlisting lang="JAVA" role="JAVA">
 95
 96// mandatory
 97	private Long invokeId;
 98
 99	// optional
100	private Long linkedId;
101
102	// mandatory
103	private OperationCode operationCode;
104
105	// optional
106	private Parameter parameter;
107		
108public void doDecoding(	AsnInputStream ais )	
109{
110		
111	int len = ais.readLength();
112	if (len == 0x80) {
113		throw new ParseException("Unspiecified length is not supported.");
114	}
115	
116	byte[] data = new byte[len];
117	if (len != ais.read(data)) {
118		throw new ParseException("Not enough data read.");
119	}
120	
121	AsnInputStream localAis = new AsnInputStream(new ByteArrayInputStream(data));
122	
123	int tag = localAis.readTag();
124	if (tag != _TAG_IID) {
125		throw new ParseException("Expected InvokeID tag, found: " + tag);
126	}
127	
128	this.invokeId = localAis.readInteger();
129	
130	if (localAis.available() &lt;= 0) {
131		return;
132	}
133	
134	tag = localAis.readTag();
135	
136	if (tag == Tag.SEQUENCE) {
137		// sequence of OperationCode
138	
139		len = localAis.readLength();
140		if (len == 0x80) {
141			throw new ParseException("Unspiecified length is not supported.");
142		}
143	
144		data = new byte[len];
145		int tlen = localAis.read(data);
146		if (len != tlen) {
147			throw new ParseException("Not enough data read. Expected: " + len + ", actaul: " + tlen);
148		}
149		AsnInputStream sequenceStream = new AsnInputStream(new ByteArrayInputStream(data));
150	
151		tag = sequenceStream.readTag();
152		if (tag == OperationCode._TAG_GLOBAL || tag == OperationCode._TAG_LOCAL) {
153			this.operationCode = TcapFactory.createOperationCode(tag, sequenceStream);
154		} else {
155			throw new ParseException("Expected Global|Local operation code.");
156		}
157	
158		if (sequenceStream.available() > 0) {
159			tag = sequenceStream.readTag();
160			this.parameter = TcapFactory.createParameter(tag, sequenceStream);
161				
162		} else {
163			throw new ParseException("Not enought data to decode Parameter part of result!");
164		}
165	} else {
166		throw new ParseException("Expected SEQUENCE tag for OperationCode and Parameter part, found: " + tag);
167	}
168}
169		</programlisting>
170	</section>
171</chapter>
172