1ISDS.H.LIBDATOVK(3)          Manual for Libdatovka         ISDS.H.LIBDATOVK(3)
2
3
4

NAME

6       isds.h.libdatovka - API definition for libdatovka
7

SYNOPSIS

9       #include <libdatovka/isds.h>
10

DESCRIPTION

12       This header file declares interface for the libdatovka library.
13

CONSTANTS

15   Service locators
16       Addresses of known ISDS servers.
17
18       Base URLs of production ISDS instance
19           isds_locator
20                  extern const char isds_locator[];
21
22              Without client certificate authentication.
23
24           isds_cert_locator
25                  extern const char isds_cert_locator[];
26
27              With client certificate authentication.
28
29           isds_otp_locator
30                  extern const char isds_otp_locator[];
31
32              Without OTP authentication.
33
34       Base URLs of testing ISDS instance
35           isds_testing_locator
36                  extern const char isds_testing_locator[];
37
38              Without client certificate authentication.
39
40           isds_cert_testing_locator
41                  extern const char isds_cert_testing_locator[];
42
43              With client certificate authentication.
44
45           isds_otp_testing_locator
46                  extern const char isds_otp_testing_locator[];
47
48              Without OTP authentication.
49

DATA TYPES

51   struct isds_ctx
52           struct isds_ctx;
53
54       Context for specific ISDS box.
55
56   isds_error
57           typedef enum isds_error;
58
59       Error code. Known values:
60
61       IE_SUCCESS
62           No error. Numeric value 0.
63
64       IE_ERROR
65           Unspecified error.
66
67       IE_NOTSUP
68           Operation is not supported.
69
70       IE_INVAL
71           Invalid value.
72
73       IE_INVALID_CONTEXT
74           The context is not valid.
75
76       IE_NOT_LOGGED_IN
77           The context has not been logged in.
78
79       IE_CONNECTION_CLOSED
80           Network connection has been closed.
81
82       IE_TIMED_OUT
83           Time limit for network operation exceeded.
84
85       IE_NONEXIST
86           Requested entity doesn't exist.
87
88       IE_NOMEM
89           Not enough memory.
90
91       IE_NETWORK
92           Network error.
93
94       IE_HTTP
95           Error on HTTP level.
96
97       IE_SOAP
98           Error on SOAP level.
99
100       IE_XML
101           Error on XML level.
102
103       IE_ISDS
104           Problem with ISDS server.
105
106       IE_ENUM
107           Invalid enumeration value.
108
109       IE_DATE
110           Invalid date value.
111
112       IE_TOO_BIG
113           Value is too big.
114
115       IE_TOO_SMALL
116           Value is too small.
117
118       IE_NOTUNIQ
119           Value is not unique.
120
121       IE_NOTEQUAL
122           Compared values are not equal.
123
124       IE_PARTIAL_SUCCESS
125           Operation on a vector succeeded for some values but failed for oth‐
126           ers.
127
128       IE_ABORTED
129           Operation was aborted by application request.
130
131       IE_SECURITY
132           Security requirements were not satisfied.
133
134   isds_log_level
135           typedef enum isds_log_level;
136
137       Log level. Know values:
138
139       ILL_NONE
140           0
141
142       ILL_CRIT
143           10
144
145       ILL_ERR
146           20
147
148       ILL_WARNING
149           30
150
151       ILL_INFO
152           40
153
154       ILL_DEBUG
155           50
156
157       ILL_ALL
158           100
159
160   isds_log_facility
161           typedef enum isds_log_facility;
162
163       Log facility. Know values:
164
165       ILF_NONE
166           0x0
167
168       ILF_HTTP
169           0x1
170
171       ILF_SOAP
172           0x2
173
174       ILF_ISDS
175           0x4
176
177       ILF_FILE
178           0x8
179
180       ILF_SEC
181           0x10
182
183       ILF_XML
184           0x20
185
186       ILF_ALL
187           0xFF
188
189   isds_option
190           typedef enum isds_option;
191
192       libdatovka option identifiers. Known values:
193
194       IOPT_TLS_VERIFY_SERVER
195           Option type is _Bool. Whether to verify  server  identity.  Default
196           value is true.
197
198       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
203       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
208       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
213       IOPT_NORMALIZE_MIME_TYPE
214           Optiona  type  is _Bool. Whether to normalize MIME type values. De‐
215           fault value is false.
216
217   isds_tls_option
218           typedef enum isds_tls_option;
219
220
221           Warning
222           This type is deprecated.
223
224       TLS libdatovka option identifiers. Known values:
225
226       ITLS_VERIFY_SERVER
227           Option type is _Bool. Whether to verify server identity.
228
229       ITLS_CA_FILE
230           Option type is char *. Option value is a file name with certificate
231           authority certificates.
232
233       ITLS_CA_DIRECTORY
234           Option  type  is char *. Option value is a directory name with cer‐
235           tificate authority certificates.
236
237       ITLS_CRL_FILE
238           Option type is char *. Option value is a file name with certificate
239           revocation list in PEM format.
240
241   isds_pki_format
242           typedef enum isds_pki_format;
243
244       Cryptographic material encoding. Known values:
245
246       PKI_FORMAT_PEM
247           PEM format.
248
249       PKI_FORMAT_DER
250           DER format.
251
252       PKI_FORMAT_ENG
253           The material is stored in a cryptographic engine.
254
255   struct isds_pki_credentials
256           struct isds_pki_credentials;
257
258       This  structure  holds public key infrastructure cryptographic material
259       to authenticate a client. Members are:
260
261       char *engine;
262           String identifier of cryptographic engine  to  use  (where  key  is
263           stored). Use NULL for no engine.
264
265       isds_pki_format certificate_format;
266           Certificate format.
267
268       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
274       isds_pki_format key_format;
275           Private key format.
276
277       char *key;
278           A path to client private key, or key identifier in case  an  engine
279           is used.
280
281       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
286   isds_otp_method
287           typedef enum isds_otp_method;
288
289       One-time password authentication method. Known values:
290
291       OTP_HMAC
292           HMAC-based OTP method.
293
294       OTP_TIME
295           Time-based OTP method.
296
297   isds_otp_resolution
298           typedef enum isds_otp_resolution;
299
300       One-time password authentication resolution. Known values:
301
302       OTP_RESOLUTION_SUCCESS
303           Authentication succeeded.
304
305       OTP_RESOLUTION_UNKNOWN
306           Status is unknown.
307
308       OTP_RESOLUTION_BAD_AUTHENTICATION
309           Bad log-in. You can retry to log in.
310
311       OTP_RESOLUTION_ACCESS_BLOCKED
312           Access  blocked  for  60 minutes. (Because a brute force attack was
313           detected.)
314
315       OTP_RESOLUTION_PASSWORD_EXPIRED
316           Password has expired.
317
318               Note
319               It's not clear which password expired: OTP or regular password?
320
321       OTP_RESOLUTION_TOO_FAST
322           OTP cannot be sent repeatedly at this rate. (Minimal delay  depends
323           on TOTP window setting.)
324
325       OTP_RESOLUTION_UNAUTHORIZED
326           User name is not allowed to access requested URI.
327
328       OTP_RESOLUTION_TOTP_SENT
329           OTP has been generated and sent by the ISDS to the user.
330
331       OTP_RESOLUTION_TOTP_NOT_SENT
332           OTP could not been sent by the ISDS. Retry later.
333
334   struct isds_otp
335           struct isds_otp;
336
337       This structure holds one-time password when authenticating a client and
338       resolution of the authentication.
339
340       Input members are:
341
342       isds_otp_method method;
343           Select OTP method to use.
344
345       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
350       Output members are:
351
352       isds_otp_resolution resolution;
353           Fine-grade resolution of this OTP authentication attempt.
354
355   isds_DbType
356           typedef enum isds_DbType;
357
358       Box type. It classifies box owner by his legal status. Known values:
359
360       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
364       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
369       DBTYPE_OVM
370           Standard government (state or municipality or similar) office.
371
372       DBTYPE_OVM_NOTAR
373           Notary (stopped being used, replaced with OVM_PFO).
374
375       DBTYPE_OVM_EXEKUT
376           Executor (stopped being used, replaced with OVM_PFO).
377
378       DBTYPE_OVM_REQ
379           Subsidiary  office  with OVM (governing) status assigned on request
380           (section 6 and 7 of the act).
381
382       DBTYPE_OVM_FO
383           Natural person with OVM status (without identification number).
384
385       DBTYPE_OVM_PFO
386           Natural person in business with OVM status (e.g. notary  or  execu‐
387           tor).
388
389       DBTYPE_OVM_PO
390           Juridical  person  with OVM status (arisen from previously existing
391           PO or PO_REQ).
392
393       DBTYPE_PO
394           Standard commercial organization (listed in trade registry).
395
396       DBTYPE_PO_ZAK
397           Other organization founded by an act (stopped being used,  replaced
398           with PO).
399
400       DBTYPE_PO_REQ
401           An organization with a box assigned on its request.
402
403       DBTYPE_PFO
404           Person in business.
405
406       DBTYPE_PFO_ADVOK
407           Lawyer.
408
409       DBTYPE_PFO_DANPOR
410           Tax consultant.
411
412       DBTYPE_PFO_INSSPR
413           Administrator of insolvency.
414
415       DBTYPE_PFO_AUDITOR
416           Statutory auditor.
417
418       DBTYPE_PFO_ZNALEC
419           Expert witness.
420
421       DBTYPE_PFO_TLUMOCNIK
422           Sworn translator.
423
424       DBTYPE_FO
425           Standard person.
426
427       Some  interfaces  refer to gross box type. These are the shortest names
428       of the identifiers.  For  example,  DBTYPE_OVM  is  a  gross  type  for
429       DB_OVM_NOTAR or DBTYPE_OVM. But not for DBTYPE_PO.
430
431   isds_DbState
432           typedef enum isds_DbState;
433
434       Box status from point of view of accessibility. Known values:
435
436       DBSTATE_ACCESSIBLE
437           The box is accessible.
438
439       DBSTATE_TEMP_INACCESSIBLE
440           The box is temporarily inaccessible (at the request of the user).
441
442       DBSTATE_NOT_YET_ACCESSIBLE
443           The box has not yet been activated.
444
445       DBSTATE_PERM_INACCESSIBLE
446           The box is permanently inaccessible.
447
448       DBSTATE_REMOVED
449           The box has been removed.
450
451       DBSTATE_TEMP_INACCESSIBLE_LAW
452           The box is temporarily inaccessible (because of the reasons enumer‐
453           ated in the law).
454
455   isds_privileges
456           typedef enum isds_privileges;
457
458       Distinct user permissions from point of view of ISDS. Instances can  be
459       bitmaps of any of these distinct values. Distinct known values are:
460
461       PRIVIL_READ_NON_PERSONAL
462           The  user  can  download  and read messages with dmPersonalDelivery
463           equal to false.
464
465       PRIVIL_READ_ALL
466           The user can download and  read  messages  with  dmPersonalDelivery
467           equal to true.
468
469       PRIVIL_CREATE_DM
470           The user can create and send messages, the user can download outgo‐
471           ing (sent) messages.
472
473       PRIVIL_VIEW_INFO
474           The user can list messages and read data about a message  post  and
475           delivery.
476
477       PRIVIL_SEARCH_DB
478           The user can can search for boxes.
479
480       PRIVIL_OWNER_ADM
481           The  user can administer his box (to add and remove permitted users
482           and to modify theirs permissions.)
483
484       PRIVIL_READ_VAULT
485           The user can read messages stored in the long term storage.
486
487               Note
488               This permission is not used since 2012-05.
489
490       PRIVIL_ERASE_VAULT
491           The user can delete messages from the long term storage.
492
493   isds_message_status
494           typedef enum isds_message_status;
495
496       Message status. Known values are:
497
498       MESSAGESTATE_SENT
499           The message has been put into ISDS.
500
501       MESSAGESTATE_STAMPED
502           Message was stamped by a time stamp authority.
503
504       MESSAGESTATE_INFECTED
505           The message included viruses. Infected documents have been  removed
506           from the message.
507
508       MESSAGESTATE_DELIVERED
509           The message was delivered. (dmDeliveryTime is populated.)
510
511       MESSAGESTATE_SUBSTITUTED
512           The message was delivered through fiction, dmAcceptanceTime is pop‐
513           ulated.
514
515       MESSAGESTATE_RECEIVED
516           The message was accepted (by user's log-in or user's  explicit  re‐
517           quest).  dmAcceptanceTime is populated.
518
519       MESSAGESTATE_READ
520           The message has been read by a user.
521
522       MESSAGESTATE_UNDELIVERABLE
523           The  message could not been delivered. (E.g.The recipient's box has
524           been made inaccessible meantime.)
525
526       MESSAGESTATE_REMOVED
527           The message's content was deleted.
528
529       MESSAGESTATE_IN_VAULT
530           The message is stored in the long term storage.
531
532       The values can be combined into a bit mask for some functions.  A  spe‐
533       cial MESSAGESTATE_ANY macro denotes any of the states.
534
535   isds_hash_algorithm
536           typedef enum isds_hash_algorithm;
537
538       Hash algorithm types. Known values are:
539
540       HASH_ALGORITHM_MD5
541           MD5.
542
543       HASH_ALGORITHM_SHA_1
544           SHA-1.
545
546       HASH_ALGORITHM_SHA_224
547           SHA-224.
548
549       HASH_ALGORITHM_SHA_256
550           SHA-256.
551
552       HASH_ALGORITHM_SHA_384
553           SHA-384.
554
555       HASH_ALGORITHM_SHA_512
556           SHA-256.
557
558   isds_buffer_strategy
559           typedef enum isds_buffer_strategy;
560
561       Buffer  storage strategy. This type defines how a function should embed
562       application provided buffer into raw element of output structure. Known
563       values are:
564
565       BUFFER_DONT_STORE
566           Don't fill raw member.
567
568       BUFFER_COPY
569           Copy buffer content into newly allocated raw member.
570
571       BUFFER_MOVE
572           Copy   pointer.  Leave  deallocation  to  structure  destructor  (‐
573           isds_*_free()).
574
575   struct isds_hash
576           struct isds_hash;
577
578       This is a hash value storage. Members are:
579
580       isds_hash_algorithm algorithm;
581           Hash algorithm.
582
583       size_t length;
584           Hash value length in bytes.
585
586       void *value;
587           Hash value as a byte stream.
588
589   struct isds_PersonName
590           struct isds_PersonName;
591
592       Name of a person. Members are:
593
594       char *pnFirstName;
595           First name.
596
597       char *pnMiddleName;
598           Middle name.
599
600       char *pnLastName;
601           Current last name.
602
603       char *pnLastNameAtBirth;
604           Last name at birth.
605
606   struct isds_BirthInfo
607           struct isds_BirthInfo;
608
609       Date and place of a birth. Members are:
610
611       struct tm *biDate;
612           Date of birth in local time  at  the  birth  place.  Only  tm_year,
613           tm_mon  and tm_mday members of the struct tm carry sane value. Oth‐
614           ers are undefined.
615
616       char *biCity;
617           City where a person was born.
618
619       char *biCounty;
620           Region where a person was born. This is the kind of region that  is
621           called Bezirk in German and okres in Czech.
622
623       char *biState;
624           State wher a person was born.
625
626   struct isds_Address
627           struct isds_Address;
628
629       Postal address. Members are:
630
631       char *adCity;
632           City.
633
634       char *adStreet;
635           Street.
636
637       char *adNumberInStreet;
638           Identification  of  an entrance on the street.  Číslo orientační in
639           Czech.
640
641       char *adNumberInMunicipality;
642           Identification of a building in the municipality.  Číslo popisné in
643           Czech.
644
645       char *adZipCode;
646           Postal code for mail routing.
647
648       char *adState;
649           State.
650
651   struct isds_DbOwnerInfo
652           struct isds_DbOwnerInfo;
653
654       Data about a box and his owner. NULL pointer values mean undefined val‐
655       ues. Members are:
656
657       char *dbID;
658           Box identifier. Specification limits the length to 7 characters.
659
660       isds_DbType *dbType;
661           Box type.
662
663       char *ic;
664           Identifier of the owner.
665
666       isds_PersonName *personName;
667           Name of a person owning the box.
668
669       char *firmName;
670           Name of a firm owning the box.
671
672       isds_BirthInfo *birthInfo;
673           Birth details of the person.
674
675       isds_Address *address;
676           Postal address of the owner.
677
678       char *nationality;
679           Nationality of the owner.
680
681       char *email;
682           E-mail addres of the owner.
683
684       char *telNumber;
685           Telephone number of the owner.
686
687       char *identifier;
688           External box identifier for data provider (OVM, PO, maybe  PFO  box
689           types.) Specification limits the length to 20 characters.
690
691       char *registryCode;
692           PFO  external  registry  code. Specification limits the length to 5
693           characters.
694
695       long int *dbState;
696           Box state. 1 means the box is active.
697
698               Note
699               The type is long  int  because  specification  declares  it  as
700               xsd:integer.
701
702               Note
703               TODO: enum?
704
705       _Bool *dbEffectiveOVM;
706           The Box has OVM role (section 5a of the act).
707
708       _Bool *dbOpenAddressing;
709           This non-OVM box is free to receive messages from anybody.
710
711   isds_UserType
712           typedef enum isds_UserType;
713
714       User type. Known values are:
715
716       USERTYPE_PRIMARY
717           Owner of the box.
718
719       USERTYPE_ENTRUSTED
720           User with limited access to the box.
721
722       USERTYPE_ADMINISTRATOR
723           User who can manage USERTYPE_ENTRUSTED users.
724
725       USERTYPE_OFFICIAL
726           ???
727
728       USERTYPE_OFFICIAL_CERT
729           ???
730
731       USERTYPE_LIQUIDATOR
732           Company liquidator.
733
734       USERTYPE_RECEIVER
735           Company receiver.
736
737       USERTYPE_GUARDIAN
738           Legal guardian.
739
740   struct isds_DbUserInfo
741           struct isds_DbUserInfo;
742
743       Data  about  a user. NULL pointer values mean undefined values. Members
744       are:
745
746       char *userID;
747           User identifier. Specification limits the length from 6 to 12 char‐
748           acters.
749
750       isds_UserType *userType;
751           User type.
752
753       long int *userPrivils;
754           Set of user permissions.
755
756       isds_PersonName *personName;
757           Name of the user.
758
759       isds_Address *address;
760           Postal address of the user.
761
762       struct tm *biDate;
763           Date  of birth in local time. Only tm_year, tm_mon and tm_mday mem‐
764           bers of the struct tm carry sane value. Others are undefined.
765
766       char *ic;
767           Identifier a supervising firm. Specification limits the length to 8
768           characters.
769
770       char *firmName;
771           Name  of a supervising firm. Specification limits the length to 100
772           characters.
773
774       char *caStreet;
775           Contact address. Street and number.
776
777       char *caCity;
778           Czech city of the contact address.
779
780       char *caZipCode;
781           Postal code of the contact address.
782
783       char *caState;
784           Abbreviated country of contact address. This value is optional  and
785           implicit meaning is CZ.
786
787   isds_event_type
788           typedef enum isds_event_type;
789
790       Message event type. Known values are:
791
792       EVENT_UNKNOWN
793           Event unknown to this library.
794
795       EVENT_ACCEPTED_BY_RECIPIENT
796           Message has been delivered and accepted by recipient action.
797
798       EVENT_ACCEPTED_BY_FICTION
799           Message  has  been delivered, acceptance period timed out, the mes‐
800           sage is considered accepted.
801
802       EVENT_ACCEPTED_BY_FICTION_NO_USER
803           Message has been delivered, acceptance  period  timed  out  because
804           there was no user who could accept the message.
805
806       EVENT_UNDELIVERABLE
807           Recipient box was made inaccessible, thus the message is undeliver‐
808           able.
809
810       EVENT_COMMERCIAL_ACCEPTED
811           Recipient confirmed acceptance of this commercial message.
812
813       EVENT_ENTERED_SYSTEM
814           The message entered the ISDSsystem, i.e.  it has been just sent  by
815           a sender.
816
817       EVENT_DELIVERED
818           The message has been delivered into recipient's box.
819
820       EVENT_PRIMARY_LOGIN
821           Primary user logged into recipient's box.
822
823       EVENT_ENTRUSTED_LOGIN
824           Entrusted user with capability to read logged into recipient's box.
825
826       EVENT_SYSCERT_LOGIN
827           An  application authenticated by system certificate logged into re‐
828           cipient's box.
829
830   struct isds_event
831           struct isds_event;
832
833       An event that happened in a message life.  All  members  are  optional.
834       Members are:
835
836       struct isds_timeval *time;
837           When the event occurred.
838
839       isds_event_type *type;
840           Type of the event.
841
842       char *description;
843           Human-readable  event  description  generated  by  the ISDS system.
844           (Very probably in Czech language).
845
846   struct isds_envelope
847           struct isds_envelope;
848
849       Message envelope. These are the metadata about a message. It does  con‐
850       tain the message documents.
851
852       Be  ware  that  the string length constraints are forced only on output
853       members transmitted to the ISDS. The other direction (downloading  from
854       the ISDS) can break these rules. It should not happen, but nobody knows
855       how much incompatible new version of the ISDS protocol will be. This is
856       the gold Internet rule: be strict on what you send, be tolerant on what
857       you receive.
858
859       Following members apply to incoming messages only:
860
861       char *dmID;
862           Message identifier. Maximal length is 20 characters.
863
864       char *dbIDSender;
865           Box identifier of the sender. Special value aaaaaaa means the  mes‐
866           sage  was  sent  by  the  ISDS system. Not by another user. Maximal
867           length is 7 characters.
868
869       char *dmSender;
870           Sender's name. Maximal length is 100 characters.
871
872       char *dmSenderAddress;
873           Postal address of the sender. Maximal length is 100 characters.
874
875       long int *dmSenderType;
876           Gross box type of the sender. You can use isds_DbType to  enumerate
877           some  known box types. This is a generic integer because the proto‐
878           col keeps the value unconstrained and the library must support  any
879           syntactically correct value.
880
881       char *dmRecipient;
882           Recipient's name. Maximal length is 100 characters.
883
884       char *dmRecipientAddress;
885           Postal address of the recipient. Maximal length is 100 characters.
886
887       _Bool *dmAmbiguousRecipient;
888           The recipient has OVM role.
889
890       Following  members are assigned by the ISDS in different phases of mes‐
891       sage life cycle:
892
893       unsigned long int *dmOrdinal;
894           Ordinal number in list of incoming/outgoing messages.
895
896       isds_message_status *dmMessageStatus;
897           Message state.
898
899       long int *dmAttachmentSize;
900           Size of message documents in kilobytes. The value is rounded.
901
902       struct isds_timeval *dmDeliveryTime;
903           The time of delivering the message into recipient's box. It will be
904           NULL, if the message has not been delivered yet.
905
906       struct isds_timeval *dmAcceptanceTime;
907           The  time  of  accepting  the  message by the recipient. It will be
908           NULL, if message has not been accepted yet.
909
910       struct isds_hash *hash;
911           The message digest. This is a  hash  of  a  substring  representing
912           isds:dmDM  XML subtree. You can use isds_compute_message_hash func‐
913           tion to compute a hash of the message and then compare  it  against
914           this structure member using isds_hash_cmp function.
915
916       void *timestamp;
917           This is a binary image of a qualified time stamp of the hash value.
918           The time stamp is provided by the ISDS system. Messages  that  have
919           not yet been stamped will have this value NULL.
920
921       size_t timestamp_length;
922           Length of the timestamp value in bytes.
923
924       struct isds_list *events;
925           Events  the message passed trough. It's a list of isds_event struc‐
926           tures.
927
928       Following members apply to both outgoing and incoming messages:
929
930       char *dmSenderOrgUnit;
931           Sender's organisation unit as a string. This is optional.
932
933       long int *dmSenderOrgUnitNum;
934           Sender's organisation unit as a number. This is optional.
935
936       char *dbIDRecipient;
937           Recipient's box identifier. This is mandatory. Maximal length is  7
938           characters.
939
940       char *dmRecipientOrgUnit;
941           Recipient's organisation unit as a string. This is optional.
942
943       long int *dmRecipientOrgUnitNum;
944           Recipient's organisation unit of as a number. This is optional.
945
946       char *dmToHands;
947           A person in recipient's organisation. This is optional.
948
949       char *dmAnnotation;
950           A subject (title) of the message. Maximal length is 255 characters.
951
952       char *dmRecipientRefNumber;
953           Czech:  číslo jednací příjemce. This is optional. Maximal length is
954           50 characters.
955
956       char *dmSenderRefNumber;
957           Czech: číslo jednací odesílatele. This is optional. Maximal  length
958           is 50 chars.
959
960       char *dmRecipientIdent;
961           Czech: spisová značka příjemce. This is optional. Maximal length is
962           50 characters.
963
964       char *dmSenderIdent;
965           Czech: spisová značka odesílatele This is optional. Maximal  length
966           is 50 chars.
967
968       Following five members constitute a reference to an item from the Czech
969       Act Collection. The human-readable reference looks  like  Point  (Para‐
970       graph) § Section Law/Year Coll.  The members apply to both incoming and
971       outgoing messages:
972
973       long int *dmLegalTitleLaw;
974           A number of an act mandating the authority.
975
976       long int *dmLegalTitleYear;
977           A year of issuing the act mandating the authority.
978
979       char *dmLegalTitleSect;
980           A section of the act mandating the authority. Czech: paragraf.
981
982       char *dmLegalTitlePar;
983           A paragraph of the act mandating the authority. Czech: odstavec.
984
985       char *dmLegalTitlePoint;
986           A point of the act mandating the authority. Czech: písmeno.
987
988       Other incoming/outgoing message members:
989
990       _Bool *dmPersonalDelivery;
991           If true, only person with higher privileges can read this message.
992
993       _Bool *dmAllowSubstDelivery;
994           Allow delivery through fiction.  I.e.  Even if  the  recipient  did
995           not read this message, the message is considered as delivered after
996           (currently) 10 days. This is called delivery through fiction.  Only
997           OVM dbType sender can set it.
998
999       char *dmType;
1000           Message type (commercial subtypes or government message).
1001
1002           Input values (when sending the message):
1003
1004           "I"
1005               A  commercial  message offering paying the response (initiatory
1006               message). It's necessary to define dmSenderRefNumber member.
1007
1008           "K"
1009               A commercial message paid by the sender.
1010
1011           "O"
1012               A commercial response paid by the sender of a  initiatory  mes‐
1013               sage. It's necessary to copy a value from the dmSenderRefNumber
1014               of the initiatory message to the dmRecipientRefNumber  of  this
1015               message.
1016
1017           "V"
1018               A  non-commercial government message. This is the default mean‐
1019               ing if the value is undefined while sending a message.
1020
1021           Output values (when retrieving the message):
1022
1023           "A"
1024               This is a subsidized initiatory commercial  message  which  can
1025               pay a response.
1026
1027           "B"
1028               This  is  a  subsidized initiatory commercial message which has
1029               already paid the response.
1030
1031           "C"
1032               This is a subsidized initiatory commercial  message  where  the
1033               response offer has expired.
1034
1035           "D"
1036               This is an externally subsidized commercial message.
1037
1038           "E"
1039               This is a commercial message prepaid by a stamp.
1040
1041           "G"
1042               This is a commercial message paid by a sponsor.
1043
1044           "I"
1045               See the input values.
1046
1047           "K"
1048               See the input values.
1049
1050           "O"
1051               See the input values.
1052
1053           "V"
1054               See the input values.
1055
1056           "X"
1057               This is an initiatory commercial message where the response of‐
1058               fer has expired.
1059
1060           "Y"
1061               This is an initiatory commercial message which has already paid
1062               the response.
1063
1064           "Z"
1065               This is limitedly subsidized commercial message.
1066
1067           Length  of  the value is exactly 1 UTF-8 character if defined. That
1068           means it's still zero-terminated character string.
1069
1070       Following members apply to outgoing messages only:
1071
1072       _Bool *dmOVM;
1073           OVM sending mode. Non-OVM dbType  boxes  that  have  dbEffectiveOVM
1074           equal  to  true  MUST  select  between  true  (OVM  mode) and false
1075           (non-OVM mode). Otherwise the value is  optional  and  the  default
1076           value is true.
1077
1078       _Bool *dmPublishOwnID;
1079           To  allow to reveal sender's login name. The name will be available
1080           to the  recipient  through  isds_get_message_sender  function.  The
1081           sender's  box  type  and  identifier will be always available. This
1082           feature exists because more users can have access to  one  box  and
1083           the  recipient could not tell who was the sender. This value is op‐
1084           tional. Default value is false.
1085
1086   isds_FileMetaType
1087           typedef enum isds_FileMetaType;
1088
1089       Document type from point of view of hierarchy of documents  in  a  mes‐
1090       sage. Known values are:
1091
1092       FILEMETATYPE_MAIN
1093           Main document. There should be exactly one document of this type in
1094           a message.
1095
1096       FILEMETATYPE_ENCLOSURE
1097           An appendix. If a message has more documents, generic-purpose docu‐
1098           ments other than the main one should have this type.
1099
1100       FILEMETATYPE_SIGNATURE
1101           Digital signature. This document is a signature of another document
1102           in the message.
1103
1104       FILEMETATYPE_META
1105           XML document for electronic document information system,  elektron‐
1106           ická spisová služba (ESS) in Czech, purpose.
1107
1108   struct isds_document
1109           struct isds_document;
1110
1111       A message document. Members are:
1112
1113       _Bool is_xml;
1114           True if the document is an ISDS XML document. False if the document
1115           is an ISDS binary document.
1116
1117       xmlNodePtr xml_node_list;
1118           XML node-set presenting the XML document content. This is a pointer
1119           to  first  XML  node  of  the  XML representation of the message as
1120           stored in xml member of isds_message structure.  Use  children  and
1121           next members to walk through the document. See libxml2 library doc‐
1122           umentation for more details. The xml_node_list will be NULL if  the
1123           document is empty. It's valid only if the is_xml is true.
1124
1125       void *data;
1126           A  binary  document  content.  The  encoding  and format depends on
1127           dmMimeType member value. This is valid only if the is_xml is false.
1128
1129       size_t data_length;
1130           Length of the data buffer in bytes. It's valid only if  the  is_xml
1131           is false.
1132
1133       char *dmMimeType;
1134           MIME type of document. This member is mandatory.
1135
1136       isds_FileMetaType dmFileMetaType;
1137           Document type to create document hierarchy inside a message.
1138
1139       char *dmFileGuid;
1140           Message-local document identifier. It can be used as a key to refer
1141           to this document by dmUpFileGuid member from a different  document.
1142           This is optional.
1143
1144       char *dmUpFileGuid;
1145           A  reference to upper document identifier stored in dmFileGuid mem‐
1146           ber of different document.  You  can  use  isds_find_document_by_id
1147           function to locate the upper document. This value is optional.
1148
1149       char *dmFileDescr;
1150           Document name (title).  E.g.  a file name. This value is mandatory.
1151
1152       char *dmFormat;
1153           A reference to XML format definition that explains how to interpret
1154           the XML document.  E.g.  a URL to an XML schema. This value is  op‐
1155           tional.
1156
1157   struct isds_box_state_period
1158           struct isds_box_state_period;
1159
1160       A box state valid in the time range. Members are:
1161
1162       struct isds_timeval *from;
1163           Time range beginning.
1164
1165       struct isds_timeval *to;
1166           Time range end.
1167
1168       long int dbState;
1169           Box  state.   1  means the box is accessible. Other values mean the
1170           box is inaccessible. You can use isds_DbState enum to identify some
1171           states.
1172

FUNCTIONS

1174
1175
1176           const char *isds_strerror(const isds_error error);
1177
1178
1179
1180           struct isds_ctx *isds_ctx_create(void);
1181

SEE ALSO

1183       libcurl(3), libdatovka(3), time.h(0p)
1184

AUTHORS

1186       CZ.NIC, z. s. p. o.
1187           Maintains libdatovka. Has been contributing to libisds.
1188
1189       Petr Písař
1190           He has written libisds.
1191
1192
1193
1194[FIXME: source]                   07/21/2022               ISDS.H.LIBDATOVK(3)
Impressum