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 (stopped being used, replaced with
880 <abbrev>OVM_PFO</abbrev>).</para></listitem>
884 <term><constant>DBTYPE_OVM_EXEKUT</constant></term>
885 <listitem><para>Executor (stopped being used, replaced with
886 <abbrev>OVM_PFO</abbrev>).</para></listitem>
890 <term><constant>DBTYPE_OVM_REQ</constant></term>
891 <listitem><para>Subsidiary office with <abbrev>OVM</abbrev>
892 (governing) status assigned on request (section 6 and 7 of the
893 act).</para></listitem>
897 <term><constant>DBTYPE_OVM_FO</constant></term>
898 <listitem><para>Natural person with <abbrev>OVM</abbrev> status
899 (without identification number).</para></listitem>
903 <term><constant>DBTYPE_OVM_PFO</constant></term>
904 <listitem><para>Natural person in business with <abbrev>OVM</abbrev>
905 status (e.g. notary or executor).</para></listitem>
909 <term><constant>DBTYPE_OVM_PO</constant></term>
910 <listitem><para>Juridical person with <abbrev>OVM</abbrev> status
911 (arisen from previously existing <abbrev>PO</abbrev> or
912 <abbrev>PO_REQ</abbrev>).</para></listitem>
916 <term><constant>DBTYPE_PO</constant></term>
917 <listitem><para>Standard commercial organization (listed in trade
918 registry).</para></listitem>
922 <term><constant>DBTYPE_PO_ZAK</constant></term>
923 <listitem><para>Other organization founded by an act
924 (stopped being used, replaced with
925 <abbrev>PO</abbrev>).</para></listitem>
929 <term><constant>DBTYPE_PO_REQ</constant></term>
930 <listitem><para>An organization with a box assigned on its
931 request.</para></listitem>
935 <term><constant>DBTYPE_PFO</constant></term>
936 <listitem><para>Person in business.</para></listitem>
940 <term><constant>DBTYPE_PFO_ADVOK</constant></term>
941 <listitem><para>Lawyer.</para></listitem>
945 <term><constant>DBTYPE_PFO_DANPOR</constant></term>
946 <listitem><para>Tax consultant.</para></listitem>
950 <term><constant>DBTYPE_PFO_INSSPR</constant></term>
951 <listitem><para>Administrator of insolvency.</para></listitem>
955 <term><constant>DBTYPE_PFO_AUDITOR</constant></term>
956 <listitem><para>Statutory auditor.</para></listitem>
960 <term><constant>DBTYPE_FO</constant></term>
961 <listitem><para>Standard person.</para></listitem>
965 <para>Some interfaces refer to <emphasis>gross</emphasis> box type.
966 These are the shortest names of the identifiers. For example,
967 <literal>DBTYPE_OVM</literal> is a gross type for
968 <literal>DB_OVM_NOTAR</literal> or <literal>DBTYPE_OVM</literal>.
969 But not for <literal>DBTYPE_PO</literal>.</para>
973 <title><type>isds_DbState</type></title>
974 <synopsis>typedef enum <type>isds_DbState</type>;</synopsis>
975 <para>Box status from point of view of accessibility. Known
979 <term><constant>DBSTATE_ACCESSIBLE</constant></term>
980 <listitem><para>The box is accessible.</para></listitem>
984 <term><constant>DBSTATE_TEMP_UNACCESSIBLE</constant></term>
985 <listitem><para>The box is temporarily inaccessible (at the request of the user).</para></listitem>
989 <term><constant>DBSTATE_NOT_YET_ACCESSIBLE</constant></term>
990 <listitem><para>The box has not yet been activated.</para></listitem>
994 <term><constant>DBSTATE_PERM_UNACCESSIBLE</constant></term>
995 <listitem><para>The box is permanently inaccessible.</para></listitem>
999 <term><constant>DBSTATE_REMOVED</constant></term>
1000 <listitem><para>The box has been removed.</para></listitem>
1004 <term><constant>DBSTATE_TEMP_UNACCESSIBLE_LAW</constant></term>
1005 <listitem><para>The box is temporarily inaccessible (because of the reasons enumerated in the law).</para></listitem>
1011 <title><type>isds_priviledges</type></title>
1012 <synopsis>typedef enum <type>isds_priviledges</type>;</synopsis>
1013 <para>Distinct user permissions from point of view of <abbrev>ISDS</abbrev>.
1014 Instances can be bitmaps of any of these distinct values. Distinct known
1018 <term><constant>PRIVIL_READ_NON_PERSONAL</constant></term>
1019 <listitem><para>The user can download and read messages with
1020 <structfield>dmPersonalDelivery</structfield> equaled to
1021 false.</para></listitem>
1025 <term><constant>PRIVIL_READ_ALL</constant></term>
1026 <listitem><para>The user can download and read messages with
1027 <structfield>dmPersonalDelivery</structfield> equaled to
1028 true.</para></listitem>
1032 <term><constant>PRIVIL_CREATE_DM</constant></term>
1033 <listitem><para>The user can create and send messages, the user
1034 can download outgoing (sent) messages.</para></listitem>
1038 <term><constant>PRIVIL_VIEW_INFO</constant></term>
1039 <listitem><para>The user can list messages and read data about
1040 a message post and delivery.</para></listitem>
1044 <term><constant>PRIVIL_SEARCH_DB</constant></term>
1045 <listitem><para>The user can can search for
1046 boxes.</para></listitem>
1050 <term><constant>PRIVIL_OWNER_ADM</constant></term>
1051 <listitem><para>The user can administer his box (to add and remove
1052 permitted users and to modify theirs
1053 permissions.)</para></listitem>
1057 <term><constant>PRIVIL_READ_VAULT</constant></term>
1059 <para>The user can read messages stored in the long term storage.</para>
1060 <note><para>This permission is not used since 2012-05.</para></note>
1065 <term><constant>PRIVIL_ERASE_VAULT</constant></term>
1066 <listitem><para>The user can delete messages from the long term
1067 storage.</para></listitem>
1073 <title><type>isds_message_status</type></title>
1074 <synopsis>typedef enum <type>isds_message_status</type>;</synopsis>
1075 <para>Message status. Known values are:</para>
1078 <term><constant>MESSAGESTATE_SENT</constant></term>
1079 <listitem><para>The message has been put into
1080 <abbrev>ISDS</abbrev>.</para></listitem>
1084 <term><constant>MESSAGESTATE_STAMPED</constant></term>
1085 <listitem><para>Message was stamped by a time stamp
1086 authority.</para></listitem>
1090 <term><constant>MESSAGESTATE_INFECTED</constant></term>
1091 <listitem><para>The message included viruses. Infected documents
1092 have been removed from the message.</para></listitem>
1096 <term><constant>MESSAGESTATE_DELIVERED</constant></term>
1097 <listitem><para>The message was delivered.
1098 (<structfield>dmDeliveryTime</structfield> is
1099 populated.)</para></listitem>
1103 <term><constant>MESSAGESTATE_SUBSTITUTED</constant></term>
1104 <listitem><para>The message was delivered through fiction,
1105 <structfield>dmAcceptanceTime</structfield> is
1106 populated.</para></listitem>
1110 <term><constant>MESSAGESTATE_RECEIVED</constant></term>
1111 <listitem><para>The message was accepted (by user's log-in or
1112 user's explicit request).
1113 <structfield>dmAcceptanceTime</structfield> is
1114 populated.</para></listitem>
1118 <term><constant>MESSAGESTATE_READ</constant></term>
1119 <listitem><para>The message has been read by
1120 a user.</para></listitem>
1124 <term><constant>MESSAGESTATE_UNDELIVERABLE</constant></term>
1125 <listitem><para>The message could not been delivered.
1126 (<abbrev>E.g.</abbrev>The recipient's box has been made
1127 inaccessible meantime.)</para></listitem>
1131 <term><constant>MESSAGESTATE_REMOVED</constant></term>
1132 <listitem><para>The message's content was
1133 deleted.</para></listitem>
1137 <term><constant>MESSAGESTATE_IN_SAFE</constant></term>
1138 <listitem><para>The message is stored in the long term
1139 storage.</para></listitem>
1143 <para>The values can be combined into a bit mask for some functions.
1144 A special <constant>MESSAGESTATE_ANY</constant> macro denotes any of
1149 <title><type>isds_hash_algorithm</type></title>
1150 <synopsis>typedef enum <type>isds_hash_algorithm</type>;</synopsis>
1151 <para>Hash algorithm types. Known values are:</para>
1154 <term><constant>HASH_ALGORITHM_MD5</constant></term>
1155 <listitem><para><abbrev>MD5</abbrev>.</para></listitem>
1159 <term><constant>HASH_ALGORITHM_SHA_1</constant></term>
1160 <listitem><para><abbrev>SHA-1</abbrev>.</para></listitem>
1164 <term><constant>HASH_ALGORITHM_SHA_224</constant></term>
1165 <listitem><para><abbrev>SHA-224</abbrev>.</para></listitem>
1169 <term><constant>HASH_ALGORITHM_SHA_256</constant></term>
1170 <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1174 <term><constant>HASH_ALGORITHM_SHA_384</constant></term>
1175 <listitem><para><abbrev>SHA-384</abbrev>.</para></listitem>
1179 <term><constant>HASH_ALGORITHM_SHA_512</constant></term>
1180 <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1186 <title><type>isds_buffer_strategy</type></title>
1187 <synopsis>typedef enum <type>isds_buffer_strategy</type>;</synopsis>
1188 <para>Buffer storage strategy. This type defines how a function should
1189 embed application provided buffer into
1190 <structfield>raw</structfield> element of output structure. Known
1194 <term><constant>BUFFER_DONT_STORE</constant></term>
1195 <listitem><para>Don't fill <structfield>raw</structfield>
1196 member.</para></listitem>
1200 <term><constant>BUFFER_COPY</constant></term>
1201 <listitem><para>Copy buffer content into newly allocated
1202 <structfield>raw</structfield> member.</para></listitem>
1206 <term><constant>BUFFER_MOVE</constant></term>
1207 <listitem><para>Copy pointer. Leave deallocation to structure
1209 (<function>isds_*_free</function>()).</para></listitem>
1215 <title>struct <structname>isds_hash</structname></title>
1216 <synopsis>struct <structname>isds_hash</structname>;</synopsis>
1217 <para>This is a hash value storage. Members are:</para>
1220 <term><type>isds_hash_algorithm</type>
1221 <structfield>algorithm</structfield>;</term>
1222 <listitem><para>Hash algorithm.</para></listitem>
1226 <term><type>size_t</type> <structfield>length</structfield>;</term>
1227 <listitem><para>Hash value length in bytes.</para></listitem>
1231 <term><type>void *</type><structfield>value</structfield>;</term>
1232 <listitem><para>Hash value as a byte stream.</para></listitem>
1238 <title>struct <structname>isds_PersonName</structname></title>
1239 <synopsis>struct <structname>isds_PersonName</structname>;</synopsis>
1240 <para>Name of a person. Members are:</para>
1243 <term><type>char *</type><structfield>pnFirstName</structfield>;</term>
1244 <listitem><para>First name.</para></listitem>
1248 <term><type>char *</type><structfield>pnMiddleName</structfield>;</term>
1249 <listitem><para>Middle name.</para></listitem>
1253 <term><type>char *</type><structfield>pnLastName</structfield>;</term>
1254 <listitem><para>Current last name.</para></listitem>
1258 <term><type>char *</type><structfield>pnLastNameAtBirth</structfield>;</term>
1259 <listitem><para>Last name at birth.</para></listitem>
1265 <title>struct <structname>isds_BirthInfo</structname></title>
1266 <synopsis>struct <structname>isds_BirthInfo</structname>;</synopsis>
1267 <para>Date and place of a birth. Members are:</para>
1270 <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1271 <listitem><para>Date of birth in local time at the birth place.
1272 Only <structfield>tm_year</structfield>,
1273 <structfield>tm_mon</structfield> and
1274 <structfield>tm_mday</structfield> members of the <type>struct
1275 tm</type> carry sane value. Others are
1276 undefined.</para></listitem>
1280 <term><type>char *</type><structfield>biCity</structfield>;</term>
1281 <listitem><para>City where a person was born.</para></listitem>
1285 <term><type>char *</type><structfield>biCounty</structfield>;</term>
1286 <listitem><para>Region where a person was born. This is the kind
1287 of region that is called <foreignphrase
1288 lang="de">Bezirk</foreignphrase> in
1289 German and <foreignphrase lang="cs">okres</foreignphrase> in
1290 Czech.</para></listitem>
1294 <term><type>char *</type><structfield>biState</structfield>;</term>
1295 <listitem><para>State wher a person was born.</para></listitem>
1301 <title>struct <structname>isds_Address</structname></title>
1302 <synopsis>struct <structname>isds_Address</structname>;</synopsis>
1303 <para>Postal address. Members are:</para>
1306 <term><type>long int *</type><structfield>adCode</structfield>;</term>
1307 <listitem><para><abbrev>RUIN</abbrev> address code.</para></listitem>
1311 <term><type>char *</type><structfield>adCity</structfield>;</term>
1312 <listitem><para>City.</para></listitem>
1316 <term><type>char *</type><structfield>adDistrict</structfield>;</term>
1317 <listitem><para>Municipality part.</para></listitem>
1321 <term><type>char *</type><structfield>adStreet</structfield>;</term>
1322 <listitem><para>Street.</para></listitem>
1326 <term><type>char *</type><structfield>adNumberInStreet</structfield>;</term>
1327 <listitem><para>Identification of an entrance on the
1328 street. <foreignphrase lang="cs">Číslo
1329 orientační</foreignphrase> in Czech.</para></listitem>
1333 <term><type>char *</type><structfield>adNumberInMunicipality</structfield>;</term>
1334 <listitem><para>Identification of a building in the municipality.
1335 <foreignphrase lang="cs">Číslo popisné</foreignphrase> in
1336 Czech.</para></listitem>
1340 <term><type>char *</type><structfield>adZipCode</structfield>;</term>
1341 <listitem><para>Postal code for mail routing.</para></listitem>
1345 <term><type>char *</type><structfield>adState</structfield>;</term>
1346 <listitem><para>State.</para></listitem>
1352 <title>struct <structname>isds_DbOwnerInfo</structname></title>
1353 <synopsis>struct <structname>isds_DbOwnerInfo</structname>;</synopsis>
1354 <para>Data about a box and his owner. NULL pointer values mean
1355 undefined values. Members are:</para>
1358 <term><type>char *</type><structfield>dbID</structfield>;</term>
1359 <listitem><para>Box identifier. Specification limits the length to
1360 7 characters.</para></listitem>
1364 <term><type>isds_DbType *</type><structfield>dbType</structfield>;</term>
1365 <listitem><para>Box type.</para></listitem>
1369 <term><type>char *</type><structfield>ic</structfield>;</term>
1370 <listitem><para>Identifier of the owner.</para></listitem>
1374 <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1375 <listitem><para>Name of a person owning the box.</para></listitem>
1379 <term><type>char *</type><structfield>firmName</structfield>;</term>
1380 <listitem><para>Name of a firm owning the box.</para></listitem>
1384 <term><type>isds_BirthInfo *</type><structfield>birthInfo</structfield>;</term>
1385 <listitem><para>Birth details of the person.</para></listitem>
1389 <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1390 <listitem><para>Postal address of the owner.</para></listitem>
1394 <term><type>char *</type><structfield>nationality</structfield>;</term>
1395 <listitem><para>Nationality of the owner.</para></listitem>
1399 <term><type>char *</type><structfield>email</structfield>;</term>
1400 <listitem><para>E-mail addres of the owner.</para></listitem>
1404 <term><type>char *</type><structfield>telNumber</structfield>;</term>
1405 <listitem><para>Telephone number of the owner.</para></listitem>
1409 <term><type>char *</type><structfield>identifier</structfield>;</term>
1410 <listitem><para>External box identifier for data provider
1411 (<abbrev>OVM</abbrev>, <abbrev>PO</abbrev>, maybe
1412 <abbrev>PFO</abbrev> box types.) Specification limits the
1413 length to 20 characters.</para></listitem>
1417 <term><type>_Bool *</type><structfield>aifoIsds</structfield>;</term>
1418 <listitem><para>Reference to citizen registry exists.</para></listitem>
1422 <term><type>char *</type><structfield>registryCode</structfield>;</term>
1423 <listitem><para><abbrev>PFO</abbrev> external registry code.
1424 Specification limits the length to
1425 5 characters.</para></listitem>
1429 <term><type>long int *</type><structfield>dbState</structfield>;</term>
1431 <para>Box state. 1 means the box is active.</para>
1432 <note><para>The type is long int because specification declares it
1433 as <type>xsd:integer</type>.</para></note>
1434 <note><para>TODO: enum?</para></note></listitem>
1438 <term><type>_Bool *</type><structfield>dbEffectiveOVM</structfield>;</term>
1439 <listitem><para>The Box has <abbrev>OVM</abbrev> role (section 5a
1440 of the act).</para></listitem>
1444 <term><type>_Bool *</type><structfield>dbOpenAddressing</structfield>;</term>
1445 <listitem>This <para>non-<abbrev>OVM</abbrev> box is free to
1446 receive messages from anybody.</para></listitem>
1452 <title><type>isds_UserType</type></title>
1453 <synopsis>typedef enum <type>isds_UserType</type>;</synopsis>
1454 <para>User type. Known values are:</para>
1457 <term><constant>USERTYPE_PRIMARY</constant></term>
1458 <listitem><para>Owner of the box.</para></listitem>
1462 <term><constant>USERTYPE_ENTRUSTED</constant></term>
1463 <listitem><para>User with limited access to the box.</para></listitem>
1467 <term><constant>USERTYPE_ADMINISTRATOR</constant></term>
1468 <listitem><para>User who can manage
1469 <constant>USERTYPE_ENTRUSTED</constant>
1470 users.</para></listitem>
1474 <term><constant>USERTYPE_OFFICIAL</constant></term>
1475 <listitem><para>???</para></listitem>
1479 <term><constant>USERTYPE_OFFICIAL_CERT</constant></term>
1480 <listitem><para>???</para></listitem>
1484 <term><constant>USERTYPE_LIQUIDATOR</constant></term>
1485 <listitem><para>Company liquidator.</para></listitem>
1489 <term><constant>USERTYPE_RECEIVER</constant></term>
1490 <listitem><para>Company receiver.</para></listitem>
1494 <term><constant>USERTYPE_GUARDIAN</constant></term>
1495 <listitem><para>Legal guardian.</para></listitem>
1501 <title>struct <structname>isds_DbUserInfo</structname></title>
1502 <synopsis>struct <structname>isds_DbUserInfo</structname>;</synopsis>
1503 <para>Data about a user. NULL pointer values mean
1504 undefined values. Members are:</para>
1507 <term><type>char *</type><structfield>userID</structfield>;</term>
1508 <listitem><para>User identifier. Specification limits the length
1509 from 6 to 12 characters.</para></listitem>
1513 <term><type>isds_UserType *</type><structfield>userType</structfield>;</term>
1514 <listitem><para>User type.</para></listitem>
1518 <term><type>long int *</type><structfield>userPrivils</structfield>;</term>
1519 <listitem><para>Set of user permissions.</para></listitem>
1523 <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1524 <listitem><para>Name of the user.</para></listitem>
1528 <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1529 <listitem><para>Postal address of the user.</para></listitem>
1533 <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1534 <listitem><para>Date of birth in local time.
1535 Only <structfield>tm_year</structfield>,
1536 <structfield>tm_mon</structfield> and
1537 <structfield>tm_mday</structfield> members of the <type>struct
1538 tm</type> carry sane value. Others are
1539 undefined.</para></listitem>
1543 <term><type>char *</type><structfield>ic</structfield>;</term>
1544 <listitem><para>Identifier a supervising firm. Specification
1545 limits the length to 8 characters.</para></listitem>
1549 <term><type>char *</type><structfield>firmName</structfield>;</term>
1550 <listitem><para>Name of a supervising firm. Specification limits
1551 the length to 100 characters.</para></listitem>
1555 <term><type>char *</type><structfield>caStreet</structfield>;</term>
1556 <listitem><para>Contact address. Street and number.</para></listitem>
1560 <term><type>char *</type><structfield>caCity</structfield>;</term>
1561 <listitem><para>Czech city of the contact address.</para></listitem>
1565 <term><type>char *</type><structfield>caZipCode</structfield>;</term>
1566 <listitem><para>Postal code of the contact address.</para></listitem>
1570 <term><type>char *</type><structfield>caState</structfield>;</term>
1571 <listitem><para>Abbreviated country of contact address. This value
1572 is optional and implicit meaning is
1573 <constant>CZ</constant>.</para></listitem>
1577 <term><type>char *</type><structfield>aifo_ticket</structfield>;</term>
1578 <listitem><para>Reference to citizen registry. This value is
1579 optional.</para></listitem>
1585 <title><type>isds_event_type</type></title>
1586 <synopsis>typedef enum <type>isds_event_type</type>;</synopsis>
1587 <para>Message event type. Known values are:</para>
1590 <term><constant>EVENT_UKNOWN</constant></term>
1591 <listitem><para>Event uknown to this library.</para></listitem>
1595 <term><constant>EVENT_ACCEPTED_BY_RECIPIENT</constant></term>
1596 <listitem><para>Message has been delivered and accepted by
1597 recipient action.</para></listitem>
1601 <term><constant>EVENT_ACCEPTED_BY_FICTION</constant></term>
1602 <listitem><para>Message has been delivered, acceptance period
1603 timed out, the message is considered as
1604 accepted.</para></listitem>
1608 <term><constant>EVENT_UNDELIVERABLE</constant></term>
1609 <listitem><para>Recipient box was made inaccessible, thus the
1610 message is undeliverable.</para></listitem>
1614 <term><constant>EVENT_COMMERCIAL_ACCEPTED</constant></term>
1615 <listitem><para>Recipient confirmed acceptance of this commercial
1616 message.</para></listitem>
1620 <term><constant>EVENT_ENTERED_SYSTEM</constant></term>
1621 <listitem><para>The message entered the
1622 <abbrev>ISDS</abbrev>system, <abbrev>i.e.</abbrev> it has been
1623 just sent by a sender.</para></listitem>
1627 <term><constant>EVENT_DELIVERED</constant></term>
1628 <listitem><para>The message has been delivered into recipient's
1629 box.</para></listitem>
1633 <term><constant>EVENT_PRIMARY_LOGIN</constant></term>
1634 <listitem><para>Primary user logged into recipent's
1635 box.</para></listitem>
1639 <term><constant>EVENT_ENTRUSTED_LOGIN</constant></term>
1640 <listitem><para>Entrusted user with capability to read logged
1641 into recipient's box.</para></listitem>
1645 <term><constant>EVENT_SYSCERT_LOGIN</constant></term>
1646 <listitem><para>An application authenticated by
1647 <emphasis>system</emphasis> certificate logged into
1648 recipient's box.</para></listitem>
1654 <title>struct <structname>isds_event</structname></title>
1655 <synopsis>struct <structname>isds_event</structname>;</synopsis>
1656 <para>An event that happened in a message life. All members are
1657 optional. Members are:</para>
1660 <term><type>struct timeval *</type><structfield>time</structfield>;</term>
1661 <listitem><para>When the event occurred.</para></listitem>
1665 <term><type>isds_event_type *</type><structfield>type</structfield>;</term>
1666 <listitem><para>Type of the envent.</para></listitem>
1670 <term><type>charr *</type><structfield>description</structfield>;</term>
1671 <listitem><para>Human-readable event description generated by the
1672 <abbrev>ISDS</abbrev> system. (Very probably in Czech
1673 language).</para></listitem>
1679 <title>struct <structname>isds_envelope</structname></title>
1680 <synopsis>struct <structname>isds_envelope</structname>;</synopsis>
1681 <para>Message envelope. These are the metadata about a message. It
1682 does contain the message documents.</para>
1683 <para>Be ware that the string length constraints are forced only on
1684 output members transmitted to the <abbrev>ISDS</abbrev>. The other
1685 direction (downloading from the <abbrev>ISDS</abbrev>) can break
1686 these rules. It should not happen, but nobody knows how much
1687 incompatible new version of the <abbrev>ISDS</abbrev> protocol will
1688 be. This is the gold Internet rule: be strict on what you send, be
1689 tolerant on what you receive.</para>
1690 <para>Following members apply to incoming messages only:</para>
1693 <term><type>char *</type><structfield>dmID</structfield>;</term>
1694 <listitem><para>Message identifier. Maximal length is 20
1695 characters.</para></listitem>
1699 <term><type>char *</type><structfield>dbIDSender</structfield>;</term>
1700 <listitem><para>Box identifier of the sender. Special value
1701 <literal>aaaaaaa</literal> means the message was sent by the
1702 <abbrev>ISDS</abbrev> system. Not by another user. Maximal
1703 length is 7 characters.</para></listitem>
1707 <term><type>char *</type><structfield>dmSender</structfield>;</term>
1708 <listitem><para>Sender's name. Maximal length is 100
1709 characters.</para></listitem>
1713 <term><type>char *</type><structfield>dmSenderAddress</structfield>;</term>
1714 <listitem><para>Postal address of the sender. Maximal length is 100
1715 characters.</para></listitem>
1719 <term><type>long int *</type><structfield>dmSenderType</structfield>;</term>
1720 <listitem><para>Gross box type of the sender. You can use
1721 <type>isds_DbType</type> to enumarate some known box types.
1722 This is a generic integer because the protocol keeps the value
1723 unconstrained and the library must support any syntactically
1724 correct value.</para></listitem>
1728 <term><type>char *</type><structfield>dmRecipient</structfield>;</term>
1729 <listitem><para>Recipient's name. Maximal length is 100
1730 characters.</para></listitem>
1734 <term><type>char *</type><structfield>dmRecipientAddress</structfield>;</term>
1735 <listitem><para>Postal address of the recipient. Maximal length is
1736 100 characters.</para></listitem>
1740 <term><type>_Bool *</type><structfield>dmAmbiguousRecipient</structfield>;</term>
1741 <listitem><para>The recipient has <abbrev>OVM</abbrev> role.</para></listitem>
1745 <para>Following members are assigned by the <abbrev>ISDS</abbrev> in
1746 different phases of message life cycle:</para>
1749 <term><type>unsigned long int *</type><structfield>dmOrdinal</structfield>;</term>
1750 <listitem><para>Ordinal number in list of incoming/outgoing
1751 messages.</para></listitem>
1755 <term><type>isds_message_status *</type><structfield>dmMessageStatus</structfield>;</term>
1756 <listitem><para>Message state.</para></listitem>
1760 <term><type>long int *</type><structfield>dmAttachmentSize</structfield>;</term>
1761 <listitem><para>Size of message documents in kilobytes. The value
1762 is rounded.</para></listitem>
1766 <term><type>struct timeval *</type><structfield>dmDeliveryTime</structfield>;</term>
1767 <listitem><para>The time of delivering the message into recipient's
1768 box. It will be <constant>NULL</constant>, if the message has not
1769 been delivered yet.</para></listitem>
1773 <term><type>struct timeval *</type><structfield>dmAcceptanceTime</structfield>;</term>
1774 <listitem><para>The time of acceptancing the message by the
1775 recipient. It will be <constant>NULL</constant>, if message
1776 has not been accepted yet.</para></listitem>
1780 <term><type>struct isds_hash *</type><structfield>hash</structfield>;</term>
1781 <listitem><para>The message digest. This is a hash of a substring representing
1782 <literal>isds:dmDM</literal> <abbrev>XML</abbrev>
1783 subtree. You can use
1784 <function>isds_compute_message_hash</function> function to
1785 compute a hash of the message and then compare it against this
1786 structure member using <function>isds_hash_cmp</function>
1787 function.</para></listitem>
1791 <term><type>void *</type><structfield>timestamp</structfield>;</term>
1792 <listitem><para>This is a binary image of a qualified time stamp
1793 of the <structfield>hash</structfield> value. The time stamp
1794 is provided by the <abbrev>ISDS</abbrev> system. Messages that
1795 have not yet been stamped will have this value
1796 <constant>NULL</constant>.</para></listitem>
1800 <term><type>size_t</type> <structfield>timestamp_length</structfield>;</term>
1801 <listitem><para>Length of the <structfield>timestamp</structfield>
1802 value in bytes.</para></listitem>
1806 <term><type>struct isds_list *</type><structfield>events</structfield>;</term>
1807 <listitem><para>Events the message passed trough. It's a list of
1808 <type>isds_event</type> structures.</para></listitem>
1812 <para>Following members apply to both outgoing and incoming
1817 <term><type>char *</type><structfield>dmSenderOrgUnit</structfield>;</term>
1818 <listitem><para>Sender's organisation unit as a string. This is
1819 optional.</para></listitem>
1823 <term><type>long int *</type><structfield>dmSenderOrgUnitNum</structfield>;</term>
1824 <listitem><para>Sender's organisation unit as a number. This is
1825 optional.</para></listitem>
1829 <term><type>char *</type><structfield>dbIDRecipient</structfield>;</term>
1830 <listitem><para>Recipent's box identifier. This is mandatory.
1831 Maximal length is 7 characters.</para></listitem>
1835 <term><type>char *</type><structfield>dmRecipientOrgUnit</structfield>;</term>
1836 <listitem><para>Recipient's organisation unit as a string. This is
1837 optional.</para></listitem>
1841 <term><type>long int *</type><structfield>dmRecipientOrgUnitNum</structfield>;</term>
1842 <listitem><para>Recipent's organisation unit of as a number. This
1843 is optional.</para></listitem>
1847 <term><type>char *</type><structfield>dmToHands</structfield>;</term>
1848 <listitem><para>A person in recipient's organisation. This is
1849 optional.</para></listitem>
1853 <term><type>char *</type><structfield>dmAnnotation</structfield>;</term>
1854 <listitem><para>A subject (title) of the message. Maximal length
1855 is 255 characters.</para></listitem>
1859 <term><type>char *</type><structfield>dmRecipientRefNumber</structfield>;</term>
1860 <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1861 příjemce</foreignphrase>. This is optional. Maximal length is 50
1862 characters.</para></listitem>
1866 <term><type>char *</type><structfield>dmSenderRefNumber</structfield>;</term>
1867 <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1868 odesílatele</foreignphrase>. This is optional. Maximal length is 50
1869 chars.</para></listitem>
1873 <term><type>char *</type><structfield>dmRecipientIdent</structfield>;</term>
1874 <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1875 příjemce</foreignphrase>. This is optional. Maximal length is 50
1876 characters.</para></listitem>
1880 <term><type>char *</type><structfield>dmSenderIdent</structfield>;</term>
1881 <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1882 odesílatele</foreignphrase> This is optional. Maximal length is 50
1883 chars.</para></listitem>
1887 <para>Following five members constitue a reference to an item from the
1888 Czech Act Collection. The human-readable reference looks
1889 like <phrase><emphasis>Point</emphasis>
1890 (<emphasis>Paragraph</emphasis>)
1891 § <emphasis>Section</emphasis>
1892 <emphasis>Law</emphasis>/<emphasis>Year</emphasis>
1893 Coll.</phrase> The memebers apply to both incoming and outgoing
1898 <term><type>long int *</type><structfield>dmLegalTitleLaw</structfield>;</term>
1899 <listitem><para>A number of an act mandating the
1900 authority.</para></listitem>
1904 <term><type>long int *</type><structfield>dmLegalTitleYear</structfield>;</term>
1905 <listitem><para>A year of issuing the act mandating the
1906 authority.</para></listitem>
1910 <term><type>char *</type><structfield>dmLegalTitleSect</structfield>;</term>
1911 <listitem><para>A section of the act mandating the authority.
1912 Czech: <foreignphrase
1913 lang="cs">paragraf</foreignphrase>.</para></listitem>
1917 <term><type>char *</type><structfield>dmLegalTitlePar</structfield>;</term>
1918 <listitem><para>A paragraph of the act mandating the authority.
1919 Czech: <foreignphrase
1920 lang="cs">odstavec</foreignphrase>.</para></listitem>
1924 <term><type>char *</type><structfield>dmLegalTitlePoint</structfield>;</term>
1925 <listitem><para>A point of the act mandating the authority. Czech:
1926 <foreignphrase lang="cs">písmeno</foreignphrase>.</para></listitem>
1930 <para>Other incoming/outgoing message members:</para>
1934 <term><type>_Bool *</type><structfield>dmPersonalDelivery</structfield>;</term>
1935 <listitem><para>If true, only person with higher privileges can
1936 read this message.</para></listitem>
1940 <term><type>_Bool *</type><structfield>dmAllowSubstDelivery</structfield>;</term>
1941 <listitem><para>Allow delivery through fiction.
1942 <abbrev>I.e.</abbrev> Even if the recipient did not read this
1943 message, the message is considered as delivered after
1944 (currently) 10 days. This is called <phrase>delivery through
1945 fiction</phrase>. Oonly OVM dbType sender can set
1946 it.</para></listitem>
1950 <term><type>char *</type><structfield>dmType</structfield>;</term>
1952 <para>Message type (commercial subtypes or government message).</para>
1954 <para>Input values (when sending the message):</para>
1958 <term><literal>"I"</literal></term>
1959 <listitem><para>A commercial message offering paying the
1960 response (<phrase>initiatory message</phrase>). It's
1962 <structfield>dmSenderRefNumber</structfield>
1963 member.</para></listitem>
1967 <term><literal>"K"</literal></term>
1968 <listitem><para>A commercial message paid by the sender.</para></listitem>
1972 <term><literal>"O"</literal></term>
1973 <listitem><para>A commercial response paid by the sender of
1974 a initiatory message. It's necessary to copy a value
1975 from the <structfield>dmSenderRefNumber</structfield> of
1976 the initiatory message to the
1977 <structfield>dmRecipientRefNumber</structfield> of this
1978 message.</para></listitem>
1982 <term><literal>"V"</literal></term>
1983 <listitem><para>A noncommercial government message. This is
1984 the default meaning if the value is undefined while
1985 sending a message.</para></listitem>
1989 <para>Output values (when retrieving the message):</para>
1993 <term><literal>"A"</literal></term>
1994 <listitem><para>This is a subsidized initiatory commercial
1995 message which can pay a response.</para></listitem>
1999 <term><literal>"B"</literal></term>
2000 <listitem><para>This is a subsidized initiatory commercial
2001 message which has already paid the
2002 response.</para></listitem>
2006 <term><literal>"C"</literal></term>
2007 <listitem><para>This is a subsidized initiatory commercial
2008 message where the response offer has
2009 expired.</para></listitem>
2013 <term><literal>"D"</literal></term>
2014 <listitem><para>This is an externally subsidized commercial
2015 messsage.</para></listitem>
2019 <term><literal>"E"</literal></term>
2020 <listitem><para>This is a commercial message prepaid by
2021 a stamp.</para></listitem>
2025 <term><literal>"G"</literal></term>
2026 <listitem><para>This is a commerical message paid by
2027 a sponsor.</para></listitem>
2031 <term><literal>"I"</literal></term>
2032 <listitem><para>See the input values.</para></listitem>
2036 <term><literal>"K"</literal></term>
2037 <listitem><para>See the input values.</para></listitem>
2041 <term><literal>"O"</literal></term>
2042 <listitem><para>See the input values.</para></listitem>
2046 <term><literal>"V"</literal></term>
2047 <listitem><para>See the input values.</para></listitem>
2051 <term><literal>"X"</literal></term>
2052 <listitem><para>This is an initiatory commercial message
2053 where the response offer has expired.</para></listitem>
2057 <term><literal>"Y"</literal></term>
2058 <listitem><para>This is an initiatory commercial message
2059 which has already paid the response.</para></listitem>
2063 <term><literal>"Z"</literal></term>
2064 <listitem><para>This is limitedly subsidized commercial message.</para></listitem>
2068 <para>Length of the value is exactly 1 UTF-8 character if
2069 defined. That means it's still zero-terminated character
2070 string.</para></listitem>
2074 <para>Following members apply to outgoing messages only:</para>
2078 <term><type>_Bool *</type><structfield>dmOVM</structfield>;</term>
2079 <listitem><para>OVM sending mode. Non-OVM dbType boxes that have
2080 dbEffectiveOVM equaled to true <emphasis>MUST</emphasis>
2081 select between true (OVM mode) and false (non-OVM mode).
2082 Otherwise the value is optional and the default value is
2083 true.</para></listitem>
2087 <term><type>_Bool *</type><structfield>dmPublishOwnID</structfield>;</term>
2088 <listitem><para>To allow to reveal sender's login name. The name
2089 will be available to the recipient through
2090 <function>isds_get_message_sender</function> function. The
2091 sender's box type and identifier will be always available.
2092 This feature exists because more users can have access to one
2093 box and the recipient could not tell who was the sender. This
2094 value is optional. Default value is false.</para></listitem>
2100 <title><type>isds_FileMetaType</type></title>
2101 <synopsis>typedef enum <type>isds_FileMetaType</type>;</synopsis>
2102 <para>Document type from point fo view of hierarchy of documents in
2103 a message. Known values are:</para>
2106 <term><constant>FILEMETATYPE_MAIN</constant></term>
2107 <listitem><para>Main document. There should be exactly one
2108 document of this type in a message.</para></listitem>
2112 <term><constant>FILEMETATYPE_ENCLOSURE</constant></term>
2113 <listitem><para>An appendix. If a message has more documents,
2114 generic-purpose documents other than the main one should have
2115 this type.</para></listitem>
2119 <term><constant>FILEMETATYPE_SIGNATURE</constant></term>
2120 <listitem><para>Digital signature. This document is a signature of
2121 another document in the message.</para></listitem>
2125 <term><constant>FILEMETATYPE_META</constant></term>
2126 <listitem><para><abbrev>XML</abbrev> document for
2127 <phrase>electronic document information system</phrase>,
2128 <foreignphrase lang="cs">elektronická spisová
2129 služba</foreignphrase> (<abbrev lang="cs">ESS</abbrev>) in
2130 Czech, purpose. </para></listitem>
2136 <title>struct <structname>isds_document</structname></title>
2137 <synopsis>struct <structname>isds_document</structname>;</synopsis>
2138 <para>A message document. Members are:</para>
2141 <term><type>_Bool</type> <structfield>is_xml</structfield>;</term>
2142 <listitem><para>True if the document is an <abbrev>ISDS</abbrev>
2143 <abbrev>XML</abbrev> document. False if the document is an
2144 <abbrev>ISDS</abbrev> binary document.</para></listitem>
2148 <term><type>xmlNodePtr</type> <structfield>xml_node_list</structfield>;</term>
2149 <listitem><para><abbrev>XML</abbrev> node-set presenting the
2150 <abbrev>XML</abbrev> document content. This is a pointer to
2151 first <abbrev>XML</abbrev> node of the <abbrev>XML</abbrev>
2152 representation of the message as stored in
2153 <structfield>xml</structfield> member of
2154 <type>isds_message</type> structure. Use
2155 <structfield>children</structfield> and
2156 <structfield>next</structfield> members to walk through the
2157 document. See <systemitem class="library">libxml2</systemitem>
2158 library documentation for more details. The
2159 <structfield>xml_node_list</structfield> will be
2160 <constant>NULL</constant> if the document is empty. It's valid
2161 only if the <structfield>is_xml</structfield> is
2162 true.</para></listitem>
2166 <term><type>void *</type><structfield>data</structfield>;</term>
2167 <listitem><para>A binary document content. The encoding and format
2168 depends on <structfield>dmMimeType</structfield> member value.
2169 This is valid only if the <structfield>is_xml</structfield> is
2170 false.</para></listitem>
2174 <term><type>size_t</type> <structfield>data_length</structfield>;</term>
2175 <listitem><para>Length of the <structfield>data</structfield>
2176 buffer in bytes. It's valid only if the
2177 <structfield>is_xml</structfield> is false.</para></listitem>
2181 <term><type>char *</type><structfield>dmMimeType</structfield>;</term>
2182 <listitem><para><abbrev>MIME</abbrev> type of document. This
2183 member is mandatory.</para></listitem>
2187 <term><type>isds_FileMetaType</type> <structfield>dmFileMetaType</structfield>;</term>
2188 <listitem><para>Document type to create document hierarchy inside
2189 a message.</para></listitem>
2193 <term><type>char *</type><structfield>dmFileGuid</structfield>;</term>
2194 <listitem><para>Message-local document identifier. It can be used
2195 as a key to refer to this document by
2196 <structfield>dmUpFileGuid</structfield> member from a different
2197 document. This is optional.</para></listitem>
2201 <term><type>char *</type><structfield>dmUpFileGuid</structfield>;</term>
2202 <listitem><para>A reference to upper document identifier stored in
2203 <structfield>dmFileGuid</structfield> member of different
2204 document. You can use
2205 <function>isds_find_document_by_id</function> function to
2206 locate the upper document. This value is
2207 optional.</para></listitem>
2211 <term><type>char *</type><structfield>dmFileDescr</structfield>;</term>
2212 <listitem><para>Document name (title). <abbrev>E.g.</abbrev>
2213 a file name. This value is mandatory.</para></listitem>
2217 <term><type>char *</type><structfield>dmFormat</structfield>;</term>
2218 <listitem><para>A reference to <abbrev>XML</abbrev> format
2219 definition that explains how to interpret the
2220 <abbrev>XML</abbrev> document. <abbrev>E.g.</abbrev>
2221 a <abbrev>URL</abbrev> to an <abbrev>XML</abbrev> schema. This
2222 value is optional.</para></listitem>
2228 <title>struct <structname>isds_box_state_period</structname></title>
2229 <synopsis>struct <structname>isds_box_state_period</structname>;</synopsis>
2230 <para>A box state valid in the time range. Members are:</para>
2233 <term><type>struct timeval *</type><structfield>from</structfield>;</term>
2234 <listitem><para>Time range beginning.</para></listitem>
2238 <term><type>struct timeval *</type><structfield>to</structfield>;</term>
2239 <listitem><para>Time range end.</para></listitem>
2243 <term><type>long int </type><structfield>dbState</structfield>;</term>
2244 <listitem><para>Box state. <constant>1</constant> means the box is
2245 accessible. Other values mean the box is inaccessible. You can
2246 use <type>isds_DbState</type> enum to identify some
2247 states.</para></listitem>
2256 <title>Functions</title>
2259 <listitem><funcsynopsis><funcprototype>
2260 <funcdef>const char *<function>isds_strerror</function></funcdef>
2261 <paramdef>const isds_error <parameter>error</parameter></paramdef>
2262 </funcprototype></funcsynopsis></listitem>
2264 <listitem><funcsynopsis><funcprototype>
2265 <funcdef>struct isds_ctx *<function>isds_ctx_create</function></funcdef>
2267 </funcprototype></funcsynopsis></listitem>
2272 <title>See Also</title>
2275 <simplelist type="inline">
2276 <member><citerefentry>
2277 <refentrytitle>libcurl</refentrytitle>
2278 <manvolnum>3</manvolnum>
2279 </citerefentry></member>
2280 <member><citerefentry>
2281 <refentrytitle>libisds</refentrytitle>
2282 <manvolnum>3</manvolnum>
2283 </citerefentry></member>
2284 <member><citerefentry>
2285 <refentrytitle>time.h</refentrytitle>
2286 <manvolnum>0p</manvolnum>
2287 </citerefentry></member>