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_vodz_locator
30 extern const char isds_vodz_locator[];
31 High-volume data message locator without client certificate au‐
33 thentication.
34 isds_vodz_cert_locator
36 extern const char isds_vodz_cert_locator[];
37 High-volume data message locator with client certificate authen‐
39 tication.
40 isds_otp_locator
42 extern const char isds_otp_locator[];
43 With OTP authentication.
45 isds_mep_locator
47 extern const char isds_mep_locator[];
48 With MEP authentication.
50 Base URLs of testing ISDS instance
52 isds_testing_locator
53 extern const char isds_testing_locator[];
54 Without client certificate authentication.
56 isds_cert_testing_locator
58 extern const char isds_cert_testing_locator[];
59 With client certificate authentication.
61 isds_vodz_testing_locator
63 extern const char isds_vodz_testing_locator[];
64 High-volume data message locator without client certificate au‐
66 thentication.
67 isds_vodz_cert_testing_locator
69 extern const char isds_vodz_cert_testing_locator[];
70 High-volume data message locator with client certificate authen‐
72 tication.
73 isds_otp_testing_locator
75 extern const char isds_otp_testing_locator[];
76 With OTP authentication.
78 isds_mep_testing_locator
80 extern const char isds_mep_testing_locator[];
81 With MEP authentication.
83
85 struct isds_ctx
86 struct isds_ctx;
87 Context for specific ISDS box.
89 isds_error
91 typedef enum isds_error;
92 Error code. Known values:
94 IE_SUCCESS
96 No error. Numeric value 0.
97 IE_ERROR
99 Unspecified error.
100 IE_NOTSUP
102 Operation is not supported.
103 IE_INVAL
105 Invalid value.
106 IE_INVALID_CONTEXT
108 The context is not valid.
109 IE_NOT_LOGGED_IN
111 The context has not been logged in.
112 IE_CONNECTION_CLOSED
114 Network connection has been closed.
115 IE_TIMED_OUT
117 Time limit for network operation exceeded.
118 IE_NONEXIST
120 Requested entity doesn't exist.
121 IE_NOMEM
123 Not enough memory.
124 IE_NETWORK
126 Network error.
127 IE_HTTP
129 Error on HTTP level.
130 IE_SOAP
132 Error on SOAP level.
133 IE_XML
135 Error on XML level.
136 IE_ISDS
138 Problem with ISDS server.
139 IE_ENUM
141 Invalid enumeration value.
142 IE_DATE
144 Invalid date value.
145 IE_TOO_BIG
147 Value is too big.
148 IE_TOO_SMALL
150 Value is too small.
151 IE_NOTUNIQ
153 Value is not unique.
154 IE_NOTEQUAL
156 Compared values are not equal.
157 IE_PARTIAL_SUCCESS
159 Operation on a vector succeeded for some values but failed for oth‐
160 ers.
161 IE_ABORTED
163 Operation was aborted by application request.
164 IE_SECURITY
166 Security requirements were not satisfied.
167 isds_log_level
169 typedef enum isds_log_level;
170 Log level. Know values:
172 ILL_NONE
174 0
175 ILL_CRIT
177 10
178 ILL_ERR
180 20
181 ILL_WARNING
183 30
184 ILL_INFO
186 40
187 ILL_DEBUG
189 50
190 ILL_ALL
192 100
193 isds_log_facility
195 typedef enum isds_log_facility;
196 Log facility. Know values:
198 ILF_NONE
200 0x0
201 ILF_HTTP
203 0x1
204 ILF_SOAP
206 0x2
207 ILF_ISDS
209 0x4
210 ILF_FILE
212 0x8
213 ILF_SEC
215 0x10
216 ILF_XML
218 0x20
219 ILF_ALL
221 0xFF
222 isds_option
224 typedef enum isds_option;
225 libdatovka option identifiers. Known values:
227 IOPT_TLS_VERIFY_SERVER
229 Option type is _Bool. Whether to verify server identity. Default
230 value is true.
231 IOPT_TLS_CA_FILE
233 Option type is char *. Option value is a file name with certificate
234 authority certificates. Default value depends on used cryptographic
235 library.
236 IOPT_TLS_CA_DIRECTORY
238 Option type is char *, Option value is a directory with certificate
239 authority certificates. Default value depends on used cryptographic
240 library.
241 IOPT_TLS_CRL_FILE
243 Option type is char *. Option value is a file name with certificat
244 revocation list in PEM format. Default value depends on used cryp‐
245 tographic library.
246 IOPT_NORMALIZE_MIME_TYPE
248 Optiona type is _Bool. Whether to normalize MIME type values. De‐
249 fault value is false.
250 isds_tls_option
252 typedef enum isds_tls_option;
253 Warning
256 This type is deprecated.
257 TLS libdatovka option identifiers. Known values:
259 ITLS_VERIFY_SERVER
261 Option type is _Bool. Whether to verify server identity.
262 ITLS_CA_FILE
264 Option type is char *. Option value is a file name with certificate
265 authority certificates.
266 ITLS_CA_DIRECTORY
268 Option type is char *. Option value is a directory name with cer‐
269 tificate authority certificates.
270 ITLS_CRL_FILE
272 Option type is char *. Option value is a file name with certificate
273 revocation list in PEM format.
274 isds_pki_format
276 typedef enum isds_pki_format;
277 Cryptographic material encoding. Known values:
279 PKI_FORMAT_PEM
281 PEM format.
282 PKI_FORMAT_DER
284 DER format.
285 PKI_FORMAT_ENG
287 The material is stored in a cryptographic engine.
288 struct isds_pki_credentials
290 struct isds_pki_credentials;
291 This structure holds public key infrastructure cryptographic material
293 to authenticate a client. Members are:
294 char *engine;
296 String identifier of cryptographic engine to use (where key is
297 stored). Use NULL for no engine.
298 isds_pki_format certificate_format;
300 Certificate format.
301 char *certificate;
303 A path to client certificate, or a certificate nickname in case of
304 NSS as curl back-end, or key slot identifier inside cryptographic
305 engine. Some cryptographic engines can pair certificate with key
306 automatically (NULL value).
307 isds_pki_format key_format;
309 Private key format.
310 char *key;
312 A path to client private key, or key identifier in case an engine
313 is used.
314 char *passphrase;
316 Zero terminated string with password for decrypting private key, or
317 engine PIN. Use NULL for no pass-phrase or to let the engine to ask
318 for it.
319 isds_otp_method
321 typedef enum isds_otp_method;
322 One-time password authentication method. Known values:
324 OTP_HMAC
326 HMAC-based OTP method.
327 OTP_TIME
329 Time-based OTP method.
330 isds_otp_resolution
332 typedef enum isds_otp_resolution;
333 One-time password authentication resolution. Known values:
335 OTP_RESOLUTION_SUCCESS
337 Authentication succeeded.
338 OTP_RESOLUTION_UNKNOWN
340 Status is unknown.
341 OTP_RESOLUTION_BAD_AUTHENTICATION
343 Bad log-in. You can retry to log in.
344 OTP_RESOLUTION_ACCESS_BLOCKED
346 Access blocked for 60 minutes. (Because a brute force attack was
347 detected.)
348 OTP_RESOLUTION_PASSWORD_EXPIRED
350 Password has expired.
351 Note
353 It's not clear which password expired: OTP or regular password?
354 OTP_RESOLUTION_TOO_FAST
356 OTP cannot be sent repeatedly at this rate. (Minimal delay depends
357 on TOTP window setting.)
358 OTP_RESOLUTION_UNAUTHORIZED
360 User name is not allowed to access requested URI.
361 OTP_RESOLUTION_TOTP_SENT
363 OTP has been generated and sent by the ISDS to the user.
364 OTP_RESOLUTION_TOTP_NOT_SENT
366 OTP could not been sent by the ISDS. Retry later.
367 struct isds_otp
369 struct isds_otp;
370 This structure holds one-time password when authenticating a client and
372 resolution of the authentication.
373 Input members are:
375 isds_otp_method method;
377 Select OTP method to use.
378 char *otp_code;
380 One-time password to use. Pass NULL, if you do not know it yet
381 (e.g. in case of first phase of time-based OTP authentication to
382 request new code from ISDS.)
383 Output members are:
385 isds_otp_resolution resolution;
387 Fine-grade resolution of this OTP authentication attempt.
388 isds_DbType
390 typedef enum isds_DbType;
391 Box type. It classifies box owner by his legal status. Known values:
393 DBTYPE_OVM_MAIN
395 This is a special value for isds_find_box_by_fulltext. It's not ac‐
396 cepted by any other services.
397 DBTYPE_SYSTEM
399 This is a special value for sender of messages sent by the ISDS.
400 You can find it only in incoming messages. It's not accepted by any
401 other services.
402 DBTYPE_OVM
404 Standard government (state or municipality or similar) office.
405 DBTYPE_OVM_NOTAR
407 Notary (stopped being used, replaced with OVM_PFO).
408 DBTYPE_OVM_EXEKUT
410 Executor (stopped being used, replaced with OVM_PFO).
411 DBTYPE_OVM_REQ
413 Subsidiary office with OVM (governing) status assigned on request
414 (section 6 and 7 of the act).
415 DBTYPE_OVM_FO
417 Natural person with OVM status (without identification number).
418 DBTYPE_OVM_PFO
420 Natural person in business with OVM status (e.g. notary or execu‐
421 tor).
422 DBTYPE_OVM_PO
424 Juridical person with OVM status (arisen from previously existing
425 PO or PO_REQ).
426 DBTYPE_PO
428 Standard commercial organization (listed in trade registry).
429 DBTYPE_PO_ZAK
431 Other organization founded by an act (stopped being used, replaced
432 with PO).
433 DBTYPE_PO_REQ
435 An organization with a box assigned on its request.
436 DBTYPE_PFO
438 Person in business.
439 DBTYPE_PFO_ADVOK
441 Lawyer.
442 DBTYPE_PFO_DANPOR
444 Tax consultant.
445 DBTYPE_PFO_INSSPR
447 Administrator of insolvency (stopped being used, replaced with
448 OVM_PFO).
449 DBTYPE_PFO_AUDITOR
451 Statutory auditor.
452 DBTYPE_PFO_ZNALEC
454 Expert witness.
455 DBTYPE_PFO_TLUMOCNIK
457 Sworn translator.
458 DBTYPE_PFO_ARCH
460 Architect.
461 DBTYPE_PFO_AIAT
463 Authorised engineer / technician.
464 DBTYPE_PFO_AZI
466 Authorised geodetics engineer.
467 DBTYPE_PFO_REQ
469 Person in business on its request.
470 DBTYPE_FO
472 Standard person.
473 Some interfaces refer to gross box type. These are the shortest names
475 of the identifiers. For example, DBTYPE_OVM is a gross type for
476 DB_OVM_NOTAR or DBTYPE_OVM. But not for DBTYPE_PO.
477 isds_DbState
479 typedef enum isds_DbState;
480 Box status from point of view of accessibility. Known values:
482 DBSTATE_ACCESSIBLE
484 The box is accessible.
485 DBSTATE_TEMP_INACCESSIBLE
487 The box is temporarily inaccessible (at the request of the user).
488 DBSTATE_NOT_YET_ACCESSIBLE
490 The box has not yet been activated.
491 DBSTATE_PERM_INACCESSIBLE
493 The box is permanently inaccessible.
494 DBSTATE_REMOVED
496 The box has been removed.
497 DBSTATE_TEMP_INACCESSIBLE_LAW
499 The box is temporarily inaccessible (because of the reasons enumer‐
500 ated in the law).
501 isds_privileges
503 typedef enum isds_privileges;
504 Distinct user permissions from point of view of ISDS. Instances can be
506 bitmaps of any of these distinct values. Distinct known values are:
507 PRIVIL_READ_NON_PERSONAL
509 The user can download and read messages with dmPersonalDelivery
510 equal to false.
511 PRIVIL_READ_ALL
513 The user can download and read messages with dmPersonalDelivery
514 equal to true.
515 PRIVIL_CREATE_DM
517 The user can create and send messages, the user can download outgo‐
518 ing (sent) messages.
519 PRIVIL_VIEW_INFO
521 The user can list messages and read data about a message post and
522 delivery.
523 PRIVIL_SEARCH_DB
525 The user can can search for boxes.
526 PRIVIL_OWNER_ADM
528 The user can administer his box (to add and remove permitted users
529 and to modify theirs permissions.)
530 PRIVIL_READ_VAULT
532 The user can read messages stored in the long term storage.
533 Note
535 This permission is not used since 2012-05.
536 PRIVIL_ERASE_VAULT
538 The user can delete messages from the long term storage.
539 enum isds_message_status
541 typedef enum isds_message_status isds_message_status;
542 Message status. Known values are:
544 MESSAGESTATE_SENT
546 The message has been put into ISDS.
547 MESSAGESTATE_STAMPED
549 Message was stamped by a time stamp authority.
550 MESSAGESTATE_INFECTED
552 The message included viruses. Infected documents have been removed
553 from the message.
554 MESSAGESTATE_DELIVERED
556 The message was delivered. (dmDeliveryTime is populated.)
557 MESSAGESTATE_SUBSTITUTED
559 The message was delivered through fiction, dmAcceptanceTime is pop‐
560 ulated.
561 MESSAGESTATE_RECEIVED
563 The message was accepted (by user's log-in or user's explicit re‐
564 quest). dmAcceptanceTime is populated.
565 MESSAGESTATE_READ
567 The message has been read by a user.
568 MESSAGESTATE_UNDELIVERABLE
570 The message could not been delivered. (E.g.The recipient's box has
571 been made inaccessible meantime.)
572 MESSAGESTATE_REMOVED
574 The message's content was deleted.
575 MESSAGESTATE_IN_VAULT
577 The message is stored in the long term storage.
578 The values can be combined into a bit mask for some functions. A spe‐
580 cial MESSAGESTATE_ANY macro denotes any of the states.
581 isds_hash_algorithm
583 typedef enum isds_hash_algorithm;
584 Hash algorithm types. Known values are:
586 HASH_ALGORITHM_MD5
588 MD5.
589 HASH_ALGORITHM_SHA_1
591 SHA-1.
592 HASH_ALGORITHM_SHA_224
594 SHA-224.
595 HASH_ALGORITHM_SHA_256
597 SHA-256.
598 HASH_ALGORITHM_SHA_384
600 SHA-384.
601 HASH_ALGORITHM_SHA_512
603 SHA-256.
604 isds_buffer_strategy
606 typedef enum isds_buffer_strategy;
607 Buffer storage strategy. This type defines how a function should embed
609 application provided buffer into raw element of output structure. Known
610 values are:
611 BUFFER_DONT_STORE
613 Don't fill raw member.
614 BUFFER_COPY
616 Copy buffer content into newly allocated raw member.
617 BUFFER_MOVE
619 Copy pointer. Leave deallocation to structure destructor (‐
620 isds_*_free()).
621 struct isds_hash
623 struct isds_hash;
624 This is a hash value storage. Members are:
626 isds_hash_algorithm algorithm;
628 Hash algorithm.
629 size_t length;
631 Hash value length in bytes.
632 void *value;
634 Hash value as a byte stream.
635 struct isds_PersonName
637 struct isds_PersonName;
638 Name of a person. Members are:
640 char *pnFirstName;
642 First name.
643 char *pnMiddleName;
645 Middle name.
646 char *pnLastName;
648 Current last name.
649 char *pnLastNameAtBirth;
651 Last name at birth.
652 struct isds_BirthInfo
654 struct isds_BirthInfo;
655 Date and place of a birth. Members are:
657 struct tm *biDate;
659 Date of birth in local time at the birth place. Only tm_year,
660 tm_mon and tm_mday members of the struct tm carry sane value. Oth‐
661 ers are undefined.
662 char *biCity;
664 City where a person was born.
665 char *biCounty;
667 Region where a person was born. This is the kind of region that is
668 called Bezirk in German and okres in Czech.
669 char *biState;
671 State wher a person was born.
672 struct isds_Address
674 struct isds_Address;
675 Postal address. Members are:
677 char *adCity;
679 City.
680 char *adStreet;
682 Street.
683 char *adNumberInStreet;
685 Identification of an entrance on the street. Číslo orientační in
686 Czech.
687 char *adNumberInMunicipality;
689 Identification of a building in the municipality. Číslo popisné in
690 Czech.
691 char *adZipCode;
693 Postal code for mail routing.
694 char *adState;
696 State.
697 struct isds_DbOwnerInfo
699 struct isds_DbOwnerInfo;
700 Data about a box and his owner. NULL pointer values mean undefined val‐
702 ues. Members are:
703 char *dbID;
705 Box identifier. Specification limits the length to 7 characters.
706 isds_DbType *dbType;
708 Box type.
709 char *ic;
711 Identifier of the owner.
712 isds_PersonName *personName;
714 Name of a person owning the box.
715 char *firmName;
717 Name of a firm owning the box.
718 isds_BirthInfo *birthInfo;
720 Birth details of the person.
721 isds_Address *address;
723 Postal address of the owner.
724 char *nationality;
726 Nationality of the owner.
727 char *email;
729 E-mail addres of the owner.
730 char *telNumber;
732 Telephone number of the owner.
733 char *identifier;
735 External box identifier for data provider (OVM, PO, maybe PFO box
736 types.) Specification limits the length to 20 characters.
737 char *registryCode;
739 PFO external registry code. Specification limits the length to 5
740 characters.
741 long int *dbState;
743 Box state. 1 means the box is active.
744 Note
746 The type is long int because specification declares it as
747 xsd:integer.
748 Note
750 TODO: enum?
751 _Bool *dbEffectiveOVM;
753 The Box has OVM role (section 5a of the act).
754 _Bool *dbOpenAddressing;
756 This non-OVM box is free to receive messages from anybody.
757 isds_UserType
759 typedef enum isds_UserType;
760 User type. Known values are:
762 USERTYPE_PRIMARY
764 Owner of the box.
765 USERTYPE_ENTRUSTED
767 User with limited access to the box.
768 USERTYPE_ADMINISTRATOR
770 User who can manage USERTYPE_ENTRUSTED users.
771 USERTYPE_OFFICIAL
773 ???
774 USERTYPE_OFFICIAL_CERT
776 ???
777 USERTYPE_LIQUIDATOR
779 Company liquidator.
780 USERTYPE_RECEIVER
782 Company receiver.
783 USERTYPE_GUARDIAN
785 Legal guardian.
786 struct isds_DbUserInfo
788 struct isds_DbUserInfo;
789 Data about a user. NULL pointer values mean undefined values. Members
791 are:
792 char *userID;
794 User identifier. Specification limits the length from 6 to 12 char‐
795 acters.
796 isds_UserType *userType;
798 User type.
799 long int *userPrivils;
801 Set of user permissions.
802 isds_PersonName *personName;
804 Name of the user.
805 isds_Address *address;
807 Postal address of the user.
808 struct tm *biDate;
810 Date of birth in local time. Only tm_year, tm_mon and tm_mday mem‐
811 bers of the struct tm carry sane value. Others are undefined.
812 char *ic;
814 Identifier a supervising firm. Specification limits the length to 8
815 characters.
816 char *firmName;
818 Name of a supervising firm. Specification limits the length to 100
819 characters.
820 char *caStreet;
822 Contact address. Street and number.
823 char *caCity;
825 Czech city of the contact address.
826 char *caZipCode;
828 Postal code of the contact address.
829 char *caState;
831 Abbreviated country of contact address. This value is optional and
832 implicit meaning is CZ.
833 isds_event_type
835 typedef enum isds_event_type;
836 Message event type. Known values are:
838 EVENT_UNKNOWN
840 Event unknown to this library.
841 EVENT_ACCEPTED_BY_RECIPIENT
843 Message has been delivered and accepted by recipient action.
844 EVENT_ACCEPTED_BY_FICTION
846 Message has been delivered, acceptance period timed out, the mes‐
847 sage is considered accepted.
848 EVENT_ACCEPTED_BY_FICTION_NO_USER
850 Message has been delivered, acceptance period timed out because
851 there was no user who could accept the message.
852 EVENT_UNDELIVERABLE
854 Recipient box was made inaccessible, thus the message is undeliver‐
855 able.
856 EVENT_COMMERCIAL_ACCEPTED
858 Recipient confirmed acceptance of this commercial message.
859 EVENT_ENTERED_SYSTEM
861 The message entered the ISDSsystem, i.e. it has been just sent by
862 a sender.
863 EVENT_DELIVERED
865 The message has been delivered into recipient's box.
866 EVENT_PRIMARY_LOGIN
868 Primary user logged into recipient's box.
869 EVENT_ENTRUSTED_LOGIN
871 Entrusted user with capability to read logged into recipient's box.
872 EVENT_SYSCERT_LOGIN
874 An application authenticated by system certificate logged into re‐
875 cipient's box.
876 struct isds_event
878 struct isds_event;
879 An event that happened in a message life. All members are optional.
881 Members are:
882 struct isds_timeval *time;
884 When the event occurred.
885 isds_event_type *type;
887 Type of the event.
888 char *description;
890 Human-readable event description generated by the ISDS system.
891 (Very probably in Czech language).
892 enum isds_IdLevel_value
894 enum isds_IdLevel_value;
895 Specifies which information the sender of a data message wants to pub‐
897 lish about his person.
898 PUBLISH_USERTYPE
900 Publish information about the sender type. This information is al‐
901 ways revealed to the recipient.
902 PUBLISH_PERSONNAME
904 Publish sender's personal name.
905 PUBLISH_BIDATE
907 Publish sender's birth date.
908 PUBLISH_BICITY
910 Publish sender's birth city. This information is available only
911 when sender is SENDERTYPE_ENTRUSTED of a FO or PFO box.
912 PUBLISH_BICOUNTY
914 Publish sender's birth county. This information is available only
915 when sender is SENDERTYPE_ENTRUSTED of a FO or PFO box.
916 PUBLISH_ADCODE
918 Publish sender's RUIAN address code.
919 PUBLISH_FULLADDRESS
921 Publish sender's full address.
922 PUBLISH_ROBIDENT
924 Publish information whether sender is identified within the ROB.
925 struct isds_envelope
927 struct isds_envelope;
928 Message envelope. These are the metadata about a message. It does con‐
930 tain the message documents.
931 Be ware that the string length constraints are forced only on output
933 members transmitted to the ISDS. The other direction (downloading from
934 the ISDS) can break these rules. It should not happen, but nobody knows
935 how much incompatible new version of the ISDS protocol will be. This is
936 the gold Internet rule: be strict on what you send, be tolerant on what
937 you receive.
938 Following members apply to incoming messages only:
940 char *dmID;
942 Message identifier. Maximal length is 20 characters.
943 char *dbIDSender;
945 Box identifier of the sender. Special value aaaaaaa means the mes‐
946 sage was sent by the ISDS system. Not by another user. Maximal
947 length is 7 characters.
948 char *dmSender;
950 Sender's name. Maximal length is 100 characters.
951 char *dmSenderAddress;
953 Postal address of the sender. Maximal length is 100 characters.
954 long int *dmSenderType;
956 Gross box type of the sender. You can use isds_DbType to enumerate
957 some known box types. This is a generic integer because the proto‐
958 col keeps the value unconstrained and the library must support any
959 syntactically correct value.
960 char *dmRecipient;
962 Recipient's name. Maximal length is 100 characters.
963 char *dmRecipientAddress;
965 Postal address of the recipient. Maximal length is 100 characters.
966 _Bool *dmAmbiguousRecipient;
968 The recipient has OVM role.
969 Following members are assigned by the ISDS in different phases of mes‐
971 sage life cycle:
972 unsigned long int *dmOrdinal;
974 Ordinal number in list of incoming/outgoing messages.
975 enum isds_message_status *dmMessageStatus;
977 Message state.
978 long int *dmAttachmentSize;
980 Size of message documents in kilobytes. The value is rounded.
981 struct isds_timeval *dmDeliveryTime;
983 The time of delivering the message into recipient's box. It will be
984 NULL, if the message has not been delivered yet.
985 struct isds_timeval *dmAcceptanceTime;
987 The time of accepting the message by the recipient. It will be
988 NULL, if message has not been accepted yet.
989 struct isds_hash *hash;
991 The message digest. This is a hash of a substring representing
992 isds:dmDM XML subtree. You can use isds_compute_message_hash func‐
993 tion to compute a hash of the message and then compare it against
994 this structure member using isds_hash_cmp function.
995 void *timestamp;
997 This is a binary image of a qualified time stamp of the hash value.
998 The time stamp is provided by the ISDS system. Messages that have
999 not yet been stamped will have this value NULL.
1000 size_t timestamp_length;
1002 Length of the timestamp value in bytes.
1003 struct isds_list *events;
1005 Events the message passed trough. It's a list of isds_event struc‐
1006 tures.
1007 Following members apply to both outgoing and incoming messages:
1009 char *dmSenderOrgUnit;
1011 Sender's organisation unit as a string. This is optional.
1012 long int *dmSenderOrgUnitNum;
1014 Sender's organisation unit as a number. This is optional.
1015 char *dbIDRecipient;
1017 Recipient's box identifier. This is mandatory. Maximal length is 7
1018 characters.
1019 char *dmRecipientOrgUnit;
1021 Recipient's organisation unit as a string. This is optional.
1022 long int *dmRecipientOrgUnitNum;
1024 Recipient's organisation unit of as a number. This is optional.
1025 char *dmToHands;
1027 A person in recipient's organisation. This is optional.
1028 char *dmAnnotation;
1030 A subject (title) of the message. Maximal length is 255 characters.
1031 char *dmRecipientRefNumber;
1033 Czech: číslo jednací příjemce. This is optional. Maximal length is
1034 50 characters.
1035 char *dmSenderRefNumber;
1037 Czech: číslo jednací odesílatele. This is optional. Maximal length
1038 is 50 chars.
1039 char *dmRecipientIdent;
1041 Czech: spisová značka příjemce. This is optional. Maximal length is
1042 50 characters.
1043 char *dmSenderIdent;
1045 Czech: spisová značka odesílatele This is optional. Maximal length
1046 is 50 chars.
1047 Following five members constitute a reference to an item from the Czech
1049 Act Collection. The human-readable reference looks like Point (Para‐
1050 graph) § Section Law/Year Coll. The members apply to both incoming and
1051 outgoing messages:
1052 long int *dmLegalTitleLaw;
1054 A number of an act mandating the authority.
1055 long int *dmLegalTitleYear;
1057 A year of issuing the act mandating the authority.
1058 char *dmLegalTitleSect;
1060 A section of the act mandating the authority. Czech: paragraf.
1061 char *dmLegalTitlePar;
1063 A paragraph of the act mandating the authority. Czech: odstavec.
1064 char *dmLegalTitlePoint;
1066 A point of the act mandating the authority. Czech: písmeno.
1067 Other incoming/outgoing message members:
1069 _Bool *dmPersonalDelivery;
1071 If true, only person with higher privileges can read this message.
1072 _Bool *dmAllowSubstDelivery;
1074 Allow delivery through fiction. I.e. Even if the recipient did
1075 not read this message, the message is considered as delivered after
1076 (currently) 10 days. This is called delivery through fiction. Only
1077 OVM dbType sender can set it.
1078 char *dmType;
1080 Message type (commercial subtypes or government message).
1081 Input values (when sending the message):
1083 "I"
1085 A commercial message offering paying the response (initiatory
1086 message). It's necessary to define dmSenderRefNumber member.
1087 "K"
1089 A commercial message paid by the sender.
1090 "O"
1092 A commercial response paid by the sender of a initiatory mes‐
1093 sage. It's necessary to copy a value from the dmSenderRefNumber
1094 of the initiatory message to the dmRecipientRefNumber of this
1095 message.
1096 "V"
1098 A non-commercial government message. This is the default mean‐
1099 ing if the value is undefined while sending a message.
1100 Output values (when retrieving the message):
1102 "A"
1104 This is a subsidized initiatory commercial message which can
1105 pay a response.
1106 "B"
1108 This is a subsidized initiatory commercial message which has
1109 already paid the response.
1110 "C"
1112 This is a subsidized initiatory commercial message where the
1113 response offer has expired.
1114 "D"
1116 This is an externally subsidized commercial message.
1117 "E"
1119 This is a commercial message prepaid by a stamp.
1120 "G"
1122 This is a commercial message paid by a sponsor.
1123 "I"
1125 See the input values.
1126 "K"
1128 See the input values.
1129 "O"
1131 See the input values.
1132 "V"
1134 See the input values.
1135 "X"
1137 This is an initiatory commercial message where the response of‐
1138 fer has expired.
1139 "Y"
1141 This is an initiatory commercial message which has already paid
1142 the response.
1143 "Z"
1145 This is limitedly subsidized commercial message.
1146 Length of the value is exactly 1 UTF-8 character if defined. That
1148 means it's still zero-terminated character string.
1149 _Bool *dmVODZ;
1151 Set to true when downloading lists of sent or received messages and
1152 a particular message is a high-volume data message.
1153 long int *attsNum;
1155 Set to number of attachments when downloading lists of sent or re‐
1156 ceived messages and a particular message is a high-volume data mes‐
1157 sage.
1158 Following members apply to outgoing messages only:
1160 _Bool *dmOVM;
1162 OVM sending mode. Non-OVM dbType boxes that have dbEffectiveOVM
1163 equal to true MUST select between true (OVM mode) and false
1164 (non-OVM mode). Otherwise the value is optional and the default
1165 value is true.
1166 _Bool *dmPublishOwnID;
1168 To allow to reveal sender's login name. The name will be available
1169 to the recipient through isds_get_message_sender function. The
1170 sender's box type and identifier will be always available. This
1171 feature exists because more users can have access to one box and
1172 the recipient could not tell who was the sender. This value is op‐
1173 tional. Default value is false.
1174 int *idLevel;
1176 Specifies which personal information about the sender should be re‐
1177 vealed to the recipient. All specified information can be acquired
1178 by the recipient by using the isds_GetMessageAuthor2 function. The
1179 sender's box type and identifier will always be available. The
1180 value of dmPublishOwnID MUST be set to true in order to specify
1181 which additional information the sender wants to disclose. The ac‐
1182 tual value of the idLevel is the sum of actual enum
1183 isds_IdLevel_value values.
1184 isds_FileMetaType
1186 typedef enum isds_FileMetaType;
1187 Document type from point of view of hierarchy of documents in a mes‐
1189 sage. Known values are:
1190 FILEMETATYPE_MAIN
1192 Main document. There should be exactly one document of this type in
1193 a message.
1194 FILEMETATYPE_ENCLOSURE
1196 An appendix. If a message has more documents, generic-purpose docu‐
1197 ments other than the main one should have this type.
1198 FILEMETATYPE_SIGNATURE
1200 Digital signature. This document is a signature of another document
1201 in the message.
1202 FILEMETATYPE_META
1204 XML document for electronic document information system, elektron‐
1205 ická spisová služba (ESS) in Czech, purpose.
1206 struct isds_document
1208 struct isds_document;
1209 A message document. Members are:
1211 _Bool is_xml;
1213 True if the document is an ISDS XML document. False if the document
1214 is an ISDS binary document.
1215 xmlNodePtr xml_node_list;
1217 XML node-set presenting the XML document content. This is a pointer
1218 to first XML node of the XML representation of the message as
1219 stored in xml member of isds_message structure. Use children and
1220 next members to walk through the document. See libxml2 library doc‐
1221 umentation for more details. The xml_node_list will be NULL if the
1222 document is empty. It's valid only if the is_xml is true.
1223 void *data;
1225 A binary document content. The encoding and format depends on
1226 dmMimeType member value. This is valid only if the is_xml is false.
1227 size_t data_length;
1229 Length of the data buffer in bytes. It's valid only if the is_xml
1230 is false.
1231 char *dmMimeType;
1233 MIME type of document. This member is mandatory.
1234 isds_FileMetaType dmFileMetaType;
1236 Document type to create document hierarchy inside a message.
1237 char *dmFileGuid;
1239 Message-local document identifier. It can be used as a key to refer
1240 to this document by dmUpFileGuid member from a different document.
1241 This is optional.
1242 char *dmUpFileGuid;
1244 A reference to upper document identifier stored in dmFileGuid mem‐
1245 ber of different document. You can use isds_find_document_by_id
1246 function to locate the upper document. This value is optional.
1247 char *dmFileDescr;
1249 Document name (title). E.g. a file name. This value is mandatory.
1250 char *dmFormat;
1252 A reference to XML format definition that explains how to interpret
1253 the XML document. E.g. a URL to an XML schema. This value is op‐
1254 tional.
1255 struct isds_box_state_period
1257 struct isds_box_state_period;
1258 A box state valid in the time range. Members are:
1260 struct isds_timeval *from;
1262 Time range beginning.
1263 struct isds_timeval *to;
1265 Time range end.
1266 long int dbState;
1268 Box state. 1 means the box is accessible. Other values mean the
1269 box is inaccessible. You can use isds_DbState enum to identify some
1270 states.
1271 struct isds_dmMessageAuthor
1273 struct isds_dmMessageAuthor;
1274 Response for GetMessageAuthor2. Members are:
1276 isds_sender_type *userType;
1278 Message sender type.
1279 struct isds_PersonName2 *personName;
1281 Contains pnGivenNames and pnLastName.
1282 struct tm *biDate;
1284 Date of birth in local time at birth place, only tm_year, tm_mon
1285 and tm_mday carry sane value.
1286 char *biCity;
1288 City of birth.
1289 char *biCounty;
1291 County of birth (German: Bezirk, Czech: okres).
1292 char *adCode;
1294 RUIAN address code.
1295 char *fullAddress;
1297 Full address.
1298 _Bool *robIdent;
1300 Flag whether the person is identifiers within the ROB.
1301 enum isds_message_type
1303 typedef enum isds_message_type isds_message_type;
1304 Specifies the direction of the message - whether the message is re‐
1306 ceived or sent:
1307 MESSAGE_TYPE_RECEIVED
1309 Specifies a received message.
1310 MESSAGE_TYPE_SENT
1312 Specifies a sent message.
1313 enum isds_data_format
1315 typedef enum isds_data_format isds_data_format;
1316 Specifies data format:
1318 FORMAT_XML
1320 Data in XML format.
1321 FORMAT_CSV
1323 Data in CSV format.
1324 enum isds_asyncReqType
1326 typedef enum isds_asyncReqType isds_asyncReqType;
1327 Specifies synchronous request type:
1329 ASYNC_REQ_TYPE_LIST_ERASED
1331 Response for the GetListOfErasedMessages request.
1332 struct isds_erased_message
1334 struct isds_erased_message;
1335 Describes entries in the lists of erased messages. Members are:
1337 char *dmID;
1339 Message ID.
1340 char *dbIDSender;
1342 Box ID of sender.
1343 char *dmSender;
1345 Sender name.
1346 char *dbIDRecipient;
1348 Box ID of recipient.
1349 char *dmRecipient;
1351 Recipient name.
1352 char *dmAnnotation;
1354 Subject (title) of the message.
1355 enum isds_message_status *dmMessageStatus;
1357 Message state.
1358 struct isds_timeval *dmDeliveryTime;
1360 Time of delivery into a box.
1361 struct isds_timeval *dmAcceptanceTime;
1363 Time of acceptance of the message by a user.
1364 char *dmType;
1366 Message type.
1367
1369 •
1370 const char *isds_strerror(const isds_error error);
1372 •
1374 struct isds_ctx *isds_ctx_create(void);
1376
1378 libcurl(3), libdatovka(3), time.h(0p)
1379
1381 CZ.NIC, z. s. p. o.
1382 Maintains libdatovka. Has been contributing to libisds.
1383 Petr Písař
1385 He has written libisds.
1386[FIXME: source] 11/09/2023 ISDS.H.LIBDATOVK(3)