1ISDS.H.LIBDATOVK(3) Manual for Libdatovka ISDS.H.LIBDATOVK(3)
2
6 isds.h.libdatovka - API definition for libdatovka
7
9 #include <libdatovka/isds.h>
10
12 This header file declares interface for the libdatovka library.
13
15 Service locators
16 Addresses of known ISDS servers.
17 Base URLs of production ISDS instance
19 isds_locator
20 extern const char isds_locator[];
21 Without client certificate authentication.
23 isds_cert_locator
25 extern const char isds_cert_locator[];
26 With client certificate authentication.
28 isds_otp_locator
30 extern const char isds_otp_locator[];
31 Without OTP authentication.
33 Base URLs of testing ISDS instance
35 isds_testing_locator
36 extern const char isds_testing_locator[];
37 Without client certificate authentication.
39 isds_cert_testing_locator
41 extern const char isds_cert_testing_locator[];
42 With client certificate authentication.
44 isds_otp_testing_locator
46 extern const char isds_otp_testing_locator[];
47 Without OTP authentication.
49
51 struct isds_ctx
52 struct isds_ctx;
53 Context for specific ISDS box.
55 isds_error
57 typedef enum isds_error;
58 Error code. Known values:
60 IE_SUCCESS
62 No error. Numeric value 0.
63 IE_ERROR
65 Unspecified error.
66 IE_NOTSUP
68 Operation is not supported.
69 IE_INVAL
71 Invalid value.
72 IE_INVALID_CONTEXT
74 The context is not valid.
75 IE_NOT_LOGGED_IN
77 The context has not been logged in.
78 IE_CONNECTION_CLOSED
80 Network connection has been closed.
81 IE_TIMED_OUT
83 Time limit for network operation exceeded.
84 IE_NONEXIST
86 Requested entity doesn't exist.
87 IE_NOMEM
89 Not enough memory.
90 IE_NETWORK
92 Network error.
93 IE_HTTP
95 Error on HTTP level.
96 IE_SOAP
98 Error on SOAP level.
99 IE_XML
101 Error on XML level.
102 IE_ISDS
104 Problem with ISDS server.
105 IE_ENUM
107 Invalid enumeration value.
108 IE_DATE
110 Invalid date value.
111 IE_TOO_BIG
113 Value is too big.
114 IE_TOO_SMALL
116 Value is too small.
117 IE_NOTUNIQ
119 Value is not unique.
120 IE_NOTEQUAL
122 Compared values are not equal.
123 IE_PARTIAL_SUCCESS
125 Operation on a vector succeeded for some values but failed for oth‐
126 ers.
127 IE_ABORTED
129 Operation was aborted by application request.
130 IE_SECURITY
132 Security requirements were not satisfied.
133 isds_log_level
135 typedef enum isds_log_level;
136 Log level. Know values:
138 ILL_NONE
140 0
141 ILL_CRIT
143 10
144 ILL_ERR
146 20
147 ILL_WARNING
149 30
150 ILL_INFO
152 40
153 ILL_DEBUG
155 50
156 ILL_ALL
158 100
159 isds_log_facility
161 typedef enum isds_log_facility;
162 Log facility. Know values:
164 ILF_NONE
166 0x0
167 ILF_HTTP
169 0x1
170 ILF_SOAP
172 0x2
173 ILF_ISDS
175 0x4
176 ILF_FILE
178 0x8
179 ILF_SEC
181 0x10
182 ILF_XML
184 0x20
185 ILF_ALL
187 0xFF
188 isds_option
190 typedef enum isds_option;
191 libdatovka option identifiers. Known values:
193 IOPT_TLS_VERIFY_SERVER
195 Option type is _Bool. Whether to verify server identity. Default
196 value is true.
197 IOPT_TLS_CA_FILE
199 Option type is char *. Option value is a file name with certificate
200 authority certificates. Default value depends on used cryptographic
201 library.
202 IOPT_TLS_CA_DIRECTORY
204 Option type is char *, Option value is a directory with certificate
205 authority certificates. Default value depends on used cryptographic
206 library.
207 IOPT_TLS_CRL_FILE
209 Option type is char *. Option value is a file name with certificat
210 revocation list in PEM format. Default value depends on used cryp‐
211 tographic library.
212 IOPT_NORMALIZE_MIME_TYPE
214 Optiona type is _Bool. Whether to normalize MIME type values. De‐
215 fault value is false.
216 isds_tls_option
218 typedef enum isds_tls_option;
219 Warning
222 This type is deprecated.
223 TLS libdatovka option identifiers. Known values:
225 ITLS_VERIFY_SERVER
227 Option type is _Bool. Whether to verify server identity.
228 ITLS_CA_FILE
230 Option type is char *. Option value is a file name with certificate
231 authority certificates.
232 ITLS_CA_DIRECTORY
234 Option type is char *. Option value is a directory name with cer‐
235 tificate authority certificates.
236 ITLS_CRL_FILE
238 Option type is char *. Option value is a file name with certificate
239 revocation list in PEM format.
240 isds_pki_format
242 typedef enum isds_pki_format;
243 Cryptographic material encoding. Known values:
245 PKI_FORMAT_PEM
247 PEM format.
248 PKI_FORMAT_DER
250 DER format.
251 PKI_FORMAT_ENG
253 The material is stored in a cryptographic engine.
254 struct isds_pki_credentials
256 struct isds_pki_credentials;
257 This structure holds public key infrastructure cryptographic material
259 to authenticate a client. Members are:
260 char *engine;
262 String identifier of cryptographic engine to use (where key is
263 stored). Use NULL for no engine.
264 isds_pki_format certificate_format;
266 Certificate format.
267 char *certificate;
269 A path to client certificate, or a certificate nickname in case of
270 NSS as curl back-end, or key slot identifier inside cryptographic
271 engine. Some cryptographic engines can pair certificate with key
272 automatically (NULL value).
273 isds_pki_format key_format;
275 Private key format.
276 char *key;
278 A path to client private key, or key identifier in case an engine
279 is used.
280 char *passphrase;
282 Zero terminated string with password for decrypting private key, or
283 engine PIN. Use NULL for no pass-phrase or to let the engine to ask
284 for it.
285 isds_otp_method
287 typedef enum isds_otp_method;
288 One-time password authentication method. Known values:
290 OTP_HMAC
292 HMAC-based OTP method.
293 OTP_TIME
295 Time-based OTP method.
296 isds_otp_resolution
298 typedef enum isds_otp_resolution;
299 One-time password authentication resolution. Known values:
301 OTP_RESOLUTION_SUCCESS
303 Authentication succeeded.
304 OTP_RESOLUTION_UNKNOWN
306 Status is unknown.
307 OTP_RESOLUTION_BAD_AUTHENTICATION
309 Bad log-in. You can retry to log in.
310 OTP_RESOLUTION_ACCESS_BLOCKED
312 Access blocked for 60 minutes. (Because a brute force attack was
313 detected.)
314 OTP_RESOLUTION_PASSWORD_EXPIRED
316 Password has expired.
317 Note
319 It's not clear which password expired: OTP or regular password?
320 OTP_RESOLUTION_TOO_FAST
322 OTP cannot be sent repeatedly at this rate. (Minimal delay depends
323 on TOTP window setting.)
324 OTP_RESOLUTION_UNAUTHORIZED
326 User name is not allowed to access requested URI.
327 OTP_RESOLUTION_TOTP_SENT
329 OTP has been generated and sent by the ISDS to the user.
330 OTP_RESOLUTION_TOTP_NOT_SENT
332 OTP could not been sent by the ISDS. Retry later.
333 struct isds_otp
335 struct isds_otp;
336 This structure holds one-time password when authenticating a client and
338 resolution of the authentication.
339 Input members are:
341 isds_otp_method method;
343 Select OTP method to use.
344 char *otp_code;
346 One-time password to use. Pass NULL, if you do not know it yet
347 (e.g. in case of first phase of time-based OTP authentication to
348 request new code from ISDS.)
349 Output members are:
351 isds_otp_resolution resolution;
353 Fine-grade resolution of this OTP authentication attempt.
354 isds_DbType
356 typedef enum isds_DbType;
357 Box type. It classifies box owner by his legal status. Known values:
359 DBTYPE_OVM_MAIN
361 This is a special value for isds_find_box_by_fulltext. It's not ac‐
362 cepted by any other services.
363 DBTYPE_SYSTEM
365 This is a special value for sender of messages sent by the ISDS.
366 You can find it only in incoming messages. It's not accepted by any
367 other services.
368 DBTYPE_OVM
370 Standard government (state or municipality or similar) office.
371 DBTYPE_OVM_NOTAR
373 Notary (stopped being used, replaced with OVM_PFO).
374 DBTYPE_OVM_EXEKUT
376 Executor (stopped being used, replaced with OVM_PFO).
377 DBTYPE_OVM_REQ
379 Subsidiary office with OVM (governing) status assigned on request
380 (section 6 and 7 of the act).
381 DBTYPE_OVM_FO
383 Natural person with OVM status (without identification number).
384 DBTYPE_OVM_PFO
386 Natural person in business with OVM status (e.g. notary or execu‐
387 tor).
388 DBTYPE_OVM_PO
390 Juridical person with OVM status (arisen from previously existing
391 PO or PO_REQ).
392 DBTYPE_PO
394 Standard commercial organization (listed in trade registry).
395 DBTYPE_PO_ZAK
397 Other organization founded by an act (stopped being used, replaced
398 with PO).
399 DBTYPE_PO_REQ
401 An organization with a box assigned on its request.
402 DBTYPE_PFO
404 Person in business.
405 DBTYPE_PFO_ADVOK
407 Lawyer.
408 DBTYPE_PFO_DANPOR
410 Tax consultant.
411 DBTYPE_PFO_INSSPR
413 Administrator of insolvency.
414 DBTYPE_PFO_AUDITOR
416 Statutory auditor.
417 DBTYPE_PFO_ZNALEC
419 Expert witness.
420 DBTYPE_PFO_TLUMOCNIK
422 Sworn translator.
423 DBTYPE_PFO_REQ
425 Person in business on its request.
426 DBTYPE_FO
428 Standard person.
429 Some interfaces refer to gross box type. These are the shortest names
431 of the identifiers. For example, DBTYPE_OVM is a gross type for
432 DB_OVM_NOTAR or DBTYPE_OVM. But not for DBTYPE_PO.
433 isds_DbState
435 typedef enum isds_DbState;
436 Box status from point of view of accessibility. Known values:
438 DBSTATE_ACCESSIBLE
440 The box is accessible.
441 DBSTATE_TEMP_INACCESSIBLE
443 The box is temporarily inaccessible (at the request of the user).
444 DBSTATE_NOT_YET_ACCESSIBLE
446 The box has not yet been activated.
447 DBSTATE_PERM_INACCESSIBLE
449 The box is permanently inaccessible.
450 DBSTATE_REMOVED
452 The box has been removed.
453 DBSTATE_TEMP_INACCESSIBLE_LAW
455 The box is temporarily inaccessible (because of the reasons enumer‐
456 ated in the law).
457 isds_privileges
459 typedef enum isds_privileges;
460 Distinct user permissions from point of view of ISDS. Instances can be
462 bitmaps of any of these distinct values. Distinct known values are:
463 PRIVIL_READ_NON_PERSONAL
465 The user can download and read messages with dmPersonalDelivery
466 equal to false.
467 PRIVIL_READ_ALL
469 The user can download and read messages with dmPersonalDelivery
470 equal to true.
471 PRIVIL_CREATE_DM
473 The user can create and send messages, the user can download outgo‐
474 ing (sent) messages.
475 PRIVIL_VIEW_INFO
477 The user can list messages and read data about a message post and
478 delivery.
479 PRIVIL_SEARCH_DB
481 The user can can search for boxes.
482 PRIVIL_OWNER_ADM
484 The user can administer his box (to add and remove permitted users
485 and to modify theirs permissions.)
486 PRIVIL_READ_VAULT
488 The user can read messages stored in the long term storage.
489 Note
491 This permission is not used since 2012-05.
492 PRIVIL_ERASE_VAULT
494 The user can delete messages from the long term storage.
495 isds_message_status
497 typedef enum isds_message_status;
498 Message status. Known values are:
500 MESSAGESTATE_SENT
502 The message has been put into ISDS.
503 MESSAGESTATE_STAMPED
505 Message was stamped by a time stamp authority.
506 MESSAGESTATE_INFECTED
508 The message included viruses. Infected documents have been removed
509 from the message.
510 MESSAGESTATE_DELIVERED
512 The message was delivered. (dmDeliveryTime is populated.)
513 MESSAGESTATE_SUBSTITUTED
515 The message was delivered through fiction, dmAcceptanceTime is pop‐
516 ulated.
517 MESSAGESTATE_RECEIVED
519 The message was accepted (by user's log-in or user's explicit re‐
520 quest). dmAcceptanceTime is populated.
521 MESSAGESTATE_READ
523 The message has been read by a user.
524 MESSAGESTATE_UNDELIVERABLE
526 The message could not been delivered. (E.g.The recipient's box has
527 been made inaccessible meantime.)
528 MESSAGESTATE_REMOVED
530 The message's content was deleted.
531 MESSAGESTATE_IN_VAULT
533 The message is stored in the long term storage.
534 The values can be combined into a bit mask for some functions. A spe‐
536 cial MESSAGESTATE_ANY macro denotes any of the states.
537 isds_hash_algorithm
539 typedef enum isds_hash_algorithm;
540 Hash algorithm types. Known values are:
542 HASH_ALGORITHM_MD5
544 MD5.
545 HASH_ALGORITHM_SHA_1
547 SHA-1.
548 HASH_ALGORITHM_SHA_224
550 SHA-224.
551 HASH_ALGORITHM_SHA_256
553 SHA-256.
554 HASH_ALGORITHM_SHA_384
556 SHA-384.
557 HASH_ALGORITHM_SHA_512
559 SHA-256.
560 isds_buffer_strategy
562 typedef enum isds_buffer_strategy;
563 Buffer storage strategy. This type defines how a function should embed
565 application provided buffer into raw element of output structure. Known
566 values are:
567 BUFFER_DONT_STORE
569 Don't fill raw member.
570 BUFFER_COPY
572 Copy buffer content into newly allocated raw member.
573 BUFFER_MOVE
575 Copy pointer. Leave deallocation to structure destructor (‐
576 isds_*_free()).
577 struct isds_hash
579 struct isds_hash;
580 This is a hash value storage. Members are:
582 isds_hash_algorithm algorithm;
584 Hash algorithm.
585 size_t length;
587 Hash value length in bytes.
588 void *value;
590 Hash value as a byte stream.
591 struct isds_PersonName
593 struct isds_PersonName;
594 Name of a person. Members are:
596 char *pnFirstName;
598 First name.
599 char *pnMiddleName;
601 Middle name.
602 char *pnLastName;
604 Current last name.
605 char *pnLastNameAtBirth;
607 Last name at birth.
608 struct isds_BirthInfo
610 struct isds_BirthInfo;
611 Date and place of a birth. Members are:
613 struct tm *biDate;
615 Date of birth in local time at the birth place. Only tm_year,
616 tm_mon and tm_mday members of the struct tm carry sane value. Oth‐
617 ers are undefined.
618 char *biCity;
620 City where a person was born.
621 char *biCounty;
623 Region where a person was born. This is the kind of region that is
624 called Bezirk in German and okres in Czech.
625 char *biState;
627 State wher a person was born.
628 struct isds_Address
630 struct isds_Address;
631 Postal address. Members are:
633 char *adCity;
635 City.
636 char *adStreet;
638 Street.
639 char *adNumberInStreet;
641 Identification of an entrance on the street. Číslo orientační in
642 Czech.
643 char *adNumberInMunicipality;
645 Identification of a building in the municipality. Číslo popisné in
646 Czech.
647 char *adZipCode;
649 Postal code for mail routing.
650 char *adState;
652 State.
653 struct isds_DbOwnerInfo
655 struct isds_DbOwnerInfo;
656 Data about a box and his owner. NULL pointer values mean undefined val‐
658 ues. Members are:
659 char *dbID;
661 Box identifier. Specification limits the length to 7 characters.
662 isds_DbType *dbType;
664 Box type.
665 char *ic;
667 Identifier of the owner.
668 isds_PersonName *personName;
670 Name of a person owning the box.
671 char *firmName;
673 Name of a firm owning the box.
674 isds_BirthInfo *birthInfo;
676 Birth details of the person.
677 isds_Address *address;
679 Postal address of the owner.
680 char *nationality;
682 Nationality of the owner.
683 char *email;
685 E-mail addres of the owner.
686 char *telNumber;
688 Telephone number of the owner.
689 char *identifier;
691 External box identifier for data provider (OVM, PO, maybe PFO box
692 types.) Specification limits the length to 20 characters.
693 char *registryCode;
695 PFO external registry code. Specification limits the length to 5
696 characters.
697 long int *dbState;
699 Box state. 1 means the box is active.
700 Note
702 The type is long int because specification declares it as
703 xsd:integer.
704 Note
706 TODO: enum?
707 _Bool *dbEffectiveOVM;
709 The Box has OVM role (section 5a of the act).
710 _Bool *dbOpenAddressing;
712 This non-OVM box is free to receive messages from anybody.
713 isds_UserType
715 typedef enum isds_UserType;
716 User type. Known values are:
718 USERTYPE_PRIMARY
720 Owner of the box.
721 USERTYPE_ENTRUSTED
723 User with limited access to the box.
724 USERTYPE_ADMINISTRATOR
726 User who can manage USERTYPE_ENTRUSTED users.
727 USERTYPE_OFFICIAL
729 ???
730 USERTYPE_OFFICIAL_CERT
732 ???
733 USERTYPE_LIQUIDATOR
735 Company liquidator.
736 USERTYPE_RECEIVER
738 Company receiver.
739 USERTYPE_GUARDIAN
741 Legal guardian.
742 struct isds_DbUserInfo
744 struct isds_DbUserInfo;
745 Data about a user. NULL pointer values mean undefined values. Members
747 are:
748 char *userID;
750 User identifier. Specification limits the length from 6 to 12 char‐
751 acters.
752 isds_UserType *userType;
754 User type.
755 long int *userPrivils;
757 Set of user permissions.
758 isds_PersonName *personName;
760 Name of the user.
761 isds_Address *address;
763 Postal address of the user.
764 struct tm *biDate;
766 Date of birth in local time. Only tm_year, tm_mon and tm_mday mem‐
767 bers of the struct tm carry sane value. Others are undefined.
768 char *ic;
770 Identifier a supervising firm. Specification limits the length to 8
771 characters.
772 char *firmName;
774 Name of a supervising firm. Specification limits the length to 100
775 characters.
776 char *caStreet;
778 Contact address. Street and number.
779 char *caCity;
781 Czech city of the contact address.
782 char *caZipCode;
784 Postal code of the contact address.
785 char *caState;
787 Abbreviated country of contact address. This value is optional and
788 implicit meaning is CZ.
789 isds_event_type
791 typedef enum isds_event_type;
792 Message event type. Known values are:
794 EVENT_UNKNOWN
796 Event unknown to this library.
797 EVENT_ACCEPTED_BY_RECIPIENT
799 Message has been delivered and accepted by recipient action.
800 EVENT_ACCEPTED_BY_FICTION
802 Message has been delivered, acceptance period timed out, the mes‐
803 sage is considered accepted.
804 EVENT_ACCEPTED_BY_FICTION_NO_USER
806 Message has been delivered, acceptance period timed out because
807 there was no user who could accept the message.
808 EVENT_UNDELIVERABLE
810 Recipient box was made inaccessible, thus the message is undeliver‐
811 able.
812 EVENT_COMMERCIAL_ACCEPTED
814 Recipient confirmed acceptance of this commercial message.
815 EVENT_ENTERED_SYSTEM
817 The message entered the ISDSsystem, i.e. it has been just sent by
818 a sender.
819 EVENT_DELIVERED
821 The message has been delivered into recipient's box.
822 EVENT_PRIMARY_LOGIN
824 Primary user logged into recipient's box.
825 EVENT_ENTRUSTED_LOGIN
827 Entrusted user with capability to read logged into recipient's box.
828 EVENT_SYSCERT_LOGIN
830 An application authenticated by system certificate logged into re‐
831 cipient's box.
832 struct isds_event
834 struct isds_event;
835 An event that happened in a message life. All members are optional.
837 Members are:
838 struct isds_timeval *time;
840 When the event occurred.
841 isds_event_type *type;
843 Type of the event.
844 char *description;
846 Human-readable event description generated by the ISDS system.
847 (Very probably in Czech language).
848 enum isds_IdLevel_value
850 enum isds_IdLevel_value;
851 Specifies which information the sender of a data message wants to pub‐
853 lish about his person.
854 PUBLISH_USERTYPE
856 Publish information about the sender type. This information is al‐
857 ways revealed to the recipient.
858 PUBLISH_PERSONNAME
860 Publish sender's personal name.
861 PUBLISH_BIDATE
863 Publish sender's birth date.
864 PUBLISH_BICITY
866 Publish sender's birth city. This information is available only
867 when sender is SENDERTYPE_ENTRUSTED of a FO or PFO box.
868 PUBLISH_BICOUNTY
870 Publish sender's birth county. This information is available only
871 when sender is SENDERTYPE_ENTRUSTED of a FO or PFO box.
872 PUBLISH_ADCODE
874 Publish sender's RUIAN address code.
875 PUBLISH_FULLADDRESS
877 Publish sender's full address.
878 PUBLISH_ROBIDENT
880 Publish information whether sender is identified within the ROB.
881 struct isds_envelope
883 struct isds_envelope;
884 Message envelope. These are the metadata about a message. It does con‐
886 tain the message documents.
887 Be ware that the string length constraints are forced only on output
889 members transmitted to the ISDS. The other direction (downloading from
890 the ISDS) can break these rules. It should not happen, but nobody knows
891 how much incompatible new version of the ISDS protocol will be. This is
892 the gold Internet rule: be strict on what you send, be tolerant on what
893 you receive.
894 Following members apply to incoming messages only:
896 char *dmID;
898 Message identifier. Maximal length is 20 characters.
899 char *dbIDSender;
901 Box identifier of the sender. Special value aaaaaaa means the mes‐
902 sage was sent by the ISDS system. Not by another user. Maximal
903 length is 7 characters.
904 char *dmSender;
906 Sender's name. Maximal length is 100 characters.
907 char *dmSenderAddress;
909 Postal address of the sender. Maximal length is 100 characters.
910 long int *dmSenderType;
912 Gross box type of the sender. You can use isds_DbType to enumerate
913 some known box types. This is a generic integer because the proto‐
914 col keeps the value unconstrained and the library must support any
915 syntactically correct value.
916 char *dmRecipient;
918 Recipient's name. Maximal length is 100 characters.
919 char *dmRecipientAddress;
921 Postal address of the recipient. Maximal length is 100 characters.
922 _Bool *dmAmbiguousRecipient;
924 The recipient has OVM role.
925 Following members are assigned by the ISDS in different phases of mes‐
927 sage life cycle:
928 unsigned long int *dmOrdinal;
930 Ordinal number in list of incoming/outgoing messages.
931 isds_message_status *dmMessageStatus;
933 Message state.
934 long int *dmAttachmentSize;
936 Size of message documents in kilobytes. The value is rounded.
937 struct isds_timeval *dmDeliveryTime;
939 The time of delivering the message into recipient's box. It will be
940 NULL, if the message has not been delivered yet.
941 struct isds_timeval *dmAcceptanceTime;
943 The time of accepting the message by the recipient. It will be
944 NULL, if message has not been accepted yet.
945 struct isds_hash *hash;
947 The message digest. This is a hash of a substring representing
948 isds:dmDM XML subtree. You can use isds_compute_message_hash func‐
949 tion to compute a hash of the message and then compare it against
950 this structure member using isds_hash_cmp function.
951 void *timestamp;
953 This is a binary image of a qualified time stamp of the hash value.
954 The time stamp is provided by the ISDS system. Messages that have
955 not yet been stamped will have this value NULL.
956 size_t timestamp_length;
958 Length of the timestamp value in bytes.
959 struct isds_list *events;
961 Events the message passed trough. It's a list of isds_event struc‐
962 tures.
963 Following members apply to both outgoing and incoming messages:
965 char *dmSenderOrgUnit;
967 Sender's organisation unit as a string. This is optional.
968 long int *dmSenderOrgUnitNum;
970 Sender's organisation unit as a number. This is optional.
971 char *dbIDRecipient;
973 Recipient's box identifier. This is mandatory. Maximal length is 7
974 characters.
975 char *dmRecipientOrgUnit;
977 Recipient's organisation unit as a string. This is optional.
978 long int *dmRecipientOrgUnitNum;
980 Recipient's organisation unit of as a number. This is optional.
981 char *dmToHands;
983 A person in recipient's organisation. This is optional.
984 char *dmAnnotation;
986 A subject (title) of the message. Maximal length is 255 characters.
987 char *dmRecipientRefNumber;
989 Czech: číslo jednací příjemce. This is optional. Maximal length is
990 50 characters.
991 char *dmSenderRefNumber;
993 Czech: číslo jednací odesílatele. This is optional. Maximal length
994 is 50 chars.
995 char *dmRecipientIdent;
997 Czech: spisová značka příjemce. This is optional. Maximal length is
998 50 characters.
999 char *dmSenderIdent;
1001 Czech: spisová značka odesílatele This is optional. Maximal length
1002 is 50 chars.
1003 Following five members constitute a reference to an item from the Czech
1005 Act Collection. The human-readable reference looks like Point (Para‐
1006 graph) § Section Law/Year Coll. The members apply to both incoming and
1007 outgoing messages:
1008 long int *dmLegalTitleLaw;
1010 A number of an act mandating the authority.
1011 long int *dmLegalTitleYear;
1013 A year of issuing the act mandating the authority.
1014 char *dmLegalTitleSect;
1016 A section of the act mandating the authority. Czech: paragraf.
1017 char *dmLegalTitlePar;
1019 A paragraph of the act mandating the authority. Czech: odstavec.
1020 char *dmLegalTitlePoint;
1022 A point of the act mandating the authority. Czech: písmeno.
1023 Other incoming/outgoing message members:
1025 _Bool *dmPersonalDelivery;
1027 If true, only person with higher privileges can read this message.
1028 _Bool *dmAllowSubstDelivery;
1030 Allow delivery through fiction. I.e. Even if the recipient did
1031 not read this message, the message is considered as delivered after
1032 (currently) 10 days. This is called delivery through fiction. Only
1033 OVM dbType sender can set it.
1034 char *dmType;
1036 Message type (commercial subtypes or government message).
1037 Input values (when sending the message):
1039 "I"
1041 A commercial message offering paying the response (initiatory
1042 message). It's necessary to define dmSenderRefNumber member.
1043 "K"
1045 A commercial message paid by the sender.
1046 "O"
1048 A commercial response paid by the sender of a initiatory mes‐
1049 sage. It's necessary to copy a value from the dmSenderRefNumber
1050 of the initiatory message to the dmRecipientRefNumber of this
1051 message.
1052 "V"
1054 A non-commercial government message. This is the default mean‐
1055 ing if the value is undefined while sending a message.
1056 Output values (when retrieving the message):
1058 "A"
1060 This is a subsidized initiatory commercial message which can
1061 pay a response.
1062 "B"
1064 This is a subsidized initiatory commercial message which has
1065 already paid the response.
1066 "C"
1068 This is a subsidized initiatory commercial message where the
1069 response offer has expired.
1070 "D"
1072 This is an externally subsidized commercial message.
1073 "E"
1075 This is a commercial message prepaid by a stamp.
1076 "G"
1078 This is a commercial message paid by a sponsor.
1079 "I"
1081 See the input values.
1082 "K"
1084 See the input values.
1085 "O"
1087 See the input values.
1088 "V"
1090 See the input values.
1091 "X"
1093 This is an initiatory commercial message where the response of‐
1094 fer has expired.
1095 "Y"
1097 This is an initiatory commercial message which has already paid
1098 the response.
1099 "Z"
1101 This is limitedly subsidized commercial message.
1102 Length of the value is exactly 1 UTF-8 character if defined. That
1104 means it's still zero-terminated character string.
1105 Following members apply to outgoing messages only:
1107 _Bool *dmOVM;
1109 OVM sending mode. Non-OVM dbType boxes that have dbEffectiveOVM
1110 equal to true MUST select between true (OVM mode) and false
1111 (non-OVM mode). Otherwise the value is optional and the default
1112 value is true.
1113 _Bool *dmPublishOwnID;
1115 To allow to reveal sender's login name. The name will be available
1116 to the recipient through isds_get_message_sender function. The
1117 sender's box type and identifier will be always available. This
1118 feature exists because more users can have access to one box and
1119 the recipient could not tell who was the sender. This value is op‐
1120 tional. Default value is false.
1121 int *idLevel;
1123 Specifies which personal information about the sender should be re‐
1124 vealed to the recipient. All specified information can be acquired
1125 by the recipient by using the isds_GetMessageAuthor2 function. The
1126 sender's box type and identifier will always be available. The
1127 value of dmPublishOwnID MUST be set to true in order to specify
1128 which additional information the sender wants to disclose. The ac‐
1129 tual value of the idLevel is the sum of actual enum
1130 isds_IdLevel_value values.
1131 isds_FileMetaType
1133 typedef enum isds_FileMetaType;
1134 Document type from point of view of hierarchy of documents in a mes‐
1136 sage. Known values are:
1137 FILEMETATYPE_MAIN
1139 Main document. There should be exactly one document of this type in
1140 a message.
1141 FILEMETATYPE_ENCLOSURE
1143 An appendix. If a message has more documents, generic-purpose docu‐
1144 ments other than the main one should have this type.
1145 FILEMETATYPE_SIGNATURE
1147 Digital signature. This document is a signature of another document
1148 in the message.
1149 FILEMETATYPE_META
1151 XML document for electronic document information system, elektron‐
1152 ická spisová služba (ESS) in Czech, purpose.
1153 struct isds_document
1155 struct isds_document;
1156 A message document. Members are:
1158 _Bool is_xml;
1160 True if the document is an ISDS XML document. False if the document
1161 is an ISDS binary document.
1162 xmlNodePtr xml_node_list;
1164 XML node-set presenting the XML document content. This is a pointer
1165 to first XML node of the XML representation of the message as
1166 stored in xml member of isds_message structure. Use children and
1167 next members to walk through the document. See libxml2 library doc‐
1168 umentation for more details. The xml_node_list will be NULL if the
1169 document is empty. It's valid only if the is_xml is true.
1170 void *data;
1172 A binary document content. The encoding and format depends on
1173 dmMimeType member value. This is valid only if the is_xml is false.
1174 size_t data_length;
1176 Length of the data buffer in bytes. It's valid only if the is_xml
1177 is false.
1178 char *dmMimeType;
1180 MIME type of document. This member is mandatory.
1181 isds_FileMetaType dmFileMetaType;
1183 Document type to create document hierarchy inside a message.
1184 char *dmFileGuid;
1186 Message-local document identifier. It can be used as a key to refer
1187 to this document by dmUpFileGuid member from a different document.
1188 This is optional.
1189 char *dmUpFileGuid;
1191 A reference to upper document identifier stored in dmFileGuid mem‐
1192 ber of different document. You can use isds_find_document_by_id
1193 function to locate the upper document. This value is optional.
1194 char *dmFileDescr;
1196 Document name (title). E.g. a file name. This value is mandatory.
1197 char *dmFormat;
1199 A reference to XML format definition that explains how to interpret
1200 the XML document. E.g. a URL to an XML schema. This value is op‐
1201 tional.
1202 struct isds_box_state_period
1204 struct isds_box_state_period;
1205 A box state valid in the time range. Members are:
1207 struct isds_timeval *from;
1209 Time range beginning.
1210 struct isds_timeval *to;
1212 Time range end.
1213 long int dbState;
1215 Box state. 1 means the box is accessible. Other values mean the
1216 box is inaccessible. You can use isds_DbState enum to identify some
1217 states.
1218
1220 •
1221 const char *isds_strerror(const isds_error error);
1223 •
1225 struct isds_ctx *isds_ctx_create(void);
1227
1229 libcurl(3), libdatovka(3), time.h(0p)
1230
1232 CZ.NIC, z. s. p. o.
1233 Maintains libdatovka. Has been contributing to libisds.
1234 Petr Písař
1236 He has written libisds.
1237[FIXME: source] 02/23/2023 ISDS.H.LIBDATOVK(3)