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> (<phrase lang="cs">Informační systém datových
63 schránek</phrase> / 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 <phrase lang="cs">Provozní řád</phrase> that can be downloaded from
68 <ulink url="https://www.datoveschranky.info/ke-stazeni"><phrase
69 lang="cs">Dokumenty ke stažení</phrase> 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 classify box owner by his legal status. Known
856 <term><constant>DBTYPE_SYSTEM</constant></term>
857 <listitem><para>This is a special value for sender of messages sent
858 by the <abbrev>ISDS</abbrev>. You can find it only in
859 incomming messages. It's not accepted by any other
860 <abbrev>services</abbrev>.</para></listitem>
864 <term><constant>DBTYPE_OVM</constant></term>
865 <listitem><para>Standard government (state or municipality or
866 similar) office.</para></listitem>
870 <term><constant>DBTYPE_OVM_NOTAR</constant></term>
871 <listitem><para>Notary.</para></listitem>
875 <term><constant>DBTYPE_OVM_EXEKUT</constant></term>
876 <listitem><para>Executor.</para></listitem>
880 <term><constant>DBTYPE_OVM_REQ</constant></term>
881 <listitem><para>Subsidiary office with <abbrev>OVM</abbrev>
882 (governing) status assigned on request (section 6 and 7 of the
883 act).</para></listitem>
887 <term><constant>DBTYPE_PO</constant></term>
888 <listitem><para>Standard commercial organization (listed in trade
889 registry).</para></listitem>
893 <term><constant>DBTYPE_PO_ZAK</constant></term>
894 <listitem><para>Other organization founded by an act.</para></listitem>
898 <term><constant>DBTYPE_PO_REQ</constant></term>
899 <listitem><para>An organization with a box assigned on its
900 request.</para></listitem>
904 <term><constant>DBTYPE_PFO</constant></term>
905 <listitem><para>Person in bussiness.</para></listitem>
909 <term><constant>DBTYPE_PFO_ADVOK</constant></term>
910 <listitem><para>Lawyer.</para></listitem>
914 <term><constant>DBTYPE_PFO_DANPOR</constant></term>
915 <listitem><para>Tax consultant.</para></listitem>
919 <term><constant>DBTYPE_PFO_INSSPR</constant></term>
920 <listitem><para>Administrator of insolvency.</para></listitem>
924 <term><constant>DBTYPE_FO</constant></term>
925 <listitem><para>Standard person.</para></listitem>
931 <title><type>isds_DbState</type></title>
932 <synopsis>typedef enum <type>isds_DbState</type>;</synopsis>
933 <para>Box status from point of view of accessibility. Known
937 <term><constant>DBSTATE_ACCESSIBLE</constant></term>
938 <listitem><para>The box is accessible.</para></listitem>
942 <term><constant>DBSTATE_TEMP_UNACCESSIBLE</constant></term>
943 <listitem><para>The box is temporarily inaccessible.</para></listitem>
947 <term><constant>DBSTATE_NOT_YET_ACCESSIBLE</constant></term>
948 <listitem><para>The box has not yet been activated.</para></listitem>
952 <term><constant>DBSTATE_PERM_UNACCESSIBLE</constant></term>
953 <listitem><para>The box is permanently inaccessible.</para></listitem>
957 <term><constant>DBSTATE_REMOVED</constant></term>
958 <listitem><para>The box has been removed.</para></listitem>
964 <title><type>isds_priviledges</type></title>
965 <synopsis>typedef enum <type>isds_priviledges</type>;</synopsis>
966 <para>Distinct user permissions from point of view of <abbrev>ISDS</abbrev>.
967 Instances can be bitmaps of any of these distinct values. Distinct known
971 <term><constant>PRIVIL_READ_NON_PERSONAL</constant></term>
972 <listitem><para>The user can download and read messages with
973 <structfield>dmPersonalDelivery</structfield> equaled to
974 false.</para></listitem>
978 <term><constant>PRIVIL_READ_ALL</constant></term>
979 <listitem><para>The user can download and read messages with
980 <structfield>dmPersonalDelivery</structfield> equaled to
981 true.</para></listitem>
985 <term><constant>PRIVIL_CREATE_DM</constant></term>
986 <listitem><para>The user can create and send messages, the user
987 can download outgoing (sent) messages.</para></listitem>
991 <term><constant>PRIVIL_VIEW_INFO</constant></term>
992 <listitem><para>The user can list messages and read data about
993 a message post and delivery.</para></listitem>
997 <term><constant>PRIVIL_SEARCH_DB</constant></term>
998 <listitem><para>The user can can search for
999 boxes.</para></listitem>
1003 <term><constant>PRIVIL_OWNER_ADM</constant></term>
1004 <listitem><para>The user can administer his box (to add and remove
1005 permitted users and to modify theirs
1006 permissions.)</para></listitem>
1010 <term><constant>PRIVIL_READ_VAULT</constant></term>
1012 <para>The user can read messages stored in the long term storage.</para>
1013 <note><para>This permission is not used since 2012-05.</para></note>
1018 <term><constant>PRIVIL_ERASE_VAULT</constant></term>
1019 <listitem><para>The user can delete messages from the long term
1020 storage.</para></listitem>
1026 <title><type>isds_message_status</type></title>
1027 <synopsis>typedef enum <type>isds_message_status</type>;</synopsis>
1028 <para>Message status. Known values are:</para>
1031 <term><constant>MESSAGESTATE_SENT</constant></term>
1032 <listitem><para>The message has been put into
1033 <abbrev>ISDS</abbrev>.</para></listitem>
1037 <term><constant>MESSAGESTATE_STAMPED</constant></term>
1038 <listitem><para>Message was stamped by a time stamp
1039 authority.</para></listitem>
1043 <term><constant>MESSAGESTATE_INFECTED</constant></term>
1044 <listitem><para>The message included viruses. Infected documents
1045 have been removed from the message.</para></listitem>
1049 <term><constant>MESSAGESTATE_DELIVERED</constant></term>
1050 <listitem><para>The message was delivered.
1051 (<structfield>dmDeliveryTime</structfield> is
1052 populated.)</para></listitem>
1056 <term><constant>MESSAGESTATE_SUBSTITUTED</constant></term>
1057 <listitem><para>The message was delivered through fiction,
1058 <structfield>dmAcceptanceTime</structfield> is
1059 populated.</para></listitem>
1063 <term><constant>MESSAGESTATE_RECEIVED</constant></term>
1064 <listitem><para>The message was accepted (by user's log-in or
1065 user's explicit request).
1066 <structfield>dmAcceptanceTime</structfield> is
1067 populated.</para></listitem>
1071 <term><constant>MESSAGESTATE_READ</constant></term>
1072 <listitem><para>The message has been read by
1073 a user.</para></listitem>
1077 <term><constant>MESSAGESTATE_UNDELIVERABLE</constant></term>
1078 <listitem><para>The message could not been delivered.
1079 (<abbrev>E.g.</abbrev>The recipient's box has been made
1080 inaccessible meantime.)</para></listitem>
1084 <term><constant>MESSAGESTATE_REMOVED</constant></term>
1085 <listitem><para>The message's content was
1086 deleted.</para></listitem>
1090 <term><constant>MESSAGESTATE_IN_SAFE</constant></term>
1091 <listitem><para>The message is stored in the long term
1092 storage.</para></listitem>
1096 <para>The values can be combined into a bit mask for some functions.
1097 A special <constant>MESSAGESTATE_ANY</constant> macro denotes any of
1102 <title><type>isds_hash_algorithm</type></title>
1103 <synopsis>typedef enum <type>isds_hash_algorithm</type>;</synopsis>
1104 <para>Hash algorithm types. Known values are:</para>
1107 <term><constant>HASH_ALGORITHM_MD5</constant></term>
1108 <listitem><para><abbrev>MD5</abbrev>.</para></listitem>
1112 <term><constant>HASH_ALGORITHM_SHA_1</constant></term>
1113 <listitem><para><abbrev>SHA-1</abbrev>.</para></listitem>
1117 <term><constant>HASH_ALGORITHM_SHA_224</constant></term>
1118 <listitem><para><abbrev>SHA-224</abbrev>.</para></listitem>
1122 <term><constant>HASH_ALGORITHM_SHA_256</constant></term>
1123 <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1127 <term><constant>HASH_ALGORITHM_SHA_384</constant></term>
1128 <listitem><para><abbrev>SHA-384</abbrev>.</para></listitem>
1132 <term><constant>HASH_ALGORITHM_SHA_512</constant></term>
1133 <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1139 <title><type>isds_buffer_strategy</type></title>
1140 <synopsis>typedef enum <type>isds_buffer_strategy</type>;</synopsis>
1141 <para>Buffer storage strategy. This type defines how a function should
1142 embed application provided buffer into
1143 <structfield>raw</structfield> element of output structure. Known
1147 <term><constant>BUFFER_DONT_STORE</constant></term>
1148 <listitem><para>Don't fill <structfield>raw</structfield>
1149 member.</para></listitem>
1153 <term><constant>BUFFER_COPY</constant></term>
1154 <listitem><para>Copy buffer content into newly allocated
1155 <structfield>raw</structfield> member.</para></listitem>
1159 <term><constant>BUFFER_MOVE</constant></term>
1160 <listitem><para>Copy pointer. Leave deallocation to structure
1162 (<function>isds_*_free</function>()).</para></listitem>
1168 <title>struct <structname>isds_hash</structname></title>
1169 <synopsis>struct <structname>isds_hash</structname>;</synopsis>
1170 <para>This is a hash value storage. Members are:</para>
1173 <term><type>isds_hash_algorithm</type>
1174 <structfield>algorithm</structfield>;</term>
1175 <listitem><para>Hash algorithm.</para></listitem>
1179 <term><type>size_t</type> <structfield>length</structfield>;</term>
1180 <listitem><para>Hash value length in bytes.</para></listitem>
1184 <term><type>void *</type><structfield>value</structfield>;</term>
1185 <listitem><para>Hash value as a byte stream.</para></listitem>
1191 <title>struct <structname>isds_PersonName</structname></title>
1192 <synopsis>struct <structname>isds_PersonName</structname>;</synopsis>
1193 <para>Name of a person. Members are:</para>
1196 <term><type>char *</type><structfield>pnFirstName</structfield>;</term>
1197 <listitem><para>First name.</para></listitem>
1201 <term><type>char *</type><structfield>pnMiddleName</structfield>;</term>
1202 <listitem><para>Middle name.</para></listitem>
1206 <term><type>char *</type><structfield>pnLastName</structfield>;</term>
1207 <listitem><para>Current last name.</para></listitem>
1211 <term><type>char *</type><structfield>pnLastNameAtBirth</structfield>;</term>
1212 <listitem><para>Last name at birth.</para></listitem>
1218 <title>struct <structname>isds_BirthInfo</structname></title>
1219 <synopsis>struct <structname>isds_BirthInfo</structname>;</synopsis>
1220 <para>Date and place of a birth. Members are:</para>
1223 <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1224 <listitem><para>Date of birth in local time at the birth place.
1225 Only <structfield>tm_year</structfield>,
1226 <structfield>tm_mon</structfield> and
1227 <structfield>tm_mday</structfield> members of the <type>struct
1228 tm</type> carry sane value. Others are
1229 undefined.</para></listitem>
1233 <term><type>char *</type><structfield>biCity</structfield>;</term>
1234 <listitem><para>City where a person was born.</para></listitem>
1238 <term><type>char *</type><structfield>biCounty</structfield>;</term>
1239 <listitem><para>Region where a person was born. This is the kind
1240 of region that is called <phrase lang="de">Bezirk</phrase> in
1241 German and <phrase lang="cs">okres</phrase> in
1242 Czech.</para></listitem>
1246 <term><type>char *</type><structfield>biState</structfield>;</term>
1247 <listitem><para>State wher a person was born.</para></listitem>
1253 <title>struct <structname>isds_Address</structname></title>
1254 <synopsis>struct <structname>isds_Address</structname>;</synopsis>
1255 <para>Postal address. Members are:</para>
1258 <term><type>char *</type><structfield>adCity</structfield>;</term>
1259 <listitem><para>City.</para></listitem>
1263 <term><type>char *</type><structfield>adStreet</structfield>;</term>
1264 <listitem><para>Street.</para></listitem>
1268 <term><type>char *</type><structfield>adNumberInStreet</structfield>;</term>
1269 <listitem><para>Identification of an entrance on the
1270 street. <phrase lang="cs">Číslo orientační</phrase> in
1271 Czech.</para></listitem>
1275 <term><type>char *</type><structfield>adNumberInMunicipality</structfield>;</term>
1276 <listitem><para>Identification of a building in the municipality.
1277 <phrase lang="cs">Číslo popisné</phrase> in
1278 Czech.</para></listitem>
1282 <term><type>char *</type><structfield>adZipCode</structfield>;</term>
1283 <listitem><para>Postal code for mail routing.</para></listitem>
1287 <term><type>char *</type><structfield>adState</structfield>;</term>
1288 <listitem><para>State.</para></listitem>
1294 <title>struct <structname>isds_DbOwnerInfo</structname></title>
1295 <synopsis>struct <structname>isds_DbOwnerInfo</structname>;</synopsis>
1296 <para>Data about a box and his owner. NULL pointer values mean
1297 undefined values. Members are:</para>
1300 <term><type>char *</type><structfield>dbID</structfield>;</term>
1301 <listitem><para>Box identifier. Specification limits the length to
1302 7 characters.</para></listitem>
1306 <term><type>isds_DbType *</type><structfield>dbType</structfield>;</term>
1307 <listitem><para>Box type.</para></listitem>
1311 <term><type>char *</type><structfield>ic</structfield>;</term>
1312 <listitem><para>Identifier of the owner.</para></listitem>
1316 <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1317 <listitem><para>Name of a person owning the box.</para></listitem>
1321 <term><type>char *</type><structfield>firmName</structfield>;</term>
1322 <listitem><para>Name of a firm owning the box.</para></listitem>
1326 <term><type>isds_BirthInfo *</type><structfield>birthInfo</structfield>;</term>
1327 <listitem><para>Birth details of the person.</para></listitem>
1331 <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1332 <listitem><para>Postal address of the owner.</para></listitem>
1336 <term><type>char *</type><structfield>nationality</structfield>;</term>
1337 <listitem><para>Nationality of the owner.</para></listitem>
1341 <term><type>char *</type><structfield>email</structfield>;</term>
1342 <listitem><para>E-mail addres of the owner.</para></listitem>
1346 <term><type>char *</type><structfield>telNumber</structfield>;</term>
1347 <listitem><para>Telephone number of the owner.</para></listitem>
1351 <term><type>char *</type><structfield>identifier</structfield>;</term>
1352 <listitem><para>External box identifier for data provider
1353 (<abbrev>OVM</abbrev>, <abbrev>PO</abbrev>, maybe
1354 <abbrev>PFO</abbrev> box types.) Specification limits the
1355 length to 20 characters.</para></listitem>
1359 <term><type>char *</type><structfield>registryCode</structfield>;</term>
1360 <listitem><para><abbrev>PFO</abbrev> external registry code.
1361 Specification limits the length to
1362 5 characters.</para></listitem>
1366 <term><type>long int *</type><structfield>dbState</structfield>;</term>
1368 <para>Box state. 1 means the box is active.</para>
1369 <note><para>The type is long int because specification declares it
1370 as <type>xsd:integer</type>.</para></note>
1371 <note><para>TODO: enum?</para></note></listitem>
1375 <term><type>_Bool *</type><structfield>dbEffectiveOVM</structfield>;</term>
1376 <listitem><para>The Box has <abbrev>OVM</abbrev> role (section 5a
1377 of the act).</para></listitem>
1381 <term><type>_Bool *</type><structfield>dbOpenAddressing</structfield>;</term>
1382 <listitem>This <para>non-<abbrev>OVM</abbrev> box is free to
1383 receive messages from anybody.</para></listitem>
1389 <title><type>isds_UserType</type></title>
1390 <synopsis>typedef enum <type>isds_UserType</type>;</synopsis>
1391 <para>User type. Known values are:</para>
1394 <term><constant>USERTYPE_PRIMARY</constant></term>
1395 <listitem><para>Owner of the box.</para></listitem>
1399 <term><constant>USERTYPE_ENTRUSTED</constant></term>
1400 <listitem><para>User with limited access to the box.</para></listitem>
1404 <term><constant>USERTYPE_ADMINISTRATOR</constant></term>
1405 <listitem><para>User who can manage
1406 <constant>USERTYPE_ENTRUSTED</constant>
1407 users.</para></listitem>
1411 <term><constant>USERTYPE_OFFICIAL</constant></term>
1412 <listitem><para>???</para></listitem>
1416 <term><constant>USERTYPE_OFFICIAL_CERT</constant></term>
1417 <listitem><para>???</para></listitem>
1421 <term><constant>USERTYPE_LIQUIDATOR</constant></term>
1422 <listitem><para>Company liquidator.</para></listitem>
1428 <title>struct <structname>isds_DbUserInfo</structname></title>
1429 <synopsis>struct <structname>isds_DbUserInfo</structname>;</synopsis>
1430 <para>Data about a user. NULL pointer values mean
1431 undefined values. Members are:</para>
1434 <term><type>char *</type><structfield>userID</structfield>;</term>
1435 <listitem><para>User identifier. Specification limits the length
1436 from 6 to 12 characters.</para></listitem>
1440 <term><type>isds_UserType *</type><structfield>userType</structfield>;</term>
1441 <listitem><para>User type.</para></listitem>
1445 <term><type>long int *</type><structfield>userPrivils</structfield>;</term>
1446 <listitem><para>Set of user permissions.</para></listitem>
1450 <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1451 <listitem><para>Name of the user.</para></listitem>
1455 <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1456 <listitem><para>Postal address of the user.</para></listitem>
1460 <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1461 <listitem><para>Date of birth in local time.
1462 Only <structfield>tm_year</structfield>,
1463 <structfield>tm_mon</structfield> and
1464 <structfield>tm_mday</structfield> members of the <type>struct
1465 tm</type> carry sane value. Others are
1466 undefined.</para></listitem>
1470 <term><type>char *</type><structfield>ic</structfield>;</term>
1471 <listitem><para>Identifier a supervising firm. Specification
1472 limits the length to 8 characters.</para></listitem>
1476 <term><type>char *</type><structfield>firmName</structfield>;</term>
1477 <listitem><para>Name of a supervising firm. Specification limits
1478 the length to 100 characters.</para></listitem>
1482 <term><type>char *</type><structfield>caStreet</structfield>;</term>
1483 <listitem><para>Contact address. Street and number.</para></listitem>
1487 <term><type>char *</type><structfield>caCity</structfield>;</term>
1488 <listitem><para>Czech city of the contact address.</para></listitem>
1492 <term><type>char *</type><structfield>caZipCode</structfield>;</term>
1493 <listitem><para>Postal code of the contact address.</para></listitem>
1497 <term><type>char *</type><structfield>caState</structfield>;</term>
1498 <listitem><para>Abbreviated country of contact address. This value
1499 is optional and implicit meaning is
1500 <constant>CZ</constant>.</para></listitem>
1504 <term><type>char *</type><structfield>aifo_ticket</structfield>;</term>
1505 <listitem><para>Reference to citizen registry. This value is
1506 optional.</para></listitem>
1515 <title>Functions</title>
1518 <listitem><funcsynopsis><funcprototype>
1519 <funcdef>const char *<function>isds_strerror</function></funcdef>
1520 <paramdef>const isds_error <parameter>error</parameter></paramdef>
1521 </funcprototype></funcsynopsis></listitem>
1523 <listitem><funcsynopsis><funcprototype>
1524 <funcdef>struct isds_ctx *<function>isds_ctx_create</function></funcdef>
1526 </funcprototype></funcsynopsis></listitem>
1531 <title>See Also</title>
1534 <simplelist type="inline">
1535 <member><citerefentry>
1536 <refentrytitle>libcurl</refentrytitle>
1537 <manvolnum>3</manvolnum>
1538 </citerefentry></member>
1539 <member><citerefentry>
1540 <refentrytitle>libisds</refentrytitle>
1541 <manvolnum>3</manvolnum>
1542 </citerefentry></member>
1543 <member><citerefentry>
1544 <refentrytitle>time.h</refentrytitle>
1545 <manvolnum>0p</manvolnum>
1546 </citerefentry></member>