/protocols/asn/docs/sources/src/main/resources/en-US/Chapter-Protocol.xml
XML | 169 lines | 143 code | 26 blank | 0 comment | 0 complexity | 0e140534935729a02889a56790b2f36a MD5 | raw file
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() <= 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