1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
3 <!DOCTYPE reference PUBLIC "-//OASIS/DTD DocBook XML V4.5//EN"
4 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
11 <firstname>Petr</firstname>
12 <surname>Písař</surname>
15 <simpara>He has written libisds.</simpara>
18 <productname>libisds</productname>
21 <title>Manual for Libisds</title>
24 <refentry id="libisds.3">
26 <refentrytitle>libisds</refentrytitle>
27 <manvolnum>3</manvolnum>
31 <refname>libisds</refname>
32 <refpurpose>ISDS client library</refpurpose>
36 <synopsis><![CDATA[#include <isds.h>
43 ctx = isds_ctx_create();
45 err = isds_login(ctx, NULL, "username", "password", NULL, NULL);
47 printf("isds_login() failed: %s: %s\n",
48 isds_strerror(err), isds_long_message(ctx));
50 printf("Logged in.\n");
53 err = isds_ctx_free(&ctx);
59 <title>Description</title>
61 <para>This is a client library for accessing SOAP services of
62 <abbrev>ISDS</abbrev> (<foreignphrase lang="cs">Informační systém datových
63 schránek</foreignphrase> / Data Box Information System) as defined in
64 <ulink url="http://portal.gov.cz/zakon/300/2008">Czech
65 <abbrev>ISDS</abbrev> Act (300/2008 <abbrev>Coll.</abbrev>)</ulink>
66 and implied documents. Current implementation details are described in
67 <foreignphrase lang="cs">Provozní řád</foreignphrase> that can be downloaded from
68 <ulink url="https://www.datoveschranky.info/ke-stazeni"><foreignphrase
69 lang="cs">Dokumenty ke stažení</foreignphrase> section of
70 <abbrev>ISDS</abbrev> Information Portal</ulink>.</para>
72 <para>The library provides a C language interface with synchronous
73 non-reentrant blocking calls. Network communication progress reporting
74 and operation logging and library debugging are implemented by calling
75 back application-provided functions. Network operations can be
76 canceled from network reporting call-back.</para>
80 <title>Library Initialization and Deinitialization</title>
82 <para>A libisds application must include <filename>isds.h</filename>
83 header file. The application must call <function>isds_init</function>
84 function to initialize the library before calling any other library
85 functions. After last libisds call, <function>isds_cleanup</function>
86 function should be called to clean up some global resources and to
87 deinitialize dependent libraries.</para>
91 <title>Contexts</title>
93 <para>Most of the functions operate on an established connection to the
94 <abbrev>ISDS</abbrev> server. This is called a context and it's
95 represented by a pointer to an opaque
96 <structname>isds_ctx</structname> structure. The structure maintains
97 state about network connection, authorization or error from last call
98 on the context.</para>
100 <para>The context is allocated by <function>isds_ctx_create</function>
101 function and deallocated by <function>isds_ctx_free</function>
104 <para>There are more context subtypes. A specific subtype is assigned to
105 the context when a fresh new context is passed to one of the few
106 stratifying functions (<function>isds_login</function>,
107 <function>czp_convert_document</function>,
108 <function>isds_request_new_testing_box</function>). Once the context
109 is specialized, you can use it only with functions understanding the
110 subtype. This is not enforced by the library now, but it does not
111 matter much because all the other functions assume the
112 <function>isds_login</function> was called on the context. In other
113 words, do not share the context among the three stratifying
116 <para>For example create a context with
117 <function>isds_ctx_create</function>, then call
118 <function>isds_login</function>, then work with box, then call
119 <function>isds_logout</function>. Here you can reuse the context and
120 log in as another user by calling <function>isds_login</function>
121 again or destroy the context with <function>isds_ctx_free</function> if
122 you don't need it anymore.</para>
124 <para>Or create a context with <function>isds_ctx_create</function>,
125 send a document to authorized conversion using
126 <function>czp_convert_document</function>, then you can send more
127 documents to the authorized conversion by calling
128 <function>czp_convert_document</function> again on the same context
129 and finally destroy the context with
130 <function>isds_ctx_free</function>.</para>
135 <title>Errors</title>
137 <para>Most of the functions return an error code of
138 <type>isds_error</type> type. <errorname>IE_SUCCESS</errorname> value
139 denotes a successful call. Other values represent some kind of
142 <para>You can use <function>isds_strerror</function> function to obtain
143 a human readable string representation of the error code.</para>
145 <para>If a function with context argument failed, you can use
146 <function>isds_long_message</function> function to obtain a detailed
147 error message. Please note that returned value lasts only to the next
148 call on the context.</para>
152 <title>Character Encoding</title>
154 <para>All strings exchanged between the library and the application are
155 encoded in <abbrev>UTF-8</abbrev>. Although there are a few
160 <para><function>isds_strerror</function> and
161 <function>isds_long_message</function> functions return
162 locale encoded string.</para>
166 <para><function>isds_version</function> returns locale encoded
171 <para>Log call-back function set by
172 <function>isds_set_log_callback</function> function is called with
173 raw byte stream.</para>
177 <para><structname>isds_pki_credentials</structname> structure string
178 members have encoding specific to cryptographic library linked to
186 <title>Global Settings</title>
188 <para>Some functions influence library behavior globally. These are:</para>
192 <para><function>isds_init</function> and
193 <function>isds_cleanup</function> used to initialize and
194 deinitialize the library.</para>
198 <para><function>isds_set_logging</function> and
199 <function>isds_set_log_callback</function> to set logging.</para>
205 <title>Logging and Debugging</title>
207 <para>Logging is global for all libisds calls. Log level and facility
208 can be set with <function>isds_set_logging</function> function.</para>
210 <para>The log is printed on standard error output by default.
211 Application can redirect the messages to a call-back function by
212 registering the call-back function with
213 <function>isds_set_log_callback</function>.</para>
217 <title>Network Input/Output</title>
219 <para>Some functions operating on a context create network sockets and
220 do network input and output.</para>
222 <para>Network timeout can be set with
223 <function>isds_set_timeout</function> function. Function calls aborted
224 owing to the timeout will return
225 <errorname>IE_TIMED_OUT</errorname>.</para>
227 <para>Network operation progress can be monitored by a call-back
228 function. The call-back function can be registered using
229 <function>isds_set_progress_callback</function> function. Registered
230 call-back function will be called periodically with arguments
231 declaring amount of transferred data. The call-back return value
232 determines whether to continue in the network operation or to cancel
233 the operation. Functions failed owing to canceling network operation
234 will return <errorname>IE_ABORTED</errorname>.</para>
238 <title>Memory management</title>
240 <para>The library provides destructors for all libisds data structures.
241 For example <function>isds_ctx_free</function> function accepts a pointer
242 to a pointer to the <structname>isds_ctx</structname> structure, frees
243 the double referenced structure (recursively), writes NULL to the
244 pointed pointer (which invalidates the pointer effectively) and returns
247 <para>Upon a function call, all output arguments are automatically
248 reallocated to desired size. On a function failure, all output
249 arguments are automatically deallocated and their pointers set to
250 NULL. Exceptions are documented at respective functions.</para>
252 <para>Output strings are allocated using standard
253 <function>malloc</function> call. Application is responsible for their
254 deallocation (in case of no failure and if not specified otherwise.)
255 Use standard <function>free</function> call for strings,
256 use libisds destructors for libisds structures.</para>
260 <title>Available Functions, Types, and Constants</title>
262 <para>See <filename>isds.h</filename> header file.</para>
266 <title>See Also</title>
269 <simplelist type="inline">
270 <member><citerefentry>
271 <refentrytitle>isds.h</refentrytitle>
272 <manvolnum>3</manvolnum>
273 </citerefentry></member>
274 <member><citerefentry>
275 <refentrytitle>libcurl</refentrytitle>
276 <manvolnum>3</manvolnum>
277 </citerefentry></member>
284 <refentry id="isds.h.3">
286 <refentrytitle>isds.h</refentrytitle>
287 <manvolnum>3</manvolnum>
291 <refname>isds.h</refname>
292 <refpurpose>API definition for libisds</refpurpose>
296 <synopsis><![CDATA[#include <isds.h>
301 <title>Description</title>
303 <para>This header file declares inteface for libisds library.</para>
307 <title>Constants</title>
310 <title>Service locators</title>
312 <para>Addresses of known <abbrev>ISDS</abbrev> servers.</para>
315 <title>Base <abbrev>URL</abbrev>s of production <abbrev>ISDS</abbrev> instance</title>
318 <title><varname>isds_locator</varname></title>
319 <synopsis>extern const char <varname>isds_locator</varname>[];</synopsis>
320 <para>Without client certificate authentication.</para>
324 <title><varname>isds_cert_locator</varname></title>
325 <synopsis>extern const char <varname>isds_cert_locator</varname>[];</synopsis>
326 <para>With client certificate authentication.</para>
330 <title><varname>isds_otp_locator</varname></title>
331 <synopsis>extern const char <varname>isds_otp_locator</varname>[];</synopsis>
332 <para>Without <abbrev>OTP</abbrev> authentication.</para>
337 <title>Base <abbrev>URL</abbrev>s of testing <abbrev>ISDS</abbrev> instance</title>
340 <title><varname>isds_testing_locator</varname></title>
341 <synopsis>extern const char <varname>isds_testing_locator</varname>[];</synopsis>
342 <para>Without client certificate authentication.</para>
346 <title><varname>isds_cert_testing_locator</varname></title>
347 <synopsis>extern const char <varname>isds_cert_testing_locator</varname>[];</synopsis>
348 <para>With client certificate authentication.</para>
352 <title><varname>isds_otp_testing_locator</varname></title>
353 <synopsis>extern const char <varname>isds_otp_testing_locator</varname>[];</synopsis>
354 <para>Without <abbrev>OTP</abbrev> authentication.</para>
362 <title>Data types</title>
365 <title>struct <structname>isds_ctx</structname></title>
366 <synopsis>struct <structname>isds_ctx</structname>;</synopsis>
367 <para>Context for specific <abbrev>ISDS</abbrev> box.</para>
371 <title><type>isds_error</type></title>
372 <synopsis>typedef enum <type>isds_error</type>;</synopsis>
373 <para>Error code. Known values:</para>
376 <term><errorname>IE_SUCCESS</errorname></term>
377 <listitem><para>No error. Numeric value 0.</para></listitem>
381 <term><errorname>IE_ERROR</errorname></term>
382 <listitem><para>Unspecified error.</para></listitem>
386 <term><errorname>IE_NOTSUP</errorname></term>
387 <listitem><para>Operation is not supported.</para></listitem>
391 <term><errorname>IE_INVAL</errorname></term>
392 <listitem><para>Invalid value.</para></listitem>
396 <term><errorname>IE_INVALID_CONTEXT</errorname></term>
397 <listitem><para>The context is not valid.</para></listitem>
401 <term><errorname>IE_NOT_LOGGED_IN</errorname></term>
402 <listitem><para>The context has not been logged in.</para></listitem>
406 <term><errorname>IE_CONNECTION_CLOSED</errorname></term>
407 <listitem><para>Network connection has been closed.</para></listitem>
411 <term><errorname>IE_TIMED_OUT</errorname></term>
412 <listitem><para>Time limit for network operation exceeded.</para></listitem>
416 <term><errorname>IE_NOEXIST</errorname></term>
417 <listitem><para>Requested entity does exist.</para></listitem>
421 <term><errorname>IE_NOMEM</errorname></term>
422 <listitem><para>Not enough memory.</para></listitem>
426 <term><errorname>IE_NETWORK</errorname></term>
427 <listitem><para>Network error.</para></listitem>
431 <term><errorname>IE_HTTP</errorname></term>
432 <listitem><para>Error on <abbrev>HTTP</abbrev> level.</para></listitem>
436 <term><errorname>IE_SOAP</errorname></term>
437 <listitem><para>Error on <abbrev>SOAP</abbrev> level.</para></listitem>
441 <term><errorname>IE_XML</errorname></term>
442 <listitem><para>Error on XML level.</para></listitem>
446 <term><errorname>IE_ISDS</errorname></term>
447 <listitem><para>Problem with <abbrev>ISDS</abbrev> server.</para></listitem>
451 <term><errorname>IE_ENUM</errorname></term>
452 <listitem><para>Invalid enum value.</para></listitem>
456 <term><errorname>IE_DATE</errorname></term>
457 <listitem><para>Invalid date value.</para></listitem>
461 <term><errorname>IE_2BIG</errorname></term>
462 <listitem><para>Value is too big.</para></listitem>
466 <term><errorname>IE_2SMALL</errorname></term>
467 <listitem><para>Value is too small.</para></listitem>
471 <term><errorname>IE_NOTUNIQ</errorname></term>
472 <listitem><para>Value is not uniq.</para></listitem>
476 <term><errorname>IE_NOTEQUAL</errorname></term>
477 <listitem><para>Compared values are not equal.</para></listitem>
481 <term><errorname>IE_PARTIAL_SUCCESS</errorname></term>
482 <listitem><para>Operaration on a vector succeded for some values, but failed for others.</para></listitem>
486 <term><errorname>IE_ABORTED</errorname></term>
487 <listitem><para>Operation was aborted by application request.</para></listitem>
491 <term><errorname>IE_SECURITY</errorname></term>
492 <listitem><para>Security requirements were not satisfied.</para></listitem>
498 <title><type>isds_log_level</type></title>
499 <synopsis>typedef enum <type>isds_log_level</type>;</synopsis>
500 <para>Log level. Know values:</para>
503 <term><constant>ILL_NONE</constant></term>
504 <listitem><para>0</para></listitem>
508 <term><constant>ILL_CRIT</constant></term>
509 <listitem><para>10</para></listitem>
513 <term><constant>ILL_ERR</constant></term>
514 <listitem><para>20</para></listitem>
518 <term><constant>ILL_WARNING</constant></term>
519 <listitem><para>30</para></listitem>
523 <term><constant>ILL_INFO</constant></term>
524 <listitem><para>40</para></listitem>
528 <term><constant>ILL_DEBUG</constant></term>
529 <listitem><para>50</para></listitem>
533 <term><constant>ILL_ALL</constant></term>
534 <listitem><para>100</para></listitem>
540 <title><type>isds_log_facility</type></title>
541 <synopsis>typedef enum <type>isds_log_facility</type>;</synopsis>
542 <para>Log facility. Know values:</para>
545 <term><constant>ILF_NONE</constant></term>
546 <listitem><para>0x0</para></listitem>
550 <term><constant>ILF_HTTP</constant></term>
551 <listitem><para>0x1</para></listitem>
555 <term><constant>ILF_SOAP</constant></term>
556 <listitem><para>0x2</para></listitem>
560 <term><constant>ILF_ISDS</constant></term>
561 <listitem><para>0x4</para></listitem>
565 <term><constant>ILF_FILE</constant></term>
566 <listitem><para>0x8</para></listitem>
570 <term><constant>ILF_SEC</constant></term>
571 <listitem><para>0x10</para></listitem>
575 <term><constant>ILF_XML</constant></term>
576 <listitem><para>0x20</para></listitem>
580 <term><constant>ILF_ALL</constant></term>
581 <listitem><para>0xFF</para></listitem>
587 <title><type>isds_option</type></title>
588 <synopsis>typedef enum <type>isds_option</type>;</synopsis>
589 <para>libisds option identifiers. Known values:</para>
592 <term><constant>IOPT_TLS_VERIFY_SERVER</constant></term>
593 <listitem><para>Option type is <type>_Bool</type>. Whether to
594 verify server identity. Default value is
595 true.</para></listitem>
599 <term><constant>IOPT_TLS_CA_FILE</constant></term>
600 <listitem><para>Option type is <type>char *</type>. Option value
601 is a file name with certificate authority
602 certificates. Default value depends on used cryptographic
603 library.</para></listitem>
607 <term><constant>IOPT_TLS_CA_DIRECTORY</constant></term>
608 <listitem><para>Option type is <type>char *</type>, Option value
609 is a directory with certificate authority certificates.
610 Default value depends on used cryptographic
611 library.</para></listitem>
615 <term><constant>IOPT_TLS_CRL_FILE</constant></term>
616 <listitem><para>Option type is <type>char *</type>. Option value
617 is a file name with certificat revocation list in
618 <abbrev>PEM</abbrev> format. Default value depends on used
619 cryptographic library.</para></listitem>
623 <term><constant>IOPT_NORMALIZE_MIME_TYPE</constant></term>
624 <listitem><para>Optiona type is <type>_Bool</type>. Whether to
625 normalize <abbrev>MIME</abbrev> type values. Default value is
626 false.</para></listitem>
632 <title><type>isds_tls_option</type></title>
633 <synopsis>typedef enum <type>isds_tls_option</type>;</synopsis>
634 <warning><para>This type is deprecated.</para></warning>
635 <para><abbrev>TLS</abbrev> libisds option identifiers. Known values:</para>
638 <term><constant>ITLS_VERIFY_SERVER</constant></term>
639 <listitem><para>Option type is <type>_Bool</type>. Whether to
640 verify server identity.</para></listitem>
644 <term><constant>ITLS_CA_FILE</constant></term>
645 <listitem><para>Option type is <type>char *</type>. Option value
646 is a file name with certificate authority
647 certificates.</para></listitem>
651 <term><constant>ITLS_CA_DIRECTORY</constant></term>
652 <listitem><para>Option type is <type>char *</type>. Option value
653 is a directory name with certificate authority
654 certificates.</para></listitem>
658 <term><constant>ITLS_CRL_FILE</constant></term>
659 <listitem><para>Option type is <type>char *</type>. Option value
660 is a file name with certificate revocation list in
661 <abbrev>PEM</abbrev> format.</para></listitem>
667 <title><type>isds_pki_format</type></title>
668 <synopsis>typedef enum <type>isds_pki_format</type>;</synopsis>
669 <para>Cryptographic material encoding. Known values:</para>
672 <term><constant>PKI_FORMAT_PEM</constant></term>
673 <listitem><para><abbrev>PEM</abbrev> format.</para></listitem>
677 <term><constant>PKI_FORMAT_DER</constant></term>
678 <listitem><para><abbrev>DER format.</abbrev></para></listitem>
682 <term><constant>PKI_FORMAT_ENG</constant></term>
683 <listitem><para>The material is stored in a cryptographic engine.</para></listitem>
689 <title>struct <structname>isds_pki_credentials</structname></title>
690 <synopsis>struct <structname>isds_pki_credentials</structname>;</synopsis>
691 <para>This structure holds public key infrastructure cryptographic
692 material to authenticate a client. Members are:</para>
695 <term><type>char *</type><structfield>engine</structfield>;</term>
696 <listitem><para>String identifier of cryptographic engine to use
697 (where key is stored). Use NULL for no
698 engine.</para></listitem>
702 <term><type>isds_pki_format</type> <structfield>certificate_format</structfield>;</term>
703 <listitem><para>Certificate format.</para></listitem>
707 <term><type>char *</type><structfield>certificate</structfield>;</term>
708 <listitem><para>A path to client certificate, or a certificate
709 nickname in case of <abbrev>NSS</abbrev> as curl back-end, or
710 key slot identifier inside cryptographic engine. Some
711 cryptographinc engines can pair certificate with key
712 automatically (NULL value).</para></listitem>
716 <term><type>isds_pki_format</type> <structfield>key_format</structfield>;</term>
717 <listitem><para>Private key format.</para></listitem>
721 <term><type>char *</type><structfield>key</structfield>;</term>
722 <listitem><para>A path to client private key, or key identifier in
723 case an engine is used.</para></listitem>
727 <term><type>char *</type><structfield>passphrase</structfield>;</term>
728 <listitem><para>Zero terminated string with password for
729 decrypting private key, or engine <abbrev>PIN</abbrev>. Use
730 NULL for no pass-phrase or to let the engine to ask for
731 it.</para></listitem>
737 <title><type>isds_otp_method</type></title>
738 <synopsis>typedef enum <type>isds_otp_method</type>;</synopsis>
739 <para>One-time password authentication method. Known values:</para>
742 <term><constant>OTP_HMAC</constant></term>
743 <listitem><para><abbrev>HMAC</abbrev>-based <abbrev>OTP</abbrev> method.</para></listitem>
747 <term><constant>OTP_TIME</constant></term>
748 <listitem><para>Time-based <abbrev>OTP</abbrev> method.</para></listitem>
754 <title><type>isds_otp_resolution</type></title>
755 <synopsis>typedef enum <type>isds_otp_resolution</type>;</synopsis>
756 <para>One-time password authentication resolution. Known values:</para>
759 <term><constant>OTP_RESOLUTION_SUCCESS</constant></term>
760 <listitem><para>Authentication succeded.</para></listitem>
764 <term><constant>OTP_RESOLUTION_UNKNOWN</constant></term>
765 <listitem><para>Status is unkown.</para></listitem>
769 <term><constant>OTP_RESOLUTION_BAD_AUTHENTICATION</constant></term>
770 <listitem><para>Bad log-in. You can retry to log in.</para></listitem>
774 <term><constant>OTP_RESOLUTION_ACCESS_BLOCKED</constant></term>
775 <listitem><para>Access blocked for 60 minutes. (Because a brute
776 force attack was detected.)</para></listitem>
780 <term><constant>OTP_RESOLUTION_PASSWORD_EXPIRED</constant></term>
782 <para>Password has expired.</para>
784 <para>It's not clear which password expired:
785 <abbrev>OTP</abbrev> or regular password?</para>
791 <term><constant>OTP_RESOLUTION_TO_FAST</constant></term>
792 <listitem><para><abbrev>OTP</abbrev> cannot be sent repeatedly at
793 this rate. (Minimal delay depends on <abbrev>TOTP</abbrev>
794 window setting.)</para></listitem>
798 <term><constant>OTP_RESOLUTION_UNAUTHORIZED</constant></term>
799 <listitem><para>User name is not allowed to access requested
800 <abbrev>URI</abbrev>.</para></listitem>
804 <term><constant>OTP_RESOLUTION_TOTP_SENT</constant></term>
805 <listitem><para><abbrev>OTP</abbrev> has been generated and sent
806 by the <abbrev>ISDS</abbrev> to the user.</para></listitem>
810 <term><constant>OTP_RESOLUTION_TOTP_NOT_SENT</constant></term>
811 <listitem><para><abbrev>OTP</abbrev> could not been sent by the
812 <abbrev>ISDS</abbrev>. Retry later.</para></listitem>
818 <title>struct <structname>isds_otp</structname></title>
819 <synopsis>struct <structname>isds_otp</structname>;</synopsis>
820 <para>This structure holds one-time password when authenticating
821 a client and resolution of the authentication.</para>
823 <para>Input members are:</para>
826 <term><type>isds_otp_method</type> <structfield>method</structfield>;</term>
827 <listitem><para>Select <abbrev>OTP</abbrev> method to use.</para></listitem>
831 <term><type>char *</type><structfield>otp_code</structfield>;</term>
832 <listitem><para>One-time password to use. Pass NULL, if you do not
833 know it yet (<abbrev>e.g.</abbrev> in case of first phase of
834 time-based <abbrev>OTP</abbrev> authentication to request new
835 code from <abbrev>ISDS</abbrev>.)</para></listitem>
839 <para>Output members are:</para>
842 <term><type>isds_otp_resolution</type> <structfield>resolution</structfield>;</term>
843 <listitem><para>Fine-grade resolution of this <abbrev>OTP</abbrev>
844 authentication attempt.</para></listitem>
850 <title><type>isds_DbType</type></title>
851 <synopsis>typedef enum <type>isds_DbType</type>;</synopsis>
852 <para>Box type. It classifies box owner by his legal status. Known
856 <term><constant>DBTYPE_OVM_MAIN</constant></term>
857 <listitem><para>This is a special value for
858 <function>isds_find_box_by_fulltext</function>.
859 It's not accepted by any other
860 <abbrev>services</abbrev>.</para></listitem>
864 <term><constant>DBTYPE_SYSTEM</constant></term>
865 <listitem><para>This is a special value for sender of messages sent
866 by the <abbrev>ISDS</abbrev>. You can find it only in
867 incomming messages. It's not accepted by any other
868 <abbrev>services</abbrev>.</para></listitem>
872 <term><constant>DBTYPE_OVM</constant></term>
873 <listitem><para>Standard government (state or municipality or
874 similar) office.</para></listitem>
878 <term><constant>DBTYPE_OVM_NOTAR</constant></term>
879 <listitem><para>Notary.</para></listitem>
883 <term><constant>DBTYPE_OVM_EXEKUT</constant></term>
884 <listitem><para>Executor.</para></listitem>
888 <term><constant>DBTYPE_OVM_REQ</constant></term>
889 <listitem><para>Subsidiary office with <abbrev>OVM</abbrev>
890 (governing) status assigned on request (section 6 and 7 of the
891 act).</para></listitem>
895 <term><constant>DBTYPE_PO</constant></term>
896 <listitem><para>Standard commercial organization (listed in trade
897 registry).</para></listitem>
901 <term><constant>DBTYPE_PO_ZAK</constant></term>
902 <listitem><para>Other organization founded by an act.</para></listitem>
906 <term><constant>DBTYPE_PO_REQ</constant></term>
907 <listitem><para>An organization with a box assigned on its
908 request.</para></listitem>
912 <term><constant>DBTYPE_PFO</constant></term>
913 <listitem><para>Person in bussiness.</para></listitem>
917 <term><constant>DBTYPE_PFO_ADVOK</constant></term>
918 <listitem><para>Lawyer.</para></listitem>
922 <term><constant>DBTYPE_PFO_DANPOR</constant></term>
923 <listitem><para>Tax consultant.</para></listitem>
927 <term><constant>DBTYPE_PFO_INSSPR</constant></term>
928 <listitem><para>Administrator of insolvency.</para></listitem>
932 <term><constant>DBTYPE_PFO_AUDITOR</constant></term>
933 <listitem><para>Statutory auditor.</para></listitem>
937 <term><constant>DBTYPE_FO</constant></term>
938 <listitem><para>Standard person.</para></listitem>
942 <para>Some interfaces refer to <emphasis>gross</emphasis> box type.
943 These are the shortest names of the identifiers. For example,
944 <literal>DBTYPE_OVM</literal> is a gross type for
945 <literal>DB_OVM_NOTAR</literal> or <literal>DBTYPE_OVM</literal>.
946 But not for <literal>DBTYPE_PO</literal>.</para>
950 <title><type>isds_DbState</type></title>
951 <synopsis>typedef enum <type>isds_DbState</type>;</synopsis>
952 <para>Box status from point of view of accessibility. Known
956 <term><constant>DBSTATE_ACCESSIBLE</constant></term>
957 <listitem><para>The box is accessible.</para></listitem>
961 <term><constant>DBSTATE_TEMP_UNACCESSIBLE</constant></term>
962 <listitem><para>The box is temporarily inaccessible (at the request of the user).</para></listitem>
966 <term><constant>DBSTATE_NOT_YET_ACCESSIBLE</constant></term>
967 <listitem><para>The box has not yet been activated.</para></listitem>
971 <term><constant>DBSTATE_PERM_UNACCESSIBLE</constant></term>
972 <listitem><para>The box is permanently inaccessible.</para></listitem>
976 <term><constant>DBSTATE_REMOVED</constant></term>
977 <listitem><para>The box has been removed.</para></listitem>
981 <term><constant>DBSTATE_TEMP_UNACCESSIBLE_LAW</constant></term>
982 <listitem><para>The box is temporarily inaccessible (because of the reasons enumerated in the law).</para></listitem>
988 <title><type>isds_priviledges</type></title>
989 <synopsis>typedef enum <type>isds_priviledges</type>;</synopsis>
990 <para>Distinct user permissions from point of view of <abbrev>ISDS</abbrev>.
991 Instances can be bitmaps of any of these distinct values. Distinct known
995 <term><constant>PRIVIL_READ_NON_PERSONAL</constant></term>
996 <listitem><para>The user can download and read messages with
997 <structfield>dmPersonalDelivery</structfield> equaled to
998 false.</para></listitem>
1002 <term><constant>PRIVIL_READ_ALL</constant></term>
1003 <listitem><para>The user can download and read messages with
1004 <structfield>dmPersonalDelivery</structfield> equaled to
1005 true.</para></listitem>
1009 <term><constant>PRIVIL_CREATE_DM</constant></term>
1010 <listitem><para>The user can create and send messages, the user
1011 can download outgoing (sent) messages.</para></listitem>
1015 <term><constant>PRIVIL_VIEW_INFO</constant></term>
1016 <listitem><para>The user can list messages and read data about
1017 a message post and delivery.</para></listitem>
1021 <term><constant>PRIVIL_SEARCH_DB</constant></term>
1022 <listitem><para>The user can can search for
1023 boxes.</para></listitem>
1027 <term><constant>PRIVIL_OWNER_ADM</constant></term>
1028 <listitem><para>The user can administer his box (to add and remove
1029 permitted users and to modify theirs
1030 permissions.)</para></listitem>
1034 <term><constant>PRIVIL_READ_VAULT</constant></term>
1036 <para>The user can read messages stored in the long term storage.</para>
1037 <note><para>This permission is not used since 2012-05.</para></note>
1042 <term><constant>PRIVIL_ERASE_VAULT</constant></term>
1043 <listitem><para>The user can delete messages from the long term
1044 storage.</para></listitem>
1050 <title><type>isds_message_status</type></title>
1051 <synopsis>typedef enum <type>isds_message_status</type>;</synopsis>
1052 <para>Message status. Known values are:</para>
1055 <term><constant>MESSAGESTATE_SENT</constant></term>
1056 <listitem><para>The message has been put into
1057 <abbrev>ISDS</abbrev>.</para></listitem>
1061 <term><constant>MESSAGESTATE_STAMPED</constant></term>
1062 <listitem><para>Message was stamped by a time stamp
1063 authority.</para></listitem>
1067 <term><constant>MESSAGESTATE_INFECTED</constant></term>
1068 <listitem><para>The message included viruses. Infected documents
1069 have been removed from the message.</para></listitem>
1073 <term><constant>MESSAGESTATE_DELIVERED</constant></term>
1074 <listitem><para>The message was delivered.
1075 (<structfield>dmDeliveryTime</structfield> is
1076 populated.)</para></listitem>
1080 <term><constant>MESSAGESTATE_SUBSTITUTED</constant></term>
1081 <listitem><para>The message was delivered through fiction,
1082 <structfield>dmAcceptanceTime</structfield> is
1083 populated.</para></listitem>
1087 <term><constant>MESSAGESTATE_RECEIVED</constant></term>
1088 <listitem><para>The message was accepted (by user's log-in or
1089 user's explicit request).
1090 <structfield>dmAcceptanceTime</structfield> is
1091 populated.</para></listitem>
1095 <term><constant>MESSAGESTATE_READ</constant></term>
1096 <listitem><para>The message has been read by
1097 a user.</para></listitem>
1101 <term><constant>MESSAGESTATE_UNDELIVERABLE</constant></term>
1102 <listitem><para>The message could not been delivered.
1103 (<abbrev>E.g.</abbrev>The recipient's box has been made
1104 inaccessible meantime.)</para></listitem>
1108 <term><constant>MESSAGESTATE_REMOVED</constant></term>
1109 <listitem><para>The message's content was
1110 deleted.</para></listitem>
1114 <term><constant>MESSAGESTATE_IN_SAFE</constant></term>
1115 <listitem><para>The message is stored in the long term
1116 storage.</para></listitem>
1120 <para>The values can be combined into a bit mask for some functions.
1121 A special <constant>MESSAGESTATE_ANY</constant> macro denotes any of
1126 <title><type>isds_hash_algorithm</type></title>
1127 <synopsis>typedef enum <type>isds_hash_algorithm</type>;</synopsis>
1128 <para>Hash algorithm types. Known values are:</para>
1131 <term><constant>HASH_ALGORITHM_MD5</constant></term>
1132 <listitem><para><abbrev>MD5</abbrev>.</para></listitem>
1136 <term><constant>HASH_ALGORITHM_SHA_1</constant></term>
1137 <listitem><para><abbrev>SHA-1</abbrev>.</para></listitem>
1141 <term><constant>HASH_ALGORITHM_SHA_224</constant></term>
1142 <listitem><para><abbrev>SHA-224</abbrev>.</para></listitem>
1146 <term><constant>HASH_ALGORITHM_SHA_256</constant></term>
1147 <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1151 <term><constant>HASH_ALGORITHM_SHA_384</constant></term>
1152 <listitem><para><abbrev>SHA-384</abbrev>.</para></listitem>
1156 <term><constant>HASH_ALGORITHM_SHA_512</constant></term>
1157 <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1163 <title><type>isds_buffer_strategy</type></title>
1164 <synopsis>typedef enum <type>isds_buffer_strategy</type>;</synopsis>
1165 <para>Buffer storage strategy. This type defines how a function should
1166 embed application provided buffer into
1167 <structfield>raw</structfield> element of output structure. Known
1171 <term><constant>BUFFER_DONT_STORE</constant></term>
1172 <listitem><para>Don't fill <structfield>raw</structfield>
1173 member.</para></listitem>
1177 <term><constant>BUFFER_COPY</constant></term>
1178 <listitem><para>Copy buffer content into newly allocated
1179 <structfield>raw</structfield> member.</para></listitem>
1183 <term><constant>BUFFER_MOVE</constant></term>
1184 <listitem><para>Copy pointer. Leave deallocation to structure
1186 (<function>isds_*_free</function>()).</para></listitem>
1192 <title>struct <structname>isds_hash</structname></title>
1193 <synopsis>struct <structname>isds_hash</structname>;</synopsis>
1194 <para>This is a hash value storage. Members are:</para>
1197 <term><type>isds_hash_algorithm</type>
1198 <structfield>algorithm</structfield>;</term>
1199 <listitem><para>Hash algorithm.</para></listitem>
1203 <term><type>size_t</type> <structfield>length</structfield>;</term>
1204 <listitem><para>Hash value length in bytes.</para></listitem>
1208 <term><type>void *</type><structfield>value</structfield>;</term>
1209 <listitem><para>Hash value as a byte stream.</para></listitem>
1215 <title>struct <structname>isds_PersonName</structname></title>
1216 <synopsis>struct <structname>isds_PersonName</structname>;</synopsis>
1217 <para>Name of a person. Members are:</para>
1220 <term><type>char *</type><structfield>pnFirstName</structfield>;</term>
1221 <listitem><para>First name.</para></listitem>
1225 <term><type>char *</type><structfield>pnMiddleName</structfield>;</term>
1226 <listitem><para>Middle name.</para></listitem>
1230 <term><type>char *</type><structfield>pnLastName</structfield>;</term>
1231 <listitem><para>Current last name.</para></listitem>
1235 <term><type>char *</type><structfield>pnLastNameAtBirth</structfield>;</term>
1236 <listitem><para>Last name at birth.</para></listitem>
1242 <title>struct <structname>isds_BirthInfo</structname></title>
1243 <synopsis>struct <structname>isds_BirthInfo</structname>;</synopsis>
1244 <para>Date and place of a birth. Members are:</para>
1247 <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1248 <listitem><para>Date of birth in local time at the birth place.
1249 Only <structfield>tm_year</structfield>,
1250 <structfield>tm_mon</structfield> and
1251 <structfield>tm_mday</structfield> members of the <type>struct
1252 tm</type> carry sane value. Others are
1253 undefined.</para></listitem>
1257 <term><type>char *</type><structfield>biCity</structfield>;</term>
1258 <listitem><para>City where a person was born.</para></listitem>
1262 <term><type>char *</type><structfield>biCounty</structfield>;</term>
1263 <listitem><para>Region where a person was born. This is the kind
1264 of region that is called <foreignphrase
1265 lang="de">Bezirk</foreignphrase> in
1266 German and <foreignphrase lang="cs">okres</foreignphrase> in
1267 Czech.</para></listitem>
1271 <term><type>char *</type><structfield>biState</structfield>;</term>
1272 <listitem><para>State wher a person was born.</para></listitem>
1278 <title>struct <structname>isds_Address</structname></title>
1279 <synopsis>struct <structname>isds_Address</structname>;</synopsis>
1280 <para>Postal address. Members are:</para>
1283 <term><type>long int *</type><structfield>adCode</structfield>;</term>
1284 <listitem><para><abbrev>RUIN</abbrev> address code.</para></listitem>
1288 <term><type>char *</type><structfield>adCity</structfield>;</term>
1289 <listitem><para>City.</para></listitem>
1293 <term><type>char *</type><structfield>adDistrict</structfield>;</term>
1294 <listitem><para>Municipality part.</para></listitem>
1298 <term><type>char *</type><structfield>adStreet</structfield>;</term>
1299 <listitem><para>Street.</para></listitem>
1303 <term><type>char *</type><structfield>adNumberInStreet</structfield>;</term>
1304 <listitem><para>Identification of an entrance on the
1305 street. <foreignphrase lang="cs">Číslo
1306 orientační</foreignphrase> in Czech.</para></listitem>
1310 <term><type>char *</type><structfield>adNumberInMunicipality</structfield>;</term>
1311 <listitem><para>Identification of a building in the municipality.
1312 <foreignphrase lang="cs">Číslo popisné</foreignphrase> in
1313 Czech.</para></listitem>
1317 <term><type>char *</type><structfield>adZipCode</structfield>;</term>
1318 <listitem><para>Postal code for mail routing.</para></listitem>
1322 <term><type>char *</type><structfield>adState</structfield>;</term>
1323 <listitem><para>State.</para></listitem>
1329 <title>struct <structname>isds_DbOwnerInfo</structname></title>
1330 <synopsis>struct <structname>isds_DbOwnerInfo</structname>;</synopsis>
1331 <para>Data about a box and his owner. NULL pointer values mean
1332 undefined values. Members are:</para>
1335 <term><type>char *</type><structfield>dbID</structfield>;</term>
1336 <listitem><para>Box identifier. Specification limits the length to
1337 7 characters.</para></listitem>
1341 <term><type>isds_DbType *</type><structfield>dbType</structfield>;</term>
1342 <listitem><para>Box type.</para></listitem>
1346 <term><type>char *</type><structfield>ic</structfield>;</term>
1347 <listitem><para>Identifier of the owner.</para></listitem>
1351 <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1352 <listitem><para>Name of a person owning the box.</para></listitem>
1356 <term><type>char *</type><structfield>firmName</structfield>;</term>
1357 <listitem><para>Name of a firm owning the box.</para></listitem>
1361 <term><type>isds_BirthInfo *</type><structfield>birthInfo</structfield>;</term>
1362 <listitem><para>Birth details of the person.</para></listitem>
1366 <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1367 <listitem><para>Postal address of the owner.</para></listitem>
1371 <term><type>char *</type><structfield>nationality</structfield>;</term>
1372 <listitem><para>Nationality of the owner.</para></listitem>
1376 <term><type>char *</type><structfield>email</structfield>;</term>
1377 <listitem><para>E-mail addres of the owner.</para></listitem>
1381 <term><type>char *</type><structfield>telNumber</structfield>;</term>
1382 <listitem><para>Telephone number of the owner.</para></listitem>
1386 <term><type>char *</type><structfield>identifier</structfield>;</term>
1387 <listitem><para>External box identifier for data provider
1388 (<abbrev>OVM</abbrev>, <abbrev>PO</abbrev>, maybe
1389 <abbrev>PFO</abbrev> box types.) Specification limits the
1390 length to 20 characters.</para></listitem>
1394 <term><type>_Bool *</type><structfield>aifoIsds</structfield>;</term>
1395 <listitem><para>Reference to citizen registry exists.</para></listitem>
1399 <term><type>char *</type><structfield>registryCode</structfield>;</term>
1400 <listitem><para><abbrev>PFO</abbrev> external registry code.
1401 Specification limits the length to
1402 5 characters.</para></listitem>
1406 <term><type>long int *</type><structfield>dbState</structfield>;</term>
1408 <para>Box state. 1 means the box is active.</para>
1409 <note><para>The type is long int because specification declares it
1410 as <type>xsd:integer</type>.</para></note>
1411 <note><para>TODO: enum?</para></note></listitem>
1415 <term><type>_Bool *</type><structfield>dbEffectiveOVM</structfield>;</term>
1416 <listitem><para>The Box has <abbrev>OVM</abbrev> role (section 5a
1417 of the act).</para></listitem>
1421 <term><type>_Bool *</type><structfield>dbOpenAddressing</structfield>;</term>
1422 <listitem>This <para>non-<abbrev>OVM</abbrev> box is free to
1423 receive messages from anybody.</para></listitem>
1429 <title><type>isds_UserType</type></title>
1430 <synopsis>typedef enum <type>isds_UserType</type>;</synopsis>
1431 <para>User type. Known values are:</para>
1434 <term><constant>USERTYPE_PRIMARY</constant></term>
1435 <listitem><para>Owner of the box.</para></listitem>
1439 <term><constant>USERTYPE_ENTRUSTED</constant></term>
1440 <listitem><para>User with limited access to the box.</para></listitem>
1444 <term><constant>USERTYPE_ADMINISTRATOR</constant></term>
1445 <listitem><para>User who can manage
1446 <constant>USERTYPE_ENTRUSTED</constant>
1447 users.</para></listitem>
1451 <term><constant>USERTYPE_OFFICIAL</constant></term>
1452 <listitem><para>???</para></listitem>
1456 <term><constant>USERTYPE_OFFICIAL_CERT</constant></term>
1457 <listitem><para>???</para></listitem>
1461 <term><constant>USERTYPE_LIQUIDATOR</constant></term>
1462 <listitem><para>Company liquidator.</para></listitem>
1466 <term><constant>USERTYPE_RECEIVER</constant></term>
1467 <listitem><para>Company receiver.</para></listitem>
1471 <term><constant>USERTYPE_GUARDIAN</constant></term>
1472 <listitem><para>Legal guardian.</para></listitem>
1478 <title>struct <structname>isds_DbUserInfo</structname></title>
1479 <synopsis>struct <structname>isds_DbUserInfo</structname>;</synopsis>
1480 <para>Data about a user. NULL pointer values mean
1481 undefined values. Members are:</para>
1484 <term><type>char *</type><structfield>userID</structfield>;</term>
1485 <listitem><para>User identifier. Specification limits the length
1486 from 6 to 12 characters.</para></listitem>
1490 <term><type>isds_UserType *</type><structfield>userType</structfield>;</term>
1491 <listitem><para>User type.</para></listitem>
1495 <term><type>long int *</type><structfield>userPrivils</structfield>;</term>
1496 <listitem><para>Set of user permissions.</para></listitem>
1500 <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1501 <listitem><para>Name of the user.</para></listitem>
1505 <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1506 <listitem><para>Postal address of the user.</para></listitem>
1510 <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1511 <listitem><para>Date of birth in local time.
1512 Only <structfield>tm_year</structfield>,
1513 <structfield>tm_mon</structfield> and
1514 <structfield>tm_mday</structfield> members of the <type>struct
1515 tm</type> carry sane value. Others are
1516 undefined.</para></listitem>
1520 <term><type>char *</type><structfield>ic</structfield>;</term>
1521 <listitem><para>Identifier a supervising firm. Specification
1522 limits the length to 8 characters.</para></listitem>
1526 <term><type>char *</type><structfield>firmName</structfield>;</term>
1527 <listitem><para>Name of a supervising firm. Specification limits
1528 the length to 100 characters.</para></listitem>
1532 <term><type>char *</type><structfield>caStreet</structfield>;</term>
1533 <listitem><para>Contact address. Street and number.</para></listitem>
1537 <term><type>char *</type><structfield>caCity</structfield>;</term>
1538 <listitem><para>Czech city of the contact address.</para></listitem>
1542 <term><type>char *</type><structfield>caZipCode</structfield>;</term>
1543 <listitem><para>Postal code of the contact address.</para></listitem>
1547 <term><type>char *</type><structfield>caState</structfield>;</term>
1548 <listitem><para>Abbreviated country of contact address. This value
1549 is optional and implicit meaning is
1550 <constant>CZ</constant>.</para></listitem>
1554 <term><type>char *</type><structfield>aifo_ticket</structfield>;</term>
1555 <listitem><para>Reference to citizen registry. This value is
1556 optional.</para></listitem>
1562 <title><type>isds_event_type</type></title>
1563 <synopsis>typedef enum <type>isds_event_type</type>;</synopsis>
1564 <para>Message event type. Known values are:</para>
1567 <term><constant>EVENT_UKNOWN</constant></term>
1568 <listitem><para>Event uknown to this library.</para></listitem>
1572 <term><constant>EVENT_ACCEPTED_BY_RECIPIENT</constant></term>
1573 <listitem><para>Message has been delivered and accepted by
1574 recipient action.</para></listitem>
1578 <term><constant>EVENT_ACCEPTED_BY_FICTION</constant></term>
1579 <listitem><para>Message has been delivered, acceptance period
1580 timed out, the message is considered as
1581 accepted.</para></listitem>
1585 <term><constant>EVENT_UNDELIVERABLE</constant></term>
1586 <listitem><para>Recipient box was made inaccessible, thus the
1587 message is undeliverable.</para></listitem>
1591 <term><constant>EVENT_COMMERCIAL_ACCEPTED</constant></term>
1592 <listitem><para>Recipient confirmed acceptance of this commercial
1593 message.</para></listitem>
1597 <term><constant>EVENT_ENTERED_SYSTEM</constant></term>
1598 <listitem><para>The message entered the
1599 <abbrev>ISDS</abbrev>system, <abbrev>i.e.</abbrev> it has been
1600 just sent by a sender.</para></listitem>
1604 <term><constant>EVENT_DELIVERED</constant></term>
1605 <listitem><para>The message has been delivered into recipient's
1606 box.</para></listitem>
1610 <term><constant>EVENT_PRIMARY_LOGIN</constant></term>
1611 <listitem><para>Primary user logged into recipent's
1612 box.</para></listitem>
1616 <term><constant>EVENT_ENTRUSTED_LOGIN</constant></term>
1617 <listitem><para>Entrusted user with capability to read logged
1618 into recipient's box.</para></listitem>
1622 <term><constant>EVENT_SYSCERT_LOGIN</constant></term>
1623 <listitem><para>An application authenticated by
1624 <emphasis>system</emphasis> certificate logged into
1625 recipient's box.</para></listitem>
1631 <title>struct <structname>isds_event</structname></title>
1632 <synopsis>struct <structname>isds_event</structname>;</synopsis>
1633 <para>An event that happened in a message life. All members are
1634 optional. Members are:</para>
1637 <term><type>struct timeval *</type><structfield>time</structfield>;</term>
1638 <listitem><para>When the event occurred.</para></listitem>
1642 <term><type>isds_event_type *</type><structfield>type</structfield>;</term>
1643 <listitem><para>Type of the envent.</para></listitem>
1647 <term><type>charr *</type><structfield>description</structfield>;</term>
1648 <listitem><para>Human-readable event description generated by the
1649 <abbrev>ISDS</abbrev> system. (Very probably in Czech
1650 language).</para></listitem>
1656 <title>struct <structname>isds_envelope</structname></title>
1657 <synopsis>struct <structname>isds_envelope</structname>;</synopsis>
1658 <para>Message envelope. These are the metadata about a message. It
1659 does contain the message documents.</para>
1660 <para>Be ware that the string length constraints are forced only on
1661 output members transmitted to the <abbrev>ISDS</abbrev>. The other
1662 direction (downloading from the <abbrev>ISDS</abbrev>) can break
1663 these rules. It should not happen, but nobody knows how much
1664 incompatible new version of the <abbrev>ISDS</abbrev> protocol will
1665 be. This is the gold Internet rule: be strict on what you send, be
1666 tolerant on what you receive.</para>
1667 <para>Following members apply to incoming messages only:</para>
1670 <term><type>char *</type><structfield>dmID</structfield>;</term>
1671 <listitem><para>Message identifier. Maximal length is 20
1672 characters.</para></listitem>
1676 <term><type>char *</type><structfield>dbIDSender</structfield>;</term>
1677 <listitem><para>Box identifier of the sender. Special value
1678 <literal>aaaaaaa</literal> means the message was sent by the
1679 <abbrev>ISDS</abbrev> system. Not by another user. Maximal
1680 length is 7 characters.</para></listitem>
1684 <term><type>char *</type><structfield>dmSender</structfield>;</term>
1685 <listitem><para>Sender's name. Maximal length is 100
1686 characters.</para></listitem>
1690 <term><type>char *</type><structfield>dmSenderAddress</structfield>;</term>
1691 <listitem><para>Postal address of the sender. Maximal length is 100
1692 characters.</para></listitem>
1696 <term><type>long int *</type><structfield>dmSenderType</structfield>;</term>
1697 <listitem><para>Gross box type of the sender. You can use
1698 <type>isds_DbType</type> to enumarate some known box types.
1699 This is a generic integer because the protocol keeps the value
1700 unconstrained and the library must support any syntactically
1701 correct value.</para></listitem>
1705 <term><type>char *</type><structfield>dmRecipient</structfield>;</term>
1706 <listitem><para>Recipient's name. Maximal length is 100
1707 characters.</para></listitem>
1711 <term><type>char *</type><structfield>dmRecipientAddress</structfield>;</term>
1712 <listitem><para>Postal address of the recipient. Maximal length is
1713 100 characters.</para></listitem>
1717 <term><type>_Bool *</type><structfield>dmAmbiguousRecipient</structfield>;</term>
1718 <listitem><para>The recipient has <abbrev>OVM</abbrev> role.</para></listitem>
1722 <para>Following members are assigned by the <abbrev>ISDS</abbrev> in
1723 different phases of message life cycle:</para>
1726 <term><type>unsigned long int *</type><structfield>dmOrdinal</structfield>;</term>
1727 <listitem><para>Ordinal number in list of incoming/outgoing
1728 messages.</para></listitem>
1732 <term><type>isds_message_status *</type><structfield>dmMessageStatus</structfield>;</term>
1733 <listitem><para>Message state.</para></listitem>
1737 <term><type>long int *</type><structfield>dmAttachmentSize</structfield>;</term>
1738 <listitem><para>Size of message documents in kilobytes. The value
1739 is rounded.</para></listitem>
1743 <term><type>struct timeval *</type><structfield>dmDeliveryTime</structfield>;</term>
1744 <listitem><para>The time of delivering the message into recipient's
1745 box. It will be <constant>NULL</constant>, if the message has not
1746 been delivered yet.</para></listitem>
1750 <term><type>struct timeval *</type><structfield>dmAcceptanceTime</structfield>;</term>
1751 <listitem><para>The time of acceptancing the message by the
1752 recipient. It will be <constant>NULL</constant>, if message
1753 has not been accepted yet.</para></listitem>
1757 <term><type>struct isds_hash *</type><structfield>hash</structfield>;</term>
1758 <listitem><para>The message digest. This is a hash of a substring representing
1759 <literal>isds:dmDM</literal> <abbrev>XML</abbrev>
1760 subtree. You can use
1761 <function>isds_compute_message_hash</function> function to
1762 compute a hash of the message and then compare it against this
1763 structure member using <function>isds_hash_cmp</function>
1764 function.</para></listitem>
1768 <term><type>void *</type><structfield>timestamp</structfield>;</term>
1769 <listitem><para>This is a binary image of a qualified time stamp
1770 of the <structfield>hash</structfield> value. The time stamp
1771 is provided by the <abbrev>ISDS</abbrev> system. Messages that
1772 have not yet been stamped will have this value
1773 <constant>NULL</constant>.</para></listitem>
1777 <term><type>size_t</type> <structfield>timestamp_length</structfield>;</term>
1778 <listitem><para>Length of the <structfield>timestamp</structfield>
1779 value in bytes.</para></listitem>
1783 <term><type>struct isds_list *</type><structfield>events</structfield>;</term>
1784 <listitem><para>Events the message passed trough. It's a list of
1785 <type>isds_event</type> structures.</para></listitem>
1789 <para>Following members apply to both outgoing and incoming
1794 <term><type>char *</type><structfield>dmSenderOrgUnit</structfield>;</term>
1795 <listitem><para>Sender's organisation unit as a string. This is
1796 optional.</para></listitem>
1800 <term><type>long int *</type><structfield>dmSenderOrgUnitNum</structfield>;</term>
1801 <listitem><para>Sender's organisation unit as a number. This is
1802 optional.</para></listitem>
1806 <term><type>char *</type><structfield>dbIDRecipient</structfield>;</term>
1807 <listitem><para>Recipent's box identifier. This is mandatory.
1808 Maximal length is 7 characters.</para></listitem>
1812 <term><type>char *</type><structfield>dmRecipientOrgUnit</structfield>;</term>
1813 <listitem><para>Recipient's organisation unit as a string. This is
1814 optional.</para></listitem>
1818 <term><type>long int *</type><structfield>dmRecipientOrgUnitNum</structfield>;</term>
1819 <listitem><para>Recipent's organisation unit of as a number. This
1820 is optional.</para></listitem>
1824 <term><type>char *</type><structfield>dmToHands</structfield>;</term>
1825 <listitem><para>A person in recipient's organisation. This is
1826 optional.</para></listitem>
1830 <term><type>char *</type><structfield>dmAnnotation</structfield>;</term>
1831 <listitem><para>A subject (title) of the message. Maximal length
1832 is 255 characters.</para></listitem>
1836 <term><type>char *</type><structfield>dmRecipientRefNumber</structfield>;</term>
1837 <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1838 příjemce</foreignphrase>. This is optional. Maximal length is 50
1839 characters.</para></listitem>
1843 <term><type>char *</type><structfield>dmSenderRefNumber</structfield>;</term>
1844 <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1845 odesílatele</foreignphrase>. This is optional. Maximal length is 50
1846 chars.</para></listitem>
1850 <term><type>char *</type><structfield>dmRecipientIdent</structfield>;</term>
1851 <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1852 příjemce</foreignphrase>. This is optional. Maximal length is 50
1853 characters.</para></listitem>
1857 <term><type>char *</type><structfield>dmSenderIdent</structfield>;</term>
1858 <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1859 odesílatele</foreignphrase> This is optional. Maximal length is 50
1860 chars.</para></listitem>
1864 <para>Following five members constitue a reference to an item from the
1865 Czech Act Collection. The human-readable reference looks
1866 like <phrase><emphasis>Point</emphasis>
1867 (<emphasis>Paragraph</emphasis>)
1868 § <emphasis>Section</emphasis>
1869 <emphasis>Law</emphasis>/<emphasis>Year</emphasis>
1870 Coll.</phrase> The memebers apply to both incoming and outgoing
1875 <term><type>long int *</type><structfield>dmLegalTitleLaw</structfield>;</term>
1876 <listitem><para>A number of an act mandating the
1877 authority.</para></listitem>
1881 <term><type>long int *</type><structfield>dmLegalTitleYear</structfield>;</term>
1882 <listitem><para>A year of issuing the act mandating the
1883 authority.</para></listitem>
1887 <term><type>char *</type><structfield>dmLegalTitleSect</structfield>;</term>
1888 <listitem><para>A section of the act mandating the authority.
1889 Czech: <foreignphrase
1890 lang="cs">paragraf</foreignphrase>.</para></listitem>
1894 <term><type>char *</type><structfield>dmLegalTitlePar</structfield>;</term>
1895 <listitem><para>A paragraph of the act mandating the authority.
1896 Czech: <foreignphrase
1897 lang="cs">odstavec</foreignphrase>.</para></listitem>
1901 <term><type>char *</type><structfield>dmLegalTitlePoint</structfield>;</term>
1902 <listitem><para>A point of the act mandating the authority. Czech:
1903 <foreignphrase lang="cs">písmeno</foreignphrase>.</para></listitem>
1907 <para>Other incoming/outgoing message members:</para>
1911 <term><type>_Bool *</type><structfield>dmPersonalDelivery</structfield>;</term>
1912 <listitem><para>If true, only person with higher privileges can
1913 read this message.</para></listitem>
1917 <term><type>_Bool *</type><structfield>dmAllowSubstDelivery</structfield>;</term>
1918 <listitem><para>Allow delivery through fiction.
1919 <abbrev>I.e.</abbrev> Even if the recipient did not read this
1920 message, the message is considered as delivered after
1921 (currently) 10 days. This is called <phrase>delivery through
1922 fiction</phrase>. Oonly OVM dbType sender can set
1923 it.</para></listitem>
1927 <term><type>char *</type><structfield>dmType</structfield>;</term>
1929 <para>Message type (commercial subtypes or government message).</para>
1931 <para>Input values (when sending the message):</para>
1935 <term><literal>"I"</literal></term>
1936 <listitem><para>A commercial message offering paying the
1937 response (<phrase>initiatory message</phrase>). It's
1939 <structfield>dmSenderRefNumber</structfield>
1940 member.</para></listitem>
1944 <term><literal>"K"</literal></term>
1945 <listitem><para>A commercial message paid by the sender.</para></listitem>
1949 <term><literal>"O"</literal></term>
1950 <listitem><para>A commercial response paid by the sender of
1951 a initiatory message. It's necessary to copy a value
1952 from the <structfield>dmSenderRefNumber</structfield> of
1953 the initiatory message to the
1954 <structfield>dmRecipientRefNumber</structfield> of this
1955 message.</para></listitem>
1959 <term><literal>"V"</literal></term>
1960 <listitem><para>A noncommercial government message. This is
1961 the default meaning if the value is undefined while
1962 sending a message.</para></listitem>
1966 <para>Output values (when retrieving the message):</para>
1970 <term><literal>"A"</literal></term>
1971 <listitem><para>This is a subsidized initiatory commercial
1972 message which can pay a response.</para></listitem>
1976 <term><literal>"B"</literal></term>
1977 <listitem><para>This is a subsidized initiatory commercial
1978 message which has already paid the
1979 response.</para></listitem>
1983 <term><literal>"C"</literal></term>
1984 <listitem><para>This is a subsidized initiatory commercial
1985 message where the response offer has
1986 expired.</para></listitem>
1990 <term><literal>"D"</literal></term>
1991 <listitem><para>This is an externally subsidized commercial
1992 messsage.</para></listitem>
1996 <term><literal>"E"</literal></term>
1997 <listitem><para>This is a commercial message prepaid by
1998 a stamp.</para></listitem>
2002 <term><literal>"G"</literal></term>
2003 <listitem><para>This is a commerical message paid by
2004 a sponsor.</para></listitem>
2008 <term><literal>"I"</literal></term>
2009 <listitem><para>See the input values.</para></listitem>
2013 <term><literal>"K"</literal></term>
2014 <listitem><para>See the input values.</para></listitem>
2018 <term><literal>"O"</literal></term>
2019 <listitem><para>See the input values.</para></listitem>
2023 <term><literal>"V"</literal></term>
2024 <listitem><para>See the input values.</para></listitem>
2028 <term><literal>"X"</literal></term>
2029 <listitem><para>This is an initiatory commercial message
2030 where the response offer has expired.</para></listitem>
2034 <term><literal>"Y"</literal></term>
2035 <listitem><para>This is an initiatory commercial message
2036 which has already paid the response.</para></listitem>
2040 <term><literal>"Z"</literal></term>
2041 <listitem><para>This is limitedly subsidized commercial message.</para></listitem>
2045 <para>Length of the value is exactly 1 UTF-8 character if
2046 defined. That means it's still zero-terminated character
2047 string.</para></listitem>
2051 <para>Following members apply to outgoing messages only:</para>
2055 <term><type>_Bool *</type><structfield>dmOVM</structfield>;</term>
2056 <listitem><para>OVM sending mode. Non-OVM dbType boxes that have
2057 dbEffectiveOVM equaled to true <emphasis>MUST</emphasis>
2058 select between true (OVM mode) and false (non-OVM mode).
2059 Otherwise the value is optional and the default value is
2060 true.</para></listitem>
2064 <term><type>_Bool *</type><structfield>dmPublishOwnID</structfield>;</term>
2065 <listitem><para>To allow to reveal sender's login name. The name
2066 will be available to the recipient through
2067 <function>isds_get_message_sender</function> function. The
2068 sender's box type and identifier will be always available.
2069 This feature exists because more users can have access to one
2070 box and the recipient could not tell who was the sender. This
2071 value is optional. Default value is false.</para></listitem>
2077 <title><type>isds_FileMetaType</type></title>
2078 <synopsis>typedef enum <type>isds_FileMetaType</type>;</synopsis>
2079 <para>Document type from point fo view of hierarchy of documents in
2080 a message. Known values are:</para>
2083 <term><constant>FILEMETATYPE_MAIN</constant></term>
2084 <listitem><para>Main document. There should be exactly one
2085 document of this type in a message.</para></listitem>
2089 <term><constant>FILEMETATYPE_ENCLOSURE</constant></term>
2090 <listitem><para>An appendix. If a message has more documents,
2091 generic-purpose documents other than the main one should have
2092 this type.</para></listitem>
2096 <term><constant>FILEMETATYPE_SIGNATURE</constant></term>
2097 <listitem><para>Digital signature. This document is a signature of
2098 another document in the message.</para></listitem>
2102 <term><constant>FILEMETATYPE_META</constant></term>
2103 <listitem><para><abbrev>XML</abbrev> document for
2104 <phrase>electronic document information system</phrase>,
2105 <foreignphrase lang="cs">elektronická spisová
2106 služba</foreignphrase> (<abbrev lang="cs">ESS</abbrev>) in
2107 Czech, purpose. </para></listitem>
2113 <title>struct <structname>isds_document</structname></title>
2114 <synopsis>struct <structname>isds_document</structname>;</synopsis>
2115 <para>A message document. Members are:</para>
2118 <term><type>_Bool</type> <structfield>is_xml</structfield>;</term>
2119 <listitem><para>True if the document is an <abbrev>ISDS</abbrev>
2120 <abbrev>XML</abbrev> document. False if the document is an
2121 <abbrev>ISDS</abbrev> binary document.</para></listitem>
2125 <term><type>xmlNodePtr</type> <structfield>xml_node_list</structfield>;</term>
2126 <listitem><para><abbrev>XML</abbrev> node-set presenting the
2127 <abbrev>XML</abbrev> document content. This is a pointer to
2128 first <abbrev>XML</abbrev> node of the <abbrev>XML</abbrev>
2129 representation of the message as stored in
2130 <structfield>xml</structfield> member of
2131 <type>isds_message</type> structure. Use
2132 <structfield>children</structfield> and
2133 <structfield>next</structfield> members to walk through the
2134 document. See <systemitem class="library">libxml2</systemitem>
2135 library documentation for more details. The
2136 <structfield>xml_node_list</structfield> will be
2137 <constant>NULL</constant> if the document is empty. It's valid
2138 only if the <structfield>is_xml</structfield> is
2139 true.</para></listitem>
2143 <term><type>void *</type><structfield>data</structfield>;</term>
2144 <listitem><para>A binary document content. The encoding and format
2145 depends on <structfield>dmMimeType</structfield> member value.
2146 This is valid only if the <structfield>is_xml</structfield> is
2147 false.</para></listitem>
2151 <term><type>size_t</type> <structfield>data_length</structfield>;</term>
2152 <listitem><para>Length of the <structfield>data</structfield>
2153 buffer in bytes. It's valid only if the
2154 <structfield>is_xml</structfield> is false.</para></listitem>
2158 <term><type>char *</type><structfield>dmMimeType</structfield>;</term>
2159 <listitem><para><abbrev>MIME</abbrev> type of document. This
2160 member is mandatory.</para></listitem>
2164 <term><type>isds_FileMetaType</type> <structfield>dmFileMetaType</structfield>;</term>
2165 <listitem><para>Document type to create document hierarchy inside
2166 a message.</para></listitem>
2170 <term><type>char *</type><structfield>dmFileGuid</structfield>;</term>
2171 <listitem><para>Message-local document identifier. It can be used
2172 as a key to refer to this document by
2173 <structfield>dmUpFileGuid</structfield> member from a different
2174 document. This is optional.</para></listitem>
2178 <term><type>char *</type><structfield>dmUpFileGuid</structfield>;</term>
2179 <listitem><para>A reference to upper document identifier stored in
2180 <structfield>dmFileGuid</structfield> member of different
2181 document. You can use
2182 <function>isds_find_document_by_id</function> function to
2183 locate the upper document. This value is
2184 optional.</para></listitem>
2188 <term><type>char *</type><structfield>dmFileDescr</structfield>;</term>
2189 <listitem><para>Document name (title). <abbrev>E.g.</abbrev>
2190 a file name. This value is mandatory.</para></listitem>
2194 <term><type>char *</type><structfield>dmFormat</structfield>;</term>
2195 <listitem><para>A reference to <abbrev>XML</abbrev> format
2196 definition that explains how to interpret the
2197 <abbrev>XML</abbrev> document. <abbrev>E.g.</abbrev>
2198 a <abbrev>URL</abbrev> to an <abbrev>XML</abbrev> schema. This
2199 value is optional.</para></listitem>
2205 <title>struct <structname>isds_box_state_period</structname></title>
2206 <synopsis>struct <structname>isds_box_state_period</structname>;</synopsis>
2207 <para>A box state valid in the time range. Members are:</para>
2210 <term><type>struct timeval *</type><structfield>from</structfield>;</term>
2211 <listitem><para>Time range beginning.</para></listitem>
2215 <term><type>struct timeval *</type><structfield>to</structfield>;</term>
2216 <listitem><para>Time range end.</para></listitem>
2220 <term><type>long int </type><structfield>dbState</structfield>;</term>
2221 <listitem><para>Box state. <constant>1</constant> means the box is
2222 accessible. Other values mean the box is inaccessible. You can
2223 use <type>isds_DbState</type> enum to identify some
2224 states.</para></listitem>
2233 <title>Functions</title>
2236 <listitem><funcsynopsis><funcprototype>
2237 <funcdef>const char *<function>isds_strerror</function></funcdef>
2238 <paramdef>const isds_error <parameter>error</parameter></paramdef>
2239 </funcprototype></funcsynopsis></listitem>
2241 <listitem><funcsynopsis><funcprototype>
2242 <funcdef>struct isds_ctx *<function>isds_ctx_create</function></funcdef>
2244 </funcprototype></funcsynopsis></listitem>
2249 <title>See Also</title>
2252 <simplelist type="inline">
2253 <member><citerefentry>
2254 <refentrytitle>libcurl</refentrytitle>
2255 <manvolnum>3</manvolnum>
2256 </citerefentry></member>
2257 <member><citerefentry>
2258 <refentrytitle>libisds</refentrytitle>
2259 <manvolnum>3</manvolnum>
2260 </citerefentry></member>
2261 <member><citerefentry>
2262 <refentrytitle>time.h</refentrytitle>
2263 <manvolnum>0p</manvolnum>
2264 </citerefentry></member>