<?xml version="1.0" encoding="utf-8" standalone="no"?>

<!DOCTYPE reference PUBLIC "-//OASIS/DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<reference lang="en">

  <referenceinfo>
    <authorgroup>
    <!-- corpauthor has a weird format -->
    <author>
      <personname>
        <othername>CZ.NIC, z. s. p. o.</othername>
      </personname>
      <personblurb>
        <simpara>Maintains libdatovka. Has been contributing to libisds.</simpara>
      </personblurb>
    </author>
    <author>
      <personname>
        <firstname>Petr</firstname>
        <surname>Písař</surname>
      </personname>
      <personblurb>
        <simpara>He has written libisds.</simpara>
      </personblurb>
    </author>
    <productname>libdatovka</productname>
    </authorgroup>
  </referenceinfo>

  <title>Manual for Libdatovka</title>


  <refentry id="libdatovka.3">
    <refmeta>
      <refentrytitle>libdatovka</refentrytitle>
      <manvolnum>3</manvolnum>
    </refmeta>

    <refnamediv>
      <refname>libdatovka</refname>
      <refpurpose>ISDS client library</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <synopsis><![CDATA[#include <libdatovka/isds.h>
#include <stdio.h>

isds_error err;
struct isds_ctx *ctx;

err = isds_init();
ctx = isds_ctx_create();

err = isds_login(ctx, NULL, "username", "password", NULL, NULL);
if (err) {
    printf("isds_login() failed: %s: %s\n",
        isds_strerror(err), isds_long_message(ctx));
} else {
    printf("Logged in.\n");
}

err = isds_ctx_free(&ctx);
err = isds_cleanup();
]]></synopsis>
    </refsynopsisdiv>

    <refsection>
      <title>Description</title>

      <para>This is a client library for accessing SOAP services of
        <abbrev>ISDS</abbrev> (<foreignphrase lang="cs">Informační systém datových
          schránek</foreignphrase> / Data Box Information System) as defined in
        <ulink url="http://portal.gov.cz/zakon/300/2008">Czech
          <abbrev>ISDS</abbrev> Act (300/2008 <abbrev>Coll.</abbrev>)</ulink>
        and implied documents. Current implementation details are described in
        <foreignphrase lang="cs">Provozní řád</foreignphrase> that can be downloaded from
        <ulink url="https://www.datoveschranky.info/ke-stazeni"><foreignphrase
            lang="cs">Dokumenty ke stažení</foreignphrase> section of
          <abbrev>ISDS</abbrev> Information Portal</ulink>.</para>

      <para>The library provides a C language interface with synchronous
        non-reentrant blocking calls. Network communication progress reporting
        and operation logging and library debugging are implemented by calling
        back application-provided functions. Network operations can be
        cancelled from network reporting call-back.</para>
    </refsection>

    <refsection>
      <title>Library Initialization and Deinitialization</title>

      <para>A libdatovka application must include the <filename>libdatovka/isds.h</filename>
        header file. The application must call <function>isds_init</function>
        function to initialize the library before calling any other library
        functions.  After last libdatovka call, <function>isds_cleanup</function>
        function should be called to clean up some global resources and to
        deinitialize dependent libraries.</para>
    </refsection>

    <refsection>
      <title>Contexts</title>

      <para>Most of the functions operate on an established connection to the
        <abbrev>ISDS</abbrev> server. This is called a context and it's
        represented by a pointer to an opaque
        <structname>isds_ctx</structname> structure. The structure maintains
        state about network connection, authorization or error from last call
        on the context.</para>

      <para>The context is allocated by <function>isds_ctx_create</function>
        function and deallocated by <function>isds_ctx_free</function>
        function.</para>

      <para>There are more context subtypes. A specific subtype is assigned to
        the context when a fresh new context is passed to one of the few
        stratifying functions (<function>isds_login</function>,
        <function>czp_convert_document</function>,
        <function>isds_request_new_testing_box</function>). Once the context
        is specialized, you can use it only with functions understanding the
        subtype. This is not enforced by the library now, but it does not
        matter much because all the other functions assume the
        <function>isds_login</function> was called on the context. In other
        words, do not share the context among the three stratifying
        functions.</para>

      <para>For example create a context with
        <function>isds_ctx_create</function>, then call
        <function>isds_login</function>, then work with box, then call
        <function>isds_logout</function>. Here you can reuse the context and
        log in as another user by calling <function>isds_login</function>
        again or destroy the context with <function>isds_ctx_free</function> if
        you don't need it anymore.</para>

      <para>Or create a context with <function>isds_ctx_create</function>,
        send a document to authorized conversion using
        <function>czp_convert_document</function>, then you can send more
        documents to the authorized conversion by calling
        <function>czp_convert_document</function> again on the same context
        and finally destroy the context with
        <function>isds_ctx_free</function>.</para>

    </refsection>

    <refsection>
      <title>Errors</title>

      <para>Most of the functions return an error code of
        <type>isds_error</type> type. <errorname>IE_SUCCESS</errorname> value
        denotes a successful call. Other values represent some kind of
        failure.</para>

      <para>You can use <function>isds_strerror</function> function to obtain
        a human readable string representation of the error code.</para>

      <para>If a function with context argument failed, you can use
        <function>isds_long_message</function> function to obtain a detailed
        error message. Please note that returned value lasts only to the next
        call on the context.</para>
    </refsection>

    <refsection>
      <title>Character Encoding</title>

      <para>All strings exchanged between the library and the application are
        encoded in <abbrev>UTF-8</abbrev>. Although there are a few
        exceptions:</para>

      <itemizedlist>
        <listitem>
          <para><function>isds_strerror</function> and
            <function>isds_long_message</function> functions return
            locale encoded string.</para>
        </listitem>

        <listitem>
          <para><function>isds_version</function> returns locale encoded
            string.</para>
        </listitem>

        <listitem>
          <para>Log call-back function set by
            <function>isds_set_log_callback</function> function is called with
            raw byte stream.</para>
        </listitem>

        <listitem>
          <para><structname>isds_pki_credentials</structname> structure string
            members have encoding specific to cryptographic library linked to
            cURL library.</para>
        </listitem>

      </itemizedlist>
    </refsection>

    <refsection>
      <title>Global Settings</title>

      <para>Some functions influence library behaviour globally. These are:</para>

      <itemizedlist>
        <listitem>
          <para><function>isds_init</function> and
            <function>isds_cleanup</function> used to initialize and
            deinitialize the library.</para>
        </listitem>

        <listitem>
          <para><function>isds_set_logging</function> and
            <function>isds_set_log_callback</function> to set logging.</para>
        </listitem>
      </itemizedlist>
    </refsection>

    <refsection>
      <title>Logging and Debugging</title>

      <para>Logging is global for all libdatovka calls. Log level and facility
        can be set with <function>isds_set_logging</function> function.</para>

      <para>The log is printed on standard error output by default.
        Application can redirect the messages to a call-back function by
        registering the call-back function with
        <function>isds_set_log_callback</function>.</para>
    </refsection>

    <refsection>
      <title>Network Input/Output</title>

      <para>Some functions operating on a context create network sockets and
        do network input and output.</para>

      <para>Network timeout can be set with
        <function>isds_set_timeout</function> function. Function calls aborted
        owing to the timeout will return
        <errorname>IE_TIMED_OUT</errorname>.</para>

      <para>Network operation progress can be monitored by a call-back
        function. The call-back function can be registered using
        <function>isds_set_xferinfo_callback</function> function. Registered
        call-back function will be called periodically with arguments
        declaring amount of transferred data. The call-back return value
        determines whether to continue in the network operation or to cancel
        the operation. Functions failed owing to cancelling network operation
        will return <errorname>IE_ABORTED</errorname>. The now deprecated
        call-back function <function>isds_set_progress_callback</function>
        behaves similarly but uses floating-point values to pass amounts
        of transferred data. Is is discouraged to use
        <function>isds_set_progress_callback</function> in new code.</para>
    </refsection>

    <refsection>
      <title>Memory management</title>

      <para>The library provides destructors for all libdatovka data structures.
        For example <function>isds_ctx_free</function> function accepts a pointer
        to a pointer to the <structname>isds_ctx</structname> structure, frees
        the double referenced structure (recursively), writes NULL to the
        pointed pointer (which invalidates the pointer effectively) and returns
        nothing.</para>

      <para>Upon a function call, all output arguments are automatically
        reallocated to desired size. On a function failure, all output
        arguments are automatically deallocated and their pointers set to
        NULL. Exceptions are documented at respective functions.</para>

      <para>Output strings are allocated using standard
        <function>malloc</function> call. Application is responsible for their
        deallocation (in case of no failure and if not specified otherwise.)
        Use standard <function>free</function> call for strings,
        use libdatovka destructors for libdatovka structures.</para>
    </refsection>

    <refsection>
      <title>Available Functions, Types, and Constants</title>

      <para>See <filename>libdatovka/isds.h</filename> header file.</para>
    </refsection>

    <refsection>
      <title>See Also</title>

      <para>
        <simplelist type="inline">
          <member><citerefentry>
              <refentrytitle>isds.h.libdatovka</refentrytitle>
              <manvolnum>3</manvolnum>
          </citerefentry></member>
          <member><citerefentry>
              <refentrytitle>libcurl</refentrytitle>
              <manvolnum>3</manvolnum>
          </citerefentry></member>
        </simplelist>
      </para>
    </refsection>
  </refentry>


  <refentry id="isds.h.libdatovka.3">
    <refmeta>
      <refentrytitle>isds.h.libdatovka</refentrytitle>
      <manvolnum>3</manvolnum>
    </refmeta>

    <refnamediv>
      <refname>isds.h.libdatovka</refname>
      <refpurpose>API definition for libdatovka</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <synopsis><![CDATA[#include <libdatovka/isds.h>
]]></synopsis>
    </refsynopsisdiv>

    <refsection>
      <title>Description</title>

      <para>This header file declares interface for the libdatovka library.</para>
    </refsection>

    <refsection>
      <title>Constants</title>

      <refsection>
        <title>Service locators</title>

        <para>Addresses of known <abbrev>ISDS</abbrev> servers.</para>

        <refsection>
          <title>Base <abbrev>URL</abbrev>s of production <abbrev>ISDS</abbrev> instance</title>

          <refsection>
            <title><varname>isds_locator</varname></title>
            <synopsis>extern const char <varname>isds_locator</varname>[];</synopsis>
            <para>Without client certificate authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_cert_locator</varname></title>
            <synopsis>extern const char <varname>isds_cert_locator</varname>[];</synopsis>
            <para>With client certificate authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_vodz_locator</varname></title>
            <synopsis>extern const char <varname>isds_vodz_locator</varname>[];</synopsis>
            <para>High-volume data message locator without client certificate authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_vodz_cert_locator</varname></title>
            <synopsis>extern const char <varname>isds_vodz_cert_locator</varname>[];</synopsis>
            <para>High-volume data message locator with client certificate authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_otp_locator</varname></title>
            <synopsis>extern const char <varname>isds_otp_locator</varname>[];</synopsis>
            <para>With <abbrev>OTP</abbrev> authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_mep_locator</varname></title>
            <synopsis>extern const char <varname>isds_mep_locator</varname>[];</synopsis>
            <para>With <abbrev>MEP</abbrev> authentication.</para>
          </refsection>
        </refsection>

        <refsection>
          <title>Base <abbrev>URL</abbrev>s of testing <abbrev>ISDS</abbrev> instance</title>

          <refsection>
            <title><varname>isds_testing_locator</varname></title>
            <synopsis>extern const char <varname>isds_testing_locator</varname>[];</synopsis>
            <para>Without client certificate authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_cert_testing_locator</varname></title>
            <synopsis>extern const char <varname>isds_cert_testing_locator</varname>[];</synopsis>
            <para>With client certificate authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_vodz_testing_locator</varname></title>
            <synopsis>extern const char <varname>isds_vodz_testing_locator</varname>[];</synopsis>
            <para>High-volume data message locator without client certificate authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_vodz_cert_testing_locator</varname></title>
            <synopsis>extern const char <varname>isds_vodz_cert_testing_locator</varname>[];</synopsis>
            <para>High-volume data message locator with client certificate authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_otp_testing_locator</varname></title>
            <synopsis>extern const char <varname>isds_otp_testing_locator</varname>[];</synopsis>
            <para>With <abbrev>OTP</abbrev> authentication.</para>
          </refsection>

          <refsection>
            <title><varname>isds_mep_testing_locator</varname></title>
            <synopsis>extern const char <varname>isds_mep_testing_locator</varname>[];</synopsis>
            <para>With <abbrev>MEP</abbrev> authentication.</para>
          </refsection>
        </refsection>

      </refsection>
    </refsection>

    <refsection>
      <title>Data types</title>

      <refsection>
        <title>struct <structname>isds_ctx</structname></title>
        <synopsis>struct <structname>isds_ctx</structname>;</synopsis>
        <para>Context for specific <abbrev>ISDS</abbrev> box.</para>
      </refsection>

      <refsection>
        <title><type>isds_error</type></title>
        <synopsis>typedef enum <type>isds_error</type>;</synopsis>
        <para>Error code. Known values:</para>
        <variablelist>
          <varlistentry>
            <term><errorname>IE_SUCCESS</errorname></term>
            <listitem><para>No error. Numeric value 0.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_ERROR</errorname></term>
            <listitem><para>Unspecified error.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_NOTSUP</errorname></term>
            <listitem><para>Operation is not supported.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_INVAL</errorname></term>
            <listitem><para>Invalid value.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_INVALID_CONTEXT</errorname></term>
            <listitem><para>The context is not valid.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_NOT_LOGGED_IN</errorname></term>
            <listitem><para>The context has not been logged in.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_CONNECTION_CLOSED</errorname></term>
            <listitem><para>Network connection has been closed.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_TIMED_OUT</errorname></term>
            <listitem><para>Time limit for network operation exceeded.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_NONEXIST</errorname></term>
            <listitem><para>Requested entity doesn't exist.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_NOMEM</errorname></term>
            <listitem><para>Not enough memory.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_NETWORK</errorname></term>
            <listitem><para>Network error.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_HTTP</errorname></term>
            <listitem><para>Error on <abbrev>HTTP</abbrev> level.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_SOAP</errorname></term>
            <listitem><para>Error on <abbrev>SOAP</abbrev> level.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_XML</errorname></term>
            <listitem><para>Error on XML level.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_ISDS</errorname></term>
            <listitem><para>Problem with <abbrev>ISDS</abbrev> server.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_ENUM</errorname></term>
            <listitem><para>Invalid enumeration value.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_DATE</errorname></term>
            <listitem><para>Invalid date value.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_TOO_BIG</errorname></term>
            <listitem><para>Value is too big.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_TOO_SMALL</errorname></term>
            <listitem><para>Value is too small.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_NOTUNIQ</errorname></term>
            <listitem><para>Value is not unique.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_NOTEQUAL</errorname></term>
            <listitem><para>Compared values are not equal.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_PARTIAL_SUCCESS</errorname></term>
            <listitem><para>Operation on a vector succeeded for some values but failed for others.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_ABORTED</errorname></term>
            <listitem><para>Operation was aborted by application request.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><errorname>IE_SECURITY</errorname></term>
            <listitem><para>Security requirements were not satisfied.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_log_level</type></title>
        <synopsis>typedef enum <type>isds_log_level</type>;</synopsis>
        <para>Log level. Know values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>ILL_NONE</constant></term>
            <listitem><para>0</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILL_CRIT</constant></term>
            <listitem><para>10</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILL_ERR</constant></term>
            <listitem><para>20</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILL_WARNING</constant></term>
            <listitem><para>30</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILL_INFO</constant></term>
            <listitem><para>40</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILL_DEBUG</constant></term>
            <listitem><para>50</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILL_ALL</constant></term>
            <listitem><para>100</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_log_facility</type></title>
        <synopsis>typedef enum <type>isds_log_facility</type>;</synopsis>
        <para>Log facility. Know values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>ILF_NONE</constant></term>
            <listitem><para>0x0</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILF_HTTP</constant></term>
            <listitem><para>0x1</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILF_SOAP</constant></term>
            <listitem><para>0x2</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILF_ISDS</constant></term>
            <listitem><para>0x4</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILF_FILE</constant></term>
            <listitem><para>0x8</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILF_SEC</constant></term>
            <listitem><para>0x10</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILF_XML</constant></term>
            <listitem><para>0x20</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ILF_ALL</constant></term>
            <listitem><para>0xFF</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_option</type></title>
        <synopsis>typedef enum <type>isds_option</type>;</synopsis>
        <para>libdatovka option identifiers. Known values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>IOPT_TLS_VERIFY_SERVER</constant></term>
            <listitem><para>Option type is <type>_Bool</type>. Whether to
                verify server identity. Default value is
                true.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>IOPT_TLS_CA_FILE</constant></term>
            <listitem><para>Option type is <type>char *</type>. Option value
                is a file name with certificate authority
                certificates. Default value depends on used cryptographic
                library.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>IOPT_TLS_CA_DIRECTORY</constant></term>
            <listitem><para>Option type is <type>char *</type>, Option value
                is a directory with certificate authority certificates.
                Default value depends on used cryptographic
                library.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>IOPT_TLS_CRL_FILE</constant></term>
            <listitem><para>Option type is <type>char *</type>. Option value
                is a file name with certificat revocation list in
                <abbrev>PEM</abbrev> format. Default value depends on used
                cryptographic library.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>IOPT_NORMALIZE_MIME_TYPE</constant></term>
            <listitem><para>Optiona type is <type>_Bool</type>. Whether to
                normalize <abbrev>MIME</abbrev> type values. Default value is
                false.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_tls_option</type></title>
        <synopsis>typedef enum <type>isds_tls_option</type>;</synopsis>
        <warning><para>This type is deprecated.</para></warning>
        <para><abbrev>TLS</abbrev> libdatovka option identifiers. Known values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>ITLS_VERIFY_SERVER</constant></term>
            <listitem><para>Option type is <type>_Bool</type>. Whether to
                verify server identity.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ITLS_CA_FILE</constant></term>
            <listitem><para>Option type is <type>char *</type>. Option value
                is a file name with certificate authority
                certificates.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ITLS_CA_DIRECTORY</constant></term>
            <listitem><para>Option type is <type>char *</type>. Option value
                is a directory name with certificate authority
                certificates.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>ITLS_CRL_FILE</constant></term>
            <listitem><para>Option type is <type>char *</type>. Option value
                is a file name with certificate revocation list in
                <abbrev>PEM</abbrev> format.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_pki_format</type></title>
        <synopsis>typedef enum <type>isds_pki_format</type>;</synopsis>
        <para>Cryptographic material encoding. Known values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>PKI_FORMAT_PEM</constant></term>
            <listitem><para><abbrev>PEM</abbrev> format.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PKI_FORMAT_DER</constant></term>
            <listitem><para><abbrev>DER format.</abbrev></para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PKI_FORMAT_ENG</constant></term>
            <listitem><para>The material is stored in a cryptographic engine.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_pki_credentials</structname></title>
        <synopsis>struct <structname>isds_pki_credentials</structname>;</synopsis>
        <para>This structure holds public key infrastructure cryptographic
          material to authenticate a client. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>char *</type><structfield>engine</structfield>;</term>
            <listitem><para>String identifier of cryptographic engine to use
                (where key is stored). Use NULL for no
                engine.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_pki_format</type> <structfield>certificate_format</structfield>;</term>
            <listitem><para>Certificate format.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>certificate</structfield>;</term>
            <listitem><para>A path to client certificate, or a certificate
                nickname in case of <abbrev>NSS</abbrev> as curl back-end, or
                key slot identifier inside cryptographic engine. Some
                cryptographic engines can pair certificate with key
                automatically (NULL value).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_pki_format</type> <structfield>key_format</structfield>;</term>
            <listitem><para>Private key format.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>key</structfield>;</term>
            <listitem><para>A path to client private key, or key identifier in
                case an engine is used.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>passphrase</structfield>;</term>
            <listitem><para>Zero terminated string with password for
                decrypting private key, or engine <abbrev>PIN</abbrev>. Use
                NULL for no pass-phrase or to let the engine to ask for
                it.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_otp_method</type></title>
        <synopsis>typedef enum <type>isds_otp_method</type>;</synopsis>
        <para>One-time password authentication method. Known values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>OTP_HMAC</constant></term>
            <listitem><para><abbrev>HMAC</abbrev>-based <abbrev>OTP</abbrev> method.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_TIME</constant></term>
            <listitem><para>Time-based <abbrev>OTP</abbrev> method.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_otp_resolution</type></title>
        <synopsis>typedef enum <type>isds_otp_resolution</type>;</synopsis>
        <para>One-time password authentication resolution. Known values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>OTP_RESOLUTION_SUCCESS</constant></term>
            <listitem><para>Authentication succeeded.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_RESOLUTION_UNKNOWN</constant></term>
            <listitem><para>Status is unknown.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_RESOLUTION_BAD_AUTHENTICATION</constant></term>
            <listitem><para>Bad log-in. You can retry to log in.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_RESOLUTION_ACCESS_BLOCKED</constant></term>
            <listitem><para>Access blocked for 60 minutes. (Because a brute
                force attack was detected.)</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_RESOLUTION_PASSWORD_EXPIRED</constant></term>
            <listitem>
              <para>Password has expired.</para>
              <note>
                <para>It's not clear which password expired:
                  <abbrev>OTP</abbrev> or regular password?</para>
              </note>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_RESOLUTION_TOO_FAST</constant></term>
            <listitem><para><abbrev>OTP</abbrev> cannot be sent repeatedly at
                this rate. (Minimal delay depends on <abbrev>TOTP</abbrev>
                window setting.)</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_RESOLUTION_UNAUTHORIZED</constant></term>
            <listitem><para>User name is not allowed to access requested
                <abbrev>URI</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_RESOLUTION_TOTP_SENT</constant></term>
            <listitem><para><abbrev>OTP</abbrev> has been generated and sent
                by the <abbrev>ISDS</abbrev> to the user.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>OTP_RESOLUTION_TOTP_NOT_SENT</constant></term>
            <listitem><para><abbrev>OTP</abbrev> could not been sent by the
                <abbrev>ISDS</abbrev>. Retry later.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_otp</structname></title>
        <synopsis>struct <structname>isds_otp</structname>;</synopsis>
        <para>This structure holds one-time password when authenticating
          a client and resolution of the authentication.</para>

        <para>Input members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>isds_otp_method</type> <structfield>method</structfield>;</term>
            <listitem><para>Select <abbrev>OTP</abbrev> method to use.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>otp_code</structfield>;</term>
            <listitem><para>One-time password to use. Pass NULL, if you do not
                know it yet (<abbrev>e.g.</abbrev> in case of first phase of
                time-based <abbrev>OTP</abbrev> authentication to request new
                code from <abbrev>ISDS</abbrev>.)</para></listitem>
          </varlistentry>
        </variablelist>

        <para>Output members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>isds_otp_resolution</type> <structfield>resolution</structfield>;</term>
            <listitem><para>Fine-grade resolution of this <abbrev>OTP</abbrev>
                authentication attempt.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_DbType</type></title>
        <synopsis>typedef enum <type>isds_DbType</type>;</synopsis>
        <para>Box type. It classifies box owner by his legal status. Known
          values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>DBTYPE_OVM_MAIN</constant></term>
            <listitem><para>This is a special value for
                <function>isds_find_box_by_fulltext</function>.
                It's not accepted by any other
                <abbrev>services</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_SYSTEM</constant></term>
            <listitem><para>This is a special value for sender of messages sent
                by the <abbrev>ISDS</abbrev>. You can find it only in
                incoming messages. It's not accepted by any other
                <abbrev>services</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_OVM</constant></term>
            <listitem><para>Standard government (state or municipality or
                similar) office.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_OVM_NOTAR</constant></term>
            <listitem><para>Notary (stopped being used, replaced with
                <abbrev>OVM_PFO</abbrev>).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_OVM_EXEKUT</constant></term>
            <listitem><para>Executor (stopped being used, replaced with
                <abbrev>OVM_PFO</abbrev>).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_OVM_REQ</constant></term>
            <listitem><para>Subsidiary office with <abbrev>OVM</abbrev>
                (governing) status assigned on request (section 6 and 7 of the
                act).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_OVM_FO</constant></term>
            <listitem><para>Natural person with <abbrev>OVM</abbrev> status
                (without identification number).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_OVM_PFO</constant></term>
            <listitem><para>Natural person in business with <abbrev>OVM</abbrev>
                status (e.g. notary or executor).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_OVM_PO</constant></term>
            <listitem><para>Juridical person with <abbrev>OVM</abbrev> status
                (arisen from previously existing <abbrev>PO</abbrev> or
                <abbrev>PO_REQ</abbrev>).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PO</constant></term>
            <listitem><para>Standard commercial organization (listed in trade
                registry).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PO_ZAK</constant></term>
            <listitem><para>Other organization founded by an act
                (stopped being used, replaced with
                <abbrev>PO</abbrev>).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PO_REQ</constant></term>
            <listitem><para>An organization with a box assigned on its
                request.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO</constant></term>
            <listitem><para>Person in business.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_ADVOK</constant></term>
            <listitem><para>Lawyer.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_DANPOR</constant></term>
            <listitem><para>Tax consultant.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_INSSPR</constant></term>
            <listitem><para>Administrator of insolvency (stopped being used,
                replaced with <abbrev>OVM_PFO</abbrev>).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_AUDITOR</constant></term>
            <listitem><para>Statutory auditor.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_ZNALEC</constant></term>
            <listitem><para>Expert witness.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_TLUMOCNIK</constant></term>
            <listitem><para>Sworn translator.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_ARCH</constant></term>
            <listitem><para>Architect.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_AIAT</constant></term>
            <listitem><para>Authorised engineer / technician.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_AZI</constant></term>
            <listitem><para>Authorised geodetics engineer.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_PFO_REQ</constant></term>
            <listitem><para>Person in business on its
                request.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBTYPE_FO</constant></term>
            <listitem><para>Standard person.</para></listitem>
          </varlistentry>
        </variablelist>

        <para>Some interfaces refer to <emphasis>gross</emphasis> box type.
          These are the shortest names of the identifiers. For example,
          <literal>DBTYPE_OVM</literal> is a gross type for
          <literal>DB_OVM_NOTAR</literal> or <literal>DBTYPE_OVM</literal>.
          But not for <literal>DBTYPE_PO</literal>.</para>
      </refsection>

      <refsection>
        <title><type>isds_DbState</type></title>
        <synopsis>typedef enum <type>isds_DbState</type>;</synopsis>
        <para>Box status from point of view of accessibility. Known
          values:</para>
        <variablelist>
          <varlistentry>
            <term><constant>DBSTATE_ACCESSIBLE</constant></term>
            <listitem><para>The box is accessible.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBSTATE_TEMP_INACCESSIBLE</constant></term>
            <listitem><para>The box is temporarily inaccessible (at the request of the user).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBSTATE_NOT_YET_ACCESSIBLE</constant></term>
            <listitem><para>The box has not yet been activated.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBSTATE_PERM_INACCESSIBLE</constant></term>
            <listitem><para>The box is permanently inaccessible.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBSTATE_REMOVED</constant></term>
            <listitem><para>The box has been removed.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>DBSTATE_TEMP_INACCESSIBLE_LAW</constant></term>
            <listitem><para>The box is temporarily inaccessible (because of the reasons enumerated in the law).</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_privileges</type></title>
        <synopsis>typedef enum <type>isds_privileges</type>;</synopsis>
        <para>Distinct user permissions from point of view of <abbrev>ISDS</abbrev>.
          Instances can be bitmaps of any of these distinct values. Distinct known
          values are:</para>
        <variablelist>
          <varlistentry>
            <term><constant>PRIVIL_READ_NON_PERSONAL</constant></term>
            <listitem><para>The user can download and read messages with
                <structfield>dmPersonalDelivery</structfield> equal to
                false.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PRIVIL_READ_ALL</constant></term>
            <listitem><para>The user can download and read messages with
                <structfield>dmPersonalDelivery</structfield> equal to
                true.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PRIVIL_CREATE_DM</constant></term>
            <listitem><para>The user can create and send messages, the user
                can download outgoing (sent) messages.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PRIVIL_VIEW_INFO</constant></term>
            <listitem><para>The user can list messages and read data about
                a message post and delivery.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PRIVIL_SEARCH_DB</constant></term>
            <listitem><para>The user can can search for
                boxes.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PRIVIL_OWNER_ADM</constant></term>
            <listitem><para>The user can administer his box (to add and remove
                permitted users and to modify theirs
                permissions.)</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PRIVIL_READ_VAULT</constant></term>
            <listitem>
              <para>The user can read messages stored in the long term storage.</para>
              <note><para>This permission is not used since 2012-05.</para></note>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PRIVIL_ERASE_VAULT</constant></term>
            <listitem><para>The user can delete messages from the long term
                storage.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>enum isds_message_status</type></title>
        <synopsis>typedef enum isds_message_status <type>isds_message_status</type>;</synopsis>
        <para>Message status. Known values are:</para>
        <variablelist>
          <varlistentry>
            <term><constant>MESSAGESTATE_SENT</constant></term>
            <listitem><para>The message has been put into
                <abbrev>ISDS</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_STAMPED</constant></term>
            <listitem><para>Message was stamped by a time stamp
                authority.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_INFECTED</constant></term>
            <listitem><para>The message included viruses. Infected documents
                have been removed from the message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_DELIVERED</constant></term>
            <listitem><para>The message was delivered.
                (<structfield>dmDeliveryTime</structfield> is
                    populated.)</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_SUBSTITUTED</constant></term>
            <listitem><para>The message was delivered through fiction,
                <structfield>dmAcceptanceTime</structfield> is
                populated.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_RECEIVED</constant></term>
            <listitem><para>The message was accepted (by user's log-in or
                user's explicit request).
                <structfield>dmAcceptanceTime</structfield> is
                populated.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_READ</constant></term>
            <listitem><para>The message has been read by
                a user.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_UNDELIVERABLE</constant></term>
            <listitem><para>The message could not been delivered.
                (<abbrev>E.g.</abbrev>The recipient's box has been made
                inaccessible meantime.)</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_REMOVED</constant></term>
            <listitem><para>The message's content was
                deleted.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGESTATE_IN_VAULT</constant></term>
            <listitem><para>The message is stored in the long term
                storage.</para></listitem>
          </varlistentry>
        </variablelist>

        <para>The values can be combined into a bit mask for some functions.
          A special <constant>MESSAGESTATE_ANY</constant> macro denotes any of
          the states.</para>
      </refsection>

      <refsection>
        <title><type>isds_hash_algorithm</type></title>
        <synopsis>typedef enum <type>isds_hash_algorithm</type>;</synopsis>
        <para>Hash algorithm types. Known values are:</para>
        <variablelist>
          <varlistentry>
            <term><constant>HASH_ALGORITHM_MD5</constant></term>
            <listitem><para><abbrev>MD5</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>HASH_ALGORITHM_SHA_1</constant></term>
            <listitem><para><abbrev>SHA-1</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>HASH_ALGORITHM_SHA_224</constant></term>
            <listitem><para><abbrev>SHA-224</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>HASH_ALGORITHM_SHA_256</constant></term>
            <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>HASH_ALGORITHM_SHA_384</constant></term>
            <listitem><para><abbrev>SHA-384</abbrev>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>HASH_ALGORITHM_SHA_512</constant></term>
            <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_buffer_strategy</type></title>
        <synopsis>typedef enum <type>isds_buffer_strategy</type>;</synopsis>
        <para>Buffer storage strategy. This type defines how a function should
          embed application provided buffer into
          <structfield>raw</structfield> element of output structure. Known
          values are:</para>
        <variablelist>
          <varlistentry>
            <term><constant>BUFFER_DONT_STORE</constant></term>
            <listitem><para>Don't fill <structfield>raw</structfield>
                member.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>BUFFER_COPY</constant></term>
            <listitem><para>Copy buffer content into newly allocated
                <structfield>raw</structfield> member.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>BUFFER_MOVE</constant></term>
            <listitem><para>Copy pointer. Leave deallocation to structure
                destructor
                (<function>isds_*_free</function>()).</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_hash</structname></title>
        <synopsis>struct <structname>isds_hash</structname>;</synopsis>
        <para>This is a hash value storage. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>isds_hash_algorithm</type>
              <structfield>algorithm</structfield>;</term>
            <listitem><para>Hash algorithm.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>size_t</type> <structfield>length</structfield>;</term>
            <listitem><para>Hash value length in bytes.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>void *</type><structfield>value</structfield>;</term>
            <listitem><para>Hash value as a byte stream.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_PersonName</structname></title>
        <synopsis>struct <structname>isds_PersonName</structname>;</synopsis>
        <para>Name of a person. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>char *</type><structfield>pnFirstName</structfield>;</term>
            <listitem><para>First name.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>pnMiddleName</structfield>;</term>
            <listitem><para>Middle name.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>pnLastName</structfield>;</term>
            <listitem><para>Current last name.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>pnLastNameAtBirth</structfield>;</term>
            <listitem><para>Last name at birth.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_BirthInfo</structname></title>
        <synopsis>struct <structname>isds_BirthInfo</structname>;</synopsis>
        <para>Date and place of a birth. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
            <listitem><para>Date of birth in local time at the birth place.
                Only <structfield>tm_year</structfield>,
                <structfield>tm_mon</structfield> and
                <structfield>tm_mday</structfield> members of the <type>struct
                  tm</type> carry sane value. Others are
                undefined.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>biCity</structfield>;</term>
            <listitem><para>City where a person was born.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>biCounty</structfield>;</term>
            <listitem><para>Region where a person was born. This is the kind
                of region that is called <foreignphrase
                  lang="de">Bezirk</foreignphrase> in
                German and <foreignphrase lang="cs">okres</foreignphrase> in
                Czech.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>biState</structfield>;</term>
            <listitem><para>State wher a person was born.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_Address</structname></title>
        <synopsis>struct <structname>isds_Address</structname>;</synopsis>
        <para>Postal address. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>char *</type><structfield>adCity</structfield>;</term>
            <listitem><para>City.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>adStreet</structfield>;</term>
            <listitem><para>Street.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>adNumberInStreet</structfield>;</term>
            <listitem><para>Identification of an entrance on the
                street. <foreignphrase lang="cs">Číslo
                  orientační</foreignphrase> in Czech.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>adNumberInMunicipality</structfield>;</term>
            <listitem><para>Identification of a building in the municipality.
                <foreignphrase lang="cs">Číslo popisné</foreignphrase> in
                Czech.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>adZipCode</structfield>;</term>
            <listitem><para>Postal code for mail routing.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>adState</structfield>;</term>
            <listitem><para>State.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_DbOwnerInfo</structname></title>
        <synopsis>struct <structname>isds_DbOwnerInfo</structname>;</synopsis>
        <para>Data about a box and his owner. NULL pointer values mean
          undefined values. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>char *</type><structfield>dbID</structfield>;</term>
            <listitem><para>Box identifier. Specification limits the length to
                7 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_DbType *</type><structfield>dbType</structfield>;</term>
            <listitem><para>Box type.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>ic</structfield>;</term>
            <listitem><para>Identifier of the owner.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
            <listitem><para>Name of a person owning the box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>firmName</structfield>;</term>
            <listitem><para>Name of a firm owning the box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_BirthInfo *</type><structfield>birthInfo</structfield>;</term>
            <listitem><para>Birth details of the person.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_Address *</type><structfield>address</structfield>;</term>
            <listitem><para>Postal address of the owner.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>nationality</structfield>;</term>
            <listitem><para>Nationality of the owner.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>email</structfield>;</term>
            <listitem><para>E-mail addres of the owner.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>telNumber</structfield>;</term>
            <listitem><para>Telephone number of the owner.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>identifier</structfield>;</term>
            <listitem><para>External box identifier for data provider
                (<abbrev>OVM</abbrev>, <abbrev>PO</abbrev>, maybe
                <abbrev>PFO</abbrev> box types.) Specification limits the
                length to 20 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>registryCode</structfield>;</term>
            <listitem><para><abbrev>PFO</abbrev> external registry code.
                Specification limits the length to
                5 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int *</type><structfield>dbState</structfield>;</term>
            <listitem>
              <para>Box state. 1 means the box is active.</para>
              <note><para>The type is long int because specification declares it
                  as <type>xsd:integer</type>.</para></note>
              <note><para>TODO: enum?</para></note></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>_Bool *</type><structfield>dbEffectiveOVM</structfield>;</term>
            <listitem><para>The Box has <abbrev>OVM</abbrev> role (section 5a
                of the act).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>_Bool *</type><structfield>dbOpenAddressing</structfield>;</term>
            <listitem>This <para>non-<abbrev>OVM</abbrev> box is free to
                receive messages from anybody.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_UserType</type></title>
        <synopsis>typedef enum <type>isds_UserType</type>;</synopsis>
        <para>User type. Known values are:</para>
        <variablelist>
          <varlistentry>
            <term><constant>USERTYPE_PRIMARY</constant></term>
            <listitem><para>Owner of the box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>USERTYPE_ENTRUSTED</constant></term>
            <listitem><para>User with limited access to the box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>USERTYPE_ADMINISTRATOR</constant></term>
            <listitem><para>User who can manage
                <constant>USERTYPE_ENTRUSTED</constant>
                users.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>USERTYPE_OFFICIAL</constant></term>
            <listitem><para>???</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>USERTYPE_OFFICIAL_CERT</constant></term>
            <listitem><para>???</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>USERTYPE_LIQUIDATOR</constant></term>
            <listitem><para>Company liquidator.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>USERTYPE_RECEIVER</constant></term>
            <listitem><para>Company receiver.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>USERTYPE_GUARDIAN</constant></term>
            <listitem><para>Legal guardian.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_DbUserInfo</structname></title>
        <synopsis>struct <structname>isds_DbUserInfo</structname>;</synopsis>
        <para>Data about a user. NULL pointer values mean
          undefined values. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>char *</type><structfield>userID</structfield>;</term>
            <listitem><para>User identifier. Specification limits the length
                from 6 to 12 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_UserType *</type><structfield>userType</structfield>;</term>
            <listitem><para>User type.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int *</type><structfield>userPrivils</structfield>;</term>
            <listitem><para>Set of user permissions.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
            <listitem><para>Name of the user.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_Address *</type><structfield>address</structfield>;</term>
            <listitem><para>Postal address of the user.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
            <listitem><para>Date of birth in local time.
                Only <structfield>tm_year</structfield>,
                <structfield>tm_mon</structfield> and
                <structfield>tm_mday</structfield> members of the <type>struct
                  tm</type> carry sane value. Others are
                undefined.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>ic</structfield>;</term>
            <listitem><para>Identifier a supervising firm. Specification
                limits the length to 8 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>firmName</structfield>;</term>
            <listitem><para>Name of a supervising firm. Specification limits
                the length to 100 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>caStreet</structfield>;</term>
            <listitem><para>Contact address. Street and number.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>caCity</structfield>;</term>
            <listitem><para>Czech city of the contact address.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>caZipCode</structfield>;</term>
            <listitem><para>Postal code of the contact address.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>caState</structfield>;</term>
            <listitem><para>Abbreviated country of contact address. This value
                is optional and implicit meaning is
                <constant>CZ</constant>.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_event_type</type></title>
        <synopsis>typedef enum <type>isds_event_type</type>;</synopsis>
        <para>Message event type. Known values are:</para>
        <variablelist>
          <varlistentry>
            <term><constant>EVENT_UNKNOWN</constant></term>
            <listitem><para>Event unknown to this library.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_ACCEPTED_BY_RECIPIENT</constant></term>
            <listitem><para>Message has been delivered and accepted by
                recipient action.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_ACCEPTED_BY_FICTION</constant></term>
            <listitem><para>Message has been delivered, acceptance period
                timed out, the message is considered
                accepted.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_ACCEPTED_BY_FICTION_NO_USER</constant></term>
            <listitem><para>Message has been delivered, acceptance period
                timed out because there was no user who could accept
                the message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_UNDELIVERABLE</constant></term>
            <listitem><para>Recipient box was made inaccessible, thus the
                message is undeliverable.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_COMMERCIAL_ACCEPTED</constant></term>
            <listitem><para>Recipient confirmed acceptance of this commercial
                message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_ENTERED_SYSTEM</constant></term>
            <listitem><para>The message entered the
                <abbrev>ISDS</abbrev>system, <abbrev>i.e.</abbrev> it has been
                just sent by a sender.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_DELIVERED</constant></term>
            <listitem><para>The message has been delivered into recipient's
                box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_PRIMARY_LOGIN</constant></term>
            <listitem><para>Primary user logged into recipient's
                box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_ENTRUSTED_LOGIN</constant></term>
            <listitem><para>Entrusted user with capability to read logged
                into recipient's box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>EVENT_SYSCERT_LOGIN</constant></term>
            <listitem><para>An application authenticated by
                <emphasis>system</emphasis> certificate logged into
                recipient's box.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_event</structname></title>
        <synopsis>struct <structname>isds_event</structname>;</synopsis>
        <para>An event that happened in a message life. All members are
          optional. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>struct isds_timeval *</type><structfield>time</structfield>;</term>
            <listitem><para>When the event occurred.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_event_type *</type><structfield>type</structfield>;</term>
            <listitem><para>Type of the event.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>description</structfield>;</term>
            <listitem><para>Human-readable event description generated by the
                <abbrev>ISDS</abbrev> system. (Very probably in Czech
                language).</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>enum isds_IdLevel_value</type></title>
        <synopsis><type>enum isds_IdLevel_value</type>;</synopsis>
        <para>Specifies which information the sender of a data message wants
          to publish about his person.</para>
        <variablelist>
          <varlistentry>
            <term><constant>PUBLISH_USERTYPE</constant></term>
            <listitem><para>Publish information about the sender type.
                This information is always revealed to the recipient.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PUBLISH_PERSONNAME</constant></term>
            <listitem><para>Publish sender's personal name.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PUBLISH_BIDATE</constant></term>
            <listitem><para>Publish sender's birth date.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PUBLISH_BICITY</constant></term>
            <listitem><para>Publish sender's birth city. This information is available
                only when sender is SENDERTYPE_ENTRUSTED of a FO or PFO box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PUBLISH_BICOUNTY</constant></term>
            <listitem><para>Publish sender's birth county. This information is available
                only when sender is SENDERTYPE_ENTRUSTED of a FO or PFO box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PUBLISH_ADCODE</constant></term>
            <listitem><para>Publish sender's RUIAN address code.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PUBLISH_FULLADDRESS</constant></term>
            <listitem><para>Publish sender's full address.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>PUBLISH_ROBIDENT</constant></term>
            <listitem><para>Publish information whether sender is identified within the ROB.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_envelope</structname></title>
        <synopsis>struct <structname>isds_envelope</structname>;</synopsis>
        <para>Message envelope. These are the metadata about a message. It
          does contain the message documents.</para>
        <para>Be ware that the string length constraints are forced only on
          output members transmitted to the <abbrev>ISDS</abbrev>. The other
          direction (downloading from the <abbrev>ISDS</abbrev>) can break
          these rules. It should not happen, but nobody knows how much
          incompatible new version of the <abbrev>ISDS</abbrev> protocol will
          be.  This is the gold Internet rule: be strict on what you send, be
          tolerant on what you receive.</para>
        <para>Following members apply to incoming messages only:</para>
        <variablelist>
          <varlistentry>
            <term><type>char *</type><structfield>dmID</structfield>;</term>
            <listitem><para>Message identifier. Maximal length is 20
                characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dbIDSender</structfield>;</term>
            <listitem><para>Box identifier of the sender. Special value
                <literal>aaaaaaa</literal> means the message was sent by the
                <abbrev>ISDS</abbrev> system. Not by another user. Maximal
                length is 7 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmSender</structfield>;</term>
            <listitem><para>Sender's name. Maximal length is 100
                characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmSenderAddress</structfield>;</term>
            <listitem><para>Postal address of the sender. Maximal length is 100
                characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int *</type><structfield>dmSenderType</structfield>;</term>
            <listitem><para>Gross box type of the sender. You can use
                <type>isds_DbType</type> to enumerate some known box types.
                This is a generic integer because the protocol keeps the value
                unconstrained and the library must support any syntactically
                correct value.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmRecipient</structfield>;</term>
            <listitem><para>Recipient's name. Maximal length is 100
                characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmRecipientAddress</structfield>;</term>
            <listitem><para>Postal address of the recipient. Maximal length is
                100 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>_Bool *</type><structfield>dmAmbiguousRecipient</structfield>;</term>
            <listitem><para>The recipient has <abbrev>OVM</abbrev> role.</para></listitem>
          </varlistentry>
        </variablelist>

        <para>Following members are assigned by the <abbrev>ISDS</abbrev> in
          different phases of message life cycle:</para>
        <variablelist>
          <varlistentry>
            <term><type>unsigned long int *</type><structfield>dmOrdinal</structfield>;</term>
            <listitem><para>Ordinal number in list of incoming/outgoing
                messages.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>enum isds_message_status *</type><structfield>dmMessageStatus</structfield>;</term>
            <listitem><para>Message state.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int *</type><structfield>dmAttachmentSize</structfield>;</term>
            <listitem><para>Size of message documents in kilobytes. The value
                is rounded.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct isds_timeval *</type><structfield>dmDeliveryTime</structfield>;</term>
            <listitem><para>The time of delivering the message into recipient's
                box. It will be <constant>NULL</constant>, if the message has not
                been delivered yet.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct isds_timeval *</type><structfield>dmAcceptanceTime</structfield>;</term>
            <listitem><para>The time of accepting the message by the
                recipient. It will be <constant>NULL</constant>, if message
                has not been accepted yet.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct isds_hash *</type><structfield>hash</structfield>;</term>
            <listitem><para>The message digest. This is a hash of a substring representing
                <literal>isds:dmDM</literal> <abbrev>XML</abbrev>
                subtree. You can use
                <function>isds_compute_message_hash</function> function to
                compute a hash of the message and then compare it against this
                structure member using <function>isds_hash_cmp</function>
                function.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>void *</type><structfield>timestamp</structfield>;</term>
            <listitem><para>This is a binary image of a qualified time stamp
                of the <structfield>hash</structfield> value. The time stamp
                is provided by the <abbrev>ISDS</abbrev> system. Messages that
                have not yet been stamped will have this value
                <constant>NULL</constant>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>size_t</type> <structfield>timestamp_length</structfield>;</term>
            <listitem><para>Length of the <structfield>timestamp</structfield>
                value in bytes.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct isds_list *</type><structfield>events</structfield>;</term>
            <listitem><para>Events the message passed trough. It's a list of
                <type>isds_event</type> structures.</para></listitem>
          </varlistentry>
        </variablelist>

        <para>Following members apply to both outgoing and incoming
          messages:</para>

        <variablelist>
          <varlistentry>
            <term><type>char *</type><structfield>dmSenderOrgUnit</structfield>;</term>
            <listitem><para>Sender's organisation unit as a string. This is
                optional.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int *</type><structfield>dmSenderOrgUnitNum</structfield>;</term>
            <listitem><para>Sender's organisation unit as a number. This is
                optional.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dbIDRecipient</structfield>;</term>
            <listitem><para>Recipient's box identifier. This is mandatory.
                Maximal length is 7 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmRecipientOrgUnit</structfield>;</term>
            <listitem><para>Recipient's organisation unit as a string. This is
                optional.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int *</type><structfield>dmRecipientOrgUnitNum</structfield>;</term>
            <listitem><para>Recipient's organisation unit of as a number. This
                is optional.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmToHands</structfield>;</term>
            <listitem><para>A person in recipient's organisation. This is
                optional.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmAnnotation</structfield>;</term>
            <listitem><para>A subject (title) of the message. Maximal length
                is 255 characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmRecipientRefNumber</structfield>;</term>
            <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
                  příjemce</foreignphrase>. This is optional. Maximal length is 50
                characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmSenderRefNumber</structfield>;</term>
            <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
                  odesílatele</foreignphrase>. This is optional. Maximal length is 50
                chars.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmRecipientIdent</structfield>;</term>
            <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
                  příjemce</foreignphrase>. This is optional. Maximal length is 50
                characters.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmSenderIdent</structfield>;</term>
            <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
                  odesílatele</foreignphrase> This is optional. Maximal length is 50
                chars.</para></listitem>
          </varlistentry>
        </variablelist>

        <para>Following five members constitute a reference to an item from the
          Czech Act Collection. The human-readable reference looks
          like <phrase><emphasis>Point</emphasis>
            (<emphasis>Paragraph</emphasis>)
            § <emphasis>Section</emphasis>
            <emphasis>Law</emphasis>/<emphasis>Year</emphasis>
            Coll.</phrase> The members apply to both incoming and outgoing
          messages:</para>

        <variablelist>
          <varlistentry>
            <term><type>long int *</type><structfield>dmLegalTitleLaw</structfield>;</term>
            <listitem><para>A number of an act mandating the
                authority.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int *</type><structfield>dmLegalTitleYear</structfield>;</term>
            <listitem><para>A year of issuing the act mandating the
                authority.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmLegalTitleSect</structfield>;</term>
            <listitem><para>A section of the act mandating the authority.
                Czech: <foreignphrase
                  lang="cs">paragraf</foreignphrase>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmLegalTitlePar</structfield>;</term>
            <listitem><para>A paragraph of the act mandating the authority.
                Czech: <foreignphrase
                  lang="cs">odstavec</foreignphrase>.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmLegalTitlePoint</structfield>;</term>
            <listitem><para>A point of the act mandating the authority. Czech:
                <foreignphrase lang="cs">písmeno</foreignphrase>.</para></listitem>
          </varlistentry>
        </variablelist>

        <para>Other incoming/outgoing message members:</para>

        <variablelist>
          <varlistentry>
            <term><type>_Bool *</type><structfield>dmPersonalDelivery</structfield>;</term>
            <listitem><para>If true, only person with higher privileges can
                read this message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>_Bool *</type><structfield>dmAllowSubstDelivery</structfield>;</term>
            <listitem><para>Allow delivery through fiction.
                <abbrev>I.e.</abbrev> Even if the recipient did not read this
                message, the message is considered as delivered after
                (currently) 10 days. This is called <phrase>delivery through
                  fiction</phrase>. Only OVM dbType sender can set
                it.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmType</structfield>;</term>
            <listitem>
              <para>Message type (commercial subtypes or government message).</para>

              <para>Input values (when sending the message):</para>

              <variablelist>
                <varlistentry>
                  <term><literal>"I"</literal></term>
                  <listitem><para>A commercial message offering paying the
                      response (<phrase>initiatory message</phrase>). It's
                      necessary to define
                      <structfield>dmSenderRefNumber</structfield>
                      member.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"K"</literal></term>
                  <listitem><para>A commercial message paid by the sender.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"O"</literal></term>
                  <listitem><para>A commercial response paid by the sender of
                      a initiatory message. It's necessary to copy a value
                      from the <structfield>dmSenderRefNumber</structfield> of
                      the initiatory message to the
                      <structfield>dmRecipientRefNumber</structfield> of this
                      message.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"V"</literal></term>
                  <listitem><para>A non-commercial government message. This is
                      the default meaning if the value is undefined while
                      sending a message.</para></listitem>
                </varlistentry>
              </variablelist>

              <para>Output values (when retrieving the message):</para>

              <variablelist>
                <varlistentry>
                  <term><literal>"A"</literal></term>
                  <listitem><para>This is a subsidized initiatory commercial
                      message which can pay a response.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"B"</literal></term>
                  <listitem><para>This is a subsidized initiatory commercial
                      message which has already paid the
                      response.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"C"</literal></term>
                  <listitem><para>This is a subsidized initiatory commercial
                      message where the response offer has
                      expired.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"D"</literal></term>
                  <listitem><para>This is an externally subsidized commercial
                      message.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"E"</literal></term>
                  <listitem><para>This is a commercial message prepaid by
                      a stamp.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"G"</literal></term>
                  <listitem><para>This is a commercial message paid by
                      a sponsor.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"I"</literal></term>
                  <listitem><para>See the input values.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"K"</literal></term>
                  <listitem><para>See the input values.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"O"</literal></term>
                  <listitem><para>See the input values.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"V"</literal></term>
                  <listitem><para>See the input values.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"X"</literal></term>
                  <listitem><para>This is an initiatory commercial message
                      where the response offer has expired.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"Y"</literal></term>
                  <listitem><para>This is an initiatory commercial message
                      which has already paid the response.</para></listitem>
                </varlistentry>

                <varlistentry>
                  <term><literal>"Z"</literal></term>
                  <listitem><para>This is limitedly subsidized commercial message.</para></listitem>
                </varlistentry>
              </variablelist>

              <para>Length of the value is exactly 1 UTF-8 character if
                defined. That means it's still zero-terminated character
                string.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>_Bool *</type><structfield>dmVODZ</structfield>;</term>
            <listitem><para>Set to true when downloading lists of sent or
                received messages and a particular message is a high-volume
                data message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int *</type><structfield>attsNum</structfield>;</term>
            <listitem><para>Set to number of attachments when downloading lists
                of sent or received messages and a particular message is
                a high-volume data message.</para></listitem>
          </varlistentry>
        </variablelist>

        <para>Following members apply to outgoing messages only:</para>

        <variablelist>
          <varlistentry>
            <term><type>_Bool *</type><structfield>dmOVM</structfield>;</term>
            <listitem><para>OVM sending mode. Non-OVM dbType boxes that have
                dbEffectiveOVM equal to true <emphasis>MUST</emphasis>
                select between true (OVM mode) and false (non-OVM mode).
                Otherwise the value is optional and the default value is
                true.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>_Bool *</type><structfield>dmPublishOwnID</structfield>;</term>
            <listitem><para>To allow to reveal sender's login name. The name
                will be available to the recipient through
                <function>isds_get_message_sender</function> function. The
                sender's box type and identifier will be always available.
                This feature exists because more users can have access to one
                box and the recipient could not tell who was the sender. This
                value is optional. Default value is false.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>int *</type><structfield>idLevel</structfield>;</term>
            <listitem><para>Specifies which personal information about the
                sender should be revealed to the recipient. All specified
                information can be acquired by the recipient by using the
                <function>isds_GetMessageAuthor2</function> function. The
                sender's box type and identifier will always be available.
                The value of <structfield>dmPublishOwnID</structfield>
                <emphasis>MUST</emphasis> be set to true in order to specify
                which additional information the sender wants to disclose.
                The actual value of the <structfield>idLevel</structfield> is
                the sum of actual <type>enum isds_IdLevel_value</type> values.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>isds_FileMetaType</type></title>
        <synopsis>typedef enum <type>isds_FileMetaType</type>;</synopsis>
        <para>Document type from point of view of hierarchy of documents in
          a message. Known values are:</para>
        <variablelist>
          <varlistentry>
            <term><constant>FILEMETATYPE_MAIN</constant></term>
            <listitem><para>Main document. There should be exactly one
                document of this type in a message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>FILEMETATYPE_ENCLOSURE</constant></term>
            <listitem><para>An appendix. If a message has more documents,
                generic-purpose documents other than the main one should have
                this type.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>FILEMETATYPE_SIGNATURE</constant></term>
            <listitem><para>Digital signature. This document is a signature of
                another document in the message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>FILEMETATYPE_META</constant></term>
            <listitem><para><abbrev>XML</abbrev> document for
                <phrase>electronic document information system</phrase>,
                <foreignphrase lang="cs">elektronická spisová
                  služba</foreignphrase> (<abbrev lang="cs">ESS</abbrev>) in
                Czech, purpose. </para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_document</structname></title>
        <synopsis>struct <structname>isds_document</structname>;</synopsis>
        <para>A message document. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>_Bool</type> <structfield>is_xml</structfield>;</term>
            <listitem><para>True if the document is an <abbrev>ISDS</abbrev>
                <abbrev>XML</abbrev> document. False if the document is an
                <abbrev>ISDS</abbrev> binary document.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>xmlNodePtr</type> <structfield>xml_node_list</structfield>;</term>
            <listitem><para><abbrev>XML</abbrev> node-set presenting the
                <abbrev>XML</abbrev> document content. This is a pointer to
                first <abbrev>XML</abbrev> node of the <abbrev>XML</abbrev>
                representation of the message as stored in
                <structfield>xml</structfield> member of
                <type>isds_message</type> structure. Use
                <structfield>children</structfield> and
                <structfield>next</structfield> members to walk through the
                document. See <systemitem class="library">libxml2</systemitem>
                library documentation for more details. The
                <structfield>xml_node_list</structfield> will be
                <constant>NULL</constant> if the document is empty. It's valid
                only if the <structfield>is_xml</structfield> is
                true.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>void *</type><structfield>data</structfield>;</term>
            <listitem><para>A binary document content. The encoding and format
                depends on <structfield>dmMimeType</structfield> member value.
                This is valid only if the <structfield>is_xml</structfield> is
                false.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>size_t</type> <structfield>data_length</structfield>;</term>
            <listitem><para>Length of the <structfield>data</structfield>
                buffer in bytes. It's valid only if the
                <structfield>is_xml</structfield> is false.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmMimeType</structfield>;</term>
            <listitem><para><abbrev>MIME</abbrev> type of document. This
                member is mandatory.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>isds_FileMetaType</type> <structfield>dmFileMetaType</structfield>;</term>
            <listitem><para>Document type to create document hierarchy inside
                a message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmFileGuid</structfield>;</term>
            <listitem><para>Message-local document identifier. It can be used
                as a key to refer to this document by
                <structfield>dmUpFileGuid</structfield> member from a different
                document. This is optional.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmUpFileGuid</structfield>;</term>
            <listitem><para>A reference to upper document identifier stored in
                <structfield>dmFileGuid</structfield> member of different
                document. You can use
                <function>isds_find_document_by_id</function> function to
                locate the upper document. This value is
                optional.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmFileDescr</structfield>;</term>
            <listitem><para>Document name (title). <abbrev>E.g.</abbrev>
                a file name. This value is mandatory.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmFormat</structfield>;</term>
            <listitem><para>A reference to <abbrev>XML</abbrev> format
                definition that explains how to interpret the
                <abbrev>XML</abbrev> document. <abbrev>E.g.</abbrev>
                a <abbrev>URL</abbrev> to an <abbrev>XML</abbrev> schema. This
                value is optional.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_box_state_period</structname></title>
        <synopsis>struct <structname>isds_box_state_period</structname>;</synopsis>
        <para>A box state valid in the time range. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>struct isds_timeval *</type><structfield>from</structfield>;</term>
            <listitem><para>Time range beginning.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct isds_timeval *</type><structfield>to</structfield>;</term>
            <listitem><para>Time range end.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>long int </type><structfield>dbState</structfield>;</term>
            <listitem><para>Box state. <constant>1</constant> means the box is
                accessible. Other values mean the box is inaccessible. You can
                use <type>isds_DbState</type> enum to identify some
                states.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_dmMessageAuthor</structname></title>
        <synopsis>struct <structname>isds_dmMessageAuthor</structname>;</synopsis>
        <para>Response for GetMessageAuthor2. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>isds_sender_type *</type><structfield>userType</structfield>;</term>
            <listitem><para>Message sender type.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct isds_PersonName2 *</type><structfield>personName</structfield>;</term>
            <listitem><para>Contains pnGivenNames and pnLastName.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
            <listitem><para>Date of birth in local time at birth place,
                only tm_year, tm_mon and tm_mday carry sane
                value.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>biCity</structfield>;</term>
            <listitem><para>City of birth.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>biCounty</structfield>;</term>
            <listitem><para>County of birth (German: Bezirk, Czech: okres).</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>adCode</structfield>;</term>
            <listitem><para>RUIAN address code.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>fullAddress</structfield>;</term>
            <listitem><para>Full address.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>_Bool *</type><structfield>robIdent</structfield>;</term>
            <listitem><para>Flag whether the person is identifiers within the ROB.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>enum isds_message_type</type></title>
        <synopsis>typedef enum isds_message_type <type>isds_message_type</type>;</synopsis>
        <para>Specifies the direction of the message - whether the message is
          received or sent:</para>
        <variablelist>
          <varlistentry>
            <term><constant>MESSAGE_TYPE_RECEIVED</constant></term>
            <listitem><para>Specifies a received message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>MESSAGE_TYPE_SENT</constant></term>
            <listitem><para>Specifies a sent message.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>enum isds_data_format</type></title>
        <synopsis>typedef enum isds_data_format <type>isds_data_format</type>;</synopsis>
        <para>Specifies data format:</para>
        <variablelist>
          <varlistentry>
            <term><constant>FORMAT_XML</constant></term>
            <listitem><para>Data in XML format.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><constant>FORMAT_CSV</constant></term>
            <listitem><para>Data in CSV format.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title><type>enum isds_asyncReqType</type></title>
        <synopsis>typedef enum isds_asyncReqType <type>isds_asyncReqType</type>;</synopsis>
        <para>Specifies synchronous request type:</para>
        <variablelist>
          <varlistentry>
            <term><constant>ASYNC_REQ_TYPE_LIST_ERASED</constant></term>
            <listitem><para>Response for the GetListOfErasedMessages request.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>struct <structname>isds_erased_message</structname></title>
        <synopsis>struct <structname>isds_erased_message</structname>;</synopsis>
        <para>Describes entries in the lists of erased messages. Members are:</para>
        <variablelist>
          <varlistentry>
            <term><type>char *</type><structfield>dmID</structfield>;</term>
            <listitem><para>Message ID.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dbIDSender</structfield>;</term>
            <listitem><para>Box ID of sender.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmSender</structfield>;</term>
            <listitem><para>Sender name.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dbIDRecipient</structfield>;</term>
            <listitem><para>Box ID of recipient.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmRecipient</structfield>;</term>
            <listitem><para>Recipient name.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmAnnotation</structfield>;</term>
            <listitem><para>Subject (title) of the message.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>enum isds_message_status *</type><structfield>dmMessageStatus</structfield>;</term>
            <listitem><para>Message state.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct isds_timeval *</type><structfield>dmDeliveryTime</structfield>;</term>
            <listitem><para>Time of delivery into a box.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>struct isds_timeval *</type><structfield>dmAcceptanceTime</structfield>;</term>
            <listitem><para>Time of acceptance of the message by a user.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><type>char *</type><structfield>dmType</structfield>;</term>
            <listitem><para>Message type.</para></listitem>
          </varlistentry>
        </variablelist>
      </refsection>

    </refsection>

    <refsection>
      <title>Functions</title>

      <itemizedlist>
        <listitem><funcsynopsis><funcprototype>
              <funcdef>const char *<function>isds_strerror</function></funcdef>
              <paramdef>const isds_error <parameter>error</parameter></paramdef>
        </funcprototype></funcsynopsis></listitem>

        <listitem><funcsynopsis><funcprototype>
          <funcdef>struct isds_ctx *<function>isds_ctx_create</function></funcdef>
          <void/>
        </funcprototype></funcsynopsis></listitem>
      </itemizedlist>
    </refsection>

    <refsection>
      <title>See Also</title>

      <para>
        <simplelist type="inline">
          <member><citerefentry>
              <refentrytitle>libcurl</refentrytitle>
              <manvolnum>3</manvolnum>
          </citerefentry></member>
          <member><citerefentry>
              <refentrytitle>libdatovka</refentrytitle>
              <manvolnum>3</manvolnum>
          </citerefentry></member>
          <member><citerefentry>
              <refentrytitle>time.h</refentrytitle>
              <manvolnum>0p</manvolnum>
          </citerefentry></member>
        </simplelist>
      </para>
    </refsection>
  </refentry>
</reference>
