---
name: "libdatovka"
section: "3"
platform: "linux"
package: "libdatovka"
version: "0.7.4-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libdatovka"
---

# libdatovka(3)

    .SH "NAME" libdatovka - ISDS client library

    .SH "SYNOPSIS"

```
#include <libdatovka/isds.h>
#include <stdio.h>
isds_error err;
struct isds_ctx *ctx;
err = isds_init();
ctx = isds_ctx_create();
err = isds_login(ctx, NULL, "username", "password", NULL, NULL);
if (err) {
    printf("isds_login() failed: %s: %s\n",
        isds_strerror(err), isds_long_message(ctx));
} else {
    printf("Logged in.\n");
}
err = isds_ctx_free(&ctx);
err = isds_cleanup();
```

    .SH "DESCRIPTION"

      .PP This is a client library for accessing SOAP services of ISDS (Informační systém datových schránek / Data Box Information System) as defined in **Czech ISDS Act (300/2008 Coll.)**\[1\] and implied documents. Current implementation details are described in Provozní řád that can be downloaded from **Dokumenty ke stažení section of ISDS Information Portal**\[2\].

      .PP The library provides a C language interface with synchronous non-reentrant blocking calls. Network communication progress reporting and operation logging and library debugging are implemented by calling back application-provided functions. Network operations can be cancelled from network reporting call-back.

    .SH "LIBRARY INITIALIZATION AND DEINITIALIZATION"

      .PP A libdatovka application must include the libdatovka/isds.h header file. The application must call **isds\_init** function to initialize the library before calling any other library functions. After last libdatovka call, **isds\_cleanup** function should be called to clean up some global resources and to deinitialize dependent libraries.

    .SH "CONTEXTS"

      .PP Most of the functions operate on an established connection to the ISDS server. This is called a context and it's represented by a pointer to an opaque isds\_ctx structure. The structure maintains state about network connection, authorization or error from last call on the context.

      .PP The context is allocated by **isds\_ctx\_create** function and deallocated by **isds\_ctx\_free** function.

      .PP There are more context subtypes. A specific subtype is assigned to the context when a fresh new context is passed to one of the few stratifying functions (**isds\_login**, **czp\_convert\_document**, **isds\_request\_new\_testing\_box**). Once the context is specialized, you can use it only with functions understanding the subtype. This is not enforced by the library now, but it does not matter much because all the other functions assume the **isds\_login** was called on the context. In other words, do not share the context among the three stratifying functions.

      .PP For example create a context with **isds\_ctx\_create**, then call **isds\_login**, then work with box, then call **isds\_logout**. Here you can reuse the context and log in as another user by calling **isds\_login** again or destroy the context with **isds\_ctx\_free** if you don't need it anymore.

      .PP Or create a context with **isds\_ctx\_create**, send a document to authorized conversion using **czp\_convert\_document**, then you can send more documents to the authorized conversion by calling **czp\_convert\_document** again on the same context and finally destroy the context with **isds\_ctx\_free**.

    .SH "ERRORS"

      .PP Most of the functions return an error code of **isds\_error** type. IE\_SUCCESS value denotes a successful call. Other values represent some kind of failure.

      .PP You can use **isds\_strerror** function to obtain a human readable string representation of the error code.

      .PP If a function with context argument failed, you can use **isds\_long\_message** function to obtain a detailed error message. Please note that returned value lasts only to the next call on the context.

    .SH "CHARACTER ENCODING"

      .PP All strings exchanged between the library and the application are encoded in UTF-8. Although there are a few exceptions:

•

          **isds\_strerror** and **isds\_long\_message** functions return locale encoded string.

        .RE

•

          **isds\_version** returns locale encoded string.

        .RE

•

          Log call-back function set by **isds\_set\_log\_callback** function is called with raw byte stream.

        .RE

•

          isds\_pki\_credentials structure string members have encoding specific to cryptographic library linked to cURL library.

        .RE

    .SH "GLOBAL SETTINGS"

      .PP Some functions influence library behaviour globally. These are:

•

          **isds\_init** and **isds\_cleanup** used to initialize and deinitialize the library.

        .RE

•

          **isds\_set\_logging** and **isds\_set\_log\_callback** to set logging.

        .RE

    .SH "LOGGING AND DEBUGGING"

      .PP Logging is global for all libdatovka calls. Log level and facility can be set with **isds\_set\_logging** function.

      .PP The log is printed on standard error output by default. Application can redirect the messages to a call-back function by registering the call-back function with **isds\_set\_log\_callback**.

    .SH "NETWORK INPUT/OUTPUT"

      .PP Some functions operating on a context create network sockets and do network input and output.

      .PP Network timeout can be set with **isds\_set\_timeout** function. Function calls aborted owing to the timeout will return IE\_TIMED\_OUT.

      .PP Network operation progress can be monitored by a call-back function. The call-back function can be registered using **isds\_set\_xferinfo\_callback** function. Registered call-back function will be called periodically with arguments declaring amount of transferred data. The call-back return value determines whether to continue in the network operation or to cancel the operation. Functions failed owing to cancelling network operation will return IE\_ABORTED. The now deprecated call-back function **isds\_set\_progress\_callback** behaves similarly but uses floating-point values to pass amounts of transferred data. Is is discouraged to use **isds\_set\_progress\_callback** in new code.

    .SH "MEMORY MANAGEMENT"

      .PP The library provides destructors for all libdatovka data structures. For example **isds\_ctx\_free** function accepts a pointer to a pointer to the isds\_ctx structure, frees the double referenced structure (recursively), writes NULL to the pointed pointer (which invalidates the pointer effectively) and returns nothing.

      .PP Upon a function call, all output arguments are automatically reallocated to desired size. On a function failure, all output arguments are automatically deallocated and their pointers set to NULL. Exceptions are documented at respective functions.

      .PP Output strings are allocated using standard **malloc** call. Application is responsible for their deallocation (in case of no failure and if not specified otherwise.) Use standard **free** call for strings, use libdatovka destructors for libdatovka structures.

    .SH "AVAILABLE FUNCTIONS, TYPES, AND CONSTANTS"

      .PP See libdatovka/isds.h header file.

    .SH "SEE ALSO"

      .PP [**isds.h.libdatovka**(3)](/isds.h.libdatovka/3.md), [**libcurl**(3)](/libcurl/3.md)

  .SH "AUTHORS"

**CZ.NIC, z. s. p. o.**

Maintains libdatovka. Has been contributing to libisds.

**Petr Písař**

He has written libisds.

## NOTES

- 1\.

  Czech\
             ISDS Act (300/2008 Coll.)

  http://portal.gov.cz/zakon/300/2008

- 2\.

  Dokumenty ke stažení section of\
             ISDS Information Portal

  https://www.datoveschranky.info/ke-stazeni