--- name: "isds.h.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/isds.h.libdatovka" --- # isds.h.libdatovka(3) .SH "NAME" isds.h.libdatovka - API definition for libdatovka .SH "SYNOPSIS" ``` #include ``` .SH "DESCRIPTION" .PP This header file declares interface for the libdatovka library. .SH "CONSTANTS" .SS "Service locators" .PP Addresses of known ISDS servers. .sp\ **Base URLs of production ISDS instance** .sp\ **isds\_locator** ``` extern const char isds_locator[]; ``` .PP Without client certificate authentication. .RE .sp\ **isds\_cert\_locator** ``` extern const char isds_cert_locator[]; ``` .PP With client certificate authentication. .RE .sp\ **isds\_vodz\_locator** ``` extern const char isds_vodz_locator[]; ``` .PP High-volume data message locator without client certificate authentication. .RE .sp\ **isds\_vodz\_cert\_locator** ``` extern const char isds_vodz_cert_locator[]; ``` .PP High-volume data message locator with client certificate authentication. .RE .sp\ **isds\_otp\_locator** ``` extern const char isds_otp_locator[]; ``` .PP With OTP authentication. .RE .sp\ **isds\_mep\_locator** ``` extern const char isds_mep_locator[]; ``` .PP With MEP authentication. .RE\ .RE .sp\ **Base URLs of testing ISDS instance** .sp\ **isds\_testing\_locator** ``` extern const char isds_testing_locator[]; ``` .PP Without client certificate authentication. .RE .sp\ **isds\_cert\_testing\_locator** ``` extern const char isds_cert_testing_locator[]; ``` .PP With client certificate authentication. .RE .sp\ **isds\_vodz\_testing\_locator** ``` extern const char isds_vodz_testing_locator[]; ``` .PP High-volume data message locator without client certificate authentication. .RE .sp\ **isds\_vodz\_cert\_testing\_locator** ``` extern const char isds_vodz_cert_testing_locator[]; ``` .PP High-volume data message locator with client certificate authentication. .RE .sp\ **isds\_otp\_testing\_locator** ``` extern const char isds_otp_testing_locator[]; ``` .PP With OTP authentication. .RE .sp\ **isds\_mep\_testing\_locator** ``` extern const char isds_mep_testing_locator[]; ``` .PP With MEP authentication. .RE\ .RE .SH "DATA TYPES" .SS "struct isds\_ctx" ``` struct isds_ctx; ``` .PP Context for specific ISDS box. .SS "isds\_error" ``` typedef enum isds_error; ``` .PP Error code. Known values: .PP IE\_SUCCESS No error. Numeric value 0. .RE .PP IE\_ERROR Unspecified error. .RE .PP IE\_NOTSUP Operation is not supported. .RE .PP IE\_INVAL Invalid value. .RE .PP IE\_INVALID\_CONTEXT The context is not valid. .RE .PP IE\_NOT\_LOGGED\_IN The context has not been logged in. .RE .PP IE\_CONNECTION\_CLOSED Network connection has been closed. .RE .PP IE\_TIMED\_OUT Time limit for network operation exceeded. .RE .PP IE\_NONEXIST Requested entity doesn't exist. .RE .PP IE\_NOMEM Not enough memory. .RE .PP IE\_NETWORK Network error. .RE .PP IE\_HTTP Error on HTTP level. .RE .PP IE\_SOAP Error on SOAP level. .RE .PP IE\_XML Error on XML level. .RE .PP IE\_ISDS Problem with ISDS server. .RE .PP IE\_ENUM Invalid enumeration value. .RE .PP IE\_DATE Invalid date value. .RE .PP IE\_TOO\_BIG Value is too big. .RE .PP IE\_TOO\_SMALL Value is too small. .RE .PP IE\_NOTUNIQ Value is not unique. .RE .PP IE\_NOTEQUAL Compared values are not equal. .RE .PP IE\_PARTIAL\_SUCCESS Operation on a vector succeeded for some values but failed for others. .RE .PP IE\_ABORTED Operation was aborted by application request. .RE .PP IE\_SECURITY Security requirements were not satisfied. .RE .SS "isds\_log\_level" ``` typedef enum isds_log_level; ``` .PP Log level. Know values: .PP **ILL\_NONE** 0 .RE .PP **ILL\_CRIT** 10 .RE .PP **ILL\_ERR** 20 .RE .PP **ILL\_WARNING** 30 .RE .PP **ILL\_INFO** 40 .RE .PP **ILL\_DEBUG** 50 .RE .PP **ILL\_ALL** 100 .RE .SS "isds\_log\_facility" ``` typedef enum isds_log_facility; ``` .PP Log facility. Know values: .PP **ILF\_NONE** 0x0 .RE .PP **ILF\_HTTP** 0x1 .RE .PP **ILF\_SOAP** 0x2 .RE .PP **ILF\_ISDS** 0x4 .RE .PP **ILF\_FILE** 0x8 .RE .PP **ILF\_SEC** 0x10 .RE .PP **ILF\_XML** 0x20 .RE .PP **ILF\_ALL** 0xFF .RE .SS "isds\_option" ``` typedef enum isds_option; ``` .PP libdatovka option identifiers. Known values: .PP **IOPT\_TLS\_VERIFY\_SERVER** Option type is **\_Bool**. Whether to verify server identity. Default value is true. .RE .PP **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. .RE .PP **IOPT\_TLS\_CA\_DIRECTORY** Option type is **char \***, Option value is a directory with certificate authority certificates. Default value depends on used cryptographic library. .RE .PP **IOPT\_TLS\_CRL\_FILE** Option type is **char \***. Option value is a file name with certificat revocation list in PEM format. Default value depends on used cryptographic library. .RE .PP **IOPT\_NORMALIZE\_MIME\_TYPE** Optiona type is **\_Bool**. Whether to normalize MIME type values. Default value is false. .RE .SS "isds\_tls\_option" ``` typedef enum isds_tls_option; ``` .if n {.sp **Warning**\ This type is deprecated. .PP TLS libdatovka option identifiers. Known values: .PP **ITLS\_VERIFY\_SERVER** Option type is **\_Bool**. Whether to verify server identity. .RE .PP **ITLS\_CA\_FILE** Option type is **char \***. Option value is a file name with certificate authority certificates. .RE .PP **ITLS\_CA\_DIRECTORY** Option type is **char \***. Option value is a directory name with certificate authority certificates. .RE .PP **ITLS\_CRL\_FILE** Option type is **char \***. Option value is a file name with certificate revocation list in PEM format. .RE .SS "isds\_pki\_format" ``` typedef enum isds_pki_format; ``` .PP Cryptographic material encoding. Known values: .PP **PKI\_FORMAT\_PEM** PEM format. .RE .PP **PKI\_FORMAT\_DER** DER format. .RE .PP **PKI\_FORMAT\_ENG** The material is stored in a cryptographic engine. .RE .SS "struct isds\_pki\_credentials" ``` struct isds_pki_credentials; ``` .PP This structure holds public key infrastructure cryptographic material to authenticate a client. Members are: .PP **char \****engine*; String identifier of cryptographic engine to use (where key is stored). Use NULL for no engine. .RE .PP **isds\_pki\_format** *certificate\_format*; Certificate format. .RE .PP **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). .RE .PP **isds\_pki\_format** *key\_format*; Private key format. .RE .PP **char \****key*; A path to client private key, or key identifier in case an engine is used. .RE .PP **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. .RE .SS "isds\_otp\_method" ``` typedef enum isds_otp_method; ``` .PP One-time password authentication method. Known values: .PP **OTP\_HMAC** HMAC-based OTP method. .RE .PP **OTP\_TIME** Time-based OTP method. .RE .SS "isds\_otp\_resolution" ``` typedef enum isds_otp_resolution; ``` .PP One-time password authentication resolution. Known values: .PP **OTP\_RESOLUTION\_SUCCESS** Authentication succeeded. .RE .PP **OTP\_RESOLUTION\_UNKNOWN** Status is unknown. .RE .PP **OTP\_RESOLUTION\_BAD\_AUTHENTICATION** Bad log-in. You can retry to log in. .RE .PP **OTP\_RESOLUTION\_ACCESS\_BLOCKED** Access blocked for 60 minutes. (Because a brute force attack was detected.) .RE .PP **OTP\_RESOLUTION\_PASSWORD\_EXPIRED** Password has expired. .if n {.sp **Note**\ It's not clear which password expired: OTP or regular password? .sp .5v .RE .PP **OTP\_RESOLUTION\_TOO\_FAST** OTP cannot be sent repeatedly at this rate. (Minimal delay depends on TOTP window setting.) .RE .PP **OTP\_RESOLUTION\_UNAUTHORIZED** User name is not allowed to access requested URI. .RE .PP **OTP\_RESOLUTION\_TOTP\_SENT** OTP has been generated and sent by the ISDS to the user. .RE .PP **OTP\_RESOLUTION\_TOTP\_NOT\_SENT** OTP could not been sent by the ISDS. Retry later. .RE .SS "struct isds\_otp" ``` struct isds_otp; ``` .PP This structure holds one-time password when authenticating a client and resolution of the authentication. .PP Input members are: .PP **isds\_otp\_method** *method*; Select OTP method to use. .RE .PP **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.) .RE .PP Output members are: .PP **isds\_otp\_resolution** *resolution*; Fine-grade resolution of this OTP authentication attempt. .RE .SS "isds\_DbType" ``` typedef enum isds_DbType; ``` .PP Box type. It classifies box owner by his legal status. Known values: .PP **DBTYPE\_OVM\_MAIN** This is a special value for **isds\_find\_box\_by\_fulltext**. It's not accepted by any other services. .RE .PP **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. .RE .PP **DBTYPE\_OVM** Standard government (state or municipality or similar) office. .RE .PP **DBTYPE\_OVM\_NOTAR** Notary (stopped being used, replaced with OVM\_PFO). .RE .PP **DBTYPE\_OVM\_EXEKUT** Executor (stopped being used, replaced with OVM\_PFO). .RE .PP **DBTYPE\_OVM\_REQ** Subsidiary office with OVM (governing) status assigned on request (section 6 and 7 of the act). .RE .PP **DBTYPE\_OVM\_FO** Natural person with OVM status (without identification number). .RE .PP **DBTYPE\_OVM\_PFO** Natural person in business with OVM status (e.g. notary or executor). .RE .PP **DBTYPE\_OVM\_PO** Juridical person with OVM status (arisen from previously existing PO or PO\_REQ). .RE .PP **DBTYPE\_PO** Standard commercial organization (listed in trade registry). .RE .PP **DBTYPE\_PO\_ZAK** Other organization founded by an act (stopped being used, replaced with PO). .RE .PP **DBTYPE\_PO\_REQ** An organization with a box assigned on its request. .RE .PP **DBTYPE\_PFO** Person in business. .RE .PP **DBTYPE\_PFO\_ADVOK** Lawyer. .RE .PP **DBTYPE\_PFO\_DANPOR** Tax consultant. .RE .PP **DBTYPE\_PFO\_INSSPR** Administrator of insolvency (stopped being used, replaced with OVM\_PFO). .RE .PP **DBTYPE\_PFO\_AUDITOR** Statutory auditor. .RE .PP **DBTYPE\_PFO\_ZNALEC** Expert witness. .RE .PP **DBTYPE\_PFO\_TLUMOCNIK** Sworn translator. .RE .PP **DBTYPE\_PFO\_ARCH** Architect. .RE .PP **DBTYPE\_PFO\_AIAT** Authorised engineer / technician. .RE .PP **DBTYPE\_PFO\_AZI** Authorised geodetics engineer. .RE .PP **DBTYPE\_PFO\_REQ** Person in business on its request. .RE .PP **DBTYPE\_FO** Standard person. .RE .PP Some interfaces refer to *gross* box type. These are the shortest names of the identifiers. For example, DBTYPE\_OVM is a gross type for DB\_OVM\_NOTAR or DBTYPE\_OVM. But not for DBTYPE\_PO. .SS "isds\_DbState" ``` typedef enum isds_DbState; ``` .PP Box status from point of view of accessibility. Known values: .PP **DBSTATE\_ACCESSIBLE** The box is accessible. .RE .PP **DBSTATE\_TEMP\_INACCESSIBLE** The box is temporarily inaccessible (at the request of the user). .RE .PP **DBSTATE\_NOT\_YET\_ACCESSIBLE** The box has not yet been activated. .RE .PP **DBSTATE\_PERM\_INACCESSIBLE** The box is permanently inaccessible. .RE .PP **DBSTATE\_REMOVED** The box has been removed. .RE .PP **DBSTATE\_TEMP\_INACCESSIBLE\_LAW** The box is temporarily inaccessible (because of the reasons enumerated in the law). .RE .SS "isds\_privileges" ``` typedef enum isds_privileges; ``` .PP Distinct user permissions from point of view of ISDS. Instances can be bitmaps of any of these distinct values. Distinct known values are: .PP **PRIVIL\_READ\_NON\_PERSONAL** The user can download and read messages with *dmPersonalDelivery* equal to false. .RE .PP **PRIVIL\_READ\_ALL** The user can download and read messages with *dmPersonalDelivery* equal to true. .RE .PP **PRIVIL\_CREATE\_DM** The user can create and send messages, the user can download outgoing (sent) messages. .RE .PP **PRIVIL\_VIEW\_INFO** The user can list messages and read data about a message post and delivery. .RE .PP **PRIVIL\_SEARCH\_DB** The user can can search for boxes. .RE .PP **PRIVIL\_OWNER\_ADM** The user can administer his box (to add and remove permitted users and to modify theirs permissions.) .RE .PP **PRIVIL\_READ\_VAULT** The user can read messages stored in the long term storage. .if n {.sp **Note**\ This permission is not used since 2012-05. .RE .PP **PRIVIL\_ERASE\_VAULT** The user can delete messages from the long term storage. .RE .SS "enum isds\_message\_status" ``` typedef enum isds_message_status isds_message_status; ``` .PP Message status. Known values are: .PP **MESSAGESTATE\_SENT** The message has been put into ISDS. .RE .PP **MESSAGESTATE\_STAMPED** Message was stamped by a time stamp authority. .RE .PP **MESSAGESTATE\_INFECTED** The message included viruses. Infected documents have been removed from the message. .RE .PP **MESSAGESTATE\_DELIVERED** The message was delivered. (*dmDeliveryTime* is populated.) .RE .PP **MESSAGESTATE\_SUBSTITUTED** The message was delivered through fiction, *dmAcceptanceTime* is populated. .RE .PP **MESSAGESTATE\_RECEIVED** The message was accepted (by user's log-in or user's explicit request). *dmAcceptanceTime* is populated. .RE .PP **MESSAGESTATE\_READ** The message has been read by a user. .RE .PP **MESSAGESTATE\_UNDELIVERABLE** The message could not been delivered. (E.g.The recipient's box has been made inaccessible meantime.) .RE .PP **MESSAGESTATE\_REMOVED** The message's content was deleted. .RE .PP **MESSAGESTATE\_IN\_VAULT** The message is stored in the long term storage. .RE .PP The values can be combined into a bit mask for some functions. A special **MESSAGESTATE\_ANY** macro denotes any of the states. .SS "isds\_hash\_algorithm" ``` typedef enum isds_hash_algorithm; ``` .PP Hash algorithm types. Known values are: .PP **HASH\_ALGORITHM\_MD5** MD5. .RE .PP **HASH\_ALGORITHM\_SHA\_1** SHA-1. .RE .PP **HASH\_ALGORITHM\_SHA\_224** SHA-224. .RE .PP **HASH\_ALGORITHM\_SHA\_256** SHA-256. .RE .PP **HASH\_ALGORITHM\_SHA\_384** SHA-384. .RE .PP **HASH\_ALGORITHM\_SHA\_512** SHA-256. .RE .SS "isds\_buffer\_strategy" ``` typedef enum isds_buffer_strategy; ``` .PP Buffer storage strategy. This type defines how a function should embed application provided buffer into *raw* element of output structure. Known values are: .PP **BUFFER\_DONT\_STORE** Don't fill *raw* member. .RE .PP **BUFFER\_COPY** Copy buffer content into newly allocated *raw* member. .RE .PP **BUFFER\_MOVE** Copy pointer. Leave deallocation to structure destructor (**isds\_\*\_free**()). .RE .SS "struct isds\_hash" ``` struct isds_hash; ``` .PP This is a hash value storage. Members are: .PP **isds\_hash\_algorithm** *algorithm*; Hash algorithm. .RE .PP **size\_t** *length*; Hash value length in bytes. .RE .PP **void \****value*; Hash value as a byte stream. .RE .SS "struct isds\_PersonName" ``` struct isds_PersonName; ``` .PP Name of a person. Members are: .PP **char \****pnFirstName*; First name. .RE .PP **char \****pnMiddleName*; Middle name. .RE .PP **char \****pnLastName*; Current last name. .RE .PP **char \****pnLastNameAtBirth*; Last name at birth. .RE .SS "struct isds\_BirthInfo" ``` struct isds_BirthInfo; ``` .PP Date and place of a birth. Members are: .PP **struct tm \****biDate*; Date of birth in local time at the birth place. Only *tm\_year*, *tm\_mon* and *tm\_mday* members of the **struct tm** carry sane value. Others are undefined. .RE .PP **char \****biCity*; City where a person was born. .RE .PP **char \****biCounty*; Region where a person was born. This is the kind of region that is called Bezirk in German and okres in Czech. .RE .PP **char \****biState*; State wher a person was born. .RE .SS "struct isds\_Address" ``` struct isds_Address; ``` .PP Postal address. Members are: .PP **char \****adCity*; City. .RE .PP **char \****adStreet*; Street. .RE .PP **char \****adNumberInStreet*; Identification of an entrance on the street. Číslo orientační in Czech. .RE .PP **char \****adNumberInMunicipality*; Identification of a building in the municipality. Číslo popisné in Czech. .RE .PP **char \****adZipCode*; Postal code for mail routing. .RE .PP **char \****adState*; State. .RE .SS "struct isds\_DbOwnerInfo" ``` struct isds_DbOwnerInfo; ``` .PP Data about a box and his owner. NULL pointer values mean undefined values. Members are: .PP **char \****dbID*; Box identifier. Specification limits the length to 7 characters. .RE .PP **isds\_DbType \****dbType*; Box type. .RE .PP **char \****ic*; Identifier of the owner. .RE .PP **isds\_PersonName \****personName*; Name of a person owning the box. .RE .PP **char \****firmName*; Name of a firm owning the box. .RE .PP **isds\_BirthInfo \****birthInfo*; Birth details of the person. .RE .PP **isds\_Address \****address*; Postal address of the owner. .RE .PP **char \****nationality*; Nationality of the owner. .RE .PP **char \****email*; E-mail addres of the owner. .RE .PP **char \****telNumber*; Telephone number of the owner. .RE .PP **char \****identifier*; External box identifier for data provider (OVM, PO, maybe PFO box types.) Specification limits the length to 20 characters. .RE .PP **char \****registryCode*; PFO external registry code. Specification limits the length to 5 characters. .RE .PP **long int \****dbState*; Box state. 1 means the box is active. .if n {.sp **Note**\ The type is long int because specification declares it as **xsd:integer**. .if n {.sp **Note**\ TODO: enum? .RE .PP **\_Bool \****dbEffectiveOVM*; The Box has OVM role (section 5a of the act). .RE .PP **\_Bool \****dbOpenAddressing*; This non-OVM box is free to receive messages from anybody. .RE .SS "isds\_UserType" ``` typedef enum isds_UserType; ``` .PP User type. Known values are: .PP **USERTYPE\_PRIMARY** Owner of the box. .RE .PP **USERTYPE\_ENTRUSTED** User with limited access to the box. .RE .PP **USERTYPE\_ADMINISTRATOR** User who can manage **USERTYPE\_ENTRUSTED** users. .RE .PP **USERTYPE\_OFFICIAL** ??? .RE .PP **USERTYPE\_OFFICIAL\_CERT** ??? .RE .PP **USERTYPE\_LIQUIDATOR** Company liquidator. .RE .PP **USERTYPE\_RECEIVER** Company receiver. .RE .PP **USERTYPE\_GUARDIAN** Legal guardian. .RE .SS "struct isds\_DbUserInfo" ``` struct isds_DbUserInfo; ``` .PP Data about a user. NULL pointer values mean undefined values. Members are: .PP **char \****userID*; User identifier. Specification limits the length from 6 to 12 characters. .RE .PP **isds\_UserType \****userType*; User type. .RE .PP **long int \****userPrivils*; Set of user permissions. .RE .PP **isds\_PersonName \****personName*; Name of the user. .RE .PP **isds\_Address \****address*; Postal address of the user. .RE .PP **struct tm \****biDate*; Date of birth in local time. Only *tm\_year*, *tm\_mon* and *tm\_mday* members of the **struct tm** carry sane value. Others are undefined. .RE .PP **char \****ic*; Identifier a supervising firm. Specification limits the length to 8 characters. .RE .PP **char \****firmName*; Name of a supervising firm. Specification limits the length to 100 characters. .RE .PP **char \****caStreet*; Contact address. Street and number. .RE .PP **char \****caCity*; Czech city of the contact address. .RE .PP **char \****caZipCode*; Postal code of the contact address. .RE .PP **char \****caState*; Abbreviated country of contact address. This value is optional and implicit meaning is **CZ**. .RE .SS "isds\_event\_type" ``` typedef enum isds_event_type; ``` .PP Message event type. Known values are: .PP **EVENT\_UNKNOWN** Event unknown to this library. .RE .PP **EVENT\_ACCEPTED\_BY\_RECIPIENT** Message has been delivered and accepted by recipient action. .RE .PP **EVENT\_ACCEPTED\_BY\_FICTION** Message has been delivered, acceptance period timed out, the message is considered accepted. .RE .PP **EVENT\_ACCEPTED\_BY\_FICTION\_NO\_USER** Message has been delivered, acceptance period timed out because there was no user who could accept the message. .RE .PP **EVENT\_UNDELIVERABLE** Recipient box was made inaccessible, thus the message is undeliverable. .RE .PP **EVENT\_COMMERCIAL\_ACCEPTED** Recipient confirmed acceptance of this commercial message. .RE .PP **EVENT\_ENTERED\_SYSTEM** The message entered the ISDSsystem, i.e. it has been just sent by a sender. .RE .PP **EVENT\_DELIVERED** The message has been delivered into recipient's box. .RE .PP **EVENT\_PRIMARY\_LOGIN** Primary user logged into recipient's box. .RE .PP **EVENT\_ENTRUSTED\_LOGIN** Entrusted user with capability to read logged into recipient's box. .RE .PP **EVENT\_SYSCERT\_LOGIN** An application authenticated by *system* certificate logged into recipient's box. .RE .SS "struct isds\_event" ``` struct isds_event; ``` .PP An event that happened in a message life. All members are optional. Members are: .PP **struct isds\_timeval \****time*; When the event occurred. .RE .PP **isds\_event\_type \****type*; Type of the event. .RE .PP **char \****description*; Human-readable event description generated by the ISDS system. (Very probably in Czech language). .RE .SS "enum isds\_IdLevel\_value" ``` enum isds_IdLevel_value; ``` .PP Specifies which information the sender of a data message wants to publish about his person. .PP **PUBLISH\_USERTYPE** Publish information about the sender type. This information is always revealed to the recipient. .RE .PP **PUBLISH\_PERSONNAME** Publish sender's personal name. .RE .PP **PUBLISH\_BIDATE** Publish sender's birth date. .RE .PP **PUBLISH\_BICITY** Publish sender's birth city. This information is available only when sender is SENDERTYPE\_ENTRUSTED of a FO or PFO box. .RE .PP **PUBLISH\_BICOUNTY** Publish sender's birth county. This information is available only when sender is SENDERTYPE\_ENTRUSTED of a FO or PFO box. .RE .PP **PUBLISH\_ADCODE** Publish sender's RUIAN address code. .RE .PP **PUBLISH\_FULLADDRESS** Publish sender's full address. .RE .PP **PUBLISH\_ROBIDENT** Publish information whether sender is identified within the ROB. .RE .SS "struct isds\_envelope" ``` struct isds_envelope; ``` .PP Message envelope. These are the metadata about a message. It does contain the message documents. .PP Be ware that the string length constraints are forced only on output members transmitted to the ISDS. The other direction (downloading from the ISDS) can break these rules. It should not happen, but nobody knows how much incompatible new version of the ISDS protocol will be. This is the gold Internet rule: be strict on what you send, be tolerant on what you receive. .PP Following members apply to incoming messages only: .PP **char \****dmID*; Message identifier. Maximal length is 20 characters. .RE .PP **char \****dbIDSender*; Box identifier of the sender. Special value aaaaaaa means the message was sent by the ISDS system. Not by another user. Maximal length is 7 characters. .RE .PP **char \****dmSender*; Sender's name. Maximal length is 100 characters. .RE .PP **char \****dmSenderAddress*; Postal address of the sender. Maximal length is 100 characters. .RE .PP **long int \****dmSenderType*; Gross box type of the sender. You can use **isds\_DbType** to enumerate some known box types. This is a generic integer because the protocol keeps the value unconstrained and the library must support any syntactically correct value. .RE .PP **char \****dmRecipient*; Recipient's name. Maximal length is 100 characters. .RE .PP **char \****dmRecipientAddress*; Postal address of the recipient. Maximal length is 100 characters. .RE .PP **\_Bool \****dmAmbiguousRecipient*; The recipient has OVM role. .RE .PP Following members are assigned by the ISDS in different phases of message life cycle: .PP **unsigned long int \****dmOrdinal*; Ordinal number in list of incoming/outgoing messages. .RE .PP **enum isds\_message\_status \****dmMessageStatus*; Message state. .RE .PP **long int \****dmAttachmentSize*; Size of message documents in kilobytes. The value is rounded. .RE .PP **struct isds\_timeval \****dmDeliveryTime*; The time of delivering the message into recipient's box. It will be **NULL**, if the message has not been delivered yet. .RE .PP **struct isds\_timeval \****dmAcceptanceTime*; The time of accepting the message by the recipient. It will be **NULL**, if message has not been accepted yet. .RE .PP **struct isds\_hash \****hash*; The message digest. This is a hash of a substring representing isds:dmDM XML subtree. You can use **isds\_compute\_message\_hash** function to compute a hash of the message and then compare it against this structure member using **isds\_hash\_cmp** function. .RE .PP **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 have not yet been stamped will have this value **NULL**. .RE .PP **size\_t** *timestamp\_length*; Length of the *timestamp* value in bytes. .RE .PP **struct isds\_list \****events*; Events the message passed trough. It's a list of **isds\_event** structures. .RE .PP Following members apply to both outgoing and incoming messages: .PP **char \****dmSenderOrgUnit*; Sender's organisation unit as a string. This is optional. .RE .PP **long int \****dmSenderOrgUnitNum*; Sender's organisation unit as a number. This is optional. .RE .PP **char \****dbIDRecipient*; Recipient's box identifier. This is mandatory. Maximal length is 7 characters. .RE .PP **char \****dmRecipientOrgUnit*; Recipient's organisation unit as a string. This is optional. .RE .PP **long int \****dmRecipientOrgUnitNum*; Recipient's organisation unit of as a number. This is optional. .RE .PP **char \****dmToHands*; A person in recipient's organisation. This is optional. .RE .PP **char \****dmAnnotation*; A subject (title) of the message. Maximal length is 255 characters. .RE .PP **char \****dmRecipientRefNumber*; Czech: číslo jednací příjemce. This is optional. Maximal length is 50 characters. .RE .PP **char \****dmSenderRefNumber*; Czech: číslo jednací odesílatele. This is optional. Maximal length is 50 chars. .RE .PP **char \****dmRecipientIdent*; Czech: spisová značka příjemce. This is optional. Maximal length is 50 characters. .RE .PP **char \****dmSenderIdent*; Czech: spisová značka odesílatele This is optional. Maximal length is 50 chars. .RE .PP Following five members constitute a reference to an item from the Czech Act Collection. The human-readable reference looks like *Point* (*Paragraph*) § *Section* *Law*/*Year* Coll. The members apply to both incoming and outgoing messages: .PP **long int \****dmLegalTitleLaw*; A number of an act mandating the authority. .RE .PP **long int \****dmLegalTitleYear*; A year of issuing the act mandating the authority. .RE .PP **char \****dmLegalTitleSect*; A section of the act mandating the authority. Czech: paragraf. .RE .PP **char \****dmLegalTitlePar*; A paragraph of the act mandating the authority. Czech: odstavec. .RE .PP **char \****dmLegalTitlePoint*; A point of the act mandating the authority. Czech: písmeno. .RE .PP Other incoming/outgoing message members: .PP **\_Bool \****dmPersonalDelivery*; If true, only person with higher privileges can read this message. .RE .PP **\_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 OVM dbType sender can set it. .RE .PP **char \****dmType*; Message type (commercial subtypes or government message). Input values (when sending the message): .PP "I" A commercial message offering paying the response (initiatory message). It's necessary to define *dmSenderRefNumber* member. .RE .PP "K" A commercial message paid by the sender. .RE .PP "O" A commercial response paid by the sender of a initiatory message. It's necessary to copy a value from the *dmSenderRefNumber* of the initiatory message to the *dmRecipientRefNumber* of this message. .RE .PP "V" A non-commercial government message. This is the default meaning if the value is undefined while sending a message. .RE\ .sp Output values (when retrieving the message): .PP "A" This is a subsidized initiatory commercial message which can pay a response. .RE .PP "B" This is a subsidized initiatory commercial message which has already paid the response. .RE .PP "C" This is a subsidized initiatory commercial message where the response offer has expired. .RE .PP "D" This is an externally subsidized commercial message. .RE .PP "E" This is a commercial message prepaid by a stamp. .RE .PP "G" This is a commercial message paid by a sponsor. .RE .PP "I" See the input values. .RE .PP "K" See the input values. .RE .PP "O" See the input values. .RE .PP "V" See the input values. .RE .PP "X" This is an initiatory commercial message where the response offer has expired. .RE .PP "Y" This is an initiatory commercial message which has already paid the response. .RE .PP "Z" This is limitedly subsidized commercial message. .RE\ .sp Length of the value is exactly 1 UTF-8 character if defined. That means it's still zero-terminated character string. .RE .PP **\_Bool \****dmVODZ*; Set to true when downloading lists of sent or received messages and a particular message is a high-volume data message. .RE .PP **long int \****attsNum*; Set to number of attachments when downloading lists of sent or received messages and a particular message is a high-volume data message. .RE .PP Following members apply to outgoing messages only: .PP **\_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. .RE .PP **\_Bool \****dmPublishOwnID*; To allow to reveal sender's login name. The name will be available to the recipient through **isds\_get\_message\_sender** function. The sender's box type and identifier will be always available. This feature exists because more users can have access to one box and the recipient could not tell who was the sender. This value is optional. Default value is false. .RE .PP **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 actual **enum isds\_IdLevel\_value** values. .RE .SS "isds\_FileMetaType" ``` typedef enum isds_FileMetaType; ``` .PP Document type from point of view of hierarchy of documents in a message. Known values are: .PP **FILEMETATYPE\_MAIN** Main document. There should be exactly one document of this type in a message. .RE .PP **FILEMETATYPE\_ENCLOSURE** An appendix. If a message has more documents, generic-purpose documents other than the main one should have this type. .RE .PP **FILEMETATYPE\_SIGNATURE** Digital signature. This document is a signature of another document in the message. .RE .PP **FILEMETATYPE\_META** XML document for electronic document information system, elektronická spisová služba (ESS) in Czech, purpose. .RE .SS "struct isds\_document" ``` struct isds_document; ``` .PP A message document. Members are: .PP **\_Bool** *is\_xml*; True if the document is an ISDS XML document. False if the document is an ISDS binary document. .RE .PP **xmlNodePtr** *xml\_node\_list*; XML node-set presenting the XML document content. This is a pointer to first XML node of the XML representation of the message as stored in *xml* member of **isds\_message** structure. Use *children* and *next* members to walk through the document. See libxml2 library documentation for more details. The *xml\_node\_list* will be **NULL** if the document is empty. It's valid only if the *is\_xml* is true. .RE .PP **void \****data*; A binary document content. The encoding and format depends on *dmMimeType* member value. This is valid only if the *is\_xml* is false. .RE .PP **size\_t** *data\_length*; Length of the *data* buffer in bytes. It's valid only if the *is\_xml* is false. .RE .PP **char \****dmMimeType*; MIME type of document. This member is mandatory. .RE .PP **isds\_FileMetaType** *dmFileMetaType*; Document type to create document hierarchy inside a message. .RE .PP **char \****dmFileGuid*; Message-local document identifier. It can be used as a key to refer to this document by *dmUpFileGuid* member from a different document. This is optional. .RE .PP **char \****dmUpFileGuid*; A reference to upper document identifier stored in *dmFileGuid* member of different document. You can use **isds\_find\_document\_by\_id** function to locate the upper document. This value is optional. .RE .PP **char \****dmFileDescr*; Document name (title). E.g. a file name. This value is mandatory. .RE .PP **char \****dmFormat*; A reference to XML format definition that explains how to interpret the XML document. E.g. a URL to an XML schema. This value is optional. .RE .SS "struct isds\_box\_state\_period" ``` struct isds_box_state_period; ``` .PP A box state valid in the time range. Members are: .PP **struct isds\_timeval \****from*; Time range beginning. .RE .PP **struct isds\_timeval \****to*; Time range end. .RE .PP **long int** *dbState*; Box state. **1** means the box is accessible. Other values mean the box is inaccessible. You can use **isds\_DbState** enum to identify some states. .RE .SS "struct isds\_dmMessageAuthor" ``` struct isds_dmMessageAuthor; ``` .PP Response for GetMessageAuthor2. Members are: .PP **isds\_sender\_type \****userType*; Message sender type. .RE .PP **struct isds\_PersonName2 \****personName*; Contains pnGivenNames and pnLastName. .RE .PP **struct tm \****biDate*; Date of birth in local time at birth place, only tm\_year, tm\_mon and tm\_mday carry sane value. .RE .PP **char \****biCity*; City of birth. .RE .PP **char \****biCounty*; County of birth (German: Bezirk, Czech: okres). .RE .PP **char \****adCode*; RUIAN address code. .RE .PP **char \****fullAddress*; Full address. .RE .PP **\_Bool \****robIdent*; Flag whether the person is identifiers within the ROB. .RE .SS "enum isds\_message\_type" ``` typedef enum isds_message_type isds_message_type; ``` .PP Specifies the direction of the message - whether the message is received or sent: .PP **MESSAGE\_TYPE\_RECEIVED** Specifies a received message. .RE .PP **MESSAGE\_TYPE\_SENT** Specifies a sent message. .RE .SS "enum isds\_data\_format" ``` typedef enum isds_data_format isds_data_format; ``` .PP Specifies data format: .PP **FORMAT\_XML** Data in XML format. .RE .PP **FORMAT\_CSV** Data in CSV format. .RE .SS "enum isds\_asyncReqType" ``` typedef enum isds_asyncReqType isds_asyncReqType; ``` .PP Specifies synchronous request type: .PP **ASYNC\_REQ\_TYPE\_LIST\_ERASED** Response for the GetListOfErasedMessages request. .RE .SS "struct isds\_erased\_message" ``` struct isds_erased_message; ``` .PP Describes entries in the lists of erased messages. Members are: .PP **char \****dmID*; Message ID. .RE .PP **char \****dbIDSender*; Box ID of sender. .RE .PP **char \****dmSender*; Sender name. .RE .PP **char \****dbIDRecipient*; Box ID of recipient. .RE .PP **char \****dmRecipient*; Recipient name. .RE .PP **char \****dmAnnotation*; Subject (title) of the message. .RE .PP **enum isds\_message\_status \****dmMessageStatus*; Message state. .RE .PP **struct isds\_timeval \****dmDeliveryTime*; Time of delivery into a box. .RE .PP **struct isds\_timeval \****dmAcceptanceTime*; Time of acceptance of the message by a user. .RE .PP **char \****dmType*; Message type. .RE .SH "FUNCTIONS" • **const char \*isds\_strerror(const isds\_error** *error***);** • **struct isds\_ctx \*isds\_ctx\_create(void);** .SH "SEE ALSO" .PP [**libcurl**(3)](/libcurl/3.md), [**libdatovka**(3)](/libdatovka/3.md), **time.h**(0p) .SH "AUTHORS" **CZ.NIC, z. s. p. o.** Maintains libdatovka. Has been contributing to libisds. **Petr Písař** He has written libisds.