3-external_classes.adoc 4.51 KB
Newer Older
1 2 3 4
= External Classes
:table-number: 0
:toc:

5 6
TITAN allows the declaration of external classes in TTCN-3 code, which the user can (and has to) implement in {cpp}.
To help with the implementation, the TTCN-3 compiler can generate external class skeletons with the command line option `-t`.
7

8
These skeletons contain declarations and empty definitions for the constructors and methods of all external classes declared in TTCN-3 code. 
9

10 11 12 13 14
Clarifications about the skeletons and implementation tips:

* One header (`.hh`) and one source file (`.cc`) is generated for each external class. The base names of these files (i.e. their names before the extensions) are equal to the names of their external class in TTCN-3. Please note that the name mapping rules described in <<6-mapping_ttcn3_data_types_to_c++_constructs.adoc#mapping-of-names-and-identifiers, Mapping of Names and Identifiers>> also apply to the file names.
* Both the generated header and source file can be extended with additional members and methods, however these new members and methods will not be visible in TTCN-3.
* The compiler will not regenerate the external class skeletons, if they already exist. Not even if the external class declaration in TTCN-3 changes. The compiler option `-f` (in addition to `-t`) can be used to force the regeneration of external class skeletons, however this will also overwrite any user code added to the previous skeletons.
15
* The generated source file contains empty function definitions for methods declared in TTCN-3 (the code to reset `out` parameters is still generated), plus an empty default constructor, if no constructor was declared. It also contains a minimal implementation of the `log` function, which can be extended to display more information about the object while logging. The header file also contains a static inline function called `class_name`, which is used in error messages.
16 17
* The generated destructor automatically contains a try-catch block, to ensure that no exceptions are thrown from the destructor. All user code must be written inside the try-catch block.
* For more information about how to handle references of class types see <<6-mapping_ttcn3_data_types_to_c++_constructs.adoc#object-references, Object References>>.
18 19 20 21 22 23 24

== Example

Example.ttcn:
[source]
----
type external class ExternalClass {
25 26 27
  create(integer x);
  public function f_ext1(in integer x, out octetstring y);
  function f_ext2(inout template charstring p) return boolean;  
28 29 30 31 32 33
}
----

ExternalClass.hh:
[source]
----
34 35 36 37
// This external class skeleton header file was generated by the
// TTCN-3 Compiler of the TTCN-3 Test Executor version 7/CAX 105 7730 R2A
// for ebotbar (ebotbar@u2004VB) on Wed Nov 18 15:25:06 2020

Adam Knapp's avatar
Adam Knapp committed
38
// Copyright (c) 2000-2021 Ericsson Telecom AB
39

40 41
// You may modify this file. Add your attributes and prototypes of your
// member functions here.
42

43 44
#ifndef ExternalClass_HH
#define ExternalClass_HH
45 46 47

class ExternalClass : public OBJECT {
public:
48 49 50 51 52
static const char* class_name() { return "ExternalClass"; }

public:
virtual void f__ext1(const INTEGER& x, OCTETSTRING& y);

53
protected:
54 55
virtual BOOLEAN f__ext2(CHARSTRING_template& p);

56
public:
57
ExternalClass(const INTEGER& x);
58

59 60
public:
virtual ~ExternalClass();
61

62 63
public:
virtual void log() const;
64 65 66 67 68 69 70 71
};

#endif
----

ExternalClass.cc:
[source]
----
72 73 74 75
// This external class skeleton source file was generated by the
// TTCN-3 Compiler of the TTCN-3 Test Executor version 7/CAX 105 7730 R2A
// for ebotbar (ebotbar@u2004VB) on Wed Nov 18 15:25:06 2020

Adam Knapp's avatar
Adam Knapp committed
76
// Copyright (c) 2000-2021 Ericsson Telecom AB
77 78 79 80 81 82 83 84

// You may modify this file. Complete the bodies of empty functions and
// add your member functions here.

#include <TTCN3.hh>

namespace oop {

85 86
#include "ExternalClass.hh"

87 88
void ExternalClass::f__ext1(const INTEGER& x, OCTETSTRING& y)
{
89
y.clean_up();
90 91

}
92

93
BOOLEAN ExternalClass::f__ext2(CHARSTRING_template& p)
94
{
95

96 97
}

98 99
ExternalClass::ExternalClass(const INTEGER& x)
: OBJECT()
100
{
101

102 103
}

104 105 106 107 108 109 110
ExternalClass::~ExternalClass()
{
try {

} catch (...) {
fprintf(stderr, "Unhandled exception or dynamic test case error in destructor of class `ExternalClass'");
exit(EXIT_FAILURE);
111
}
112 113 114 115 116 117 118 119 120 121
}

void ExternalClass::log() const
{
TTCN_Logger::log_event_str("ExternalClass: { ");
TTCN_Logger::log_event_str(" }");
}


} /* end of namespace */
122 123
----

124
NOTE: The generated constructor automatically contains an empty base-constructor call. This is fine if the base-constructor has no parameters (e.g. it has a default constructor). If the base-constructor has at least one parameter, then appropriate parameter values need to be added to the base-constructor call, otherwise it won't compile.