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

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "SS7_Stack_User_Guide.ent">
%BOOK_ENTITIES;
]>

<chapter id="protocol">

	<title>Protocol</title>

	<section>
		<title>Supported encoding rules</title>
		<para>&THIS.PLATFORM; &THIS.APPLICATION; supports following the encoding rules:</para>
		<itemizedlist>
			<listitem>
				<para>BER</para>
			</listitem>
		</itemizedlist>
	</section>
	<section>
		<title>API</title>
		<para>
    &THIS.PLATFORM; &THIS.APPLICATION; is stream oriented. The user accesses ASN primitives by means of stream objects capable of proper decoding and encoding.
		</para>

		<para>The following classes deserve explanation:</para>
    <variablelist>
      <varlistentry>
        <term><literal>org.mobicents.protocols.asn.Tag</literal></term>
        <listitem>
          <para>
          This class defines static values that are part of header(Tag). Example values are tag values for Integer, BitString, etc.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>org.mobicents.protocols.asn.BERStatics</literal></term>
        <listitem>
          <para>
          This class defines some static values that are specific for BER
					encoding, such as real encoding schemes(NR1,NR2...).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>org.mobicents.protocols.asn.External</literal></term>
        <listitem>
          <para>
          This is a special class that is used to represent the "External" type.
					It is a special ASN type where "anything" can be used.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Input and Output stream</term>
        <listitem>
          <para>
          Simple classes that are the core of this library. They allow for chunks of data to be read/written.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
	</section>
	<section>
		<title>Examples</title>
		<para>
			Simple decode integer primitive example:
		</para>
		<programlisting lang="JAVA" role="JAVA">
		
// integer -128
byte[] data = new byte[] { 0x2, 0x1, (byte) 0x80 }; //encoded form
ByteArrayInputStream baIs = new ByteArrayInputStream(data);
AsnInputStream asnIs = new AsnInputStream(baIs);
int tag = asnIs.readTag();
if(Tag.INTEGER==tag)
{
	long value = asnIs.readInteger();
	//do somethin
}

			</programlisting>
		<para>
			Simple encode Real primitive example:
		</para>
		<programlisting lang="JAVA" role="JAVA">
		
AsnOutputStream output = new AsnOutputStream();
output.writeReal(-3145.156d, BERStatics.REAL_NR1);	
		</programlisting>
		<para>
			Complex example - how to decode some constructed data structure:
		</para>
		<programlisting lang="JAVA" role="JAVA">

// mandatory
	private Long invokeId;

	// optional
	private Long linkedId;

	// mandatory
	private OperationCode operationCode;

	// optional
	private Parameter parameter;
		
public void doDecoding(	AsnInputStream ais )	
{
		
	int len = ais.readLength();
	if (len == 0x80) {
		throw new ParseException("Unspiecified length is not supported.");
	}
	
	byte[] data = new byte[len];
	if (len != ais.read(data)) {
		throw new ParseException("Not enough data read.");
	}
	
	AsnInputStream localAis = new AsnInputStream(new ByteArrayInputStream(data));
	
	int tag = localAis.readTag();
	if (tag != _TAG_IID) {
		throw new ParseException("Expected InvokeID tag, found: " + tag);
	}
	
	this.invokeId = localAis.readInteger();
	
	if (localAis.available() &lt;= 0) {
		return;
	}
	
	tag = localAis.readTag();
	
	if (tag == Tag.SEQUENCE) {
		// sequence of OperationCode
	
		len = localAis.readLength();
		if (len == 0x80) {
			throw new ParseException("Unspiecified length is not supported.");
		}
	
		data = new byte[len];
		int tlen = localAis.read(data);
		if (len != tlen) {
			throw new ParseException("Not enough data read. Expected: " + len + ", actaul: " + tlen);
		}
		AsnInputStream sequenceStream = new AsnInputStream(new ByteArrayInputStream(data));
	
		tag = sequenceStream.readTag();
		if (tag == OperationCode._TAG_GLOBAL || tag == OperationCode._TAG_LOCAL) {
			this.operationCode = TcapFactory.createOperationCode(tag, sequenceStream);
		} else {
			throw new ParseException("Expected Global|Local operation code.");
		}
	
		if (sequenceStream.available() > 0) {
			tag = sequenceStream.readTag();
			this.parameter = TcapFactory.createParameter(tag, sequenceStream);
				
		} else {
			throw new ParseException("Not enought data to decode Parameter part of result!");
		}
	} else {
		throw new ParseException("Expected SEQUENCE tag for OperationCode and Parameter part, found: " + tag);
	}
}
		</programlisting>
	</section>
</chapter>