1ISDS.H(3) Manual for Libisds ISDS.H(3)
2
6 isds.h - API definition for libisds
7
9 #include <isds.h>
10
12 This header file declares inteface for libisds 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_NOEXIST
86 Requested entity does 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 enum value.
108 IE_DATE
110 Invalid date value.
111 IE_2BIG
113 Value is too big.
114 IE_2SMALL
116 Value is too small.
117 IE_NOTUNIQ
119 Value is not uniq.
120 IE_NOTEQUAL
122 Compared values are not equal.
123 IE_PARTIAL_SUCCESS
125 Operaration on a vector succeded for some values, but failed for
126 others.
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 libisds 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 libisds 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 cryptographinc 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 succeded.
304 OTP_RESOLUTION_UNKNOWN
306 Status is unkown.
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_TO_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 incomming messages. It's not accepted by
367 any 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_FO
419 Standard person.
420 Some interfaces refer to gross box type. These are the shortest names
422 of the identifiers. For example, DBTYPE_OVM is a gross type for
423 DB_OVM_NOTAR or DBTYPE_OVM. But not for DBTYPE_PO.
424 isds_DbState
426 typedef enum isds_DbState;
427 Box status from point of view of accessibility. Known values:
429 DBSTATE_ACCESSIBLE
431 The box is accessible.
432 DBSTATE_TEMP_UNACCESSIBLE
434 The box is temporarily inaccessible (at the request of the user).
435 DBSTATE_NOT_YET_ACCESSIBLE
437 The box has not yet been activated.
438 DBSTATE_PERM_UNACCESSIBLE
440 The box is permanently inaccessible.
441 DBSTATE_REMOVED
443 The box has been removed.
444 DBSTATE_TEMP_UNACCESSIBLE_LAW
446 The box is temporarily inaccessible (because of the reasons enumer‐
447 ated in the law).
448 isds_priviledges
450 typedef enum isds_priviledges;
451 Distinct user permissions from point of view of ISDS. Instances can be
453 bitmaps of any of these distinct values. Distinct known values are:
454 PRIVIL_READ_NON_PERSONAL
456 The user can download and read messages with dmPersonalDelivery
457 equaled to false.
458 PRIVIL_READ_ALL
460 The user can download and read messages with dmPersonalDelivery
461 equaled to true.
462 PRIVIL_CREATE_DM
464 The user can create and send messages, the user can download outgo‐
465 ing (sent) messages.
466 PRIVIL_VIEW_INFO
468 The user can list messages and read data about a message post and
469 delivery.
470 PRIVIL_SEARCH_DB
472 The user can can search for boxes.
473 PRIVIL_OWNER_ADM
475 The user can administer his box (to add and remove permitted users
476 and to modify theirs permissions.)
477 PRIVIL_READ_VAULT
479 The user can read messages stored in the long term storage.
480 Note
482 This permission is not used since 2012-05.
483 PRIVIL_ERASE_VAULT
485 The user can delete messages from the long term storage.
486 isds_message_status
488 typedef enum isds_message_status;
489 Message status. Known values are:
491 MESSAGESTATE_SENT
493 The message has been put into ISDS.
494 MESSAGESTATE_STAMPED
496 Message was stamped by a time stamp authority.
497 MESSAGESTATE_INFECTED
499 The message included viruses. Infected documents have been removed
500 from the message.
501 MESSAGESTATE_DELIVERED
503 The message was delivered. (dmDeliveryTime is populated.)
504 MESSAGESTATE_SUBSTITUTED
506 The message was delivered through fiction, dmAcceptanceTime is pop‐
507 ulated.
508 MESSAGESTATE_RECEIVED
510 The message was accepted (by user's log-in or user's explicit re‐
511 quest). dmAcceptanceTime is populated.
512 MESSAGESTATE_READ
514 The message has been read by a user.
515 MESSAGESTATE_UNDELIVERABLE
517 The message could not been delivered. (E.g.The recipient's box has
518 been made inaccessible meantime.)
519 MESSAGESTATE_REMOVED
521 The message's content was deleted.
522 MESSAGESTATE_IN_SAFE
524 The message is stored in the long term storage.
525 The values can be combined into a bit mask for some functions. A spe‐
527 cial MESSAGESTATE_ANY macro denotes any of the states.
528 isds_hash_algorithm
530 typedef enum isds_hash_algorithm;
531 Hash algorithm types. Known values are:
533 HASH_ALGORITHM_MD5
535 MD5.
536 HASH_ALGORITHM_SHA_1
538 SHA-1.
539 HASH_ALGORITHM_SHA_224
541 SHA-224.
542 HASH_ALGORITHM_SHA_256
544 SHA-256.
545 HASH_ALGORITHM_SHA_384
547 SHA-384.
548 HASH_ALGORITHM_SHA_512
550 SHA-256.
551 isds_buffer_strategy
553 typedef enum isds_buffer_strategy;
554 Buffer storage strategy. This type defines how a function should embed
556 application provided buffer into raw element of output structure. Known
557 values are:
558 BUFFER_DONT_STORE
560 Don't fill raw member.
561 BUFFER_COPY
563 Copy buffer content into newly allocated raw member.
564 BUFFER_MOVE
566 Copy pointer. Leave deallocation to structure destructor (‐
567 isds_*_free()).
568 struct isds_hash
570 struct isds_hash;
571 This is a hash value storage. Members are:
573 isds_hash_algorithm algorithm;
575 Hash algorithm.
576 size_t length;
578 Hash value length in bytes.
579 void *value;
581 Hash value as a byte stream.
582 struct isds_PersonName
584 struct isds_PersonName;
585 Name of a person. Members are:
587 char *pnFirstName;
589 First name.
590 char *pnMiddleName;
592 Middle name.
593 char *pnLastName;
595 Current last name.
596 char *pnLastNameAtBirth;
598 Last name at birth.
599 struct isds_BirthInfo
601 struct isds_BirthInfo;
602 Date and place of a birth. Members are:
604 struct tm *biDate;
606 Date of birth in local time at the birth place. Only tm_year,
607 tm_mon and tm_mday members of the struct tm carry sane value. Oth‐
608 ers are undefined.
609 char *biCity;
611 City where a person was born.
612 char *biCounty;
614 Region where a person was born. This is the kind of region that is
615 called Bezirk in German and okres in Czech.
616 char *biState;
618 State wher a person was born.
619 struct isds_Address
621 struct isds_Address;
622 Postal address. Members are:
624 char *adCity;
626 City.
627 char *adStreet;
629 Street.
630 char *adNumberInStreet;
632 Identification of an entrance on the street. Číslo orientační in
633 Czech.
634 char *adNumberInMunicipality;
636 Identification of a building in the municipality. Číslo popisné in
637 Czech.
638 char *adZipCode;
640 Postal code for mail routing.
641 char *adState;
643 State.
644 struct isds_DbOwnerInfo
646 struct isds_DbOwnerInfo;
647 Data about a box and his owner. NULL pointer values mean undefined val‐
649 ues. Members are:
650 char *dbID;
652 Box identifier. Specification limits the length to 7 characters.
653 isds_DbType *dbType;
655 Box type.
656 char *ic;
658 Identifier of the owner.
659 isds_PersonName *personName;
661 Name of a person owning the box.
662 char *firmName;
664 Name of a firm owning the box.
665 isds_BirthInfo *birthInfo;
667 Birth details of the person.
668 isds_Address *address;
670 Postal address of the owner.
671 char *nationality;
673 Nationality of the owner.
674 char *email;
676 E-mail addres of the owner.
677 char *telNumber;
679 Telephone number of the owner.
680 char *identifier;
682 External box identifier for data provider (OVM, PO, maybe PFO box
683 types.) Specification limits the length to 20 characters.
684 char *registryCode;
686 PFO external registry code. Specification limits the length to 5
687 characters.
688 long int *dbState;
690 Box state. 1 means the box is active.
691 Note
693 The type is long int because specification declares it as
694 xsd:integer.
695 Note
697 TODO: enum?
698 _Bool *dbEffectiveOVM;
700 The Box has OVM role (section 5a of the act).
701 _Bool *dbOpenAddressing;
703 This non-OVM box is free to receive messages from anybody.
704 isds_UserType
706 typedef enum isds_UserType;
707 User type. Known values are:
709 USERTYPE_PRIMARY
711 Owner of the box.
712 USERTYPE_ENTRUSTED
714 User with limited access to the box.
715 USERTYPE_ADMINISTRATOR
717 User who can manage USERTYPE_ENTRUSTED users.
718 USERTYPE_OFFICIAL
720 ???
721 USERTYPE_OFFICIAL_CERT
723 ???
724 USERTYPE_LIQUIDATOR
726 Company liquidator.
727 USERTYPE_RECEIVER
729 Company receiver.
730 USERTYPE_GUARDIAN
732 Legal guardian.
733 struct isds_DbUserInfo
735 struct isds_DbUserInfo;
736 Data about a user. NULL pointer values mean undefined values. Members
738 are:
739 char *userID;
741 User identifier. Specification limits the length from 6 to 12 char‐
742 acters.
743 isds_UserType *userType;
745 User type.
746 long int *userPrivils;
748 Set of user permissions.
749 isds_PersonName *personName;
751 Name of the user.
752 isds_Address *address;
754 Postal address of the user.
755 struct tm *biDate;
757 Date of birth in local time. Only tm_year, tm_mon and tm_mday mem‐
758 bers of the struct tm carry sane value. Others are undefined.
759 char *ic;
761 Identifier a supervising firm. Specification limits the length to 8
762 characters.
763 char *firmName;
765 Name of a supervising firm. Specification limits the length to 100
766 characters.
767 char *caStreet;
769 Contact address. Street and number.
770 char *caCity;
772 Czech city of the contact address.
773 char *caZipCode;
775 Postal code of the contact address.
776 char *caState;
778 Abbreviated country of contact address. This value is optional and
779 implicit meaning is CZ.
780 isds_event_type
782 typedef enum isds_event_type;
783 Message event type. Known values are:
785 EVENT_UKNOWN
787 Event uknown to this library.
788 EVENT_ACCEPTED_BY_RECIPIENT
790 Message has been delivered and accepted by recipient action.
791 EVENT_ACCEPTED_BY_FICTION
793 Message has been delivered, acceptance period timed out, the mes‐
794 sage is considered as accepted.
795 EVENT_UNDELIVERABLE
797 Recipient box was made inaccessible, thus the message is undeliver‐
798 able.
799 EVENT_COMMERCIAL_ACCEPTED
801 Recipient confirmed acceptance of this commercial message.
802 EVENT_ENTERED_SYSTEM
804 The message entered the ISDSsystem, i.e. it has been just sent by
805 a sender.
806 EVENT_DELIVERED
808 The message has been delivered into recipient's box.
809 EVENT_PRIMARY_LOGIN
811 Primary user logged into recipent's box.
812 EVENT_ENTRUSTED_LOGIN
814 Entrusted user with capability to read logged into recipient's box.
815 EVENT_SYSCERT_LOGIN
817 An application authenticated by system certificate logged into re‐
818 cipient's box.
819 struct isds_event
821 struct isds_event;
822 An event that happened in a message life. All members are optional.
824 Members are:
825 struct timeval *time;
827 When the event occurred.
828 isds_event_type *type;
830 Type of the envent.
831 charr *description;
833 Human-readable event description generated by the ISDS system.
834 (Very probably in Czech language).
835 struct isds_envelope
837 struct isds_envelope;
838 Message envelope. These are the metadata about a message. It does con‐
840 tain the message documents.
841 Be ware that the string length constraints are forced only on output
843 members transmitted to the ISDS. The other direction (downloading from
844 the ISDS) can break these rules. It should not happen, but nobody knows
845 how much incompatible new version of the ISDS protocol will be. This is
846 the gold Internet rule: be strict on what you send, be tolerant on what
847 you receive.
848 Following members apply to incoming messages only:
850 char *dmID;
852 Message identifier. Maximal length is 20 characters.
853 char *dbIDSender;
855 Box identifier of the sender. Special value aaaaaaa means the mes‐
856 sage was sent by the ISDS system. Not by another user. Maximal
857 length is 7 characters.
858 char *dmSender;
860 Sender's name. Maximal length is 100 characters.
861 char *dmSenderAddress;
863 Postal address of the sender. Maximal length is 100 characters.
864 long int *dmSenderType;
866 Gross box type of the sender. You can use isds_DbType to enumarate
867 some known box types. This is a generic integer because the proto‐
868 col keeps the value unconstrained and the library must support any
869 syntactically correct value.
870 char *dmRecipient;
872 Recipient's name. Maximal length is 100 characters.
873 char *dmRecipientAddress;
875 Postal address of the recipient. Maximal length is 100 characters.
876 _Bool *dmAmbiguousRecipient;
878 The recipient has OVM role.
879 Following members are assigned by the ISDS in different phases of mes‐
881 sage life cycle:
882 unsigned long int *dmOrdinal;
884 Ordinal number in list of incoming/outgoing messages.
885 isds_message_status *dmMessageStatus;
887 Message state.
888 long int *dmAttachmentSize;
890 Size of message documents in kilobytes. The value is rounded.
891 struct timeval *dmDeliveryTime;
893 The time of delivering the message into recipient's box. It will be
894 NULL, if the message has not been delivered yet.
895 struct timeval *dmAcceptanceTime;
897 The time of acceptancing the message by the recipient. It will be
898 NULL, if message has not been accepted yet.
899 struct isds_hash *hash;
901 The message digest. This is a hash of a substring representing
902 isds:dmDM XML subtree. You can use isds_compute_message_hash func‐
903 tion to compute a hash of the message and then compare it against
904 this structure member using isds_hash_cmp function.
905 void *timestamp;
907 This is a binary image of a qualified time stamp of the hash value.
908 The time stamp is provided by the ISDS system. Messages that have
909 not yet been stamped will have this value NULL.
910 size_t timestamp_length;
912 Length of the timestamp value in bytes.
913 struct isds_list *events;
915 Events the message passed trough. It's a list of isds_event struc‐
916 tures.
917 Following members apply to both outgoing and incoming messages:
919 char *dmSenderOrgUnit;
921 Sender's organisation unit as a string. This is optional.
922 long int *dmSenderOrgUnitNum;
924 Sender's organisation unit as a number. This is optional.
925 char *dbIDRecipient;
927 Recipent's box identifier. This is mandatory. Maximal length is 7
928 characters.
929 char *dmRecipientOrgUnit;
931 Recipient's organisation unit as a string. This is optional.
932 long int *dmRecipientOrgUnitNum;
934 Recipent's organisation unit of as a number. This is optional.
935 char *dmToHands;
937 A person in recipient's organisation. This is optional.
938 char *dmAnnotation;
940 A subject (title) of the message. Maximal length is 255 characters.
941 char *dmRecipientRefNumber;
943 Czech: číslo jednací příjemce. This is optional. Maximal length is
944 50 characters.
945 char *dmSenderRefNumber;
947 Czech: číslo jednací odesílatele. This is optional. Maximal length
948 is 50 chars.
949 char *dmRecipientIdent;
951 Czech: spisová značka příjemce. This is optional. Maximal length is
952 50 characters.
953 char *dmSenderIdent;
955 Czech: spisová značka odesílatele This is optional. Maximal length
956 is 50 chars.
957 Following five members constitue a reference to an item from the Czech
959 Act Collection. The human-readable reference looks like Point (Para‐
960 graph) § Section Law/Year Coll. The memebers apply to both incoming
961 and outgoing messages:
962 long int *dmLegalTitleLaw;
964 A number of an act mandating the authority.
965 long int *dmLegalTitleYear;
967 A year of issuing the act mandating the authority.
968 char *dmLegalTitleSect;
970 A section of the act mandating the authority. Czech: paragraf.
971 char *dmLegalTitlePar;
973 A paragraph of the act mandating the authority. Czech: odstavec.
974 char *dmLegalTitlePoint;
976 A point of the act mandating the authority. Czech: písmeno.
977 Other incoming/outgoing message members:
979 _Bool *dmPersonalDelivery;
981 If true, only person with higher privileges can read this message.
982 _Bool *dmAllowSubstDelivery;
984 Allow delivery through fiction. I.e. Even if the recipient did
985 not read this message, the message is considered as delivered after
986 (currently) 10 days. This is called delivery through fiction. Oonly
987 OVM dbType sender can set it.
988 char *dmType;
990 Message type (commercial subtypes or government message).
991 Input values (when sending the message):
993 "I"
995 A commercial message offering paying the response (initiatory
996 message). It's necessary to define dmSenderRefNumber member.
997 "K"
999 A commercial message paid by the sender.
1000 "O"
1002 A commercial response paid by the sender of a initiatory mes‐
1003 sage. It's necessary to copy a value from the dmSenderRefNumber
1004 of the initiatory message to the dmRecipientRefNumber of this
1005 message.
1006 "V"
1008 A noncommercial government message. This is the default meaning
1009 if the value is undefined while sending a message.
1010 Output values (when retrieving the message):
1012 "A"
1014 This is a subsidized initiatory commercial message which can
1015 pay a response.
1016 "B"
1018 This is a subsidized initiatory commercial message which has
1019 already paid the response.
1020 "C"
1022 This is a subsidized initiatory commercial message where the
1023 response offer has expired.
1024 "D"
1026 This is an externally subsidized commercial messsage.
1027 "E"
1029 This is a commercial message prepaid by a stamp.
1030 "G"
1032 This is a commerical message paid by a sponsor.
1033 "I"
1035 See the input values.
1036 "K"
1038 See the input values.
1039 "O"
1041 See the input values.
1042 "V"
1044 See the input values.
1045 "X"
1047 This is an initiatory commercial message where the response of‐
1048 fer has expired.
1049 "Y"
1051 This is an initiatory commercial message which has already paid
1052 the response.
1053 "Z"
1055 This is limitedly subsidized commercial message.
1056 Length of the value is exactly 1 UTF-8 character if defined. That
1058 means it's still zero-terminated character string.
1059 Following members apply to outgoing messages only:
1061 _Bool *dmOVM;
1063 OVM sending mode. Non-OVM dbType boxes that have dbEffectiveOVM
1064 equaled to true MUST select between true (OVM mode) and false
1065 (non-OVM mode). Otherwise the value is optional and the default
1066 value is true.
1067 _Bool *dmPublishOwnID;
1069 To allow to reveal sender's login name. The name will be available
1070 to the recipient through isds_get_message_sender function. The
1071 sender's box type and identifier will be always available. This
1072 feature exists because more users can have access to one box and
1073 the recipient could not tell who was the sender. This value is op‐
1074 tional. Default value is false.
1075 isds_FileMetaType
1077 typedef enum isds_FileMetaType;
1078 Document type from point fo view of hierarchy of documents in a mes‐
1080 sage. Known values are:
1081 FILEMETATYPE_MAIN
1083 Main document. There should be exactly one document of this type in
1084 a message.
1085 FILEMETATYPE_ENCLOSURE
1087 An appendix. If a message has more documents, generic-purpose docu‐
1088 ments other than the main one should have this type.
1089 FILEMETATYPE_SIGNATURE
1091 Digital signature. This document is a signature of another document
1092 in the message.
1093 FILEMETATYPE_META
1095 XML document for electronic document information system, elektron‐
1096 ická spisová služba (ESS) in Czech, purpose.
1097 struct isds_document
1099 struct isds_document;
1100 A message document. Members are:
1102 _Bool is_xml;
1104 True if the document is an ISDS XML document. False if the document
1105 is an ISDS binary document.
1106 xmlNodePtr xml_node_list;
1108 XML node-set presenting the XML document content. This is a pointer
1109 to first XML node of the XML representation of the message as
1110 stored in xml member of isds_message structure. Use children and
1111 next members to walk through the document. See libxml2 library doc‐
1112 umentation for more details. The xml_node_list will be NULL if the
1113 document is empty. It's valid only if the is_xml is true.
1114 void *data;
1116 A binary document content. The encoding and format depends on
1117 dmMimeType member value. This is valid only if the is_xml is false.
1118 size_t data_length;
1120 Length of the data buffer in bytes. It's valid only if the is_xml
1121 is false.
1122 char *dmMimeType;
1124 MIME type of document. This member is mandatory.
1125 isds_FileMetaType dmFileMetaType;
1127 Document type to create document hierarchy inside a message.
1128 char *dmFileGuid;
1130 Message-local document identifier. It can be used as a key to refer
1131 to this document by dmUpFileGuid member from a different document.
1132 This is optional.
1133 char *dmUpFileGuid;
1135 A reference to upper document identifier stored in dmFileGuid mem‐
1136 ber of different document. You can use isds_find_document_by_id
1137 function to locate the upper document. This value is optional.
1138 char *dmFileDescr;
1140 Document name (title). E.g. a file name. This value is mandatory.
1141 char *dmFormat;
1143 A reference to XML format definition that explains how to interpret
1144 the XML document. E.g. a URL to an XML schema. This value is op‐
1145 tional.
1146 struct isds_box_state_period
1148 struct isds_box_state_period;
1149 A box state valid in the time range. Members are:
1151 struct timeval *from;
1153 Time range beginning.
1154 struct timeval *to;
1156 Time range end.
1157 long int dbState;
1159 Box state. 1 means the box is accessible. Other values mean the
1160 box is inaccessible. You can use isds_DbState enum to identify some
1161 states.
1162
1164 •
1165 const char *isds_strerror(const isds_error error);
1167 •
1169 struct isds_ctx *isds_ctx_create(void);
1171
1173 libcurl(3), libisds(3), time.h(0p)
1174
1176 Petr Písař
1177 He has written libisds.
1178libisds 04/04/2022 ISDS.H(3)