API
This chapter documents all classes and methods of the TwinCAT Automation Interface. The interfaces provided can be divided into two different “levels”. Level 1 includes the two main interfaces of the Automation Interface— ITcSysManager and ITcSmTreeItem —through which all operations can be performed. The ITcSmTreeItem interface is a generic interface that can be used for all elements within a TwinCAT project. Level 2 includes specialized interfaces that provide advanced functions for specific ITcSmTreeItems, but these are not available for all elements in the TwinCAT project (e.g., ITcPlcPou).
Versioning of Interfaces
Over the years, the Automation Interface has been enhanced with additional features to provide access to new TwinCAT functionalities. For compatibility reasons, the new functions will be made available in a new version of the interface (e.g., ITcSysManagerX). The new versions of the interface are incremented by the number X. When starting a new Automation Interface project, it is a good idea to work with the latest version of the interface.
Return values
All methods of the COM interfaces in the Automation Interface return an HRESULT. Below is an overview of the HRESULT return values from the Automation Interface. Within .NET, these are represented by exceptions.
Name | Type | Description |
|---|---|---|
S_OK | HRESULT | The function was executed successfully. |
E_FAIL | HRESULT | The function fails. |
E_ACCESSDENIED | HRESULT | The current document in the System Manager instance is locked. This is the case when at least one reference to the System Manager object or one of the Tree Items is open. |
E_INVALIDARG | HRESULT | The specified parameter is invalid. |
E_POINTER | HRESULT | The return pointer's address is invalid. |
TSM_E_ITEMNOTFOUND | HRESULT | The path name does not refer to an existing Tree Item. |
TSM_E_INVALIDITEMSUBTYPE | HRESULT | The specified SubType is invalid. |
Level 1 interfaces
Main class | Description | Available since |
|---|---|---|
Base class for creating and parameterizing a TwinCAT configuration. | TwinCAT 2.11 | |
Represents a Tree Item within a TwinCAT configuration. | TwinCAT 2.11 |
Level 2 interfaces
Helper class | Description | Available since |
|---|---|---|
Defines methods and properties for PLC library management. | TwinCAT 3.1 | |
Defines methods and properties for working with PLC POUs. | TwinCAT 3.1 | |
Defines methods for reading and writing to the declaration area of a PLC POU. | TwinCAT 3.1 | |
Defines methods for reading and writing to the implementation area of a PLC POU. | TwinCAT 3.1 | |
Defines methods and properties related to a PLC project, such as setting the project as a boot project. | TwinCAT 3.1 | |
Defines methods required for importing and exporting PLC projects to and from PLCopen XML and for installing them as a PLC library. | TwinCAT 3.1 | |
Defines methods and properties for linking the PLC project to a task. | TwinCAT 3.1 | |
Helper class that represents a single PLC library. | TwinCAT 3.1 | |
Helper class that represents a collection of ITcPlcLibRef objects (and thus references in a PLC project). | TwinCAT 3.1 | |
Helper class that serves as a base class for ITcPlcLibrary and ITcPlcPlaceholderRef objects. | TwinCAT 3.1 | |
Helper class that represents a single PLC placeholder. | TwinCAT 3.1 | |
Helper class that represents a single PLC library repository. | TwinCAT 3.1 | |
Helper class that represents a collection of PLC library repositories. | TwinCAT 3.1 | |
Interface for importing and exporting PLC objects in the PLCopen XML format. | TwinCAT 3.1 | |
Interface for online access to a logged-in PLC application (login/logoff, start/stop/reset, and online status). | TwinCAT 3.1 | |
An interface that describes the archiving settings for a PLC project (which components are included in a target archive or a file/email archive). | TwinCAT 3.1 | |
An interface for reading and writing the XML content of an object. | TwinCAT 3.1 | |
User management entry point for logging in a user and retrieving the currently logged-in user. | TwinCAT 3.1 | |
Entry point for the registered data types of the type system (enumeration, access, and creation and deletion of data types). | TwinCAT 3.1 | |
Basic interface for data type and temporary type instances (XML serialization, name/GUID access, and determination of dependent data types). | TwinCAT 3.1 | |
vtable-based COM interface for the basic properties of a TwinCAT real-time control task, such as cycle time and priority. | TwinCAT 3.1 | |
Interface for navigating a nested project; returns the root Tree Item of the inner hierarchy. | TwinCAT 3.1 | |
ITcNestedProject | Callback interface through which the System Manager notifies a nested project of configuration changes. | TwinCAT 3.1 |
An interface that writes a single TwinCAT project and its files to a ZIP archive. | TwinCAT 3.1 | |
Central access point to the TcCOM module instances registered in the project (enumeration, lookup, and online parameter access). | TwinCAT 3.1 | |
Basic interface for a TcCOM module instance with parameter access, XML import/export, and type lookup. | TwinCAT 3.1 | |
Interface for accessing all loaded license descriptors. | TwinCAT 3.1 | |
A compact relationship entry that combines a referenced license GUID with a context-dependent numeric value. | TwinCAT 3.1 | |
An interface that describes a single license definition from the loaded license descriptions. | TwinCAT 3.1 | |
Interface for accessing the IEC declarations of libraries. | TwinCAT 3.1 | |
COM interface for EtherCAT slaves; provides the slave identification and allows a CoE variable to be resolved. | TwinCAT 3.1 | |
Interface for accessing the target platform selection of the currently loaded TwinCAT project. | TwinCAT 3.1 | |
Solution-wide archive persistence service for saving and loading entire Visual Studio solutions as ZIP archives. | TwinCAT 3.1 | |
Interface for importing and exporting archive files (*.tszip / *.tnzip) at the Tree Item level. | TwinCAT 3.1 |