doc/libisds.xml

   1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
   2
   3 <!DOCTYPE reference PUBLIC "-//OASIS/DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   5
   6 <reference lang="en">
   7
   8   <referenceinfo>
   9     <author>
  10       <personname>
  11         <firstname>Petr</firstname>
  12         <surname>Písař</surname>
  13       </personname>
  14       <personblurb>
  15         <simpara>He has written libisds.</simpara>
  16       </personblurb>
  17     </author>
  18     <productname>libisds</productname>
  19   </referenceinfo>
  20
  21   <title>Manual for Libisds</title>
  22
  23
  24   <refentry id="libisds.3">
  25     <refmeta>
  26       <refentrytitle>libisds</refentrytitle>
  27       <manvolnum>3</manvolnum>
  28     </refmeta>
  29
  30     <refnamediv>
  31       <refname>libisds</refname>
  32       <refpurpose>ISDS client library</refpurpose>
  33     </refnamediv>
  34
  35     <refsynopsisdiv>
  36       <synopsis><![CDATA[#include <isds.h>
  37 #include <stdio.h>
  38
  39 isds_error err;
  40 struct isds_ctx *ctx;
  41
  42 err = isds_init();
  43 ctx = isds_ctx_create();
  44
  45 err = isds_login(ctx, NULL, "username", "password", NULL, NULL);
  46 if (err) {
  47     printf("isds_login() failed: %s: %s\n",
  48         isds_strerror(err), isds_long_message(ctx));
  49 } else {
  50     printf("Logged in.\n");
  51 }
  52
  53 err = isds_ctx_free(&ctx);
  54 err = isds_cleanup();
  55 ]]></synopsis>
  56     </refsynopsisdiv>
  57
  58     <refsection>
  59       <title>Description</title>
  60
  61       <para>This is a client library for accessing SOAP services of
  62         <abbrev>ISDS</abbrev> (<foreignphrase lang="cs">Informační systém datových
  63           schránek</foreignphrase> / Data Box Information System) as defined in
  64         <ulink url="http://portal.gov.cz/zakon/300/2008">Czech
  65           <abbrev>ISDS</abbrev> Act (300/2008 <abbrev>Coll.</abbrev>)</ulink>
  66         and implied documents. Current implementation details are described in
  67         <foreignphrase lang="cs">Provozní řád</foreignphrase> that can be downloaded from
  68         <ulink url="https://www.datoveschranky.info/ke-stazeni"><foreignphrase
  69             lang="cs">Dokumenty ke stažení</foreignphrase> section of
  70           <abbrev>ISDS</abbrev> Information Portal</ulink>.</para>
  71
  72       <para>The library provides a C language interface with synchronous
  73         non-reentrant blocking calls. Network communication progress reporting
  74         and operation logging and library debugging are implemented by calling
  75         back application-provided functions. Network operations can be
  76         canceled from network reporting call-back.</para>
  77     </refsection>
  78
  79     <refsection>
  80       <title>Library Initialization and Deinitialization</title>
  81
  82       <para>A libisds application must include <filename>isds.h</filename>
  83         header file. The application must call <function>isds_init</function>
  84         function to initialize the library before calling any other library
  85         functions.  After last libisds call, <function>isds_cleanup</function>
  86         function should be called to clean up some global resources and to
  87         deinitialize dependent libraries.</para>
  88     </refsection>
  89
  90     <refsection>
  91       <title>Contexts</title>
  92
  93       <para>Most of the functions operate on an established connection to the
  94         <abbrev>ISDS</abbrev> server. This is called a context and it's
  95         represented by a pointer to an opaque
  96         <structname>isds_ctx</structname> structure. The structure maintains
  97         state about network connection, authorization or error from last call
  98         on the context.</para>
  99
 100       <para>The context is allocated by <function>isds_ctx_create</function>
 101         function and deallocated by <function>isds_ctx_free</function>
 102         function.</para>
 103
 104       <para>There are more context subtypes. A specific subtype is assigned to
 105         the context when a fresh new context is passed to one of the few
 106         stratifying functions (<function>isds_login</function>,
 107         <function>czp_convert_document</function>,
 108         <function>isds_request_new_testing_box</function>). Once the context
 109         is specialized, you can use it only with functions understanding the
 110         subtype. This is not enforced by the library now, but it does not
 111         matter much because all the other functions assume the
 112         <function>isds_login</function> was called on the context. In other
 113         words, do not share the context among the three stratifying
 114         functions.</para>
 115
 116       <para>For example create a context with
 117         <function>isds_ctx_create</function>, then call
 118         <function>isds_login</function>, then work with box, then call
 119         <function>isds_logout</function>. Here you can reuse the context and
 120         log in as another user by calling <function>isds_login</function>
 121         again or destroy the context with <function>isds_ctx_free</function> if
 122         you don't need it anymore.</para>
 123
 124       <para>Or create a context with <function>isds_ctx_create</function>,
 125         send a document to authorized conversion using
 126         <function>czp_convert_document</function>, then you can send more
 127         documents to the authorized conversion by calling
 128         <function>czp_convert_document</function> again on the same context
 129         and finally destroy the context with
 130         <function>isds_ctx_free</function>.</para>
 131
 132     </refsection>
 133
 134     <refsection>
 135       <title>Errors</title>
 136
 137       <para>Most of the functions return an error code of
 138         <type>isds_error</type> type. <errorname>IE_SUCCESS</errorname> value
 139         denotes a successful call. Other values represent some kind of
 140         failure.</para>
 141
 142       <para>You can use <function>isds_strerror</function> function to obtain
 143         a human readable string representation of the error code.</para>
 144
 145       <para>If a function with context argument failed, you can use
 146         <function>isds_long_message</function> function to obtain a detailed
 147         error message. Please note that returned value lasts only to the next
 148         call on the context.</para>
 149     </refsection>
 150
 151     <refsection>
 152       <title>Character Encoding</title>
 153
 154       <para>All strings exchanged between the library and the application are
 155         encoded in <abbrev>UTF-8</abbrev>. Although there are a few
 156         exceptions:</para>
 157
 158       <itemizedlist>
 159         <listitem>
 160           <para><function>isds_strerror</function> and
 161             <function>isds_long_message</function> functions return
 162             locale encoded string.</para>
 163         </listitem>
 164
 165         <listitem>
 166           <para><function>isds_version</function> returns locale encoded
 167             string.</para>
 168         </listitem>
 169
 170         <listitem>
 171           <para>Log call-back function set by
 172             <function>isds_set_log_callback</function> function is called with
 173             raw byte stream.</para>
 174         </listitem>
 175
 176         <listitem>
 177           <para><structname>isds_pki_credentials</structname> structure string
 178             members have encoding specific to cryptographic library linked to
 179             cURL library.</para>
 180         </listitem>
 181
 182       </itemizedlist>
 183     </refsection>
 184
 185     <refsection>
 186       <title>Global Settings</title>
 187
 188       <para>Some functions influence library behavior globally. These are:</para>
 189
 190       <itemizedlist>
 191         <listitem>
 192           <para><function>isds_init</function> and
 193             <function>isds_cleanup</function> used to initialize and
 194             deinitialize the library.</para>
 195         </listitem>
 196
 197         <listitem>
 198           <para><function>isds_set_logging</function> and
 199             <function>isds_set_log_callback</function> to set logging.</para>
 200         </listitem>
 201       </itemizedlist>
 202     </refsection>
 203
 204     <refsection>
 205       <title>Logging and Debugging</title>
 206
 207       <para>Logging is global for all libisds calls. Log level and facility
 208         can be set with <function>isds_set_logging</function> function.</para>
 209
 210       <para>The log is printed on standard error output by default.
 211         Application can redirect the messages to a call-back function by
 212         registering the call-back function with
 213         <function>isds_set_log_callback</function>.</para>
 214     </refsection>
 215
 216     <refsection>
 217       <title>Network Input/Output</title>
 218
 219       <para>Some functions operating on a context create network sockets and
 220         do network input and output.</para>
 221
 222       <para>Network timeout can be set with
 223         <function>isds_set_timeout</function> function. Function calls aborted
 224         owing to the timeout will return
 225         <errorname>IE_TIMED_OUT</errorname>.</para>
 226
 227       <para>Network operation progress can be monitored by a call-back
 228         function. The call-back function can be registered using
 229         <function>isds_set_progress_callback</function> function. Registered
 230         call-back function will be called periodically with arguments
 231         declaring amount of transferred data. The call-back return value
 232         determines whether to continue in the network operation or to cancel
 233         the operation. Functions failed owing to canceling network operation
 234         will return <errorname>IE_ABORTED</errorname>.</para>
 235     </refsection>
 236
 237     <refsection>
 238       <title>Memory management</title>
 239
 240       <para>The library provides destructors for all libisds data structures.
 241         For example <function>isds_ctx_free</function> function accepts a pointer
 242         to a pointer to the <structname>isds_ctx</structname> structure, frees
 243         the double referenced structure (recursively), writes NULL to the
 244         pointed pointer (which invalidates the pointer effectively) and returns
 245         nothing.</para>
 246
 247       <para>Upon a function call, all output arguments are automatically
 248         reallocated to desired size. On a function failure, all output
 249         arguments are automatically deallocated and their pointers set to
 250         NULL. Exceptions are documented at respective functions.</para>
 251
 252       <para>Output strings are allocated using standard
 253         <function>malloc</function> call. Application is responsible for their
 254         deallocation (in case of no failure and if not specified otherwise.)
 255         Use standard <function>free</function> call for strings,
 256         use libisds destructors for libisds structures.</para>
 257     </refsection>
 258
 259     <refsection>
 260       <title>Available Functions, Types, and Constants</title>
 261
 262       <para>See <filename>isds.h</filename> header file.</para>
 263     </refsection>
 264
 265     <refsection>
 266       <title>See Also</title>
 267
 268       <para>
 269         <simplelist type="inline">
 270           <member><citerefentry>
 271               <refentrytitle>isds.h</refentrytitle>
 272               <manvolnum>3</manvolnum>
 273           </citerefentry></member>
 274           <member><citerefentry>
 275               <refentrytitle>libcurl</refentrytitle>
 276               <manvolnum>3</manvolnum>
 277           </citerefentry></member>
 278         </simplelist>
 279       </para>
 280     </refsection>
 281   </refentry>
 282
 283
 284   <refentry id="isds.h.3">
 285     <refmeta>
 286       <refentrytitle>isds.h</refentrytitle>
 287       <manvolnum>3</manvolnum>
 288     </refmeta>
 289
 290     <refnamediv>
 291       <refname>isds.h</refname>
 292       <refpurpose>API definition for libisds</refpurpose>
 293     </refnamediv>
 294
 295     <refsynopsisdiv>
 296       <synopsis><![CDATA[#include <isds.h>
 297 ]]></synopsis>
 298     </refsynopsisdiv>
 299
 300     <refsection>
 301       <title>Description</title>
 302
 303       <para>This header file declares inteface for libisds library.</para>
 304     </refsection>
 305
 306     <refsection>
 307       <title>Constants</title>
 308
 309       <refsection>
 310         <title>Service locators</title>
 311
 312         <para>Addresses of known <abbrev>ISDS</abbrev> servers.</para>
 313
 314         <refsection>
 315           <title>Base <abbrev>URL</abbrev>s of production <abbrev>ISDS</abbrev> instance</title>
 316
 317           <refsection>
 318             <title><varname>isds_locator</varname></title>
 319             <synopsis>extern const char <varname>isds_locator</varname>[];</synopsis>
 320             <para>Without client certificate authentication.</para>
 321           </refsection>
 322
 323           <refsection>
 324             <title><varname>isds_cert_locator</varname></title>
 325             <synopsis>extern const char <varname>isds_cert_locator</varname>[];</synopsis>
 326             <para>With client certificate authentication.</para>
 327           </refsection>
 328
 329           <refsection>
 330             <title><varname>isds_otp_locator</varname></title>
 331             <synopsis>extern const char <varname>isds_otp_locator</varname>[];</synopsis>
 332             <para>Without <abbrev>OTP</abbrev> authentication.</para>
 333           </refsection>
 334         </refsection>
 335
 336         <refsection>
 337           <title>Base <abbrev>URL</abbrev>s of testing <abbrev>ISDS</abbrev> instance</title>
 338
 339           <refsection>
 340             <title><varname>isds_testing_locator</varname></title>
 341             <synopsis>extern const char <varname>isds_testing_locator</varname>[];</synopsis>
 342             <para>Without client certificate authentication.</para>
 343           </refsection>
 344
 345           <refsection>
 346             <title><varname>isds_cert_testing_locator</varname></title>
 347             <synopsis>extern const char <varname>isds_cert_testing_locator</varname>[];</synopsis>
 348             <para>With client certificate authentication.</para>
 349           </refsection>
 350
 351           <refsection>
 352             <title><varname>isds_otp_testing_locator</varname></title>
 353             <synopsis>extern const char <varname>isds_otp_testing_locator</varname>[];</synopsis>
 354             <para>Without <abbrev>OTP</abbrev> authentication.</para>
 355           </refsection>
 356         </refsection>
 357
 358       </refsection>
 359     </refsection>
 360
 361     <refsection>
 362       <title>Data types</title>
 363
 364       <refsection>
 365         <title>struct <structname>isds_ctx</structname></title>
 366         <synopsis>struct <structname>isds_ctx</structname>;</synopsis>
 367         <para>Context for specific <abbrev>ISDS</abbrev> box.</para>
 368       </refsection>
 369
 370       <refsection>
 371         <title><type>isds_error</type></title>
 372         <synopsis>typedef enum <type>isds_error</type>;</synopsis>
 373         <para>Error code. Known values:</para>
 374         <variablelist>
 375           <varlistentry>
 376             <term><errorname>IE_SUCCESS</errorname></term>
 377             <listitem><para>No error. Numeric value 0.</para></listitem>
 378           </varlistentry>
 379
 380           <varlistentry>
 381             <term><errorname>IE_ERROR</errorname></term>
 382             <listitem><para>Unspecified error.</para></listitem>
 383           </varlistentry>
 384
 385           <varlistentry>
 386             <term><errorname>IE_NOTSUP</errorname></term>
 387             <listitem><para>Operation is not supported.</para></listitem>
 388           </varlistentry>
 389
 390           <varlistentry>
 391             <term><errorname>IE_INVAL</errorname></term>
 392             <listitem><para>Invalid value.</para></listitem>
 393           </varlistentry>
 394
 395           <varlistentry>
 396             <term><errorname>IE_INVALID_CONTEXT</errorname></term>
 397             <listitem><para>The context is not valid.</para></listitem>
 398           </varlistentry>
 399
 400           <varlistentry>
 401             <term><errorname>IE_NOT_LOGGED_IN</errorname></term>
 402             <listitem><para>The context has not been logged in.</para></listitem>
 403           </varlistentry>
 404
 405           <varlistentry>
 406             <term><errorname>IE_CONNECTION_CLOSED</errorname></term>
 407             <listitem><para>Network connection has been closed.</para></listitem>
 408           </varlistentry>
 409
 410           <varlistentry>
 411             <term><errorname>IE_TIMED_OUT</errorname></term>
 412             <listitem><para>Time limit for network operation exceeded.</para></listitem>
 413           </varlistentry>
 414
 415           <varlistentry>
 416             <term><errorname>IE_NOEXIST</errorname></term>
 417             <listitem><para>Requested entity does exist.</para></listitem>
 418           </varlistentry>
 419
 420           <varlistentry>
 421             <term><errorname>IE_NOMEM</errorname></term>
 422             <listitem><para>Not enough memory.</para></listitem>
 423           </varlistentry>
 424
 425           <varlistentry>
 426             <term><errorname>IE_NETWORK</errorname></term>
 427             <listitem><para>Network error.</para></listitem>
 428           </varlistentry>
 429
 430           <varlistentry>
 431             <term><errorname>IE_HTTP</errorname></term>
 432             <listitem><para>Error on <abbrev>HTTP</abbrev> level.</para></listitem>
 433           </varlistentry>
 434
 435           <varlistentry>
 436             <term><errorname>IE_SOAP</errorname></term>
 437             <listitem><para>Error on <abbrev>SOAP</abbrev> level.</para></listitem>
 438           </varlistentry>
 439
 440           <varlistentry>
 441             <term><errorname>IE_XML</errorname></term>
 442             <listitem><para>Error on XML level.</para></listitem>
 443           </varlistentry>
 444
 445           <varlistentry>
 446             <term><errorname>IE_ISDS</errorname></term>
 447             <listitem><para>Problem with <abbrev>ISDS</abbrev> server.</para></listitem>
 448           </varlistentry>
 449
 450           <varlistentry>
 451             <term><errorname>IE_ENUM</errorname></term>
 452             <listitem><para>Invalid enum value.</para></listitem>
 453           </varlistentry>
 454
 455           <varlistentry>
 456             <term><errorname>IE_DATE</errorname></term>
 457             <listitem><para>Invalid date value.</para></listitem>
 458           </varlistentry>
 459
 460           <varlistentry>
 461             <term><errorname>IE_2BIG</errorname></term>
 462             <listitem><para>Value is too big.</para></listitem>
 463           </varlistentry>
 464
 465           <varlistentry>
 466             <term><errorname>IE_2SMALL</errorname></term>
 467             <listitem><para>Value is too small.</para></listitem>
 468           </varlistentry>
 469
 470           <varlistentry>
 471             <term><errorname>IE_NOTUNIQ</errorname></term>
 472             <listitem><para>Value is not uniq.</para></listitem>
 473           </varlistentry>
 474
 475           <varlistentry>
 476             <term><errorname>IE_NOTEQUAL</errorname></term>
 477             <listitem><para>Compared values are not equal.</para></listitem>
 478           </varlistentry>
 479
 480           <varlistentry>
 481             <term><errorname>IE_PARTIAL_SUCCESS</errorname></term>
 482             <listitem><para>Operaration on a vector succeded for some values, but failed for others.</para></listitem>
 483           </varlistentry>
 484
 485           <varlistentry>
 486             <term><errorname>IE_ABORTED</errorname></term>
 487             <listitem><para>Operation was aborted by application request.</para></listitem>
 488           </varlistentry>
 489
 490           <varlistentry>
 491             <term><errorname>IE_SECURITY</errorname></term>
 492             <listitem><para>Security requirements were not satisfied.</para></listitem>
 493           </varlistentry>
 494         </variablelist>
 495       </refsection>
 496
 497       <refsection>
 498         <title><type>isds_log_level</type></title>
 499         <synopsis>typedef enum <type>isds_log_level</type>;</synopsis>
 500         <para>Log level. Know values:</para>
 501         <variablelist>
 502           <varlistentry>
 503             <term><constant>ILL_NONE</constant></term>
 504             <listitem><para>0</para></listitem>
 505           </varlistentry>
 506
 507           <varlistentry>
 508             <term><constant>ILL_CRIT</constant></term>
 509             <listitem><para>10</para></listitem>
 510           </varlistentry>
 511
 512           <varlistentry>
 513             <term><constant>ILL_ERR</constant></term>
 514             <listitem><para>20</para></listitem>
 515           </varlistentry>
 516
 517           <varlistentry>
 518             <term><constant>ILL_WARNING</constant></term>
 519             <listitem><para>30</para></listitem>
 520           </varlistentry>
 521
 522           <varlistentry>
 523             <term><constant>ILL_INFO</constant></term>
 524             <listitem><para>40</para></listitem>
 525           </varlistentry>
 526
 527           <varlistentry>
 528             <term><constant>ILL_DEBUG</constant></term>
 529             <listitem><para>50</para></listitem>
 530           </varlistentry>
 531
 532           <varlistentry>
 533             <term><constant>ILL_ALL</constant></term>
 534             <listitem><para>100</para></listitem>
 535           </varlistentry>
 536         </variablelist>
 537       </refsection>
 538
 539       <refsection>
 540         <title><type>isds_log_facility</type></title>
 541         <synopsis>typedef enum <type>isds_log_facility</type>;</synopsis>
 542         <para>Log facility. Know values:</para>
 543         <variablelist>
 544           <varlistentry>
 545             <term><constant>ILF_NONE</constant></term>
 546             <listitem><para>0x0</para></listitem>
 547           </varlistentry>
 548
 549           <varlistentry>
 550             <term><constant>ILF_HTTP</constant></term>
 551             <listitem><para>0x1</para></listitem>
 552           </varlistentry>
 553
 554           <varlistentry>
 555             <term><constant>ILF_SOAP</constant></term>
 556             <listitem><para>0x2</para></listitem>
 557           </varlistentry>
 558
 559           <varlistentry>
 560             <term><constant>ILF_ISDS</constant></term>
 561             <listitem><para>0x4</para></listitem>
 562           </varlistentry>
 563
 564           <varlistentry>
 565             <term><constant>ILF_FILE</constant></term>
 566             <listitem><para>0x8</para></listitem>
 567           </varlistentry>
 568
 569           <varlistentry>
 570             <term><constant>ILF_SEC</constant></term>
 571             <listitem><para>0x10</para></listitem>
 572           </varlistentry>
 573
 574           <varlistentry>
 575             <term><constant>ILF_XML</constant></term>
 576             <listitem><para>0x20</para></listitem>
 577           </varlistentry>
 578
 579           <varlistentry>
 580             <term><constant>ILF_ALL</constant></term>
 581             <listitem><para>0xFF</para></listitem>
 582           </varlistentry>
 583         </variablelist>
 584       </refsection>
 585
 586       <refsection>
 587         <title><type>isds_option</type></title>
 588         <synopsis>typedef enum <type>isds_option</type>;</synopsis>
 589         <para>libisds option identifiers. Known values:</para>
 590         <variablelist>
 591           <varlistentry>
 592             <term><constant>IOPT_TLS_VERIFY_SERVER</constant></term>
 593             <listitem><para>Option type is <type>_Bool</type>. Whether to
 594                 verify server identity. Default value is
 595                 true.</para></listitem>
 596           </varlistentry>
 597
 598           <varlistentry>
 599             <term><constant>IOPT_TLS_CA_FILE</constant></term>
 600             <listitem><para>Option type is <type>char *</type>. Option value
 601                 is a file name with certificate authority
 602                 certificates. Default value depends on used cryptographic
 603                 library.</para></listitem>
 604           </varlistentry>
 605
 606           <varlistentry>
 607             <term><constant>IOPT_TLS_CA_DIRECTORY</constant></term>
 608             <listitem><para>Option type is <type>char *</type>, Option value
 609                 is a directory with certificate authority certificates.
 610                 Default value depends on used cryptographic
 611                 library.</para></listitem>
 612           </varlistentry>
 613
 614           <varlistentry>
 615             <term><constant>IOPT_TLS_CRL_FILE</constant></term>
 616             <listitem><para>Option type is <type>char *</type>. Option value
 617                 is a file name with certificat revocation list in
 618                 <abbrev>PEM</abbrev> format. Default value depends on used
 619                 cryptographic library.</para></listitem>
 620           </varlistentry>
 621
 622           <varlistentry>
 623             <term><constant>IOPT_NORMALIZE_MIME_TYPE</constant></term>
 624             <listitem><para>Optiona type is <type>_Bool</type>. Whether to
 625                 normalize <abbrev>MIME</abbrev> type values. Default value is
 626                 false.</para></listitem>
 627           </varlistentry>
 628         </variablelist>
 629       </refsection>
 630
 631       <refsection>
 632         <title><type>isds_tls_option</type></title>
 633         <synopsis>typedef enum <type>isds_tls_option</type>;</synopsis>
 634         <warning><para>This type is deprecated.</para></warning>
 635         <para><abbrev>TLS</abbrev> libisds option identifiers. Known values:</para>
 636         <variablelist>
 637           <varlistentry>
 638             <term><constant>ITLS_VERIFY_SERVER</constant></term>
 639             <listitem><para>Option type is <type>_Bool</type>. Whether to
 640                 verify server identity.</para></listitem>
 641           </varlistentry>
 642
 643           <varlistentry>
 644             <term><constant>ITLS_CA_FILE</constant></term>
 645             <listitem><para>Option type is <type>char *</type>. Option value
 646                 is a file name with certificate authority
 647                 certificates.</para></listitem>
 648           </varlistentry>
 649
 650           <varlistentry>
 651             <term><constant>ITLS_CA_DIRECTORY</constant></term>
 652             <listitem><para>Option type is <type>char *</type>. Option value
 653                 is a directory name with certificate authority
 654                 certificates.</para></listitem>
 655           </varlistentry>
 656
 657           <varlistentry>
 658             <term><constant>ITLS_CRL_FILE</constant></term>
 659             <listitem><para>Option type is <type>char *</type>. Option value
 660                 is a file name with certificate revocation list in
 661                 <abbrev>PEM</abbrev> format.</para></listitem>
 662           </varlistentry>
 663         </variablelist>
 664       </refsection>
 665
 666       <refsection>
 667         <title><type>isds_pki_format</type></title>
 668         <synopsis>typedef enum <type>isds_pki_format</type>;</synopsis>
 669         <para>Cryptographic material encoding. Known values:</para>
 670         <variablelist>
 671           <varlistentry>
 672             <term><constant>PKI_FORMAT_PEM</constant></term>
 673             <listitem><para><abbrev>PEM</abbrev> format.</para></listitem>
 674           </varlistentry>
 675
 676           <varlistentry>
 677             <term><constant>PKI_FORMAT_DER</constant></term>
 678             <listitem><para><abbrev>DER format.</abbrev></para></listitem>
 679           </varlistentry>
 680
 681           <varlistentry>
 682             <term><constant>PKI_FORMAT_ENG</constant></term>
 683             <listitem><para>The material is stored in a cryptographic engine.</para></listitem>
 684           </varlistentry>
 685         </variablelist>
 686       </refsection>
 687
 688       <refsection>
 689         <title>struct <structname>isds_pki_credentials</structname></title>
 690         <synopsis>struct <structname>isds_pki_credentials</structname>;</synopsis>
 691         <para>This structure holds public key infrastructure cryptographic
 692           material to authenticate a client. Members are:</para>
 693         <variablelist>
 694           <varlistentry>
 695             <term><type>char *</type><structfield>engine</structfield>;</term>
 696             <listitem><para>String identifier of cryptographic engine to use
 697                 (where key is stored). Use NULL for no
 698                 engine.</para></listitem>
 699           </varlistentry>
 700
 701           <varlistentry>
 702             <term><type>isds_pki_format</type> <structfield>certificate_format</structfield>;</term>
 703             <listitem><para>Certificate format.</para></listitem>
 704           </varlistentry>
 705
 706           <varlistentry>
 707             <term><type>char *</type><structfield>certificate</structfield>;</term>
 708             <listitem><para>A path to client certificate, or a certificate
 709                 nickname in case of <abbrev>NSS</abbrev> as curl back-end, or
 710                 key slot identifier inside cryptographic engine. Some
 711                 cryptographinc engines can pair certificate with key
 712                 automatically (NULL value).</para></listitem>
 713           </varlistentry>
 714
 715           <varlistentry>
 716             <term><type>isds_pki_format</type> <structfield>key_format</structfield>;</term>
 717             <listitem><para>Private key format.</para></listitem>
 718           </varlistentry>
 719
 720           <varlistentry>
 721             <term><type>char *</type><structfield>key</structfield>;</term>
 722             <listitem><para>A path to client private key, or key identifier in
 723                 case an engine is used.</para></listitem>
 724           </varlistentry>
 725
 726           <varlistentry>
 727             <term><type>char *</type><structfield>passphrase</structfield>;</term>
 728             <listitem><para>Zero terminated string with password for
 729                 decrypting private key, or engine <abbrev>PIN</abbrev>. Use
 730                 NULL for no pass-phrase or to let the engine to ask for
 731                 it.</para></listitem>
 732           </varlistentry>
 733         </variablelist>
 734       </refsection>
 735
 736       <refsection>
 737         <title><type>isds_otp_method</type></title>
 738         <synopsis>typedef enum <type>isds_otp_method</type>;</synopsis>
 739         <para>One-time password authentication method. Known values:</para>
 740         <variablelist>
 741           <varlistentry>
 742             <term><constant>OTP_HMAC</constant></term>
 743             <listitem><para><abbrev>HMAC</abbrev>-based <abbrev>OTP</abbrev> method.</para></listitem>
 744           </varlistentry>
 745
 746           <varlistentry>
 747             <term><constant>OTP_TIME</constant></term>
 748             <listitem><para>Time-based <abbrev>OTP</abbrev> method.</para></listitem>
 749           </varlistentry>
 750         </variablelist>
 751       </refsection>
 752
 753       <refsection>
 754         <title><type>isds_otp_resolution</type></title>
 755         <synopsis>typedef enum <type>isds_otp_resolution</type>;</synopsis>
 756         <para>One-time password authentication resolution. Known values:</para>
 757         <variablelist>
 758           <varlistentry>
 759             <term><constant>OTP_RESOLUTION_SUCCESS</constant></term>
 760             <listitem><para>Authentication succeded.</para></listitem>
 761           </varlistentry>
 762
 763           <varlistentry>
 764             <term><constant>OTP_RESOLUTION_UNKNOWN</constant></term>
 765             <listitem><para>Status is unkown.</para></listitem>
 766           </varlistentry>
 767
 768           <varlistentry>
 769             <term><constant>OTP_RESOLUTION_BAD_AUTHENTICATION</constant></term>
 770             <listitem><para>Bad log-in. You can retry to log in.</para></listitem>
 771           </varlistentry>
 772
 773           <varlistentry>
 774             <term><constant>OTP_RESOLUTION_ACCESS_BLOCKED</constant></term>
 775             <listitem><para>Access blocked for 60 minutes. (Because a brute
 776                 force attack was detected.)</para></listitem>
 777           </varlistentry>
 778
 779           <varlistentry>
 780             <term><constant>OTP_RESOLUTION_PASSWORD_EXPIRED</constant></term>
 781             <listitem>
 782               <para>Password has expired.</para>
 783               <note>
 784                 <para>It's not clear which password expired:
 785                   <abbrev>OTP</abbrev> or regular password?</para>
 786               </note>
 787             </listitem>
 788           </varlistentry>
 789
 790           <varlistentry>
 791             <term><constant>OTP_RESOLUTION_TO_FAST</constant></term>
 792             <listitem><para><abbrev>OTP</abbrev> cannot be sent repeatedly at
 793                 this rate. (Minimal delay depends on <abbrev>TOTP</abbrev>
 794                 window setting.)</para></listitem>
 795           </varlistentry>
 796
 797           <varlistentry>
 798             <term><constant>OTP_RESOLUTION_UNAUTHORIZED</constant></term>
 799             <listitem><para>User name is not allowed to access requested
 800                 <abbrev>URI</abbrev>.</para></listitem>
 801           </varlistentry>
 802
 803           <varlistentry>
 804             <term><constant>OTP_RESOLUTION_TOTP_SENT</constant></term>
 805             <listitem><para><abbrev>OTP</abbrev> has been generated and sent
 806                 by the <abbrev>ISDS</abbrev> to the user.</para></listitem>
 807           </varlistentry>
 808
 809           <varlistentry>
 810             <term><constant>OTP_RESOLUTION_TOTP_NOT_SENT</constant></term>
 811             <listitem><para><abbrev>OTP</abbrev> could not been sent by the
 812                 <abbrev>ISDS</abbrev>. Retry later.</para></listitem>
 813           </varlistentry>
 814         </variablelist>
 815       </refsection>
 816
 817       <refsection>
 818         <title>struct <structname>isds_otp</structname></title>
 819         <synopsis>struct <structname>isds_otp</structname>;</synopsis>
 820         <para>This structure holds one-time password when authenticating
 821           a client and resolution of the authentication.</para>
 822
 823         <para>Input members are:</para>
 824         <variablelist>
 825           <varlistentry>
 826             <term><type>isds_otp_method</type> <structfield>method</structfield>;</term>
 827             <listitem><para>Select <abbrev>OTP</abbrev> method to use.</para></listitem>
 828           </varlistentry>
 829
 830           <varlistentry>
 831             <term><type>char *</type><structfield>otp_code</structfield>;</term>
 832             <listitem><para>One-time password to use. Pass NULL, if you do not
 833                 know it yet (<abbrev>e.g.</abbrev> in case of first phase of
 834                 time-based <abbrev>OTP</abbrev> authentication to request new
 835                 code from <abbrev>ISDS</abbrev>.)</para></listitem>
 836           </varlistentry>
 837         </variablelist>
 838
 839         <para>Output members are:</para>
 840         <variablelist>
 841           <varlistentry>
 842             <term><type>isds_otp_resolution</type> <structfield>resolution</structfield>;</term>
 843             <listitem><para>Fine-grade resolution of this <abbrev>OTP</abbrev>
 844                 authentication attempt.</para></listitem>
 845           </varlistentry>
 846         </variablelist>
 847       </refsection>
 848
 849       <refsection>
 850         <title><type>isds_DbType</type></title>
 851         <synopsis>typedef enum <type>isds_DbType</type>;</synopsis>
 852         <para>Box type. It classifies box owner by his legal status. Known
 853           values:</para>
 854         <variablelist>
 855           <varlistentry>
 856             <term><constant>DBTYPE_OVM_MAIN</constant></term>
 857             <listitem><para>This is a special value for
 858                 <function>isds_find_box_by_fulltext</function>.
 859                 It's not accepted by any other
 860                 <abbrev>services</abbrev>.</para></listitem>
 861           </varlistentry>
 862
 863           <varlistentry>
 864             <term><constant>DBTYPE_SYSTEM</constant></term>
 865             <listitem><para>This is a special value for sender of messages sent
 866                 by the <abbrev>ISDS</abbrev>. You can find it only in
 867                 incomming messages. It's not accepted by any other
 868                 <abbrev>services</abbrev>.</para></listitem>
 869           </varlistentry>
 870
 871           <varlistentry>
 872             <term><constant>DBTYPE_OVM</constant></term>
 873             <listitem><para>Standard government (state or municipality or
 874                 similar) office.</para></listitem>
 875           </varlistentry>
 876
 877           <varlistentry>
 878             <term><constant>DBTYPE_OVM_NOTAR</constant></term>
 879             <listitem><para>Notary.</para></listitem>
 880           </varlistentry>
 881
 882           <varlistentry>
 883             <term><constant>DBTYPE_OVM_EXEKUT</constant></term>
 884             <listitem><para>Executor.</para></listitem>
 885           </varlistentry>
 886
 887           <varlistentry>
 888             <term><constant>DBTYPE_OVM_REQ</constant></term>
 889             <listitem><para>Subsidiary office with <abbrev>OVM</abbrev>
 890                 (governing) status assigned on request (section 6 and 7 of the
 891                 act).</para></listitem>
 892           </varlistentry>
 893
 894           <varlistentry>
 895             <term><constant>DBTYPE_PO</constant></term>
 896             <listitem><para>Standard commercial organization (listed in trade
 897                 registry).</para></listitem>
 898           </varlistentry>
 899
 900           <varlistentry>
 901             <term><constant>DBTYPE_PO_ZAK</constant></term>
 902             <listitem><para>Other organization founded by an act.</para></listitem>
 903           </varlistentry>
 904
 905           <varlistentry>
 906             <term><constant>DBTYPE_PO_REQ</constant></term>
 907             <listitem><para>An organization with a box assigned on its
 908                 request.</para></listitem>
 909           </varlistentry>
 910
 911           <varlistentry>
 912             <term><constant>DBTYPE_PFO</constant></term>
 913             <listitem><para>Person in bussiness.</para></listitem>
 914           </varlistentry>
 915
 916           <varlistentry>
 917             <term><constant>DBTYPE_PFO_ADVOK</constant></term>
 918             <listitem><para>Lawyer.</para></listitem>
 919           </varlistentry>
 920
 921           <varlistentry>
 922             <term><constant>DBTYPE_PFO_DANPOR</constant></term>
 923             <listitem><para>Tax consultant.</para></listitem>
 924           </varlistentry>
 925
 926           <varlistentry>
 927             <term><constant>DBTYPE_PFO_INSSPR</constant></term>
 928             <listitem><para>Administrator of insolvency.</para></listitem>
 929           </varlistentry>
 930
 931           <varlistentry>
 932             <term><constant>DBTYPE_FO</constant></term>
 933             <listitem><para>Standard person.</para></listitem>
 934           </varlistentry>
 935         </variablelist>
 936
 937         <para>Some interfaces refer to <emphasis>gross</emphasis> box type.
 938           These are the shortest names of the identifiers. For example,
 939           <literal>DBTYPE_OVM</literal> is a gross type for
 940           <literal>DB_OVM_NOTAR</literal> or <literal>DBTYPE_OVM</literal>.
 941           But not for <literal>DBTYPE_PO</literal>.</para>
 942       </refsection>
 943
 944       <refsection>
 945         <title><type>isds_DbState</type></title>
 946         <synopsis>typedef enum <type>isds_DbState</type>;</synopsis>
 947         <para>Box status from point of view of accessibility. Known
 948           values:</para>
 949         <variablelist>
 950           <varlistentry>
 951             <term><constant>DBSTATE_ACCESSIBLE</constant></term>
 952             <listitem><para>The box is accessible.</para></listitem>
 953           </varlistentry>
 954
 955           <varlistentry>
 956             <term><constant>DBSTATE_TEMP_UNACCESSIBLE</constant></term>
 957             <listitem><para>The box is temporarily inaccessible.</para></listitem>
 958           </varlistentry>
 959
 960           <varlistentry>
 961             <term><constant>DBSTATE_NOT_YET_ACCESSIBLE</constant></term>
 962             <listitem><para>The box has not yet been activated.</para></listitem>
 963           </varlistentry>
 964
 965           <varlistentry>
 966             <term><constant>DBSTATE_PERM_UNACCESSIBLE</constant></term>
 967             <listitem><para>The box is permanently inaccessible.</para></listitem>
 968           </varlistentry>
 969
 970           <varlistentry>
 971             <term><constant>DBSTATE_REMOVED</constant></term>
 972             <listitem><para>The box has been removed.</para></listitem>
 973           </varlistentry>
 974         </variablelist>
 975       </refsection>
 976
 977       <refsection>
 978         <title><type>isds_priviledges</type></title>
 979         <synopsis>typedef enum <type>isds_priviledges</type>;</synopsis>
 980         <para>Distinct user permissions from point of view of <abbrev>ISDS</abbrev>.
 981           Instances can be bitmaps of any of these distinct values. Distinct known
 982           values are:</para>
 983         <variablelist>
 984           <varlistentry>
 985             <term><constant>PRIVIL_READ_NON_PERSONAL</constant></term>
 986             <listitem><para>The user can download and read messages with
 987                 <structfield>dmPersonalDelivery</structfield> equaled to
 988                 false.</para></listitem>
 989           </varlistentry>
 990
 991           <varlistentry>
 992             <term><constant>PRIVIL_READ_ALL</constant></term>
 993             <listitem><para>The user can download and read messages with
 994                 <structfield>dmPersonalDelivery</structfield> equaled to
 995                 true.</para></listitem>
 996           </varlistentry>
 997
 998           <varlistentry>
 999             <term><constant>PRIVIL_CREATE_DM</constant></term>
1000             <listitem><para>The user can create and send messages, the user
1001                 can download outgoing (sent) messages.</para></listitem>
1002           </varlistentry>
1003
1004           <varlistentry>
1005             <term><constant>PRIVIL_VIEW_INFO</constant></term>
1006             <listitem><para>The user can list messages and read data about
1007                 a message post and delivery.</para></listitem>
1008           </varlistentry>
1009
1010           <varlistentry>
1011             <term><constant>PRIVIL_SEARCH_DB</constant></term>
1012             <listitem><para>The user can can search for
1013                 boxes.</para></listitem>
1014           </varlistentry>
1015
1016           <varlistentry>
1017             <term><constant>PRIVIL_OWNER_ADM</constant></term>
1018             <listitem><para>The user can administer his box (to add and remove
1019                 permitted users and to modify theirs
1020                 permissions.)</para></listitem>
1021           </varlistentry>
1022
1023           <varlistentry>
1024             <term><constant>PRIVIL_READ_VAULT</constant></term>
1025             <listitem>
1026               <para>The user can read messages stored in the long term storage.</para>
1027               <note><para>This permission is not used since 2012-05.</para></note>
1028             </listitem>
1029           </varlistentry>
1030
1031           <varlistentry>
1032             <term><constant>PRIVIL_ERASE_VAULT</constant></term>
1033             <listitem><para>The user can delete messages from the long term
1034                 storage.</para></listitem>
1035           </varlistentry>
1036         </variablelist>
1037       </refsection>
1038
1039       <refsection>
1040         <title><type>isds_message_status</type></title>
1041         <synopsis>typedef enum <type>isds_message_status</type>;</synopsis>
1042         <para>Message status. Known values are:</para>
1043         <variablelist>
1044           <varlistentry>
1045             <term><constant>MESSAGESTATE_SENT</constant></term>
1046             <listitem><para>The message has been put into
1047                 <abbrev>ISDS</abbrev>.</para></listitem>
1048           </varlistentry>
1049
1050           <varlistentry>
1051             <term><constant>MESSAGESTATE_STAMPED</constant></term>
1052             <listitem><para>Message was stamped by a time stamp
1053                 authority.</para></listitem>
1054           </varlistentry>
1055
1056           <varlistentry>
1057             <term><constant>MESSAGESTATE_INFECTED</constant></term>
1058             <listitem><para>The message included viruses. Infected documents
1059                 have been removed from the message.</para></listitem>
1060           </varlistentry>
1061
1062           <varlistentry>
1063             <term><constant>MESSAGESTATE_DELIVERED</constant></term>
1064             <listitem><para>The message was delivered.
1065                 (<structfield>dmDeliveryTime</structfield> is
1066                     populated.)</para></listitem>
1067           </varlistentry>
1068
1069           <varlistentry>
1070             <term><constant>MESSAGESTATE_SUBSTITUTED</constant></term>
1071             <listitem><para>The message was delivered through fiction,
1072                 <structfield>dmAcceptanceTime</structfield> is
1073                 populated.</para></listitem>
1074           </varlistentry>
1075
1076           <varlistentry>
1077             <term><constant>MESSAGESTATE_RECEIVED</constant></term>
1078             <listitem><para>The message was accepted (by user's log-in or
1079                 user's explicit request).
1080                 <structfield>dmAcceptanceTime</structfield> is
1081                 populated.</para></listitem>
1082           </varlistentry>
1083
1084           <varlistentry>
1085             <term><constant>MESSAGESTATE_READ</constant></term>
1086             <listitem><para>The message has been read by
1087                 a user.</para></listitem>
1088           </varlistentry>
1089
1090           <varlistentry>
1091             <term><constant>MESSAGESTATE_UNDELIVERABLE</constant></term>
1092             <listitem><para>The message could not been delivered.
1093                 (<abbrev>E.g.</abbrev>The recipient's box has been made
1094                 inaccessible meantime.)</para></listitem>
1095           </varlistentry>
1096
1097           <varlistentry>
1098             <term><constant>MESSAGESTATE_REMOVED</constant></term>
1099             <listitem><para>The message's content was
1100                 deleted.</para></listitem>
1101           </varlistentry>
1102
1103           <varlistentry>
1104             <term><constant>MESSAGESTATE_IN_SAFE</constant></term>
1105             <listitem><para>The message is stored in the long term
1106                 storage.</para></listitem>
1107           </varlistentry>
1108         </variablelist>
1109
1110         <para>The values can be combined into a bit mask for some functions.
1111           A special <constant>MESSAGESTATE_ANY</constant> macro denotes any of
1112           the states.</para>
1113       </refsection>
1114
1115       <refsection>
1116         <title><type>isds_hash_algorithm</type></title>
1117         <synopsis>typedef enum <type>isds_hash_algorithm</type>;</synopsis>
1118         <para>Hash algorithm types. Known values are:</para>
1119         <variablelist>
1120           <varlistentry>
1121             <term><constant>HASH_ALGORITHM_MD5</constant></term>
1122             <listitem><para><abbrev>MD5</abbrev>.</para></listitem>
1123           </varlistentry>
1124
1125           <varlistentry>
1126             <term><constant>HASH_ALGORITHM_SHA_1</constant></term>
1127             <listitem><para><abbrev>SHA-1</abbrev>.</para></listitem>
1128           </varlistentry>
1129
1130           <varlistentry>
1131             <term><constant>HASH_ALGORITHM_SHA_224</constant></term>
1132             <listitem><para><abbrev>SHA-224</abbrev>.</para></listitem>
1133           </varlistentry>
1134
1135           <varlistentry>
1136             <term><constant>HASH_ALGORITHM_SHA_256</constant></term>
1137             <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1138           </varlistentry>
1139
1140           <varlistentry>
1141             <term><constant>HASH_ALGORITHM_SHA_384</constant></term>
1142             <listitem><para><abbrev>SHA-384</abbrev>.</para></listitem>
1143           </varlistentry>
1144
1145           <varlistentry>
1146             <term><constant>HASH_ALGORITHM_SHA_512</constant></term>
1147             <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1148           </varlistentry>
1149         </variablelist>
1150       </refsection>
1151
1152       <refsection>
1153         <title><type>isds_buffer_strategy</type></title>
1154         <synopsis>typedef enum <type>isds_buffer_strategy</type>;</synopsis>
1155         <para>Buffer storage strategy. This type defines how a function should
1156           embed application provided buffer into
1157           <structfield>raw</structfield> element of output structure. Known
1158           values are:</para>
1159         <variablelist>
1160           <varlistentry>
1161             <term><constant>BUFFER_DONT_STORE</constant></term>
1162             <listitem><para>Don't fill <structfield>raw</structfield>
1163                 member.</para></listitem>
1164           </varlistentry>
1165
1166           <varlistentry>
1167             <term><constant>BUFFER_COPY</constant></term>
1168             <listitem><para>Copy buffer content into newly allocated
1169                 <structfield>raw</structfield> member.</para></listitem>
1170           </varlistentry>
1171
1172           <varlistentry>
1173             <term><constant>BUFFER_MOVE</constant></term>
1174             <listitem><para>Copy pointer. Leave deallocation to structure
1175                 destructor
1176                 (<function>isds_*_free</function>()).</para></listitem>
1177           </varlistentry>
1178         </variablelist>
1179       </refsection>
1180
1181       <refsection>
1182         <title>struct <structname>isds_hash</structname></title>
1183         <synopsis>struct <structname>isds_hash</structname>;</synopsis>
1184         <para>This is a hash value storage. Members are:</para>
1185         <variablelist>
1186           <varlistentry>
1187             <term><type>isds_hash_algorithm</type>
1188               <structfield>algorithm</structfield>;</term>
1189             <listitem><para>Hash algorithm.</para></listitem>
1190           </varlistentry>
1191
1192           <varlistentry>
1193             <term><type>size_t</type> <structfield>length</structfield>;</term>
1194             <listitem><para>Hash value length in bytes.</para></listitem>
1195           </varlistentry>
1196
1197           <varlistentry>
1198             <term><type>void *</type><structfield>value</structfield>;</term>
1199             <listitem><para>Hash value as a byte stream.</para></listitem>
1200           </varlistentry>
1201         </variablelist>
1202       </refsection>
1203
1204       <refsection>
1205         <title>struct <structname>isds_PersonName</structname></title>
1206         <synopsis>struct <structname>isds_PersonName</structname>;</synopsis>
1207         <para>Name of a person. Members are:</para>
1208         <variablelist>
1209           <varlistentry>
1210             <term><type>char *</type><structfield>pnFirstName</structfield>;</term>
1211             <listitem><para>First name.</para></listitem>
1212           </varlistentry>
1213
1214           <varlistentry>
1215             <term><type>char *</type><structfield>pnMiddleName</structfield>;</term>
1216             <listitem><para>Middle name.</para></listitem>
1217           </varlistentry>
1218
1219           <varlistentry>
1220             <term><type>char *</type><structfield>pnLastName</structfield>;</term>
1221             <listitem><para>Current last name.</para></listitem>
1222           </varlistentry>
1223
1224           <varlistentry>
1225             <term><type>char *</type><structfield>pnLastNameAtBirth</structfield>;</term>
1226             <listitem><para>Last name at birth.</para></listitem>
1227           </varlistentry>
1228         </variablelist>
1229       </refsection>
1230
1231       <refsection>
1232         <title>struct <structname>isds_BirthInfo</structname></title>
1233         <synopsis>struct <structname>isds_BirthInfo</structname>;</synopsis>
1234         <para>Date and place of a birth. Members are:</para>
1235         <variablelist>
1236           <varlistentry>
1237             <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1238             <listitem><para>Date of birth in local time at the birth place.
1239                 Only <structfield>tm_year</structfield>,
1240                 <structfield>tm_mon</structfield> and
1241                 <structfield>tm_mday</structfield> members of the <type>struct
1242                   tm</type> carry sane value. Others are
1243                 undefined.</para></listitem>
1244           </varlistentry>
1245
1246           <varlistentry>
1247             <term><type>char *</type><structfield>biCity</structfield>;</term>
1248             <listitem><para>City where a person was born.</para></listitem>
1249           </varlistentry>
1250
1251           <varlistentry>
1252             <term><type>char *</type><structfield>biCounty</structfield>;</term>
1253             <listitem><para>Region where a person was born. This is the kind
1254                 of region that is called <foreignphrase
1255                   lang="de">Bezirk</foreignphrase> in
1256                 German and <foreignphrase lang="cs">okres</foreignphrase> in
1257                 Czech.</para></listitem>
1258           </varlistentry>
1259
1260           <varlistentry>
1261             <term><type>char *</type><structfield>biState</structfield>;</term>
1262             <listitem><para>State wher a person was born.</para></listitem>
1263           </varlistentry>
1264         </variablelist>
1265       </refsection>
1266
1267       <refsection>
1268         <title>struct <structname>isds_Address</structname></title>
1269         <synopsis>struct <structname>isds_Address</structname>;</synopsis>
1270         <para>Postal address. Members are:</para>
1271         <variablelist>
1272           <varlistentry>
1273             <term><type>long int *</type><structfield>adCode</structfield>;</term>
1274             <listitem><para><abbrev>RUIN</abbrev> address code.</para></listitem>
1275           </varlistentry>
1276
1277           <varlistentry>
1278             <term><type>char *</type><structfield>adCity</structfield>;</term>
1279             <listitem><para>City.</para></listitem>
1280           </varlistentry>
1281
1282           <varlistentry>
1283             <term><type>char *</type><structfield>adDistrict</structfield>;</term>
1284             <listitem><para>Municipality part.</para></listitem>
1285           </varlistentry>
1286
1287           <varlistentry>
1288             <term><type>char *</type><structfield>adStreet</structfield>;</term>
1289             <listitem><para>Street.</para></listitem>
1290           </varlistentry>
1291
1292           <varlistentry>
1293             <term><type>char *</type><structfield>adNumberInStreet</structfield>;</term>
1294             <listitem><para>Identification of an entrance on the
1295                 street. <foreignphrase lang="cs">Číslo
1296                   orientační</foreignphrase> in Czech.</para></listitem>
1297           </varlistentry>
1298
1299           <varlistentry>
1300             <term><type>char *</type><structfield>adNumberInMunicipality</structfield>;</term>
1301             <listitem><para>Identification of a building in the municipality.
1302                 <foreignphrase lang="cs">Číslo popisné</foreignphrase> in
1303                 Czech.</para></listitem>
1304           </varlistentry>
1305
1306           <varlistentry>
1307             <term><type>char *</type><structfield>adZipCode</structfield>;</term>
1308             <listitem><para>Postal code for mail routing.</para></listitem>
1309           </varlistentry>
1310
1311           <varlistentry>
1312             <term><type>char *</type><structfield>adState</structfield>;</term>
1313             <listitem><para>State.</para></listitem>
1314           </varlistentry>
1315         </variablelist>
1316       </refsection>
1317
1318       <refsection>
1319         <title>struct <structname>isds_DbOwnerInfo</structname></title>
1320         <synopsis>struct <structname>isds_DbOwnerInfo</structname>;</synopsis>
1321         <para>Data about a box and his owner. NULL pointer values mean
1322           undefined values. Members are:</para>
1323         <variablelist>
1324           <varlistentry>
1325             <term><type>char *</type><structfield>dbID</structfield>;</term>
1326             <listitem><para>Box identifier. Specification limits the length to
1327                 7 characters.</para></listitem>
1328           </varlistentry>
1329
1330           <varlistentry>
1331             <term><type>isds_DbType *</type><structfield>dbType</structfield>;</term>
1332             <listitem><para>Box type.</para></listitem>
1333           </varlistentry>
1334
1335           <varlistentry>
1336             <term><type>char *</type><structfield>ic</structfield>;</term>
1337             <listitem><para>Identifier of the owner.</para></listitem>
1338           </varlistentry>
1339
1340           <varlistentry>
1341             <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1342             <listitem><para>Name of a person owning the box.</para></listitem>
1343           </varlistentry>
1344
1345           <varlistentry>
1346             <term><type>char *</type><structfield>firmName</structfield>;</term>
1347             <listitem><para>Name of a firm owning the box.</para></listitem>
1348           </varlistentry>
1349
1350           <varlistentry>
1351             <term><type>isds_BirthInfo *</type><structfield>birthInfo</structfield>;</term>
1352             <listitem><para>Birth details of the person.</para></listitem>
1353           </varlistentry>
1354
1355           <varlistentry>
1356             <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1357             <listitem><para>Postal address of the owner.</para></listitem>
1358           </varlistentry>
1359
1360           <varlistentry>
1361             <term><type>char *</type><structfield>nationality</structfield>;</term>
1362             <listitem><para>Nationality of the owner.</para></listitem>
1363           </varlistentry>
1364
1365           <varlistentry>
1366             <term><type>char *</type><structfield>email</structfield>;</term>
1367             <listitem><para>E-mail addres of the owner.</para></listitem>
1368           </varlistentry>
1369
1370           <varlistentry>
1371             <term><type>char *</type><structfield>telNumber</structfield>;</term>
1372             <listitem><para>Telephone number of the owner.</para></listitem>
1373           </varlistentry>
1374
1375           <varlistentry>
1376             <term><type>char *</type><structfield>identifier</structfield>;</term>
1377             <listitem><para>External box identifier for data provider
1378                 (<abbrev>OVM</abbrev>, <abbrev>PO</abbrev>, maybe
1379                 <abbrev>PFO</abbrev> box types.) Specification limits the
1380                 length to 20 characters.</para></listitem>
1381           </varlistentry>
1382
1383           <varlistentry>
1384             <term><type>_Bool *</type><structfield>aifoIsds</structfield>;</term>
1385             <listitem><para>Reference to citizen registry exists.</para></listitem>
1386           </varlistentry>
1387
1388           <varlistentry>
1389             <term><type>char *</type><structfield>registryCode</structfield>;</term>
1390             <listitem><para><abbrev>PFO</abbrev> external registry code.
1391                 Specification limits the length to
1392                 5 characters.</para></listitem>
1393           </varlistentry>
1394
1395           <varlistentry>
1396             <term><type>long int *</type><structfield>dbState</structfield>;</term>
1397             <listitem>
1398               <para>Box state. 1 means the box is active.</para>
1399               <note><para>The type is long int because specification declares it
1400                   as <type>xsd:integer</type>.</para></note>
1401               <note><para>TODO: enum?</para></note></listitem>
1402           </varlistentry>
1403
1404           <varlistentry>
1405             <term><type>_Bool *</type><structfield>dbEffectiveOVM</structfield>;</term>
1406             <listitem><para>The Box has <abbrev>OVM</abbrev> role (section 5a
1407                 of the act).</para></listitem>
1408           </varlistentry>
1409
1410           <varlistentry>
1411             <term><type>_Bool *</type><structfield>dbOpenAddressing</structfield>;</term>
1412             <listitem>This <para>non-<abbrev>OVM</abbrev> box is free to
1413                 receive messages from anybody.</para></listitem>
1414           </varlistentry>
1415         </variablelist>
1416       </refsection>
1417
1418       <refsection>
1419         <title><type>isds_UserType</type></title>
1420         <synopsis>typedef enum <type>isds_UserType</type>;</synopsis>
1421         <para>User type. Known values are:</para>
1422         <variablelist>
1423           <varlistentry>
1424             <term><constant>USERTYPE_PRIMARY</constant></term>
1425             <listitem><para>Owner of the box.</para></listitem>
1426           </varlistentry>
1427
1428           <varlistentry>
1429             <term><constant>USERTYPE_ENTRUSTED</constant></term>
1430             <listitem><para>User with limited access to the box.</para></listitem>
1431           </varlistentry>
1432
1433           <varlistentry>
1434             <term><constant>USERTYPE_ADMINISTRATOR</constant></term>
1435             <listitem><para>User who can manage
1436                 <constant>USERTYPE_ENTRUSTED</constant>
1437                 users.</para></listitem>
1438           </varlistentry>
1439
1440           <varlistentry>
1441             <term><constant>USERTYPE_OFFICIAL</constant></term>
1442             <listitem><para>???</para></listitem>
1443           </varlistentry>
1444
1445           <varlistentry>
1446             <term><constant>USERTYPE_OFFICIAL_CERT</constant></term>
1447             <listitem><para>???</para></listitem>
1448           </varlistentry>
1449
1450           <varlistentry>
1451             <term><constant>USERTYPE_LIQUIDATOR</constant></term>
1452             <listitem><para>Company liquidator.</para></listitem>
1453           </varlistentry>
1454         </variablelist>
1455       </refsection>
1456
1457       <refsection>
1458         <title>struct <structname>isds_DbUserInfo</structname></title>
1459         <synopsis>struct <structname>isds_DbUserInfo</structname>;</synopsis>
1460         <para>Data about a user. NULL pointer values mean
1461           undefined values. Members are:</para>
1462         <variablelist>
1463           <varlistentry>
1464             <term><type>char *</type><structfield>userID</structfield>;</term>
1465             <listitem><para>User identifier. Specification limits the length
1466                 from 6 to 12 characters.</para></listitem>
1467           </varlistentry>
1468
1469           <varlistentry>
1470             <term><type>isds_UserType *</type><structfield>userType</structfield>;</term>
1471             <listitem><para>User type.</para></listitem>
1472           </varlistentry>
1473
1474           <varlistentry>
1475             <term><type>long int *</type><structfield>userPrivils</structfield>;</term>
1476             <listitem><para>Set of user permissions.</para></listitem>
1477           </varlistentry>
1478
1479           <varlistentry>
1480             <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1481             <listitem><para>Name of the user.</para></listitem>
1482           </varlistentry>
1483
1484           <varlistentry>
1485             <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1486             <listitem><para>Postal address of the user.</para></listitem>
1487           </varlistentry>
1488
1489           <varlistentry>
1490             <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1491             <listitem><para>Date of birth in local time.
1492                 Only <structfield>tm_year</structfield>,
1493                 <structfield>tm_mon</structfield> and
1494                 <structfield>tm_mday</structfield> members of the <type>struct
1495                   tm</type> carry sane value. Others are
1496                 undefined.</para></listitem>
1497           </varlistentry>
1498
1499           <varlistentry>
1500             <term><type>char *</type><structfield>ic</structfield>;</term>
1501             <listitem><para>Identifier a supervising firm. Specification
1502                 limits the length to 8 characters.</para></listitem>
1503           </varlistentry>
1504
1505           <varlistentry>
1506             <term><type>char *</type><structfield>firmName</structfield>;</term>
1507             <listitem><para>Name of a supervising firm. Specification limits
1508                 the length to 100 characters.</para></listitem>
1509           </varlistentry>
1510
1511           <varlistentry>
1512             <term><type>char *</type><structfield>caStreet</structfield>;</term>
1513             <listitem><para>Contact address. Street and number.</para></listitem>
1514           </varlistentry>
1515
1516           <varlistentry>
1517             <term><type>char *</type><structfield>caCity</structfield>;</term>
1518             <listitem><para>Czech city of the contact address.</para></listitem>
1519           </varlistentry>
1520
1521           <varlistentry>
1522             <term><type>char *</type><structfield>caZipCode</structfield>;</term>
1523             <listitem><para>Postal code of the contact address.</para></listitem>
1524           </varlistentry>
1525
1526           <varlistentry>
1527             <term><type>char *</type><structfield>caState</structfield>;</term>
1528             <listitem><para>Abbreviated country of contact address. This value
1529                 is optional and implicit meaning is
1530                 <constant>CZ</constant>.</para></listitem>
1531           </varlistentry>
1532
1533           <varlistentry>
1534             <term><type>char *</type><structfield>aifo_ticket</structfield>;</term>
1535             <listitem><para>Reference to citizen registry. This value is
1536                 optional.</para></listitem>
1537           </varlistentry>
1538         </variablelist>
1539       </refsection>
1540
1541       <refsection>
1542         <title><type>isds_event_type</type></title>
1543         <synopsis>typedef enum <type>isds_event_type</type>;</synopsis>
1544         <para>Message event type. Known values are:</para>
1545         <variablelist>
1546           <varlistentry>
1547             <term><constant>EVENT_UKNOWN</constant></term>
1548             <listitem><para>Event uknown to this library.</para></listitem>
1549           </varlistentry>
1550
1551           <varlistentry>
1552             <term><constant>EVENT_ACCEPTED_BY_RECIPIENT</constant></term>
1553             <listitem><para>Message has been delivered and accepted by
1554                 recipient action.</para></listitem>
1555           </varlistentry>
1556
1557           <varlistentry>
1558             <term><constant>EVENT_ACCEPTED_BY_FICTION</constant></term>
1559             <listitem><para>Message has been delivered, acceptance period
1560                 timed out, the message is considered as
1561                 accepted.</para></listitem>
1562           </varlistentry>
1563
1564           <varlistentry>
1565             <term><constant>EVENT_UNDELIVERABLE</constant></term>
1566             <listitem><para>Recipient box was made inaccessible, thus the
1567                 message is undeliverable.</para></listitem>
1568           </varlistentry>
1569
1570           <varlistentry>
1571             <term><constant>EVENT_COMMERCIAL_ACCEPTED</constant></term>
1572             <listitem><para>Recipient confirmed acceptance of this commercial
1573                 message.</para></listitem>
1574           </varlistentry>
1575
1576           <varlistentry>
1577             <term><constant>EVENT_ENTERED_SYSTEM</constant></term>
1578             <listitem><para>The message entered the
1579                 <abbrev>ISDS</abbrev>system, <abbrev>i.e.</abbrev> it has been
1580                 just sent by a sender.</para></listitem>
1581           </varlistentry>
1582
1583           <varlistentry>
1584             <term><constant>EVENT_DELIVERED</constant></term>
1585             <listitem><para>The message has been delivered into recipient's
1586                 box.</para></listitem>
1587           </varlistentry>
1588
1589           <varlistentry>
1590             <term><constant>EVENT_PRIMARY_LOGIN</constant></term>
1591             <listitem><para>Primary user logged into recipent's
1592                 box.</para></listitem>
1593           </varlistentry>
1594
1595           <varlistentry>
1596             <term><constant>EVENT_ENTRUSTED_LOGIN</constant></term>
1597             <listitem><para>Entrusted user with capability to read logged
1598                 into recipient's box.</para></listitem>
1599           </varlistentry>
1600
1601           <varlistentry>
1602             <term><constant>EVENT_SYSCERT_LOGIN</constant></term>
1603             <listitem><para>An application authenticated by
1604                 <emphasis>system</emphasis> certificate logged into
1605                 recipient's box.</para></listitem>
1606           </varlistentry>
1607         </variablelist>
1608       </refsection>
1609
1610       <refsection>
1611         <title>struct <structname>isds_event</structname></title>
1612         <synopsis>struct <structname>isds_event</structname>;</synopsis>
1613         <para>An event that happened in a message life. All members are
1614           optional. Members are:</para>
1615         <variablelist>
1616           <varlistentry>
1617             <term><type>struct timeval *</type><structfield>time</structfield>;</term>
1618             <listitem><para>When the event occurred.</para></listitem>
1619           </varlistentry>
1620
1621           <varlistentry>
1622             <term><type>isds_event_type *</type><structfield>type</structfield>;</term>
1623             <listitem><para>Type of the envent.</para></listitem>
1624           </varlistentry>
1625
1626           <varlistentry>
1627             <term><type>charr *</type><structfield>description</structfield>;</term>
1628             <listitem><para>Human-readable event description generated by the
1629                 <abbrev>ISDS</abbrev> system. (Very probably in Czech
1630                 language).</para></listitem>
1631           </varlistentry>
1632         </variablelist>
1633       </refsection>
1634
1635       <refsection>
1636         <title>struct <structname>isds_envelope</structname></title>
1637         <synopsis>struct <structname>isds_envelope</structname>;</synopsis>
1638         <para>Message envelope. These are the metadata about a message. It
1639           does contain the message documents.</para>
1640         <para>Be ware that the string length constraints are forced only on
1641           output members transmitted to the <abbrev>ISDS</abbrev>. The other
1642           direction (downloading from the <abbrev>ISDS</abbrev>) can break
1643           these rules. It should not happen, but nobody knows how much
1644           incompatible new version of the <abbrev>ISDS</abbrev> protocol will
1645           be.  This is the gold Internet rule: be strict on what you send, be
1646           tolerant on what you receive.</para>
1647         <para>Following members apply to incoming messages only:</para>
1648         <variablelist>
1649           <varlistentry>
1650             <term><type>char *</type><structfield>dmID</structfield>;</term>
1651             <listitem><para>Message identifier. Maximal length is 20
1652                 characters.</para></listitem>
1653           </varlistentry>
1654
1655           <varlistentry>
1656             <term><type>char *</type><structfield>dbIDSender</structfield>;</term>
1657             <listitem><para>Box identifier of the sender. Special value
1658                 <literal>aaaaaaa</literal> means the message was sent by the
1659                 <abbrev>ISDS</abbrev> system. Not by another user. Maximal
1660                 length is 7 characters.</para></listitem>
1661           </varlistentry>
1662
1663           <varlistentry>
1664             <term><type>char *</type><structfield>dmSender</structfield>;</term>
1665             <listitem><para>Sender's name. Maximal length is 100
1666                 characters.</para></listitem>
1667           </varlistentry>
1668
1669           <varlistentry>
1670             <term><type>char *</type><structfield>dmSenderAddress</structfield>;</term>
1671             <listitem><para>Postal address of the sender. Maximal length is 100
1672                 characters.</para></listitem>
1673           </varlistentry>
1674
1675           <varlistentry>
1676             <term><type>long int *</type><structfield>dmSenderType</structfield>;</term>
1677             <listitem><para>Gross box type of the sender. You can use
1678                 <type>isds_DbType</type> to enumarate some known box types.
1679                 This is a generic integer because the protocol keeps the value
1680                 unconstrained and the library must support any syntactically
1681                 correct value.</para></listitem>
1682           </varlistentry>
1683
1684           <varlistentry>
1685             <term><type>char *</type><structfield>dmRecipient</structfield>;</term>
1686             <listitem><para>Recipient's name. Maximal length is 100
1687                 characters.</para></listitem>
1688           </varlistentry>
1689
1690           <varlistentry>
1691             <term><type>char *</type><structfield>dmRecipientAddress</structfield>;</term>
1692             <listitem><para>Postal address of the recipient. Maximal length is
1693                 100 characters.</para></listitem>
1694           </varlistentry>
1695
1696           <varlistentry>
1697             <term><type>_Bool *</type><structfield>dmAmbiguousRecipient</structfield>;</term>
1698             <listitem><para>The recipient has <abbrev>OVM</abbrev> role.</para></listitem>
1699           </varlistentry>
1700         </variablelist>
1701
1702         <para>Following members are assigned by the <abbrev>ISDS</abbrev> in
1703           different phases of message life cycle:</para>
1704         <variablelist>
1705           <varlistentry>
1706             <term><type>unsigned long int *</type><structfield>dmOrdinal</structfield>;</term>
1707             <listitem><para>Ordinal number in list of incoming/outgoing
1708                 messages.</para></listitem>
1709           </varlistentry>
1710
1711           <varlistentry>
1712             <term><type>isds_message_status *</type><structfield>dmMessageStatus</structfield>;</term>
1713             <listitem><para>Message state.</para></listitem>
1714           </varlistentry>
1715
1716           <varlistentry>
1717             <term><type>long int *</type><structfield>dmAttachmentSize</structfield>;</term>
1718             <listitem><para>Size of message documents in kilobytes. The value
1719                 is rounded.</para></listitem>
1720           </varlistentry>
1721
1722           <varlistentry>
1723             <term><type>struct timeval *</type><structfield>dmDeliveryTime</structfield>;</term>
1724             <listitem><para>The time of delivering the message into recipient's
1725                 box. It will be <constant>NULL</constant>, if the message has not
1726                 been delivered yet.</para></listitem>
1727           </varlistentry>
1728
1729           <varlistentry>
1730             <term><type>struct timeval *</type><structfield>dmAcceptanceTime</structfield>;</term>
1731             <listitem><para>The time of acceptancing the message by the
1732                 recipient. It will be <constant>NULL</constant>, if message
1733                 has not been accepted yet.</para></listitem>
1734           </varlistentry>
1735
1736           <varlistentry>
1737             <term><type>struct isds_hash *</type><structfield>hash</structfield>;</term>
1738             <listitem><para>The message digest. This is a hash of a substring representing
1739                 <literal>isds:dmDM</literal> <abbrev>XML</abbrev>
1740                 subtree. You can use
1741                 <function>isds_compute_message_hash</function> function to
1742                 compute a hash of the message and then compare it against this
1743                 structure member using <function>isds_hash_cmp</function>
1744                 function.</para></listitem>
1745           </varlistentry>
1746
1747           <varlistentry>
1748             <term><type>void *</type><structfield>timestamp</structfield>;</term>
1749             <listitem><para>This is a binary image of a qualified time stamp
1750                 of the <structfield>hash</structfield> value. The time stamp
1751                 is provided by the <abbrev>ISDS</abbrev> system. Messages that
1752                 have not yet been stamped will have this value
1753                 <constant>NULL</constant>.</para></listitem>
1754           </varlistentry>
1755
1756           <varlistentry>
1757             <term><type>size_t</type> <structfield>timestamp_length</structfield>;</term>
1758             <listitem><para>Length of the <structfield>timestamp</structfield>
1759                 value in bytes.</para></listitem>
1760           </varlistentry>
1761
1762           <varlistentry>
1763             <term><type>struct isds_list *</type><structfield>events</structfield>;</term>
1764             <listitem><para>Events the message passed trough. It's a list of
1765                 <type>isds_event</type> structures.</para></listitem>
1766           </varlistentry>
1767         </variablelist>
1768
1769         <para>Following members apply to both outgoing and incoming
1770           messages:</para>
1771
1772         <variablelist>
1773           <varlistentry>
1774             <term><type>char *</type><structfield>dmSenderOrgUnit</structfield>;</term>
1775             <listitem><para>Sender's organisation unit as a string. This is
1776                 optional.</para></listitem>
1777           </varlistentry>
1778
1779           <varlistentry>
1780             <term><type>long int *</type><structfield>dmSenderOrgUnitNum</structfield>;</term>
1781             <listitem><para>Sender's organisation unit as a number. This is
1782                 optional.</para></listitem>
1783           </varlistentry>
1784
1785           <varlistentry>
1786             <term><type>char *</type><structfield>dbIDRecipient</structfield>;</term>
1787             <listitem><para>Recipent's box identifier. This is mandatory.
1788                 Maximal length is 7 characters.</para></listitem>
1789           </varlistentry>
1790
1791           <varlistentry>
1792             <term><type>char *</type><structfield>dmRecipientOrgUnit</structfield>;</term>
1793             <listitem><para>Recipient's organisation unit as a string. This is
1794                 optional.</para></listitem>
1795           </varlistentry>
1796
1797           <varlistentry>
1798             <term><type>long int *</type><structfield>dmRecipientOrgUnitNum</structfield>;</term>
1799             <listitem><para>Recipent's organisation unit of as a number. This
1800                 is optional.</para></listitem>
1801           </varlistentry>
1802
1803           <varlistentry>
1804             <term><type>char *</type><structfield>dmToHands</structfield>;</term>
1805             <listitem><para>A person in recipient's organisation. This is
1806                 optional.</para></listitem>
1807           </varlistentry>
1808
1809           <varlistentry>
1810             <term><type>char *</type><structfield>dmAnnotation</structfield>;</term>
1811             <listitem><para>A subject (title) of the message. Maximal length
1812                 is 255 characters.</para></listitem>
1813           </varlistentry>
1814
1815           <varlistentry>
1816             <term><type>char *</type><structfield>dmRecipientRefNumber</structfield>;</term>
1817             <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1818                   příjemce</foreignphrase>. This is optional. Maximal length is 50
1819                 characters.</para></listitem>
1820           </varlistentry>
1821
1822           <varlistentry>
1823             <term><type>char *</type><structfield>dmSenderRefNumber</structfield>;</term>
1824             <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1825                   odesílatele</foreignphrase>. This is optional. Maximal length is 50
1826                 chars.</para></listitem>
1827           </varlistentry>
1828
1829           <varlistentry>
1830             <term><type>char *</type><structfield>dmRecipientIdent</structfield>;</term>
1831             <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1832                   příjemce</foreignphrase>. This is optional. Maximal length is 50
1833                 characters.</para></listitem>
1834           </varlistentry>
1835
1836           <varlistentry>
1837             <term><type>char *</type><structfield>dmSenderIdent</structfield>;</term>
1838             <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1839                   odesílatele</foreignphrase> This is optional. Maximal length is 50
1840                 chars.</para></listitem>
1841           </varlistentry>
1842         </variablelist>
1843
1844         <para>Following five members constitue a reference to an item from the
1845           Czech Act Collection. The human-readable reference looks
1846           like <phrase><emphasis>Point</emphasis>
1847             (<emphasis>Paragraph</emphasis>)
1848             § <emphasis>Section</emphasis>
1849             <emphasis>Law</emphasis>/<emphasis>Year</emphasis>
1850             Coll.</phrase> The memebers apply to both incoming and outgoing
1851           messages:</para>
1852
1853         <variablelist>
1854           <varlistentry>
1855             <term><type>long int *</type><structfield>dmLegalTitleLaw</structfield>;</term>
1856             <listitem><para>A number of an act mandating the
1857                 authority.</para></listitem>
1858           </varlistentry>
1859
1860           <varlistentry>
1861             <term><type>long int *</type><structfield>dmLegalTitleYear</structfield>;</term>
1862             <listitem><para>A year of issuing the act mandating the
1863                 authority.</para></listitem>
1864           </varlistentry>
1865
1866           <varlistentry>
1867             <term><type>char *</type><structfield>dmLegalTitleSect</structfield>;</term>
1868             <listitem><para>A section of the act mandating the authority.
1869                 Czech: <foreignphrase
1870                   lang="cs">paragraf</foreignphrase>.</para></listitem>
1871           </varlistentry>
1872
1873           <varlistentry>
1874             <term><type>char *</type><structfield>dmLegalTitlePar</structfield>;</term>
1875             <listitem><para>A paragraph of the act mandating the authority.
1876                 Czech: <foreignphrase
1877                   lang="cs">odstavec</foreignphrase>.</para></listitem>
1878           </varlistentry>
1879
1880           <varlistentry>
1881             <term><type>char *</type><structfield>dmLegalTitlePoint</structfield>;</term>
1882             <listitem><para>A point of the act mandating the authority. Czech:
1883                 <foreignphrase lang="cs">písmeno</foreignphrase>.</para></listitem>
1884           </varlistentry>
1885         </variablelist>
1886
1887         <para>Other incoming/outgoing message members:</para>
1888
1889         <variablelist>
1890           <varlistentry>
1891             <term><type>_Bool *</type><structfield>dmPersonalDelivery</structfield>;</term>
1892             <listitem><para>If true, only person with higher privileges can
1893                 read this message.</para></listitem>
1894           </varlistentry>
1895
1896           <varlistentry>
1897             <term><type>_Bool *</type><structfield>dmAllowSubstDelivery</structfield>;</term>
1898             <listitem><para>Allow delivery through fiction.
1899                 <abbrev>I.e.</abbrev> Even if the recipient did not read this
1900                 message, the message is considered as delivered after
1901                 (currently) 10 days. This is called <phrase>delivery through
1902                   fiction</phrase>. Oonly OVM dbType sender can set
1903                 it.</para></listitem>
1904           </varlistentry>
1905
1906           <varlistentry>
1907             <term><type>char *</type><structfield>dmType</structfield>;</term>
1908             <listitem>
1909               <para>Message type (commercial subtypes or government message).</para>
1910
1911               <para>Input values (when sending the message):</para>
1912
1913               <variablelist>
1914                 <varlistentry>
1915                   <term><literal>"I"</literal></term>
1916                   <listitem><para>A commercial message offering paying the
1917                       response (<phrase>initiatory message</phrase>). It's
1918                       necessary to define
1919                       <structfield>dmSenderRefNumber</structfield>
1920                       member.</para></listitem>
1921                 </varlistentry>
1922
1923                 <varlistentry>
1924                   <term><literal>"K"</literal></term>
1925                   <listitem><para>A commercial message paid by the sender.</para></listitem>
1926                 </varlistentry>
1927
1928                 <varlistentry>
1929                   <term><literal>"O"</literal></term>
1930                   <listitem><para>A commercial response paid by the sender of
1931                       a initiatory message. It's necessary to copy a value
1932                       from the <structfield>dmSenderRefNumber</structfield> of
1933                       the initiatory message to the
1934                       <structfield>dmRecipientRefNumber</structfield> of this
1935                       message.</para></listitem>
1936                 </varlistentry>
1937
1938                 <varlistentry>
1939                   <term><literal>"V"</literal></term>
1940                   <listitem><para>A noncommercial government message. This is
1941                       the default meaning if the value is undefined while
1942                       sending a message.</para></listitem>
1943                 </varlistentry>
1944               </variablelist>
1945
1946               <para>Output values (when retrieving the message):</para>
1947
1948               <variablelist>
1949                 <varlistentry>
1950                   <term><literal>"A"</literal></term>
1951                   <listitem><para>This is a subsidized initiatory commercial
1952                       message which can pay a response.</para></listitem>
1953                 </varlistentry>
1954
1955                 <varlistentry>
1956                   <term><literal>"B"</literal></term>
1957                   <listitem><para>This is a subsidized initiatory commercial
1958                       message which has already paid the
1959                       response.</para></listitem>
1960                 </varlistentry>
1961
1962                 <varlistentry>
1963                   <term><literal>"C"</literal></term>
1964                   <listitem><para>This is a subsidized initiatory commercial
1965                       message where the response offer has
1966                       expired.</para></listitem>
1967                 </varlistentry>
1968
1969                 <varlistentry>
1970                   <term><literal>"D"</literal></term>
1971                   <listitem><para>This is an externally subsidized commercial
1972                       messsage.</para></listitem>
1973                 </varlistentry>
1974
1975                 <varlistentry>
1976                   <term><literal>"E"</literal></term>
1977                   <listitem><para>This is a commercial message prepaid by
1978                       a stamp.</para></listitem>
1979                 </varlistentry>
1980
1981                 <varlistentry>
1982                   <term><literal>"G"</literal></term>
1983                   <listitem><para>This is a commerical message paid by
1984                       a sponsor.</para></listitem>
1985                 </varlistentry>
1986
1987                 <varlistentry>
1988                   <term><literal>"I"</literal></term>
1989                   <listitem><para>See the input values.</para></listitem>
1990                 </varlistentry>
1991
1992                 <varlistentry>
1993                   <term><literal>"K"</literal></term>
1994                   <listitem><para>See the input values.</para></listitem>
1995                 </varlistentry>
1996
1997                 <varlistentry>
1998                   <term><literal>"O"</literal></term>
1999                   <listitem><para>See the input values.</para></listitem>
2000                 </varlistentry>
2001
2002                 <varlistentry>
2003                   <term><literal>"V"</literal></term>
2004                   <listitem><para>See the input values.</para></listitem>
2005                 </varlistentry>
2006
2007                 <varlistentry>
2008                   <term><literal>"X"</literal></term>
2009                   <listitem><para>This is an initiatory commercial message
2010                       where the response offer has expired.</para></listitem>
2011                 </varlistentry>
2012
2013                 <varlistentry>
2014                   <term><literal>"Y"</literal></term>
2015                   <listitem><para>This is an initiatory commercial message
2016                       which has already paid the response.</para></listitem>
2017                 </varlistentry>
2018
2019                 <varlistentry>
2020                   <term><literal>"Z"</literal></term>
2021                   <listitem><para>This is limitedly subsidized commercial message.</para></listitem>
2022                 </varlistentry>
2023               </variablelist>
2024
2025               <para>Length of the value is exactly 1 UTF-8 character if
2026                 defined. That means it's still zero-terminated character
2027                 string.</para></listitem>
2028           </varlistentry>
2029         </variablelist>
2030
2031         <para>Following members apply to outgoing messages only:</para>
2032
2033         <variablelist>
2034           <varlistentry>
2035             <term><type>_Bool *</type><structfield>dmOVM</structfield>;</term>
2036             <listitem><para>OVM sending mode. Non-OVM dbType boxes that have
2037                 dbEffectiveOVM equaled to true <emphasis>MUST</emphasis>
2038                 select between true (OVM mode) and false (non-OVM mode).
2039                 Otherwise the value is optional and the default value is
2040                 true.</para></listitem>
2041           </varlistentry>
2042
2043           <varlistentry>
2044             <term><type>_Bool *</type><structfield>dmPublishOwnID</structfield>;</term>
2045             <listitem><para>To allow to reveal sender's login name. The name
2046                 will be available to the recipient through
2047                 <function>isds_get_message_sender</function> function. The
2048                 sender's box type and identifier will be always available.
2049                 This feature exists because more users can have access to one
2050                 box and the recipient could not tell who was the sender. This
2051                 value is optional. Default value is false.</para></listitem>
2052           </varlistentry>
2053         </variablelist>
2054       </refsection>
2055
2056       <refsection>
2057         <title><type>isds_FileMetaType</type></title>
2058         <synopsis>typedef enum <type>isds_FileMetaType</type>;</synopsis>
2059         <para>Document type from point fo view of hierarchy of documents in
2060           a message. Known values are:</para>
2061         <variablelist>
2062           <varlistentry>
2063             <term><constant>FILEMETATYPE_MAIN</constant></term>
2064             <listitem><para>Main document. There should be exactly one
2065                 document of this type in a message.</para></listitem>
2066           </varlistentry>
2067
2068           <varlistentry>
2069             <term><constant>FILEMETATYPE_ENCLOSURE</constant></term>
2070             <listitem><para>An appendix. If a message has more documents,
2071                 generic-purpose documents other than the main one should have
2072                 this type.</para></listitem>
2073           </varlistentry>
2074
2075           <varlistentry>
2076             <term><constant>FILEMETATYPE_SIGNATURE</constant></term>
2077             <listitem><para>Digital signature. This document is a signature of
2078                 another document in the message.</para></listitem>
2079           </varlistentry>
2080
2081           <varlistentry>
2082             <term><constant>FILEMETATYPE_META</constant></term>
2083             <listitem><para><abbrev>XML</abbrev> document for
2084                 <phrase>electronic document information system</phrase>,
2085                 <foreignphrase lang="cs">elektronická spisová
2086                   služba</foreignphrase> (<abbrev lang="cs">ESS</abbrev>) in
2087                 Czech, purpose. </para></listitem>
2088           </varlistentry>
2089         </variablelist>
2090       </refsection>
2091
2092       <refsection>
2093         <title>struct <structname>isds_document</structname></title>
2094         <synopsis>struct <structname>isds_document</structname>;</synopsis>
2095         <para>A message document. Members are:</para>
2096         <variablelist>
2097           <varlistentry>
2098             <term><type>_Bool</type> <structfield>is_xml</structfield>;</term>
2099             <listitem><para>True if the document is an <abbrev>ISDS</abbrev>
2100                 <abbrev>XML</abbrev> document. False if the document is an
2101                 <abbrev>ISDS</abbrev> binary document.</para></listitem>
2102           </varlistentry>
2103
2104           <varlistentry>
2105             <term><type>xmlNodePtr</type> <structfield>xml_node_list</structfield>;</term>
2106             <listitem><para><abbrev>XML</abbrev> node-set presenting the
2107                 <abbrev>XML</abbrev> document content. This is a pointer to
2108                 first <abbrev>XML</abbrev> node of the <abbrev>XML</abbrev>
2109                 representation of the message as stored in
2110                 <structfield>xml</structfield> member of
2111                 <type>isds_message</type> structure. Use
2112                 <structfield>children</structfield> and
2113                 <structfield>next</structfield> members to walk through the
2114                 document. See <systemitem class="library">libxml2</systemitem>
2115                 library documentation for more details. The
2116                 <structfield>xml_node_list</structfield> will be
2117                 <constant>NULL</constant> if the document is empty. It's valid
2118                 only if the <structfield>is_xml</structfield> is
2119                 true.</para></listitem>
2120           </varlistentry>
2121
2122           <varlistentry>
2123             <term><type>void *</type><structfield>data</structfield>;</term>
2124             <listitem><para>A binary document content. The encoding and format
2125                 depends on <structfield>dmMimeType</structfield> member value.
2126                 This is valid only if the <structfield>is_xml</structfield> is
2127                 false.</para></listitem>
2128           </varlistentry>
2129
2130           <varlistentry>
2131             <term><type>size_t</type> <structfield>data_length</structfield>;</term>
2132             <listitem><para>Length of the <structfield>data</structfield>
2133                 buffer in bytes. It's valid only if the
2134                 <structfield>is_xml</structfield> is false.</para></listitem>
2135           </varlistentry>
2136
2137           <varlistentry>
2138             <term><type>char *</type><structfield>dmMimeType</structfield>;</term>
2139             <listitem><para><abbrev>MIME</abbrev> type of document. This
2140                 member is mandatory.</para></listitem>
2141           </varlistentry>
2142
2143           <varlistentry>
2144             <term><type>isds_FileMetaType</type> <structfield>dmFileMetaType</structfield>;</term>
2145             <listitem><para>Document type to create document hierarchy inside
2146                 a message.</para></listitem>
2147           </varlistentry>
2148
2149           <varlistentry>
2150             <term><type>char *</type><structfield>dmFileGuid</structfield>;</term>
2151             <listitem><para>Message-local document identifier. It can be used
2152                 as a key to refer to this document by
2153                 <structfield>dmUpFileGuid</structfield> member from a different
2154                 document. This is optional.</para></listitem>
2155           </varlistentry>
2156
2157           <varlistentry>
2158             <term><type>char *</type><structfield>dmUpFileGuid</structfield>;</term>
2159             <listitem><para>A reference to upper document identifier stored in
2160                 <structfield>dmFileGuid</structfield> member of different
2161                 document. You can use
2162                 <function>isds_find_document_by_id</function> function to
2163                 locate the upper document. This value is
2164                 optional.</para></listitem>
2165           </varlistentry>
2166
2167           <varlistentry>
2168             <term><type>char *</type><structfield>dmFileDescr</structfield>;</term>
2169             <listitem><para>Document name (title). <abbrev>E.g.</abbrev>
2170                 a file name. This value is mandatory.</para></listitem>
2171           </varlistentry>
2172
2173           <varlistentry>
2174             <term><type>char *</type><structfield>dmFormat</structfield>;</term>
2175             <listitem><para>A reference to <abbrev>XML</abbrev> format
2176                 definition that explains how to interpret the
2177                 <abbrev>XML</abbrev> document. <abbrev>E.g.</abbrev>
2178                 a <abbrev>URL</abbrev> to an <abbrev>XML</abbrev> schema. This
2179                 value is optional.</para></listitem>
2180           </varlistentry>
2181         </variablelist>
2182       </refsection>
2183
2184       <refsection>
2185         <title>struct <structname>isds_box_state_period</structname></title>
2186         <synopsis>struct <structname>isds_box_state_period</structname>;</synopsis>
2187         <para>A box state valid in the time range. Members are:</para>
2188         <variablelist>
2189           <varlistentry>
2190             <term><type>struct timeval *</type><structfield>from</structfield>;</term>
2191             <listitem><para>Time range beginning.</para></listitem>
2192           </varlistentry>
2193
2194           <varlistentry>
2195             <term><type>struct timeval *</type><structfield>to</structfield>;</term>
2196             <listitem><para>Time range end.</para></listitem>
2197           </varlistentry>
2198
2199           <varlistentry>
2200             <term><type>long int </type><structfield>dbState</structfield>;</term>
2201             <listitem><para>Box state. <constant>1</constant> means the box is
2202                 accessible. Other values mean the box is inaccessible. You can
2203                 use <type>isds_DbState</type> enum to identify some
2204                 states.</para></listitem>
2205           </varlistentry>
2206         </variablelist>
2207       </refsection>
2208
2209
2210     </refsection>
2211
2212     <refsection>
2213       <title>Functions</title>
2214
2215       <itemizedlist>
2216         <listitem><funcsynopsis><funcprototype>
2217               <funcdef>const char *<function>isds_strerror</function></funcdef>
2218               <paramdef>const isds_error <parameter>error</parameter></paramdef>
2219         </funcprototype></funcsynopsis></listitem>
2220
2221         <listitem><funcsynopsis><funcprototype>
2222           <funcdef>struct isds_ctx *<function>isds_ctx_create</function></funcdef>
2223           <void/>
2224         </funcprototype></funcsynopsis></listitem>
2225       </itemizedlist>
2226     </refsection>
2227
2228     <refsection>
2229       <title>See Also</title>
2230
2231       <para>
2232         <simplelist type="inline">
2233           <member><citerefentry>
2234               <refentrytitle>libcurl</refentrytitle>
2235               <manvolnum>3</manvolnum>
2236           </citerefentry></member>
2237           <member><citerefentry>
2238               <refentrytitle>libisds</refentrytitle>
2239               <manvolnum>3</manvolnum>
2240           </citerefentry></member>
2241           <member><citerefentry>
2242               <refentrytitle>time.h</refentrytitle>
2243               <manvolnum>0p</manvolnum>
2244           </citerefentry></member>
2245         </simplelist>
2246       </para>
2247     </refsection>
2248   </refentry>
2249 </reference>