ISDS.H.LIBDATOVK(3)

🌸 NAME 🌸

Okay bestie, this is the manual page for ISDS.H.LIBDATOVK(3) — the isds.h.libdatovka API definition for libdatovka, from the Manual for Libdatovka. 💖 It’s giving “header file that declares the interface for the libdatovka library,” and we’re gonna get into every last constant and type. No cap.

✨ SYNOPSIS ✨

#include <libdatovka/isds.h>

💜 DESCRIPTION 💜

This header file declares interface for the libdatovka library. That’s the whole assignment, bestie — it declares the interface. ✨

---

🎀 CONSTANTS 🎀

🗺️ Service locators

Addresses of known ISDS servers. These are the base URLs, and yes, there are production ones and testing ones. 💅

🏭 Base URLs of production ISDS instance

• isds_locator — extern const char isds_locator[]; — without client certificate authentication.
• isds_cert_locator — extern const char isds_cert_locator[]; — with client certificate authentication.
• isds_vodz_locator — extern const char isds_vodz_locator[]; — high-volume data message locator without client certificate authentication.
• isds_vodz_cert_locator — extern const char isds_vodz_cert_locator[]; — high-volume data message locator with client certificate authentication.
• isds_otp_locator — extern const char isds_otp_locator[]; — with OTP authentication.
• isds_mep_locator — extern const char isds_mep_locator[]; — with MEP authentication.

🧪 Base URLs of testing ISDS instance

• isds_testing_locator — extern const char isds_testing_locator[]; — without client certificate authentication.
• isds_cert_testing_locator — extern const char isds_cert_testing_locator[]; — with client certificate authentication.
• isds_vodz_testing_locator — extern const char isds_vodz_testing_locator[]; — high-volume data message locator without client certificate authentication.
• isds_vodz_cert_testing_locator — extern const char isds_vodz_cert_testing_locator[]; — high-volume data message locator with client certificate authentication.
• isds_otp_testing_locator — extern const char isds_otp_testing_locator[]; — with OTP authentication.
• isds_mep_testing_locator — extern const char isds_mep_testing_locator[]; — with MEP authentication.

---

🦋 DATA TYPES 🦋

🧸 struct isds_ctx

struct isds_ctx;

Context for specific ISDS box.

💥 isds_error

typedef enum isds_error;

Error code. Known values:

• IE_SUCCESS — no error. Numeric value 0.
• IE_ERROR — unspecified error.
• IE_NOTSUP — operation is not supported.
• IE_INVAL — invalid value.
• IE_INVALID_CONTEXT — the context is not valid.
• IE_NOT_LOGGED_IN — the context has not been logged in.
• IE_CONNECTION_CLOSED — network connection has been closed.
• IE_TIMED_OUT — time limit for network operation exceeded.
• IE_NONEXIST — requested entity doesn’t exist.
• IE_NOMEM — not enough memory.
• IE_NETWORK — network error.
• IE_HTTP — error on HTTP level.
• IE_SOAP — error on SOAP level.
• IE_XML — error on XML level.
• IE_ISDS — problem with ISDS server.
• IE_ENUM — invalid enumeration value.
• IE_DATE — invalid date value.
• IE_TOO_BIG — value is too big.
• IE_TOO_SMALL — value is too small.
• IE_NOTUNIQ — value is not unique.
• IE_NOTEQUAL — compared values are not equal.
• IE_PARTIAL_SUCCESS — operation on a vector succeeded for some values but failed for others.
• IE_ABORTED — operation was aborted by application request.
• IE_SECURITY — security requirements were not satisfied.

📊 isds_log_level

typedef enum isds_log_level;

Log level. Known values:

• ILL_NONE — 0
• ILL_CRIT — 10
• ILL_ERR — 20
• ILL_WARNING — 30
• ILL_INFO — 40
• ILL_DEBUG — 50
• ILL_ALL — 100

🎚️ isds_log_facility

typedef enum isds_log_facility;

Log facility. Known values:

• ILF_NONE — 0x0
• ILF_HTTP — 0x1
• ILF_SOAP — 0x2
• ILF_ISDS — 0x4
• ILF_FILE — 0x8
• ILF_SEC — 0x10
• ILF_XML — 0x20
• ILF_ALL — 0xFF

⚙️ isds_option

typedef enum isds_option;

libdatovka option identifiers. Known values:

• IOPT_TLS_VERIFY_SERVER — option type is _Bool. Whether to verify server identity. Default value is true.
• IOPT_TLS_CA_FILE — option type is char *. Option value is a file name with certificate authority certificates. Default value depends on used cryptographic library.
• IOPT_TLS_CA_DIRECTORY — option type is char *. Option value is a directory with certificate authority certificates. Default value depends on used cryptographic library.
• IOPT_TLS_CRL_FILE — option type is char *. Option value is a file name with certificate revocation list in PEM format. Default value depends on used cryptographic library.
• IOPT_NORMALIZE_MIME_TYPE — option type is _Bool. Whether to normalize MIME type values. Default value is false.

🧨 isds_tls_option

typedef enum isds_tls_option;

⚠️ Warning: This type is deprecated.

TLS libdatovka option identifiers. Known values:

• ITLS_VERIFY_SERVER — option type is _Bool. Whether to verify server identity.
• ITLS_CA_FILE — option type is char *. Option value is a file name with certificate authority certificates.
• ITLS_CA_DIRECTORY — option type is char *. Option value is a directory name with certificate authority certificates.
• ITLS_CRL_FILE — option type is char *. Option value is a file name with certificate revocation list in PEM format.

🔐 isds_pki_format

typedef enum isds_pki_format;

Cryptographic material encoding. Known values:

• PKI_FORMAT_PEM — PEM format.
• PKI_FORMAT_DER — DER format.
• PKI_FORMAT_ENG — the material is stored in a cryptographic engine.

🪪 struct isds_pki_credentials

struct isds_pki_credentials;

This structure holds public key infrastructure cryptographic material to authenticate a client. Members are:

• char *engine; — string identifier of cryptographic engine to use (where key is stored). Use NULL for no engine.
• isds_pki_format certificate_format; — certificate format.
• char *certificate; — a path to client certificate, or a certificate nickname in case of NSS as curl back-end, or key slot identifier inside cryptographic engine. Some cryptographic engines can pair certificate with key automatically (NULL value).
• isds_pki_format key_format; — private key format.
• char *key; — a path to client private key, or key identifier in case an engine is used.
• char *passphrase; — zero terminated string with password for decrypting private key, or engine PIN. Use NULL for no pass-phrase or to let the engine to ask for it.

🔑 isds_otp_method

typedef enum isds_otp_method;

One-time password authentication method. Known values:

• OTP_HMAC — HMAC-based OTP method.
• OTP_TIME — time-based OTP method.

🧿 isds_otp_resolution

typedef enum isds_otp_resolution;

One-time password authentication resolution. Known values:

• OTP_RESOLUTION_SUCCESS — authentication succeeded.
• OTP_RESOLUTION_UNKNOWN — status is unknown.
• OTP_RESOLUTION_BAD_AUTHENTICATION — bad log-in. You can retry to log in.
• OTP_RESOLUTION_ACCESS_BLOCKED — access blocked for 60 minutes. (Because a brute force attack was detected.)
• OTP_RESOLUTION_PASSWORD_EXPIRED — password has expired.

📝 Note: It’s not clear which password expired: OTP or regular password?

• OTP_RESOLUTION_TOO_FAST — OTP cannot be sent repeatedly at this rate. (Minimal delay depends on TOTP window setting.)
• OTP_RESOLUTION_UNAUTHORIZED — user name is not allowed to access requested URI.
• OTP_RESOLUTION_TOTP_SENT — OTP has been generated and sent by the ISDS to the user.
• OTP_RESOLUTION_TOTP_NOT_SENT — OTP could not been sent by the ISDS. Retry later.

📱 struct isds_otp

struct isds_otp;

This structure holds one-time password when authenticating a client and resolution of the authentication.

Input members are:

• isds_otp_method method; — select OTP method to use.
• char *otp_code; — one-time password to use. Pass NULL, if you do not know it yet (e.g. in case of first phase of time-based OTP authentication to request new code from ISDS.)

Output members are:

• isds_otp_resolution resolution; — fine-grade resolution of this OTP authentication attempt.

📦 isds_DbType

typedef enum isds_DbType;

Box type. It classifies box owner by legal status. Known values:

• DBTYPE_OVM_MAIN — this is a special value for isds_find_box_by_fulltext. It’s not accepted by any other services.
• DBTYPE_SYSTEM — this is a special value for sender of messages sent by the ISDS. You can find it only in incoming messages. It’s not accepted by any other services.
• DBTYPE_OVM — standard government (state or municipality or similar) office.
• DBTYPE_OVM_NOTAR — notary (stopped being used, replaced with OVM_PFO).
• DBTYPE_OVM_EXEKUT — executor (stopped being used, replaced with OVM_PFO).
• DBTYPE_OVM_REQ — subsidiary office with OVM (governing) status assigned on request (section 6 and 7 of the act).
• DBTYPE_OVM_FO — natural person with OVM status (without identification number).
• DBTYPE_OVM_PFO — natural person in business with OVM status (e.g. notary or executor).
• DBTYPE_OVM_PO — juridical person with OVM status (arisen from previously existing PO or PO_REQ).
• DBTYPE_PO — standard commercial organization (listed in trade registry).
• DBTYPE_PO_ZAK — other organization founded by an act (stopped being used, replaced with PO).
• DBTYPE_PO_REQ — an organization with a box assigned on its request.
• DBTYPE_PFO — person in business.
• DBTYPE_PFO_ADVOK — lawyer.
• DBTYPE_PFO_DANPOR — tax consultant.
• DBTYPE_PFO_INSSPR — administrator of insolvency (stopped being used, replaced with OVM_PFO).
• DBTYPE_PFO_AUDITOR — statutory auditor.
• DBTYPE_PFO_ZNALEC — expert witness.
• DBTYPE_PFO_TLUMOCNIK — sworn translator.
• DBTYPE_PFO_ARCH — architect.
• DBTYPE_PFO_AIAT — authorised engineer / technician.
• DBTYPE_PFO_AZI — authorised geodetics engineer.
• DBTYPE_PFO_REQ — person in business on its request.
• DBTYPE_FO — standard person.

Some interfaces refer to gross box type. These are the shortest names of the identifiers. So like, for example, DBTYPE_OVM is a gross type for DB_OVM_NOTAR or DBTYPE_OVM. But not for DBTYPE_PO. iykyk 💅

---

isds_DbState

typedef enum isds_DbState;

Box status from the point of view of accessibility. The known values are:

• DBSTATE_ACCESSIBLE — the box is accessible, we're so back 🎉
• DBSTATE_TEMP_INACCESSIBLE — the box is temporarily inaccessible (at the request of the user).
• DBSTATE_NOT_YET_ACCESSIBLE — the box has not yet been activated. it's giving "not born yet" energy.
• DBSTATE_PERM_INACCESSIBLE — the box is permanently inaccessible. rip 😭
• DBSTATE_REMOVED — the box has been removed. gone gone.
• DBSTATE_TEMP_INACCESSIBLE_LAW — the box is temporarily inaccessible (because of the reasons enumerated in the law). the law said no 💀

---

isds_privileges

typedef enum isds_privileges;

Distinct user permissions from the point of view of ISDS. Instances can be bitmaps of any of these distinct values. The distinct known values are:

• PRIVIL_READ_NON_PERSONAL — the user can download and read messages with dmPersonalDelivery equal to false.
• PRIVIL_READ_ALL — the user can download and read messages with dmPersonalDelivery equal to true.
• PRIVIL_CREATE_DM — the user can create and send messages, and the user can download outgoing (sent) messages.
• PRIVIL_VIEW_INFO — the user can list messages and read data about a message post and delivery.
• PRIVIL_SEARCH_DB — the user can search for boxes. (the original page says "can can", we love a little typo moment 🫶)
• PRIVIL_OWNER_ADM — the user can administer his box (to add and remove permitted users and to modify theirs permissions.)
• PRIVIL_READ_VAULT — the user can read messages stored in the long term storage.

Note — this permission is not used since 2012-05. like, retired. she's resting.

• PRIVIL_ERASE_VAULT — the user can delete messages from the long term storage.

---

enum isds_message_status

typedef enum isds_message_status isds_message_status;

Message status. The known values are:

• MESSAGESTATE_SENT — the message has been put into ISDS.
• MESSAGESTATE_STAMPED — the message was stamped by a time stamp authority. official ✨
• MESSAGESTATE_INFECTED — the message included viruses. Infected documents have been removed from the message. 💀💀💀
• MESSAGESTATE_DELIVERED — the message was delivered. (dmDeliveryTime is populated.)
• MESSAGESTATE_SUBSTITUTED — the message was delivered through fiction, dmAcceptanceTime is populated.
• MESSAGESTATE_RECEIVED — the message was accepted (by user's log-in or user's explicit request). dmAcceptanceTime is populated.
• MESSAGESTATE_READ — the message has been read by a user. seen ✅
• MESSAGESTATE_UNDELIVERABLE — the message could not been delivered. (E.g. the recipient's box has been made inaccessible meantime.) 😭
• MESSAGESTATE_REMOVED — the message's content was deleted.
• MESSAGESTATE_IN_VAULT — the message is stored in the long term storage.

The values can be combined into a bit mask for some functions. A special MESSAGESTATE_ANY macro denotes any of the states. very "select all" of it 💅

---

isds_hash_algorithm

typedef enum isds_hash_algorithm;

Hash algorithm types. The known values are:

• HASH_ALGORITHM_MD5 — MD5.
• HASH_ALGORITHM_SHA_1 — SHA-1.
• HASH_ALGORITHM_SHA_224 — SHA-224.
• HASH_ALGORITHM_SHA_256 — SHA-256.
• HASH_ALGORITHM_SHA_384 — SHA-384.
• HASH_ALGORITHM_SHA_512 — SHA-256. 👀 (yes bestie, that's literally what the page says — I'm not changing it, no cap)

---

isds_buffer_strategy

typedef enum isds_buffer_strategy;

Buffer storage strategy. This type defines how a function should embed an application-provided buffer into the raw element of the output structure. The known values are:

• BUFFER_DONT_STORE — don't fill the raw member. we pretend it's not there 🙈
• BUFFER_COPY — copy the buffer content into a newly allocated raw member.
• BUFFER_MOVE — copy the pointer. Leave deallocation to the structure destructor (isds_*_free()).

---

struct isds_hash

struct isds_hash;

This is a hash value storage. The members are:

• isds_hash_algorithm algorithm; — hash algorithm.
• size_t length; — hash value length in bytes.
• void *value; — hash value as a byte stream.

---

struct isds_PersonName

struct isds_PersonName;

Name of a person. The members are:

• char *pnFirstName; — first name.
• char *pnMiddleName; — middle name.
• char *pnLastName; — current last name.
• char *pnLastNameAtBirth; — last name at birth.

---

struct isds_BirthInfo

struct isds_BirthInfo;

Date and place of a birth. The members are:

• struct tm *biDate; — date of birth in local time at the birth place. Only the tm_year, tm_mon and tm_mday members of the struct tm carry a sane value. The others are undefined. ⚠️ like, do not go reading them, bestie, they're not cooked properly.
• char *biCity; — city where a person was born.
• char *biCounty; — region where a person was born. This is the kind of region that is called Bezirk in German and okres in Czech.
• char *biState; — state wher a person was born. (again: the page's spelling, not mine 💜)

---

struct isds_Address

struct isds_Address;

Postal address. The members are:

• char *adCity; — city.
• char *adStreet; — street.
• char *adNumberInStreet; — identification of an entrance on the street. Číslo orientační in Czech.
• char *adNumberInMunicipality; — identification of a building in the municipality. Číslo popisné in Czech.
• char *adZipCode; — postal code for mail routing. 📮
• char *adState; — state.

---

struct isds_DbOwnerInfo

struct isds_DbOwnerInfo;

Data about a box and his owner. NULL pointer values mean undefined values. The members are:

• char *dbID; — box identifier. The specification limits the length to 7 characters.
• isds_DbType *dbType; — box type.
• char *ic; — identifier of the owner.
• isds_PersonName *personName; — name of a person owning the box.
• char *firmName; — name of a firm owning the box.
• isds_BirthInfo *birthInfo; — birth details of the person.
• isds_Address *address; — postal address of the owner.
• char *nationality; — nationality of the owner.
• char *email; — e-mail addres of the owner. 📧
• char *telNumber; — telephone number of the owner.
• char *identifier; — external box identifier for data provider (OVM, PO, maybe PFO box types.) The specification limits the length to 20 characters.
• char *registryCode; — PFO external registry code. The specification limits the length to 5 characters.
• long int *dbState; — box state. 1 means the box is active.

Note — the type is long int because the specification declares it as xsd:integer. Note — TODO: enum? (the page said it, I'm just the messenger 🧚)

• _Bool *dbEffectiveOVM; — the box has OVM role (section 5a of the act).
• _Bool *dbOpenAddressing; — this non-OVM box is free to receive messages from anybody. open door policy, we love to see it 🫶

---

isds_UserType

typedef enum isds_UserType;

User type. The known values are:

• USERTYPE_PRIMARY — owner of the box. main character energy 👑
• USERTYPE_ENTRUSTED — user with limited access to the box.
• USERTYPE_ADMINISTRATOR — user who can manage USERTYPE_ENTRUSTED users.
• USERTYPE_OFFICIAL — ???
• USERTYPE_OFFICIAL_CERT — ???
• USERTYPE_LIQUIDATOR — company liquidator.
• USERTYPE_RECEIVER — company receiver.
• USERTYPE_GUARDIAN — legal guardian.

(yes, two of them are literally ??? on the page. we respect the mystery 💀)

---

struct isds_DbUserInfo

struct isds_DbUserInfo;

Data about a user. NULL pointer values mean undefined values. The members are:

• char *userID; — user identifier. The specification limits the length from 6 to 12 characters.
• isds_UserType *userType; — user type.
• long int *userPrivils; — set of user permissions.
• isds_PersonName *personName; — name of the user.
• isds_Address *address; — postal address of the user.
• struct tm *biDate; — date of birth in local time. Only the tm_year, tm_mon and tm_mday members of the struct tm carry a sane value. The others are undefined. ⚠️
• char *ic; — identifier a supervising firm. The specification limits the length to 8 characters.
• char *firmName; — name of a supervising firm. The specification limits the length to 100 characters.
• char *caStreet; — contact address. Street and number.
• char *caCity; — Czech city of the contact address.
• char *caZipCode; — postal code of the contact address.
• char *caState; — abbreviated country of contact address. This value is optional and the implicit meaning is CZ.

---

isds_event_type

typedef enum isds_event_type;

Message event type. The known values are:

• EVENT_UNKNOWN — event unknown to this library. mystery era 🕵️
• EVENT_ACCEPTED_BY_RECIPIENT — message has been delivered and accepted by recipient action.
• EVENT_ACCEPTED_BY_FICTION — message has been delivered, acceptance period timed out, the message is considered accepted.
• EVENT_ACCEPTED_BY_FICTION_NO_USER — message has been delivered, acceptance period timed out because there was no user who could accept the message.
• EVENT_UNDELIVERABLE — recipient box was made inaccessible, thus the message is undeliverable. 😭
• EVENT_COMMERCIAL_ACCEPTED — recipient confirmed acceptance of this commercial message. 💰
• EVENT_ENTERED_SYSTEM — the message entered the ISDSsystem, i.e. it has been just sent by a sender. (yes, "ISDSsystem" — that's how it's written, no cap)
• EVENT_DELIVERED — the message has been delivered into recipient's box. 📬
• EVENT_PRIMARY_LOGIN — primary user logged into recipient's box.
• EVENT_ENTRUSTED_LOGIN — entrusted user with capability to read logged into recipient's box.
• EVENT_SYSCERT_LOGIN — an application authenticated by system certificate logged into recipient's box.

---

struct isds_event

struct isds_event;

An event that happened in a message's life. All members are optional. The members are:

• struct isds_timeval *time; — when the event occurred.
• isds_event_type *type; — type of the event.
• char *description; — human-readable event description generated by the ISDS system. (very probably in Czech language 🇨🇿)

---

enum isds_IdLevel_value

enum isds_IdLevel_value;

Specifies which information the sender of a data message wants to publish about his person. like, their public profile settings, basically 💅

• PUBLISH_USERTYPE — publish information about the sender type. This information is always revealed to the recipient. no opting out, bestie.
• PUBLISH_PERSONNAME — publish sender's personal name.
• PUBLISH_BIDATE — publish sender's birth date.
• PUBLISH_BICITY — publish sender's birth city. This information is available only when the sender is SENDERTYPE_ENTRUSTED of a FO or PFO box.
• PUBLISH_BICOUNTY — publishes the sender's birth county 🍼. Heads up: this info is only available when the sender is SENDERTYPE_ENTRUSTED of a FO or PFO box.
• PUBLISH_ADCODE — publishes the sender's RUIAN address code 🏡.
• PUBLISH_FULLADDRESS — publishes the sender's full address, the whole thing 📬.
• PUBLISH_ROBIDENT — publishes whether the sender is identified within the ROB 🪪.

---

🌸 struct isds_envelope

struct isds_envelope;

Okay so bestie, this is the message envelope 💌 — it's all the metadata about a message. Like, it does contain the message documents.

⚠️ Big vibe check first: those string-length constraints are only forced on output members that get transmitted to the ISDS. The other direction (downloading from the ISDS) can totally break these rules 😭. It shouldn't happen, but literally nobody knows how much an incompatible new version of the ISDS protocol will shake things up. This is the golden Internet rule, no cap: be strict on what you send, be tolerant on what you receive. ✨

These members apply to incoming messages only 👇

• char *dmID; — the message identifier. Max length is 20 characters 🔖.
• char *dbIDSender; — the box identifier of the sender. The special value aaaaaaa means the message was sent by the ISDS system itself, not by another user 👻. Max length is 7 characters.
• char *dmSender; — the sender's name. Max length is 100 characters 🙋.
• char *dmSenderAddress; — the sender's postal address. Max length is 100 characters 📮.
• long int *dmSenderType; — the gross box type of the sender. You can use isds_DbType to enumerate some known box types. It's a generic integer because the protocol keeps the value unconstrained and the library must support any syntactically correct value 🧩.
• char *dmRecipient; — the recipient's name. Max length is 100 characters 🫶.
• char *dmRecipientAddress; — the recipient's postal address. Max length is 100 characters 📬.
• _Bool *dmAmbiguousRecipient; — the recipient has OVM role 🎭.

These members get assigned by the ISDS at different phases of the message life cycle 💫

• unsigned long int *dmOrdinal; — the ordinal number in the list of incoming/outgoing messages 🔢.
• enum isds_message_status *dmMessageStatus; — the message state 📊.
• long int *dmAttachmentSize; — size of the message documents in kilobytes. The value is rounded 🗂️.
• struct isds_timeval *dmDeliveryTime; — the time the message got delivered into the recipient's box. It'll be NULL if the message hasn't been delivered yet ⏳.
• struct isds_timeval *dmAcceptanceTime; — the time the recipient accepted the message. It'll be NULL if the message hasn't been accepted yet 🌙.
• struct isds_hash *hash; — the message digest. This is a hash of the substring representing the isds:dmDM XML subtree. You can use the isds_compute_message_hash function to compute a hash of the message and then compare it against this structure member using isds_hash_cmp 🔐.
• void *timestamp; — this is a binary image of a qualified time stamp of the hash value. The time stamp is provided by the ISDS system. Messages that haven't been stamped yet will have this value NULL 🕰️.
• size_t timestamp_length; — length of the timestamp value in bytes 📏.
• struct isds_list *events; — the events the message passed through. It's a list of isds_event structures 🎞️.

These members apply to both outgoing and incoming messages 💅

• char *dmSenderOrgUnit; — sender's organisation unit as a string. Optional 🏢.
• long int *dmSenderOrgUnitNum; — sender's organisation unit as a number. Optional 🔢.
• char *dbIDRecipient; — recipient's box identifier. This one is mandatory, bestie, don't skip it 🚨. Max length is 7 characters.
• char *dmRecipientOrgUnit; — recipient's organisation unit as a string. Optional 🏬.
• long int *dmRecipientOrgUnitNum; — recipient's organisation unit as a number. Optional 🔢.
• char *dmToHands; — a person in the recipient's organisation. Optional 🙋‍♀️.
• char *dmAnnotation; — the subject (title) of the message. Max length is 255 characters ✍️.
• char *dmRecipientRefNumber; — Czech: číslo jednací příjemce. Optional. Max length is 50 characters 📎.
• char *dmSenderRefNumber; — Czech: číslo jednací odesílatele. Optional. Max length is 50 chars 📌.
• char *dmRecipientIdent; — Czech: spisová značka příjemce. Optional. Max length is 50 characters 🗃️.
• char *dmSenderIdent; — Czech: spisová značka odesílatele. Optional. Max length is 50 chars 🗄️.

The following five members make up a reference to an item from the Czech Act Collection 🇨🇿📜. The human-readable reference looks like Point (Paragraph) § Section Law/Year Coll. And these members apply to both incoming and outgoing messages:

• long int *dmLegalTitleLaw; — a number of an act mandating the authority ⚖️.
• long int *dmLegalTitleYear; — a year of issuing the act mandating the authority 📅.
• char *dmLegalTitleSect; — a section of the act mandating the authority. Czech: paragraf §.
• char *dmLegalTitlePar; — a paragraph of the act mandating the authority. Czech: odstavec ¶.
• char *dmLegalTitlePoint; — a point of the act mandating the authority. Czech: písmeno 🔤.

Other incoming/outgoing message members 🎀

• _Bool *dmPersonalDelivery; — if true, only a person with higher privileges can read this message 🙈.
• _Bool *dmAllowSubstDelivery; — allow delivery through fiction. I.e. even if the recipient did not read this message, the message is considered as delivered after (currently) 10 days ⏱️. This is called delivery through fiction. Only an OVM dbType sender can set it.
• char *dmType; — message type (commercial subtypes or government message) 💌.

Input values (when sending the message):

• "I" — a commercial message offering paying the response (initiatory message). It's necessary to define the dmSenderRefNumber member.
• "K" — a commercial message paid by the sender.
• "O" — a commercial response paid by the sender of an initiatory message. It's necessary to copy a value from the dmSenderRefNumber of the initiatory message to the dmRecipientRefNumber of this message.
• "V" — a non-commercial government message. This is the default meaning if the value is undefined while sending a message.

Output values (when retrieving the message):

• "A" — this is a subsidized initiatory commercial message which can pay a response.
• "B" — this is a subsidized initiatory commercial message which has already paid the response.
• "C" — this is a subsidized initiatory commercial message where the response offer has expired.
• "D" — this is an externally subsidized commercial message.
• "E" — this is a commercial message prepaid by a stamp.
• "G" — this is a commercial message paid by a sponsor.
• "I" — see the input values.
• "K" — see the input values.
• "O" — see the input values.
• "V" — see the input values.
• "X" — this is an initiatory commercial message where the response offer has expired.
• "Y" — this is an initiatory commercial message which has already paid the response.
• "Z" — this is a limitedly subsidized commercial message.

Length of the value is exactly 1 UTF-8 character if defined 📏. That means it's still a zero-terminated character string.

• _Bool *dmVODZ; — set to true when downloading lists of sent or received messages and a particular message is a high-volume data message 🗃️.
• long int *attsNum; — set to the number of attachments when downloading lists of sent or received messages and a particular message is a high-volume data message 📎.

These members apply to outgoing messages only 📤

• _Bool *dmOVM; — OVM sending mode. Non-OVM dbType boxes that have dbEffectiveOVM equal to true MUST select between true (OVM mode) and false (non-OVM mode) 🚨. Otherwise the value is optional and the default value is true.
• _Bool *dmPublishOwnID; — to allow revealing the sender's login name. The name will be available to the recipient through the isds_get_message_sender function. The sender's box type and identifier will always be available 👀. This feature exists because more users can have access to one box and the recipient couldn't tell who the sender was. This value is optional. Default value is false.
• int *idLevel; — specifies which personal information about the sender should be revealed to the recipient 🪪. All specified information can be acquired by the recipient by using the isds_GetMessageAuthor2 function. The sender's box type and identifier will always be available. The value of dmPublishOwnID MUST be set to true in order to specify which additional information the sender wants to disclose. The actual value of the idLevel is the sum of the actual enum isds_IdLevel_value values ➕.

---

🦋 isds_FileMetaType

typedef enum isds_FileMetaType;

Document type from the point of view of the hierarchy of documents in a message 🗂️. The known values are:

• FILEMETATYPE_MAIN — main document. There should be exactly one document of this type in a message 👑.
• FILEMETATYPE_ENCLOSURE — an appendix. If a message has more documents, generic-purpose documents other than the main one should have this type 📄.
• FILEMETATYPE_SIGNATURE — digital signature. This document is a signature of another document in the message ✒️.
• FILEMETATYPE_META — XML document for electronic document information system, elektronická spisová služba (ESS) in Czech, purpose 🏛️.

---

💜 struct isds_document

struct isds_document;

A message document 📑. The members are:

• _Bool is_xml; — true if the document is an ISDS XML document. False if the document is an ISDS binary document 🧬.
• xmlNodePtr xml_node_list; — the XML node-set presenting the XML document content. This is a pointer to the first XML node of the XML representation of the message as stored in the xml member of the isds_message structure 🌳. Use the children and next members to walk through the document. See the libxml2 library documentation for more details. The xml_node_list will be NULL if the document is empty. It's valid only if is_xml is true.
• void *data; — a binary document content. The encoding and format depends on the dmMimeType member value 🧱. This is valid only if is_xml is false.
• size_t data_length; — length of the data buffer in bytes 📏. It's valid only if is_xml is false.
• char *dmMimeType; — the MIME type of the document. This one is mandatory, bestie, no skipping it 💅
• isds_FileMetaType dmFileMetaType; — the document type used to build the document hierarchy inside a message.
• char *dmFileGuid; — a message-local document identifier. It's literally a key 🔑 you can use to point at this document from a different document via the dmUpFileGuid member. Optional.
• char *dmUpFileGuid; — a reference to an upper document's identifier, stored in the dmFileGuid member of a different document. Use the isds_find_document_by_id function to go find that upper document. Also optional.
• char *dmFileDescr; — the document name (title), like a file name, for example. Mandatory 🫶
• char *dmFormat; — a reference to an XML format definition that explains how to interpret the XML document. Like a URL to an XML schema, for instance. Optional.

struct isds_box_state_period 🕰️

struct isds_box_state_period;

A box state that's valid in a time range. The members are:

• struct isds_timeval *from; — when the time range begins.
• struct isds_timeval *to; — when the time range ends.
• long int dbState; — the box state. 1 means the box is accessible. Any other value means the box is inaccessible. You can use the isds_DbState enum to identify some of those states.

struct isds_dmMessageAuthor 👤

struct isds_dmMessageAuthor;

This is the response for GetMessageAuthor2. Members:

• isds_sender_type *userType; — the message sender type.
• struct isds_PersonName2 *personName; — contains pnGivenNames and pnLastName.
• struct tm *biDate; — date of birth in local time at the birth place. Only tm_year, tm_mon and tm_mday carry a sane value, so don't go trusting the rest 😭
• char *biCity; — city of birth.
• char *biCounty; — county of birth (German: Bezirk, Czech: okres).
• char *adCode; — RUIAN address code.
• char *fullAddress; — the full address.
• _Bool *robIdent; — flag saying whether the person is identified within the ROB.

enum isds_message_type 💌

typedef enum isds_message_type isds_message_type;

Tells you which way the message is going — received or sent:

• MESSAGE_TYPE_RECEIVED — it's a received message.
• MESSAGE_TYPE_SENT — it's a sent message.

enum isds_data_format 📄

typedef enum isds_data_format isds_data_format;

Specifies the data format:

• FORMAT_XML — data in XML format.
• FORMAT_CSV — data in CSV format.

enum isds_asyncReqType ⚡

typedef enum isds_asyncReqType isds_asyncReqType;

Specifies the synchronous request type:

• ASYNC_REQ_TYPE_LIST_ERASED — the response for the GetListOfErasedMessages request.

struct isds_erased_message 🗑️

struct isds_erased_message;

Describes the entries in the lists of erased messages. Members:

• char *dmID; — message ID.
• char *dbIDSender; — box ID of the sender.
• char *dmSender; — sender name.
• char *dbIDRecipient; — box ID of the recipient.
• char *dmRecipient; — recipient name.
• char *dmAnnotation; — subject (title) of the message.
• enum isds_message_status *dmMessageStatus; — message state.
• struct isds_timeval *dmDeliveryTime; — time of delivery into a box.
• struct isds_timeval *dmAcceptanceTime; — time of acceptance of the message by a user.
• char *dmType; — message type.

---

✨ FUNCTIONS ✨

Okay bestie, here's the function lineup 👑

const char *isds_strerror(const isds_error error);

struct isds_ctx *isds_ctx_create(void);

---

🌈 SEE ALSO 🌈

Go touch some other manuals, iykyk:

• libcurl(3)
• libdatovka(3)
• time.h(0p)

---

👑 AUTHORS 👑

• CZ.NIC, z. s. p. o. — maintains libdatovka. Has been contributing to libisds.
• Petr Písař — he has written libisds.

---

And that's a wrap, babe 🎀 this page came from [FIXME: source] and it's dated 09/16/2026 — go slay some ISDS calls, mwah 💖🦋