= External Classes
:table-number: 0
:toc:

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`.

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

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.
* 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.
* 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>>.

== Example

Example.ttcn:
[source]
----
type external class ExternalClass {
  create(integer x);
  public function f_ext1(in integer x, out octetstring y);
  function f_ext2(inout template charstring p) return boolean;  
}
----

ExternalClass.hh:
[source]
----
// 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

// Copyright (c) 2000-2021 Ericsson Telecom AB

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

#ifndef ExternalClass_HH
#define ExternalClass_HH

class ExternalClass : public OBJECT {
public:
static const char* class_name() { return "ExternalClass"; }

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

protected:
virtual BOOLEAN f__ext2(CHARSTRING_template& p);

public:
ExternalClass(const INTEGER& x);

public:
virtual ~ExternalClass();

public:
virtual void log() const;
};

#endif
----

ExternalClass.cc:
[source]
----
// 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

// Copyright (c) 2000-2021 Ericsson Telecom AB

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

#include <TTCN3.hh>

namespace oop {

#include "ExternalClass.hh"

void ExternalClass::f__ext1(const INTEGER& x, OCTETSTRING& y)
{
y.clean_up();

}

BOOLEAN ExternalClass::f__ext2(CHARSTRING_template& p)
{

}

ExternalClass::ExternalClass(const INTEGER& x)
: OBJECT()
{

}

ExternalClass::~ExternalClass()
{
try {

} catch (...) {
fprintf(stderr, "Unhandled exception or dynamic test case error in destructor of class `ExternalClass'");
exit(EXIT_FAILURE);
}
}

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


} /* end of namespace */
----

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.
