PageRenderTime 30ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 0ms

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

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