From 22d79a78186e4b1f45a79733eed59b1c13fd5545 Mon Sep 17 00:00:00 2001
From: Botond Baranyi <botond.baranyi@ericsson.com>
Date: Thu, 28 May 2020 17:17:57 +0200
Subject: [PATCH] Added segment about OER codec to API guide
Change-Id: I345dcac187f67f8b6f8a378d60d633cf2eaccf30
Signed-off-by: Botond Baranyi <botond.baranyi@ericsson.com>
---
.../apiguide/5-encoding_and_decoding.adoc | 75 ++++++++++++++++++-
1 file changed, 74 insertions(+), 1 deletion(-)
diff --git a/usrguide/apiguide/5-encoding_and_decoding.adoc b/usrguide/apiguide/5-encoding_and_decoding.adoc
index 759ea7241..3faf5a8cf 100644
--- a/usrguide/apiguide/5-encoding_and_decoding.adoc
+++ b/usrguide/apiguide/5-encoding_and_decoding.adoc
@@ -558,7 +558,7 @@ The following user-defined types can be encoded in XML:
* record of and set of types, if the type of the element can be encoded.
-The encoder and the decoder are working with XML data encoded in UTF-8 (described in link:https://tools.ietf.org/html/rfc3629[UTF-8, a transformation format of ISO 10646]), stored in an object of type `TTCN_buffer`. Although the contents of this object can be retrieved (using the overloads of the get_string function) as an instance of `OCTETSTRING`, `CHARSTRING` or `UNIVERSAL_CHARSTRING`, it is recommended to use only the `OCTETSTRING` representation. `CHARSTRING` is not recommended, because UTF-8 is an 8-bit encoding so the buffer may contain bytes with values over 127, which are not valid characters for a TTCN-3 `charstring` (which is implemented by `CHARSTRING`, see <<6-mapping_ttcn3_data_types_to_c+\+_constructs.adoc#Charstring, Charstring>>). `UNIVERSAL_CHARSTRING` must not be used because its internal representation is not UTF-8.
+The encoder and the decoder are working with XML data encoded in UTF-8 (described in link:https://tools.ietf.org/html/rfc3629[UTF-8, a transformation format of ISO 10646]), stored in an object of type `TTCN_buffer`. Although the contents of this object can be retrieved (using the overloads of the get_string function) as an instance of `OCTETSTRING`, `CHARSTRING` or `UNIVERSAL_CHARSTRING`, it is recommended to use only the `OCTETSTRING` representation. `CHARSTRING` is not recommended, because UTF-8 is an 8-bit encoding so the buffer may contain bytes with values over 127, which are not valid characters for a TTCN-3 `charstring` (which is implemented by `CHARSTRING`, see <<6-mapping_ttcn3_data_types_to_c++_constructs.adoc#Charstring, Charstring>>). `UNIVERSAL_CHARSTRING` must not be used because its internal representation is not UTF-8.
[[error-situations-2]]
=== Error Situations
@@ -804,3 +804,76 @@ void MyPort2::outgoing_send(const OCTETSTRING& send_par)
incoming_message(pdu);
}
----
+
+== OER
+
+The encoding rules defined in the section "OER Encoder and Decoder" of the link:https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide[Programmer's Technical Reference] can be used to encode and/or decode the values of ASN.1 types.
+
+=== Error Situations
+
+There are no extra error situations apart from the ones in <<the-common-API, The Common API>>.
+
+=== API
+
+The Application Programming Interface for ASN.1 type encoding and decoding is described in the following.
+
+==== Encoding
+
+[source, subs="+quotes"]
+void encode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf,
+ TTCN_EncDec::coding_t p_cod) const;
+
+The parameter `p_cod` must be set to `TTCN_EncDec::CT_OER`.
+
+==== Decoding
+
+[source, subs="+quotes"]
+void decode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf,
+ TTCN_EncDec::coding_t p_cod);
+
+The parameter `p_cod` must be set to `TTCN_EncDec::CT_OER`.
+
+=== Example
+
+Let us assume that we have an ASN.1 module named `MyASN` which contains a type named `ErrorReturn`, and we have a TTCN–3 module which imports this type. This module also contains two ports:
+
+[source]
+----
+type port MyPort1 message
+{
+ out ErrorReturn;
+ in octetstring;
+}
+
+type port MyPort2 message
+{
+ out octetstring;
+ in ErrorReturn;
+}
+----
+
+Then we can complete the port skeleton generated by the compiler:
+
+[source]
+----
+void MyPort1::outgoing_send(const MyASN::ErrorReturn& send_par)
+{
+ TTCN_Buffer buf;
+ send_par.encode(MyASN::ErrorReturn_descr_, buf,
+ TTCN_EncDec::CT_OER);
+ OCTETSTRING encodeddata(buf.get_len(), buf.get_data());
+ incoming_message(encodeddata);
+}
+
+void MyPort2::outgoing_send(const OCTETSTRING& send_par)
+{
+ TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_ALL,
+ TTCN_EncDec::EB_WARNING);
+ TTCN_Buffer buf;
+ buf.put_os(send_par);
+ MyASN::ErrorReturn pdu;
+ pdu.decode(MyASN::ErrorReturn_descr_, buf, TTCN_EncDec::CT_OER);
+ incoming_message(pdu);
+}
+----
+
--
GitLab