Libtase2

https://support.mz-automation.de/doc/libtase2/manual/latest/
Admin
Libtase2 is a C, C#/.NET, and Java protocol library for TASE.2/ICCP, used by developers to create...
Tokens:8,063
Snippets:96
Trust Score:8.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start TASE.2 Server

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Initiate the TASE.2 server to begin accepting connections and processing requests.

```c
Tase2_Server_start(server);
```

--------------------------------

### Enable IM Transfer Set and Install Handler

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Installs a handler for information messages and then enables the IM transfer set. This allows the client to receive text or binary messages from the server. Ensure the client is initialized and the server has the corresponding bilateral table entries.

```c
static void
imTransferSetHandler (void* parameter, int32_t infoRef, int32_t localRef, int32_t msgId, int32_t size, uint8_t* messageBuffer)
{
    printf("Received information message:\n");
    printf("  infoRef:  %d\n", infoRef);
    printf("  localRef: %d\n", localRef);
    printf("  msgId:    %d\n", msgId);
    printf("  message: (%.*s)", size, messageBuffer);
}

... 

Tase2_Client_installIMTransferSetHandler(client, imTransferSetHandler, NULL);

Tase2_Client_IMTransferSetEnable(client, &err);

if (err != TASE2_CLIENT_ERROR_OK)
    printf("Failed to enable IM transfer set (error=%d)\n", err);

```

--------------------------------

### Start and Manage Passive Endpoint

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Connects a passive endpoint to start listening for incoming connections and disconnects it. Includes state checking with a timeout.

```c
Tase2_Endpoint_connect(endpoint);

if (Tase2_Endpoint_waitForState(endpoint, TASE2_ENDPOINT_STATE_LISTENING, 1000)) {

	...

	Tase2_Endpoint_disconnect(endpoint);
}
```

--------------------------------

### Connect TASE.2 Endpoint

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Manually connect a TASE.2 endpoint, which automatically starts all associated client and server instances.

```c
Tase2_Endpoint_connect(endpoint);
```

--------------------------------

### Set Write Data Handler for TASE.2 Server

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Install a callback handler for write data accesses. The third argument can be used to pass an arbitrary pointer to the callback function, or NULL if not required.

```c
Tase2_Server_setWriteDataHandler(server, writeDataHandler, NULL);
```

--------------------------------

### Get VCC Domain from TASE.2 Data Model

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Retrieves the TASE.2 VCC (Virtual Control Center) domain instance from the data model. VCC scope variables are accessible to all clients.

```c
Tase2_Domain vcc = Tase2_DataModel_getVCC(dataModel);
```

--------------------------------

### Create TASE.2 Server Instance

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Instantiate a TASE.2 server. The first argument is the data model, and the second is the TLS configuration or NULL for insecure connections.

```c
Tase2_Server server = Tase2_Server_create(dataModel, NULL);
```

--------------------------------

### Create TASE.2 Data Model

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Initializes a TASE.2 data model object. This is the first step in defining the server's data structure.

```c
Tase2_DataModel dataModel = Tase2_DataModel_create();
```

--------------------------------

### Load TLS Certificates and Key

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Loads the private key, server certificate, and CA certificate from files for TLS configuration. Ensure file paths are correct.

```c
TLSConfiguration_setOwnKeyFromFile(tlsConfig, "server-key.pem", NULL);
TLSConfiguration_setOwnCertificateFromFile(tlsConfig, "server.cer");
TLSConfiguration_addCACertificateFromFile(tlsConfig, "root.cer");
```

--------------------------------

### Create TLS Configuration

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Creates a new TLS configuration object. This is the first step in setting up secure communication.

```c
TLSConfiguration tlsConfig = TLSConfiguration_create();
```

--------------------------------

### Move Server Between Passive Endpoints

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Demonstrates how to remove a server instance from one passive endpoint and add it to another. Note that a server cannot be added to multiple endpoints simultaneously.

```c
Tase2_Endpoint_removeServer(passiveEndpoint1, server1);

Tase2_Endpoint_addServer(passiveEndpoint2, server1);
```

--------------------------------

### Connect to TASE.2 Server

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Initiates a TCP client connection to a TASE.2 server. The function blocks until the connection is established or an error occurs. Evaluate the return value to check for success.

```c
Tase2_ClientError err = Tase2_Client_connect(client, hostname, apTitle, 12);
```

--------------------------------

### Create Dynamic Data Set with TASE2 Client

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Use this snippet to create a dynamic data set on the TASE2 server. It requires a LinkedList of data set entry names. Be aware of the server-side limit of 500 entries per data set.

```c
LinkedList newDataSet = LinkedList_create();

LinkedList_add(newDataSet, "icc1/Discrete1");
LinkedList_add(newDataSet, "icc1/Discrete2");
LinkedList_add(newDataSet, "icc1/Discrete3");

if (Tase2_Client_createDataSet(client, &err, "icc1", "DSR_AUTO_0000", newDataSet) == false)
    printf("Failed to create new data set!\n");

LinkedList_destroyStatic(newDataSet);
```

--------------------------------

### Add TASE2 Data Set and Entries

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Creates a new data set and adds system variables and data points to it. Use this to group variables for efficient reading or writing.

```c
Tase2_DataSet ds1 = Tase2_Domain_addDataSet(icc1, "ds1");

Tase2_DataSet_addEntry(ds1, icc1, "Transfer_Set_Name");
Tase2_DataSet_addEntry(ds1, icc1, "DSConditions_Detected");
Tase2_DataSet_addEntry(ds1, icc1, "Event_Code_Detected");
Tase2_DataSet_addEntry(ds1, icc1, "Transfer_Set_Time_Stamp");
Tase2_DataSet_addEntry(ds1, vcc, "VCCDiscrete1");
Tase2_DataSet_addEntry(ds1, icc1, "Discrete1");
Tase2_DataSet_addEntry(ds1, icc1, "Discrete2");
Tase2_DataSet_addEntry(ds1, icc1, "DiscreteQTimeTag4");
```

--------------------------------

### Add TASE2 Information Message Objects and Send

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Configures information message objects for a domain and adds them to the bilateral table. Subsequently, it demonstrates sending information messages to clients.

```c
Tase2_Domain_addInformationMessageObject(icc1, 64);
    Tase2_Domain_addInformationMessageObject(icc1, 1024);

    /* Add information message objects to bilateral table */
    Tase2_BilateralTable_addInformationMessage(blt2, 1, 1, true);
    Tase2_BilateralTable_addInformationMessage(blt2, 2, 2, false);


    /* send information messages */

    char* testMessage = "test message";
    Tase2_Server_sendInformationMessage(server, NULL, 1, 1, msgId, strlen(testMessage), (uint8_t*) testMessage);

    char* testMessage2 = "test message for ICC1";
    Tase2_Server_sendInformationMessage(server, icc1, 2, 2, msgId, strlen(testMessage2), (uint8_t*) testMessage2);
```

--------------------------------

### Configure and Activate a DS Transfer Set

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Configures a DS transfer set by setting its data set, interval, RBE, criticality, and requested conditions. It then activates the transfer set. Ensure the client and dataSet variables are properly initialized before use.

```c
ts = Tase2_Client_getNextDSTransferSet(client, "icc1", &err);

if (ts) {

    Tase2_ClientDSTransferSet_setDataSet(ts, dataSet);

    printf("DSTransferSet %s:%s\n", Tase2_ClientDSTransferSet_getDomain(ts), Tase2_ClientDSTransferSet_getName(ts));

    Tase2_ClientDSTransferSet_readValues(ts, client);

    printf("  data-set: %s:%s\n", Tase2_ClientDSTransferSet_getDataSetDomain(ts), Tase2_ClientDSTransferSet_getDataSetName(ts));

    if (Tase2_ClientDSTransferSet_writeDataSetName(ts, client, "icc1", "ds1") != TASE2_CLIENT_ERROR_OK)
        printf("Write data set failed!\n");

    if (Tase2_ClientDSTransferSet_writeInterval(ts, client, 1) != TASE2_CLIENT_ERROR_OK)
        printf("Write interval failed!\n");

    if (Tase2_ClientDSTransferSet_writeRBE(ts, client, true) != TASE2_CLIENT_ERROR_OK)
        printf("Write RBE failed!\n");

    if (Tase2_ClientDSTransferSet_writeCritical(ts, client, true) != TASE2_CLIENT_ERROR_OK)
        printf("Write critical failed!\n");

    if (Tase2_ClientDSTransferSet_writeDSConditionsRequested(ts, client, TASE2_DS_CONDITION_INTERVAL | TASE2_DS_CONDITION_CHANGE) != TASE2_CLIENT_ERROR_OK)
        printf("Failed to write DS conditions requested!\n");

    printf("Start DSTransferSet\n");

    if (Tase2_ClientDSTransferSet_writeStatus(ts, client, true) != TASE2_CLIENT_ERROR_OK)
        printf("  failed!\n");

}

```

--------------------------------

### Configure Application Layer Security (ALS)

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Sets up ALS for an endpoint, including peer certificate validation, CA certificates, and own certificate/key. ALS provides authentication but not encryption.

```c
ASecurityConfiguration alsConfig = ASecurityConfiguration_create();

Tase2_Endpoint_setALSMode(endpoint, TASE2_ALS_MODE_SECURE);

Crypto_X509Certificate peerCert = Crypto_X509Certificate_create();
Crypto_X509Certificate_addFromFile(peerCert, "client_CA1_3.pem");

Crypto_X509Certificate caCert = Crypto_X509Certificate_create();
Crypto_X509Certificate_addFromFile(caCert, "root_CA1.pem");

Crypto_X509Certificate ownCert = Crypto_X509Certificate_create();
Crypto_X509Certificate_addFromFile(ownCert, "client_CA1_3.pem");

Crypto_PrivateKey ownKey = Crypto_PrivateKey_create();
Crypto_PrivateKey_parseFromFile(ownKey, "client_CA1_3.key");

ASecurityConfiguration_addPeerCertificate(alsConfig, peerCert);
ASecurityConfiguration_setCACertificateChain(alsConfig, caCert);
ASecurityConfiguration_setOwnCertificate(alsConfig, ownCert);
ASecurityConfiguration_setOwnKey(alsConfig, ownKey);

Tase2_Endpoint_setALSConfiguration(endpoint, alsConfig);
```

--------------------------------

### Add TASE2 Control Point (SBO)

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Adds a command control point using the Select-Before-Operate (SBO) class. Ensure the domain and control type constants are correctly defined.

```c
Tase2_Domain_addControlPoint(icc1, "Command1", TASE2_CONTROL_TYPE_COMMAND, TASE2_DEVICE_CLASS_SBO, true, 1365);
```

--------------------------------

### Delete Dynamic Data Set with TASE2 Client

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

This code demonstrates how to delete a previously created dynamic data set using the Tase2_Client_deleteDataSet function.

```c
bool isDeleted = Tase2_Client_deleteDataSet(client, &err, "icc1", "DSR_AUTO_0000");
```

--------------------------------

### Add Protection Equipment to Domain

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Adds a protection equipment data point to a domain. These points are related to protection events and can have single or packed state values.

```c
Tase2_Domain_addProtectionEquipment(icc1, "Protect1", false);
```

--------------------------------

### Create Passive Dual-Role TASE2 Endpoint

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Creates a passive TASE2 endpoint, assigns a local application title, and then creates server and client instances associated with this endpoint. The client is configured with a remote application title for matching incoming connections.

```c
/* Create a passive endpoint (no TLS) */
Tase2_Endpoint endpoint = Tase2_Endpoint_create(NULL, true);
Tase2_Endpoint_setLocalApTitle(endpoint, "1.1.1.999.1", 12);

/* The single server instance is using the default local AP-title, AE-qualifier of the endpoint */
Tase2_Server server = Tase2_Server_createEx(dataModel, endpoint);

Tase2_Client client = Tase2_Client_createEx(endpoint);
Tase2_Client_setRemoteApTitle(client, "1.1.1.999.2", 12);
```

--------------------------------

### Add Indication Point to Domain

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Adds a new indication point to a specified domain. Supports various types like state, discrete, and real values, with optional quality and timestamp fields.

```c
Tase2_Domain_addIndicationPoint(icc1, "Real1", TASE2_IND_POINT_TYPE_REAL, TASE2_NO_QUALITY, TASE2_NO_TIMESTAMP, false, true);
```

--------------------------------

### Read Peer Identity from Server

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Retrieves the vendor, model, and revision of the TASE.2 server. This is useful for application-level heartbeats if no other data is being exchanged. Remember to free the allocated memory for the identity strings after use.

```c
char* peerVendor;
char* peerModel;
char* peerRevision;

Tase2_Client_readPeerIdentity(client, &err, &peerVendor, &peerModel, &peerRevision);

if (err == TASE2_CLIENT_ERROR_OK) {
    printf("Peer identity\n");
    printf("  vendor: %s\n", peerVendor);
    printf("  model: %s\n", peerModel);
    printf("  revision: %s\n", peerRevision);

    free(peerVendor);
    free(peerModel);
    free(peerRevision);
}
else
    printf("Failed to get peer identity (errpr=%d)\n", err);
```

--------------------------------

### Set TASE.2 Data Model Edition

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Explicitly sets the TASE.2 version for the data model. The default version is 2000.08, but can be changed to older versions like 1996.08.

```c
Tase2_DataModel_setEdition(dataModel, TASE2_EDITION_1996_08)
```

--------------------------------

### Add Domain to TASE.2 Data Model

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Adds a new domain to the TASE.2 data model. Domains organize data points and are identified by a specific name.

```c
Tase2_Domain icc1 = Tase2_DataModel_addDomain(dataModel, "icc1");
```

--------------------------------

### Add Bilateral Table to TASE.2 Server

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Register a bilateral table with the TASE.2 server to apply different access control restrictions for specific clients. This function can be called multiple times for different tables.

```c
Tase2_Server_addBilateralTable(server, blt1);
```

```c
Tase2_Server_addBilateralTable(server, blt2);
```

--------------------------------

### Iterate Through Data Set Elements

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Accesses the names and values of elements within a TASE.2 data set. This loop iterates through all elements, providing access to their names and values using dedicated functions.

```c
for (int i = 0; i < Tase2_ClientDataSet_getSize(dataSet); i++) {
    Tase2_PointName pointName = Tase2_ClientDataSet_getPointName(dataSet, i);
    Tase2_PointValue pointValue = Tase2_ClientDataSet_getPointValue(dataSet, i);

    ...
}
```

--------------------------------

### Add TASE2 Data Set Transfer Set

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Adds a new data set transfer set to a domain. This is a prerequisite for using data sets in transfer set operations.

```c
Tase2_Domain_addDSTransferSet(icc1, "DSTrans1");
```

--------------------------------

### Inform Server of Data Point Value Change

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

After updating a data point, use Tase2_Server_updateOnlineValue to notify the TASE2 server of the change.

```c
Tase2_Server_updateOnlineValue(server, (Tase2_DataPoint) icc1Discrete2);
```

--------------------------------

### Update Discrete Data Point Value

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Use Tase2_IndicationPoint_setDiscrete to update a discrete data point's value before informing the server.

```c
Tase2_IndicationPoint_setDiscrete(icc1Discrete2, 101);
```

--------------------------------

### Configure TLS Chain Validation

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Disables certificate chain validation and the acceptance of only known certificates. Use with caution as it reduces security.

```c
TLSConfiguration_setChainValidation(tlsConfig, false);
TLSConfiguration_setAllowOnlyKnownCertificates(tlsConfig, false);
```

--------------------------------

### TASE2 DSTransferSetValueHandler Callback

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Callback function invoked for each individual value within a DSTS report. It provides details about the domain, point name, and the point value received.

```c
static void
dsTransferSetValueHandler(void* parameter, Tase2_ClientDSTransferSet transferSet, const char* domainName, const char* pointName, Tase2_PointValue pointValue)
{
    printf("  Received value for %s:%s\n", domainName, pointName);
}

```

--------------------------------

### TASE2 DSTransferSetReportHandler Callback

Source: https://support.mz-automation.de/doc/libtase2/manual/latest/tase2_developer_guide.html

Callback function invoked for DSTS reports. It is called twice per report: once when the report is received and again after all values are processed. The `finished` flag indicates the second invocation.

```c
static void
dsTransferSetReportHandler(void* parameter, bool finished, uint32_t seq, Tase2_ClientDSTransferSet transferSet)
{
    if (finished) {
        printf("--> (%i) report processing finished\n", seq);
    }
    else {
        printf("New report received with seq no: %u\n", seq);
    }
}

```
Tokens:
Raw