LIBISDS(3)

💖 LIBISDS — the manual page, bestie edition 💖

okay so this is libisds(3), from the Manual for Libisds — it's the C client library for ISDS, and honestly? she's iconic. sit down, grab a boba, and let's get into it 🧋✨

---

🌸 NAME 🌸

libisds — ISDS client library. that's it, that's the girl 💅

---

✨ SYNOPSIS ✨

the way you start literally anything with her:

#include <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();

no cap, that's the whole vibe right there 🫶

---

🦋 DESCRIPTION 🦋

So. This is a client library for talking to the SOAP services of ISDS — that's Informační systém datových schránek / Data Box Information System — exactly as defined in the Czech ISDS Act (300/2008 Coll.)[1] and the documents that follow from it. The current implementation deets live in Provozní řád, which you can download from the Dokumenty ke stažení section of the ISDS Information Portal[2]. 👑

She gives you a C language interface with synchronous, non-reentrant, blocking calls. Report progress on network communication? Log operations? Debug the library? All of that happens by calling back application-provided functions — you hand her the functions, she calls them. And bestie, you can cancel network operations from the network reporting call-back. main character energy fr fr 😌

---

🌈 LIBRARY INITIALIZATION AND DEINITIALIZATION 🌈

A libisds app must include the isds.h header file. no negotiating on that one.

The app must call isds_init to initialize the library before calling any other library functions. And after your last libisds call, you should call isds_cleanup to clean up some global resources and deinitialize the dependent libraries. it's giving "say goodbye properly" 💅

---

🎀 CONTEXTS 🎀

Most of the functions operate on an established connection to the ISDS server. That connection is called a context, and it's represented by a pointer to an opaque isds_ctx structure. This structure keeps state about the network connection, the authorization, or the error from the last call on the context. she remembers everything, lowkey.

The context is allocated by isds_ctx_create and deallocated by isds_ctx_free. cute little life cycle 🦋

There are more context subtypes. A specific subtype gets assigned to the context when a fresh new context is passed to one of the few stratifying functions — that's isds_login, czp_convert_document, and isds_request_new_testing_box. Once a context is specialized, you can only use it with functions that understand that subtype. The library doesn't enforce this right now, but honestly it doesn't matter much, because all the other functions assume isds_login was called on the context. In other words:

do NOT share the context among the three stratifying functions. 🚫

For example: create a context with isds_ctx_create, then call isds_login, then work with the box, then call isds_logout. At that point 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. slay, flexible queen ✨

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. obsessed with her efficiency tbh 😭

---

💀 ERRORS 💀

Most of the functions return an error code of type isds_error. The value IE_SUCCESS means the call worked. Any other value means some kind of failure. rip.

Use isds_strerror to get a human-readable string representation of the error code — she translates the drama into words 🫶

If a function that takes a context argument failed, use isds_long_message to get a detailed error message. but bestie, heads up:

⚠️ the returned value lasts only until the next call on the context. screenshot it or it's gone.

---

🌟 CHARACTER ENCODING 🌟

All strings exchanged between the library and the application are encoded in UTF-8. periodt. But there are a few exceptions, because of course there are:

• isds_strerror and isds_long_message functions return a locale encoded string.
• isds_version returns a locale encoded string.
• The log call-back function set by isds_set_log_callback is called with a raw byte stream.
• isds_pki_credentials structure string members have an encoding specific to the cryptographic library linked to the cURL library.

iykyk 💅

---

💜 GLOBAL SETTINGS 💜

Some functions influence library behavior globally. These are:

• isds_init and isds_cleanup — used to initialize and deinitialize the library.
• isds_set_logging and isds_set_log_callback — to set logging.

global girlies, they affect everyone 🌍✨

---

🍓 LOGGING AND DEBUGGING 🍓

Logging is global for all libisds calls. Log level and facility can be set with the isds_set_logging function.

The log is printed on standard error output by default. Your application can redirect the messages to a call-back function by registering that call-back function with isds_set_log_callback. so you can send the tea wherever you want 💌

---

🌈 NETWORK INPUT/OUTPUT 🌈

Some functions operating on a context create network sockets and do network input and output. she's online, fr.

Network timeout can be set with the isds_set_timeout function. Function calls aborted owing to the timeout will return IE_TIMED_OUT. ⏰

Network operation progress can be monitored by a call-back function. You register it using isds_set_progress_callback. The registered call-back function will be called periodically with arguments declaring the amount of transferred data. Its return value determines whether to continue in the network operation or to cancel the operation. Functions that fail owing to canceling a network operation will return IE_ABORTED. dramatic but valid 🛑

---

🧚 MEMORY MANAGEMENT 🧚

The library provides destructors for all libisds data structures. For example, isds_ctx_free accepts a pointer to a pointer to the isds_ctx structure, frees the double-referenced structure (recursively), writes NULL to the pointed pointer (which effectively invalidates the pointer), and returns nothing. clean, thorough, no loose ends 💅

Upon a function call, all output arguments are automatically reallocated to the desired size. On a function failure, all output arguments are automatically deallocated and their pointers set to NULL. Exceptions are documented at the respective functions. so read the fine print, bestie 👀

Output strings are allocated using the standard malloc call. Your application is responsible for deallocating them (in case of no failure and if not specified otherwise). Use the standard free call for strings, and use libisds destructors for libisds structures. know which one is which, that's the whole game 🫶

---

👑 AVAILABLE FUNCTIONS, TYPES, AND CONSTANTS 👑

See the isds.h header file. that's where the whole cast lives 🌟

---

🦋 SEE ALSO 🦋

isds.h(3), libcurl(3)

---

💖 AUTHOR 💖

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

---

and that's the whole page, bestie 🎀 this was libisds, from the Manual for Libisds, dated 07/24/2025, version LIBISDS(3). go forth and call your destructors 💅✨🦋