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_FO</constant></term>
933 <listitem><para>Standard person.</para></listitem>
937 <para>Some interfaces refer to <emphasis>gross</emphasis> box type.
938 These are the shortest names of the identifiers. For example,
939 <literal>DBTYPE_OVM</literal> is a gross type for
940 <literal>DB_OVM_NOTAR</literal> or <literal>DBTYPE_OVM</literal>.
941 But not for <literal>DBTYPE_PO</literal>.</para>
945 <title><type>isds_DbState</type></title>
946 <synopsis>typedef enum <type>isds_DbState</type>;</synopsis>
947 <para>Box status from point of view of accessibility. Known
951 <term><constant>DBSTATE_ACCESSIBLE</constant></term>
952 <listitem><para>The box is accessible.</para></listitem>
956 <term><constant>DBSTATE_TEMP_UNACCESSIBLE</constant></term>
957 <listitem><para>The box is temporarily inaccessible (at the request of the user).</para></listitem>
961 <term><constant>DBSTATE_NOT_YET_ACCESSIBLE</constant></term>
962 <listitem><para>The box has not yet been activated.</para></listitem>
966 <term><constant>DBSTATE_PERM_UNACCESSIBLE</constant></term>
967 <listitem><para>The box is permanently inaccessible.</para></listitem>
971 <term><constant>DBSTATE_REMOVED</constant></term>
972 <listitem><para>The box has been removed.</para></listitem>
976 <term><constant>DBSTATE_TEMP_UNACCESSIBLE_LAW</constant></term>
977 <listitem><para>The box is temporarily inaccessible (because of the reasons enumerated in the law).</para></listitem>
983 <title><type>isds_priviledges</type></title>
984 <synopsis>typedef enum <type>isds_priviledges</type>;</synopsis>
985 <para>Distinct user permissions from point of view of <abbrev>ISDS</abbrev>.
986 Instances can be bitmaps of any of these distinct values. Distinct known
990 <term><constant>PRIVIL_READ_NON_PERSONAL</constant></term>
991 <listitem><para>The user can download and read messages with
992 <structfield>dmPersonalDelivery</structfield> equaled to
993 false.</para></listitem>
997 <term><constant>PRIVIL_READ_ALL</constant></term>
998 <listitem><para>The user can download and read messages with
999 <structfield>dmPersonalDelivery</structfield> equaled to
1000 true.</para></listitem>
1004 <term><constant>PRIVIL_CREATE_DM</constant></term>
1005 <listitem><para>The user can create and send messages, the user
1006 can download outgoing (sent) messages.</para></listitem>
1010 <term><constant>PRIVIL_VIEW_INFO</constant></term>
1011 <listitem><para>The user can list messages and read data about
1012 a message post and delivery.</para></listitem>
1016 <term><constant>PRIVIL_SEARCH_DB</constant></term>
1017 <listitem><para>The user can can search for
1018 boxes.</para></listitem>
1022 <term><constant>PRIVIL_OWNER_ADM</constant></term>
1023 <listitem><para>The user can administer his box (to add and remove
1024 permitted users and to modify theirs
1025 permissions.)</para></listitem>
1029 <term><constant>PRIVIL_READ_VAULT</constant></term>
1031 <para>The user can read messages stored in the long term storage.</para>
1032 <note><para>This permission is not used since 2012-05.</para></note>
1037 <term><constant>PRIVIL_ERASE_VAULT</constant></term>
1038 <listitem><para>The user can delete messages from the long term
1039 storage.</para></listitem>
1045 <title><type>isds_message_status</type></title>
1046 <synopsis>typedef enum <type>isds_message_status</type>;</synopsis>
1047 <para>Message status. Known values are:</para>
1050 <term><constant>MESSAGESTATE_SENT</constant></term>
1051 <listitem><para>The message has been put into
1052 <abbrev>ISDS</abbrev>.</para></listitem>
1056 <term><constant>MESSAGESTATE_STAMPED</constant></term>
1057 <listitem><para>Message was stamped by a time stamp
1058 authority.</para></listitem>
1062 <term><constant>MESSAGESTATE_INFECTED</constant></term>
1063 <listitem><para>The message included viruses. Infected documents
1064 have been removed from the message.</para></listitem>
1068 <term><constant>MESSAGESTATE_DELIVERED</constant></term>
1069 <listitem><para>The message was delivered.
1070 (<structfield>dmDeliveryTime</structfield> is
1071 populated.)</para></listitem>
1075 <term><constant>MESSAGESTATE_SUBSTITUTED</constant></term>
1076 <listitem><para>The message was delivered through fiction,
1077 <structfield>dmAcceptanceTime</structfield> is
1078 populated.</para></listitem>
1082 <term><constant>MESSAGESTATE_RECEIVED</constant></term>
1083 <listitem><para>The message was accepted (by user's log-in or
1084 user's explicit request).
1085 <structfield>dmAcceptanceTime</structfield> is
1086 populated.</para></listitem>
1090 <term><constant>MESSAGESTATE_READ</constant></term>
1091 <listitem><para>The message has been read by
1092 a user.</para></listitem>
1096 <term><constant>MESSAGESTATE_UNDELIVERABLE</constant></term>
1097 <listitem><para>The message could not been delivered.
1098 (<abbrev>E.g.</abbrev>The recipient's box has been made
1099 inaccessible meantime.)</para></listitem>
1103 <term><constant>MESSAGESTATE_REMOVED</constant></term>
1104 <listitem><para>The message's content was
1105 deleted.</para></listitem>
1109 <term><constant>MESSAGESTATE_IN_SAFE</constant></term>
1110 <listitem><para>The message is stored in the long term
1111 storage.</para></listitem>
1115 <para>The values can be combined into a bit mask for some functions.
1116 A special <constant>MESSAGESTATE_ANY</constant> macro denotes any of
1121 <title><type>isds_hash_algorithm</type></title>
1122 <synopsis>typedef enum <type>isds_hash_algorithm</type>;</synopsis>
1123 <para>Hash algorithm types. Known values are:</para>
1126 <term><constant>HASH_ALGORITHM_MD5</constant></term>
1127 <listitem><para><abbrev>MD5</abbrev>.</para></listitem>
1131 <term><constant>HASH_ALGORITHM_SHA_1</constant></term>
1132 <listitem><para><abbrev>SHA-1</abbrev>.</para></listitem>
1136 <term><constant>HASH_ALGORITHM_SHA_224</constant></term>
1137 <listitem><para><abbrev>SHA-224</abbrev>.</para></listitem>
1141 <term><constant>HASH_ALGORITHM_SHA_256</constant></term>
1142 <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1146 <term><constant>HASH_ALGORITHM_SHA_384</constant></term>
1147 <listitem><para><abbrev>SHA-384</abbrev>.</para></listitem>
1151 <term><constant>HASH_ALGORITHM_SHA_512</constant></term>
1152 <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1158 <title><type>isds_buffer_strategy</type></title>
1159 <synopsis>typedef enum <type>isds_buffer_strategy</type>;</synopsis>
1160 <para>Buffer storage strategy. This type defines how a function should
1161 embed application provided buffer into
1162 <structfield>raw</structfield> element of output structure. Known
1166 <term><constant>BUFFER_DONT_STORE</constant></term>
1167 <listitem><para>Don't fill <structfield>raw</structfield>
1168 member.</para></listitem>
1172 <term><constant>BUFFER_COPY</constant></term>
1173 <listitem><para>Copy buffer content into newly allocated
1174 <structfield>raw</structfield> member.</para></listitem>
1178 <term><constant>BUFFER_MOVE</constant></term>
1179 <listitem><para>Copy pointer. Leave deallocation to structure
1181 (<function>isds_*_free</function>()).</para></listitem>
1187 <title>struct <structname>isds_hash</structname></title>
1188 <synopsis>struct <structname>isds_hash</structname>;</synopsis>
1189 <para>This is a hash value storage. Members are:</para>
1192 <term><type>isds_hash_algorithm</type>
1193 <structfield>algorithm</structfield>;</term>
1194 <listitem><para>Hash algorithm.</para></listitem>
1198 <term><type>size_t</type> <structfield>length</structfield>;</term>
1199 <listitem><para>Hash value length in bytes.</para></listitem>
1203 <term><type>void *</type><structfield>value</structfield>;</term>
1204 <listitem><para>Hash value as a byte stream.</para></listitem>
1210 <title>struct <structname>isds_PersonName</structname></title>
1211 <synopsis>struct <structname>isds_PersonName</structname>;</synopsis>
1212 <para>Name of a person. Members are:</para>
1215 <term><type>char *</type><structfield>pnFirstName</structfield>;</term>
1216 <listitem><para>First name.</para></listitem>
1220 <term><type>char *</type><structfield>pnMiddleName</structfield>;</term>
1221 <listitem><para>Middle name.</para></listitem>
1225 <term><type>char *</type><structfield>pnLastName</structfield>;</term>
1226 <listitem><para>Current last name.</para></listitem>
1230 <term><type>char *</type><structfield>pnLastNameAtBirth</structfield>;</term>
1231 <listitem><para>Last name at birth.</para></listitem>
1237 <title>struct <structname>isds_BirthInfo</structname></title>
1238 <synopsis>struct <structname>isds_BirthInfo</structname>;</synopsis>
1239 <para>Date and place of a birth. Members are:</para>
1242 <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1243 <listitem><para>Date of birth in local time at the birth place.
1244 Only <structfield>tm_year</structfield>,
1245 <structfield>tm_mon</structfield> and
1246 <structfield>tm_mday</structfield> members of the <type>struct
1247 tm</type> carry sane value. Others are
1248 undefined.</para></listitem>
1252 <term><type>char *</type><structfield>biCity</structfield>;</term>
1253 <listitem><para>City where a person was born.</para></listitem>
1257 <term><type>char *</type><structfield>biCounty</structfield>;</term>
1258 <listitem><para>Region where a person was born. This is the kind
1259 of region that is called <foreignphrase
1260 lang="de">Bezirk</foreignphrase> in
1261 German and <foreignphrase lang="cs">okres</foreignphrase> in
1262 Czech.</para></listitem>
1266 <term><type>char *</type><structfield>biState</structfield>;</term>
1267 <listitem><para>State wher a person was born.</para></listitem>
1273 <title>struct <structname>isds_Address</structname></title>
1274 <synopsis>struct <structname>isds_Address</structname>;</synopsis>
1275 <para>Postal address. Members are:</para>
1278 <term><type>long int *</type><structfield>adCode</structfield>;</term>
1279 <listitem><para><abbrev>RUIN</abbrev> address code.</para></listitem>
1283 <term><type>char *</type><structfield>adCity</structfield>;</term>
1284 <listitem><para>City.</para></listitem>
1288 <term><type>char *</type><structfield>adDistrict</structfield>;</term>
1289 <listitem><para>Municipality part.</para></listitem>
1293 <term><type>char *</type><structfield>adStreet</structfield>;</term>
1294 <listitem><para>Street.</para></listitem>
1298 <term><type>char *</type><structfield>adNumberInStreet</structfield>;</term>
1299 <listitem><para>Identification of an entrance on the
1300 street. <foreignphrase lang="cs">Číslo
1301 orientační</foreignphrase> in Czech.</para></listitem>
1305 <term><type>char *</type><structfield>adNumberInMunicipality</structfield>;</term>
1306 <listitem><para>Identification of a building in the municipality.
1307 <foreignphrase lang="cs">Číslo popisné</foreignphrase> in
1308 Czech.</para></listitem>
1312 <term><type>char *</type><structfield>adZipCode</structfield>;</term>
1313 <listitem><para>Postal code for mail routing.</para></listitem>
1317 <term><type>char *</type><structfield>adState</structfield>;</term>
1318 <listitem><para>State.</para></listitem>
1324 <title>struct <structname>isds_DbOwnerInfo</structname></title>
1325 <synopsis>struct <structname>isds_DbOwnerInfo</structname>;</synopsis>
1326 <para>Data about a box and his owner. NULL pointer values mean
1327 undefined values. Members are:</para>
1330 <term><type>char *</type><structfield>dbID</structfield>;</term>
1331 <listitem><para>Box identifier. Specification limits the length to
1332 7 characters.</para></listitem>
1336 <term><type>isds_DbType *</type><structfield>dbType</structfield>;</term>
1337 <listitem><para>Box type.</para></listitem>
1341 <term><type>char *</type><structfield>ic</structfield>;</term>
1342 <listitem><para>Identifier of the owner.</para></listitem>
1346 <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1347 <listitem><para>Name of a person owning the box.</para></listitem>
1351 <term><type>char *</type><structfield>firmName</structfield>;</term>
1352 <listitem><para>Name of a firm owning the box.</para></listitem>
1356 <term><type>isds_BirthInfo *</type><structfield>birthInfo</structfield>;</term>
1357 <listitem><para>Birth details of the person.</para></listitem>
1361 <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1362 <listitem><para>Postal address of the owner.</para></listitem>
1366 <term><type>char *</type><structfield>nationality</structfield>;</term>
1367 <listitem><para>Nationality of the owner.</para></listitem>
1371 <term><type>char *</type><structfield>email</structfield>;</term>
1372 <listitem><para>E-mail addres of the owner.</para></listitem>
1376 <term><type>char *</type><structfield>telNumber</structfield>;</term>
1377 <listitem><para>Telephone number of the owner.</para></listitem>
1381 <term><type>char *</type><structfield>identifier</structfield>;</term>
1382 <listitem><para>External box identifier for data provider
1383 (<abbrev>OVM</abbrev>, <abbrev>PO</abbrev>, maybe
1384 <abbrev>PFO</abbrev> box types.) Specification limits the
1385 length to 20 characters.</para></listitem>
1389 <term><type>_Bool *</type><structfield>aifoIsds</structfield>;</term>
1390 <listitem><para>Reference to citizen registry exists.</para></listitem>
1394 <term><type>char *</type><structfield>registryCode</structfield>;</term>
1395 <listitem><para><abbrev>PFO</abbrev> external registry code.
1396 Specification limits the length to
1397 5 characters.</para></listitem>
1401 <term><type>long int *</type><structfield>dbState</structfield>;</term>
1403 <para>Box state. 1 means the box is active.</para>
1404 <note><para>The type is long int because specification declares it
1405 as <type>xsd:integer</type>.</para></note>
1406 <note><para>TODO: enum?</para></note></listitem>
1410 <term><type>_Bool *</type><structfield>dbEffectiveOVM</structfield>;</term>
1411 <listitem><para>The Box has <abbrev>OVM</abbrev> role (section 5a
1412 of the act).</para></listitem>
1416 <term><type>_Bool *</type><structfield>dbOpenAddressing</structfield>;</term>
1417 <listitem>This <para>non-<abbrev>OVM</abbrev> box is free to
1418 receive messages from anybody.</para></listitem>
1424 <title><type>isds_UserType</type></title>
1425 <synopsis>typedef enum <type>isds_UserType</type>;</synopsis>
1426 <para>User type. Known values are:</para>
1429 <term><constant>USERTYPE_PRIMARY</constant></term>
1430 <listitem><para>Owner of the box.</para></listitem>
1434 <term><constant>USERTYPE_ENTRUSTED</constant></term>
1435 <listitem><para>User with limited access to the box.</para></listitem>
1439 <term><constant>USERTYPE_ADMINISTRATOR</constant></term>
1440 <listitem><para>User who can manage
1441 <constant>USERTYPE_ENTRUSTED</constant>
1442 users.</para></listitem>
1446 <term><constant>USERTYPE_OFFICIAL</constant></term>
1447 <listitem><para>???</para></listitem>
1451 <term><constant>USERTYPE_OFFICIAL_CERT</constant></term>
1452 <listitem><para>???</para></listitem>
1456 <term><constant>USERTYPE_LIQUIDATOR</constant></term>
1457 <listitem><para>Company liquidator.</para></listitem>
1461 <term><constant>USERTYPE_RECEIVER</constant></term>
1462 <listitem><para>Company receiver.</para></listitem>
1466 <term><constant>USERTYPE_GUARDIAN</constant></term>
1467 <listitem><para>Legal guardian.</para></listitem>
1473 <title>struct <structname>isds_DbUserInfo</structname></title>
1474 <synopsis>struct <structname>isds_DbUserInfo</structname>;</synopsis>
1475 <para>Data about a user. NULL pointer values mean
1476 undefined values. Members are:</para>
1479 <term><type>char *</type><structfield>userID</structfield>;</term>
1480 <listitem><para>User identifier. Specification limits the length
1481 from 6 to 12 characters.</para></listitem>
1485 <term><type>isds_UserType *</type><structfield>userType</structfield>;</term>
1486 <listitem><para>User type.</para></listitem>
1490 <term><type>long int *</type><structfield>userPrivils</structfield>;</term>
1491 <listitem><para>Set of user permissions.</para></listitem>
1495 <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1496 <listitem><para>Name of the user.</para></listitem>
1500 <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1501 <listitem><para>Postal address of the user.</para></listitem>
1505 <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1506 <listitem><para>Date of birth in local time.
1507 Only <structfield>tm_year</structfield>,
1508 <structfield>tm_mon</structfield> and
1509 <structfield>tm_mday</structfield> members of the <type>struct
1510 tm</type> carry sane value. Others are
1511 undefined.</para></listitem>
1515 <term><type>char *</type><structfield>ic</structfield>;</term>
1516 <listitem><para>Identifier a supervising firm. Specification
1517 limits the length to 8 characters.</para></listitem>
1521 <term><type>char *</type><structfield>firmName</structfield>;</term>
1522 <listitem><para>Name of a supervising firm. Specification limits
1523 the length to 100 characters.</para></listitem>
1527 <term><type>char *</type><structfield>caStreet</structfield>;</term>
1528 <listitem><para>Contact address. Street and number.</para></listitem>
1532 <term><type>char *</type><structfield>caCity</structfield>;</term>
1533 <listitem><para>Czech city of the contact address.</para></listitem>
1537 <term><type>char *</type><structfield>caZipCode</structfield>;</term>
1538 <listitem><para>Postal code of the contact address.</para></listitem>
1542 <term><type>char *</type><structfield>caState</structfield>;</term>
1543 <listitem><para>Abbreviated country of contact address. This value
1544 is optional and implicit meaning is
1545 <constant>CZ</constant>.</para></listitem>
1549 <term><type>char *</type><structfield>aifo_ticket</structfield>;</term>
1550 <listitem><para>Reference to citizen registry. This value is
1551 optional.</para></listitem>
1557 <title><type>isds_event_type</type></title>
1558 <synopsis>typedef enum <type>isds_event_type</type>;</synopsis>
1559 <para>Message event type. Known values are:</para>
1562 <term><constant>EVENT_UKNOWN</constant></term>
1563 <listitem><para>Event uknown to this library.</para></listitem>
1567 <term><constant>EVENT_ACCEPTED_BY_RECIPIENT</constant></term>
1568 <listitem><para>Message has been delivered and accepted by
1569 recipient action.</para></listitem>
1573 <term><constant>EVENT_ACCEPTED_BY_FICTION</constant></term>
1574 <listitem><para>Message has been delivered, acceptance period
1575 timed out, the message is considered as
1576 accepted.</para></listitem>
1580 <term><constant>EVENT_UNDELIVERABLE</constant></term>
1581 <listitem><para>Recipient box was made inaccessible, thus the
1582 message is undeliverable.</para></listitem>
1586 <term><constant>EVENT_COMMERCIAL_ACCEPTED</constant></term>
1587 <listitem><para>Recipient confirmed acceptance of this commercial
1588 message.</para></listitem>
1592 <term><constant>EVENT_ENTERED_SYSTEM</constant></term>
1593 <listitem><para>The message entered the
1594 <abbrev>ISDS</abbrev>system, <abbrev>i.e.</abbrev> it has been
1595 just sent by a sender.</para></listitem>
1599 <term><constant>EVENT_DELIVERED</constant></term>
1600 <listitem><para>The message has been delivered into recipient's
1601 box.</para></listitem>
1605 <term><constant>EVENT_PRIMARY_LOGIN</constant></term>
1606 <listitem><para>Primary user logged into recipent's
1607 box.</para></listitem>
1611 <term><constant>EVENT_ENTRUSTED_LOGIN</constant></term>
1612 <listitem><para>Entrusted user with capability to read logged
1613 into recipient's box.</para></listitem>
1617 <term><constant>EVENT_SYSCERT_LOGIN</constant></term>
1618 <listitem><para>An application authenticated by
1619 <emphasis>system</emphasis> certificate logged into
1620 recipient's box.</para></listitem>
1626 <title>struct <structname>isds_event</structname></title>
1627 <synopsis>struct <structname>isds_event</structname>;</synopsis>
1628 <para>An event that happened in a message life. All members are
1629 optional. Members are:</para>
1632 <term><type>struct timeval *</type><structfield>time</structfield>;</term>
1633 <listitem><para>When the event occurred.</para></listitem>
1637 <term><type>isds_event_type *</type><structfield>type</structfield>;</term>
1638 <listitem><para>Type of the envent.</para></listitem>
1642 <term><type>charr *</type><structfield>description</structfield>;</term>
1643 <listitem><para>Human-readable event description generated by the
1644 <abbrev>ISDS</abbrev> system. (Very probably in Czech
1645 language).</para></listitem>
1651 <title>struct <structname>isds_envelope</structname></title>
1652 <synopsis>struct <structname>isds_envelope</structname>;</synopsis>
1653 <para>Message envelope. These are the metadata about a message. It
1654 does contain the message documents.</para>
1655 <para>Be ware that the string length constraints are forced only on
1656 output members transmitted to the <abbrev>ISDS</abbrev>. The other
1657 direction (downloading from the <abbrev>ISDS</abbrev>) can break
1658 these rules. It should not happen, but nobody knows how much
1659 incompatible new version of the <abbrev>ISDS</abbrev> protocol will
1660 be. This is the gold Internet rule: be strict on what you send, be
1661 tolerant on what you receive.</para>
1662 <para>Following members apply to incoming messages only:</para>
1665 <term><type>char *</type><structfield>dmID</structfield>;</term>
1666 <listitem><para>Message identifier. Maximal length is 20
1667 characters.</para></listitem>
1671 <term><type>char *</type><structfield>dbIDSender</structfield>;</term>
1672 <listitem><para>Box identifier of the sender. Special value
1673 <literal>aaaaaaa</literal> means the message was sent by the
1674 <abbrev>ISDS</abbrev> system. Not by another user. Maximal
1675 length is 7 characters.</para></listitem>
1679 <term><type>char *</type><structfield>dmSender</structfield>;</term>
1680 <listitem><para>Sender's name. Maximal length is 100
1681 characters.</para></listitem>
1685 <term><type>char *</type><structfield>dmSenderAddress</structfield>;</term>
1686 <listitem><para>Postal address of the sender. Maximal length is 100
1687 characters.</para></listitem>
1691 <term><type>long int *</type><structfield>dmSenderType</structfield>;</term>
1692 <listitem><para>Gross box type of the sender. You can use
1693 <type>isds_DbType</type> to enumarate some known box types.
1694 This is a generic integer because the protocol keeps the value
1695 unconstrained and the library must support any syntactically
1696 correct value.</para></listitem>
1700 <term><type>char *</type><structfield>dmRecipient</structfield>;</term>
1701 <listitem><para>Recipient's name. Maximal length is 100
1702 characters.</para></listitem>
1706 <term><type>char *</type><structfield>dmRecipientAddress</structfield>;</term>
1707 <listitem><para>Postal address of the recipient. Maximal length is
1708 100 characters.</para></listitem>
1712 <term><type>_Bool *</type><structfield>dmAmbiguousRecipient</structfield>;</term>
1713 <listitem><para>The recipient has <abbrev>OVM</abbrev> role.</para></listitem>
1717 <para>Following members are assigned by the <abbrev>ISDS</abbrev> in
1718 different phases of message life cycle:</para>
1721 <term><type>unsigned long int *</type><structfield>dmOrdinal</structfield>;</term>
1722 <listitem><para>Ordinal number in list of incoming/outgoing
1723 messages.</para></listitem>
1727 <term><type>isds_message_status *</type><structfield>dmMessageStatus</structfield>;</term>
1728 <listitem><para>Message state.</para></listitem>
1732 <term><type>long int *</type><structfield>dmAttachmentSize</structfield>;</term>
1733 <listitem><para>Size of message documents in kilobytes. The value
1734 is rounded.</para></listitem>
1738 <term><type>struct timeval *</type><structfield>dmDeliveryTime</structfield>;</term>
1739 <listitem><para>The time of delivering the message into recipient's
1740 box. It will be <constant>NULL</constant>, if the message has not
1741 been delivered yet.</para></listitem>
1745 <term><type>struct timeval *</type><structfield>dmAcceptanceTime</structfield>;</term>
1746 <listitem><para>The time of acceptancing the message by the
1747 recipient. It will be <constant>NULL</constant>, if message
1748 has not been accepted yet.</para></listitem>
1752 <term><type>struct isds_hash *</type><structfield>hash</structfield>;</term>
1753 <listitem><para>The message digest. This is a hash of a substring representing
1754 <literal>isds:dmDM</literal> <abbrev>XML</abbrev>
1755 subtree. You can use
1756 <function>isds_compute_message_hash</function> function to
1757 compute a hash of the message and then compare it against this
1758 structure member using <function>isds_hash_cmp</function>
1759 function.</para></listitem>
1763 <term><type>void *</type><structfield>timestamp</structfield>;</term>
1764 <listitem><para>This is a binary image of a qualified time stamp
1765 of the <structfield>hash</structfield> value. The time stamp
1766 is provided by the <abbrev>ISDS</abbrev> system. Messages that
1767 have not yet been stamped will have this value
1768 <constant>NULL</constant>.</para></listitem>
1772 <term><type>size_t</type> <structfield>timestamp_length</structfield>;</term>
1773 <listitem><para>Length of the <structfield>timestamp</structfield>
1774 value in bytes.</para></listitem>
1778 <term><type>struct isds_list *</type><structfield>events</structfield>;</term>
1779 <listitem><para>Events the message passed trough. It's a list of
1780 <type>isds_event</type> structures.</para></listitem>
1784 <para>Following members apply to both outgoing and incoming
1789 <term><type>char *</type><structfield>dmSenderOrgUnit</structfield>;</term>
1790 <listitem><para>Sender's organisation unit as a string. This is
1791 optional.</para></listitem>
1795 <term><type>long int *</type><structfield>dmSenderOrgUnitNum</structfield>;</term>
1796 <listitem><para>Sender's organisation unit as a number. This is
1797 optional.</para></listitem>
1801 <term><type>char *</type><structfield>dbIDRecipient</structfield>;</term>
1802 <listitem><para>Recipent's box identifier. This is mandatory.
1803 Maximal length is 7 characters.</para></listitem>
1807 <term><type>char *</type><structfield>dmRecipientOrgUnit</structfield>;</term>
1808 <listitem><para>Recipient's organisation unit as a string. This is
1809 optional.</para></listitem>
1813 <term><type>long int *</type><structfield>dmRecipientOrgUnitNum</structfield>;</term>
1814 <listitem><para>Recipent's organisation unit of as a number. This
1815 is optional.</para></listitem>
1819 <term><type>char *</type><structfield>dmToHands</structfield>;</term>
1820 <listitem><para>A person in recipient's organisation. This is
1821 optional.</para></listitem>
1825 <term><type>char *</type><structfield>dmAnnotation</structfield>;</term>
1826 <listitem><para>A subject (title) of the message. Maximal length
1827 is 255 characters.</para></listitem>
1831 <term><type>char *</type><structfield>dmRecipientRefNumber</structfield>;</term>
1832 <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1833 příjemce</foreignphrase>. This is optional. Maximal length is 50
1834 characters.</para></listitem>
1838 <term><type>char *</type><structfield>dmSenderRefNumber</structfield>;</term>
1839 <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1840 odesílatele</foreignphrase>. This is optional. Maximal length is 50
1841 chars.</para></listitem>
1845 <term><type>char *</type><structfield>dmRecipientIdent</structfield>;</term>
1846 <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1847 příjemce</foreignphrase>. This is optional. Maximal length is 50
1848 characters.</para></listitem>
1852 <term><type>char *</type><structfield>dmSenderIdent</structfield>;</term>
1853 <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1854 odesílatele</foreignphrase> This is optional. Maximal length is 50
1855 chars.</para></listitem>
1859 <para>Following five members constitue a reference to an item from the
1860 Czech Act Collection. The human-readable reference looks
1861 like <phrase><emphasis>Point</emphasis>
1862 (<emphasis>Paragraph</emphasis>)
1863 § <emphasis>Section</emphasis>
1864 <emphasis>Law</emphasis>/<emphasis>Year</emphasis>
1865 Coll.</phrase> The memebers apply to both incoming and outgoing
1870 <term><type>long int *</type><structfield>dmLegalTitleLaw</structfield>;</term>
1871 <listitem><para>A number of an act mandating the
1872 authority.</para></listitem>
1876 <term><type>long int *</type><structfield>dmLegalTitleYear</structfield>;</term>
1877 <listitem><para>A year of issuing the act mandating the
1878 authority.</para></listitem>
1882 <term><type>char *</type><structfield>dmLegalTitleSect</structfield>;</term>
1883 <listitem><para>A section of the act mandating the authority.
1884 Czech: <foreignphrase
1885 lang="cs">paragraf</foreignphrase>.</para></listitem>
1889 <term><type>char *</type><structfield>dmLegalTitlePar</structfield>;</term>
1890 <listitem><para>A paragraph of the act mandating the authority.
1891 Czech: <foreignphrase
1892 lang="cs">odstavec</foreignphrase>.</para></listitem>
1896 <term><type>char *</type><structfield>dmLegalTitlePoint</structfield>;</term>
1897 <listitem><para>A point of the act mandating the authority. Czech:
1898 <foreignphrase lang="cs">písmeno</foreignphrase>.</para></listitem>
1902 <para>Other incoming/outgoing message members:</para>
1906 <term><type>_Bool *</type><structfield>dmPersonalDelivery</structfield>;</term>
1907 <listitem><para>If true, only person with higher privileges can
1908 read this message.</para></listitem>
1912 <term><type>_Bool *</type><structfield>dmAllowSubstDelivery</structfield>;</term>
1913 <listitem><para>Allow delivery through fiction.
1914 <abbrev>I.e.</abbrev> Even if the recipient did not read this
1915 message, the message is considered as delivered after
1916 (currently) 10 days. This is called <phrase>delivery through
1917 fiction</phrase>. Oonly OVM dbType sender can set
1918 it.</para></listitem>
1922 <term><type>char *</type><structfield>dmType</structfield>;</term>
1924 <para>Message type (commercial subtypes or government message).</para>
1926 <para>Input values (when sending the message):</para>
1930 <term><literal>"I"</literal></term>
1931 <listitem><para>A commercial message offering paying the
1932 response (<phrase>initiatory message</phrase>). It's
1934 <structfield>dmSenderRefNumber</structfield>
1935 member.</para></listitem>
1939 <term><literal>"K"</literal></term>
1940 <listitem><para>A commercial message paid by the sender.</para></listitem>
1944 <term><literal>"O"</literal></term>
1945 <listitem><para>A commercial response paid by the sender of
1946 a initiatory message. It's necessary to copy a value
1947 from the <structfield>dmSenderRefNumber</structfield> of
1948 the initiatory message to the
1949 <structfield>dmRecipientRefNumber</structfield> of this
1950 message.</para></listitem>
1954 <term><literal>"V"</literal></term>
1955 <listitem><para>A noncommercial government message. This is
1956 the default meaning if the value is undefined while
1957 sending a message.</para></listitem>
1961 <para>Output values (when retrieving the message):</para>
1965 <term><literal>"A"</literal></term>
1966 <listitem><para>This is a subsidized initiatory commercial
1967 message which can pay a response.</para></listitem>
1971 <term><literal>"B"</literal></term>
1972 <listitem><para>This is a subsidized initiatory commercial
1973 message which has already paid the
1974 response.</para></listitem>
1978 <term><literal>"C"</literal></term>
1979 <listitem><para>This is a subsidized initiatory commercial
1980 message where the response offer has
1981 expired.</para></listitem>
1985 <term><literal>"D"</literal></term>
1986 <listitem><para>This is an externally subsidized commercial
1987 messsage.</para></listitem>
1991 <term><literal>"E"</literal></term>
1992 <listitem><para>This is a commercial message prepaid by
1993 a stamp.</para></listitem>
1997 <term><literal>"G"</literal></term>
1998 <listitem><para>This is a commerical message paid by
1999 a sponsor.</para></listitem>
2003 <term><literal>"I"</literal></term>
2004 <listitem><para>See the input values.</para></listitem>
2008 <term><literal>"K"</literal></term>
2009 <listitem><para>See the input values.</para></listitem>
2013 <term><literal>"O"</literal></term>
2014 <listitem><para>See the input values.</para></listitem>
2018 <term><literal>"V"</literal></term>
2019 <listitem><para>See the input values.</para></listitem>
2023 <term><literal>"X"</literal></term>
2024 <listitem><para>This is an initiatory commercial message
2025 where the response offer has expired.</para></listitem>
2029 <term><literal>"Y"</literal></term>
2030 <listitem><para>This is an initiatory commercial message
2031 which has already paid the response.</para></listitem>
2035 <term><literal>"Z"</literal></term>
2036 <listitem><para>This is limitedly subsidized commercial message.</para></listitem>
2040 <para>Length of the value is exactly 1 UTF-8 character if
2041 defined. That means it's still zero-terminated character
2042 string.</para></listitem>
2046 <para>Following members apply to outgoing messages only:</para>
2050 <term><type>_Bool *</type><structfield>dmOVM</structfield>;</term>
2051 <listitem><para>OVM sending mode. Non-OVM dbType boxes that have
2052 dbEffectiveOVM equaled to true <emphasis>MUST</emphasis>
2053 select between true (OVM mode) and false (non-OVM mode).
2054 Otherwise the value is optional and the default value is
2055 true.</para></listitem>
2059 <term><type>_Bool *</type><structfield>dmPublishOwnID</structfield>;</term>
2060 <listitem><para>To allow to reveal sender's login name. The name
2061 will be available to the recipient through
2062 <function>isds_get_message_sender</function> function. The
2063 sender's box type and identifier will be always available.
2064 This feature exists because more users can have access to one
2065 box and the recipient could not tell who was the sender. This
2066 value is optional. Default value is false.</para></listitem>
2072 <title><type>isds_FileMetaType</type></title>
2073 <synopsis>typedef enum <type>isds_FileMetaType</type>;</synopsis>
2074 <para>Document type from point fo view of hierarchy of documents in
2075 a message. Known values are:</para>
2078 <term><constant>FILEMETATYPE_MAIN</constant></term>
2079 <listitem><para>Main document. There should be exactly one
2080 document of this type in a message.</para></listitem>
2084 <term><constant>FILEMETATYPE_ENCLOSURE</constant></term>
2085 <listitem><para>An appendix. If a message has more documents,
2086 generic-purpose documents other than the main one should have
2087 this type.</para></listitem>
2091 <term><constant>FILEMETATYPE_SIGNATURE</constant></term>
2092 <listitem><para>Digital signature. This document is a signature of
2093 another document in the message.</para></listitem>
2097 <term><constant>FILEMETATYPE_META</constant></term>
2098 <listitem><para><abbrev>XML</abbrev> document for
2099 <phrase>electronic document information system</phrase>,
2100 <foreignphrase lang="cs">elektronická spisová
2101 služba</foreignphrase> (<abbrev lang="cs">ESS</abbrev>) in
2102 Czech, purpose. </para></listitem>
2108 <title>struct <structname>isds_document</structname></title>
2109 <synopsis>struct <structname>isds_document</structname>;</synopsis>
2110 <para>A message document. Members are:</para>
2113 <term><type>_Bool</type> <structfield>is_xml</structfield>;</term>
2114 <listitem><para>True if the document is an <abbrev>ISDS</abbrev>
2115 <abbrev>XML</abbrev> document. False if the document is an
2116 <abbrev>ISDS</abbrev> binary document.</para></listitem>
2120 <term><type>xmlNodePtr</type> <structfield>xml_node_list</structfield>;</term>
2121 <listitem><para><abbrev>XML</abbrev> node-set presenting the
2122 <abbrev>XML</abbrev> document content. This is a pointer to
2123 first <abbrev>XML</abbrev> node of the <abbrev>XML</abbrev>
2124 representation of the message as stored in
2125 <structfield>xml</structfield> member of
2126 <type>isds_message</type> structure. Use
2127 <structfield>children</structfield> and
2128 <structfield>next</structfield> members to walk through the
2129 document. See <systemitem class="library">libxml2</systemitem>
2130 library documentation for more details. The
2131 <structfield>xml_node_list</structfield> will be
2132 <constant>NULL</constant> if the document is empty. It's valid
2133 only if the <structfield>is_xml</structfield> is
2134 true.</para></listitem>
2138 <term><type>void *</type><structfield>data</structfield>;</term>
2139 <listitem><para>A binary document content. The encoding and format
2140 depends on <structfield>dmMimeType</structfield> member value.
2141 This is valid only if the <structfield>is_xml</structfield> is
2142 false.</para></listitem>
2146 <term><type>size_t</type> <structfield>data_length</structfield>;</term>
2147 <listitem><para>Length of the <structfield>data</structfield>
2148 buffer in bytes. It's valid only if the
2149 <structfield>is_xml</structfield> is false.</para></listitem>
2153 <term><type>char *</type><structfield>dmMimeType</structfield>;</term>
2154 <listitem><para><abbrev>MIME</abbrev> type of document. This
2155 member is mandatory.</para></listitem>
2159 <term><type>isds_FileMetaType</type> <structfield>dmFileMetaType</structfield>;</term>
2160 <listitem><para>Document type to create document hierarchy inside
2161 a message.</para></listitem>
2165 <term><type>char *</type><structfield>dmFileGuid</structfield>;</term>
2166 <listitem><para>Message-local document identifier. It can be used
2167 as a key to refer to this document by
2168 <structfield>dmUpFileGuid</structfield> member from a different
2169 document. This is optional.</para></listitem>
2173 <term><type>char *</type><structfield>dmUpFileGuid</structfield>;</term>
2174 <listitem><para>A reference to upper document identifier stored in
2175 <structfield>dmFileGuid</structfield> member of different
2176 document. You can use
2177 <function>isds_find_document_by_id</function> function to
2178 locate the upper document. This value is
2179 optional.</para></listitem>
2183 <term><type>char *</type><structfield>dmFileDescr</structfield>;</term>
2184 <listitem><para>Document name (title). <abbrev>E.g.</abbrev>
2185 a file name. This value is mandatory.</para></listitem>
2189 <term><type>char *</type><structfield>dmFormat</structfield>;</term>
2190 <listitem><para>A reference to <abbrev>XML</abbrev> format
2191 definition that explains how to interpret the
2192 <abbrev>XML</abbrev> document. <abbrev>E.g.</abbrev>
2193 a <abbrev>URL</abbrev> to an <abbrev>XML</abbrev> schema. This
2194 value is optional.</para></listitem>
2200 <title>struct <structname>isds_box_state_period</structname></title>
2201 <synopsis>struct <structname>isds_box_state_period</structname>;</synopsis>
2202 <para>A box state valid in the time range. Members are:</para>
2205 <term><type>struct timeval *</type><structfield>from</structfield>;</term>
2206 <listitem><para>Time range beginning.</para></listitem>
2210 <term><type>struct timeval *</type><structfield>to</structfield>;</term>
2211 <listitem><para>Time range end.</para></listitem>
2215 <term><type>long int </type><structfield>dbState</structfield>;</term>
2216 <listitem><para>Box state. <constant>1</constant> means the box is
2217 accessible. Other values mean the box is inaccessible. You can
2218 use <type>isds_DbState</type> enum to identify some
2219 states.</para></listitem>
2228 <title>Functions</title>
2231 <listitem><funcsynopsis><funcprototype>
2232 <funcdef>const char *<function>isds_strerror</function></funcdef>
2233 <paramdef>const isds_error <parameter>error</parameter></paramdef>
2234 </funcprototype></funcsynopsis></listitem>
2236 <listitem><funcsynopsis><funcprototype>
2237 <funcdef>struct isds_ctx *<function>isds_ctx_create</function></funcdef>
2239 </funcprototype></funcsynopsis></listitem>
2244 <title>See Also</title>
2247 <simplelist type="inline">
2248 <member><citerefentry>
2249 <refentrytitle>libcurl</refentrytitle>
2250 <manvolnum>3</manvolnum>
2251 </citerefentry></member>
2252 <member><citerefentry>
2253 <refentrytitle>libisds</refentrytitle>
2254 <manvolnum>3</manvolnum>
2255 </citerefentry></member>
2256 <member><citerefentry>
2257 <refentrytitle>time.h</refentrytitle>
2258 <manvolnum>0p</manvolnum>
2259 </citerefentry></member>