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 (stopped being used, replaced with
 880                 <abbrev>OVM_PFO</abbrev>).</para></listitem>
 881           </varlistentry>
 882
 883           <varlistentry>
 884             <term><constant>DBTYPE_OVM_EXEKUT</constant></term>
 885             <listitem><para>Executor (stopped being used, replaced with
 886                 <abbrev>OVM_PFO</abbrev>).</para></listitem>
 887           </varlistentry>
 888
 889           <varlistentry>
 890             <term><constant>DBTYPE_OVM_REQ</constant></term>
 891             <listitem><para>Subsidiary office with <abbrev>OVM</abbrev>
 892                 (governing) status assigned on request (section 6 and 7 of the
 893                 act).</para></listitem>
 894           </varlistentry>
 895
 896           <varlistentry>
 897             <term><constant>DBTYPE_OVM_FO</constant></term>
 898             <listitem><para>Natural person with <abbrev>OVM</abbrev> status
 899                 (without identification number).</para></listitem>
 900           </varlistentry>
 901
 902           <varlistentry>
 903             <term><constant>DBTYPE_OVM_PFO</constant></term>
 904             <listitem><para>Natural person in business with <abbrev>OVM</abbrev>
 905                 status (e.g. notary or executor).</para></listitem>
 906           </varlistentry>
 907
 908           <varlistentry>
 909             <term><constant>DBTYPE_OVM_PO</constant></term>
 910             <listitem><para>Juridical person with <abbrev>OVM</abbrev> status
 911                 (arisen from previously existing <abbrev>PO</abbrev> or
 912                 <abbrev>PO_REQ</abbrev>).</para></listitem>
 913           </varlistentry>
 914
 915           <varlistentry>
 916             <term><constant>DBTYPE_PO</constant></term>
 917             <listitem><para>Standard commercial organization (listed in trade
 918                 registry).</para></listitem>
 919           </varlistentry>
 920
 921           <varlistentry>
 922             <term><constant>DBTYPE_PO_ZAK</constant></term>
 923             <listitem><para>Other organization founded by an act
 924                 (stopped being used, replaced with
 925                 <abbrev>PO</abbrev>).</para></listitem>
 926           </varlistentry>
 927
 928           <varlistentry>
 929             <term><constant>DBTYPE_PO_REQ</constant></term>
 930             <listitem><para>An organization with a box assigned on its
 931                 request.</para></listitem>
 932           </varlistentry>
 933
 934           <varlistentry>
 935             <term><constant>DBTYPE_PFO</constant></term>
 936             <listitem><para>Person in business.</para></listitem>
 937           </varlistentry>
 938
 939           <varlistentry>
 940             <term><constant>DBTYPE_PFO_ADVOK</constant></term>
 941             <listitem><para>Lawyer.</para></listitem>
 942           </varlistentry>
 943
 944           <varlistentry>
 945             <term><constant>DBTYPE_PFO_DANPOR</constant></term>
 946             <listitem><para>Tax consultant.</para></listitem>
 947           </varlistentry>
 948
 949           <varlistentry>
 950             <term><constant>DBTYPE_PFO_INSSPR</constant></term>
 951             <listitem><para>Administrator of insolvency.</para></listitem>
 952           </varlistentry>
 953
 954           <varlistentry>
 955             <term><constant>DBTYPE_PFO_AUDITOR</constant></term>
 956             <listitem><para>Statutory auditor.</para></listitem>
 957           </varlistentry>
 958
 959           <varlistentry>
 960             <term><constant>DBTYPE_FO</constant></term>
 961             <listitem><para>Standard person.</para></listitem>
 962           </varlistentry>
 963         </variablelist>
 964
 965         <para>Some interfaces refer to <emphasis>gross</emphasis> box type.
 966           These are the shortest names of the identifiers. For example,
 967           <literal>DBTYPE_OVM</literal> is a gross type for
 968           <literal>DB_OVM_NOTAR</literal> or <literal>DBTYPE_OVM</literal>.
 969           But not for <literal>DBTYPE_PO</literal>.</para>
 970       </refsection>
 971
 972       <refsection>
 973         <title><type>isds_DbState</type></title>
 974         <synopsis>typedef enum <type>isds_DbState</type>;</synopsis>
 975         <para>Box status from point of view of accessibility. Known
 976           values:</para>
 977         <variablelist>
 978           <varlistentry>
 979             <term><constant>DBSTATE_ACCESSIBLE</constant></term>
 980             <listitem><para>The box is accessible.</para></listitem>
 981           </varlistentry>
 982
 983           <varlistentry>
 984             <term><constant>DBSTATE_TEMP_UNACCESSIBLE</constant></term>
 985             <listitem><para>The box is temporarily inaccessible (at the request of the user).</para></listitem>
 986           </varlistentry>
 987
 988           <varlistentry>
 989             <term><constant>DBSTATE_NOT_YET_ACCESSIBLE</constant></term>
 990             <listitem><para>The box has not yet been activated.</para></listitem>
 991           </varlistentry>
 992
 993           <varlistentry>
 994             <term><constant>DBSTATE_PERM_UNACCESSIBLE</constant></term>
 995             <listitem><para>The box is permanently inaccessible.</para></listitem>
 996           </varlistentry>
 997
 998           <varlistentry>
 999             <term><constant>DBSTATE_REMOVED</constant></term>
1000             <listitem><para>The box has been removed.</para></listitem>
1001           </varlistentry>
1002
1003           <varlistentry>
1004             <term><constant>DBSTATE_TEMP_UNACCESSIBLE_LAW</constant></term>
1005             <listitem><para>The box is temporarily inaccessible (because of the reasons enumerated in the law).</para></listitem>
1006           </varlistentry>
1007         </variablelist>
1008       </refsection>
1009
1010       <refsection>
1011         <title><type>isds_priviledges</type></title>
1012         <synopsis>typedef enum <type>isds_priviledges</type>;</synopsis>
1013         <para>Distinct user permissions from point of view of <abbrev>ISDS</abbrev>.
1014           Instances can be bitmaps of any of these distinct values. Distinct known
1015           values are:</para>
1016         <variablelist>
1017           <varlistentry>
1018             <term><constant>PRIVIL_READ_NON_PERSONAL</constant></term>
1019             <listitem><para>The user can download and read messages with
1020                 <structfield>dmPersonalDelivery</structfield> equaled to
1021                 false.</para></listitem>
1022           </varlistentry>
1023
1024           <varlistentry>
1025             <term><constant>PRIVIL_READ_ALL</constant></term>
1026             <listitem><para>The user can download and read messages with
1027                 <structfield>dmPersonalDelivery</structfield> equaled to
1028                 true.</para></listitem>
1029           </varlistentry>
1030
1031           <varlistentry>
1032             <term><constant>PRIVIL_CREATE_DM</constant></term>
1033             <listitem><para>The user can create and send messages, the user
1034                 can download outgoing (sent) messages.</para></listitem>
1035           </varlistentry>
1036
1037           <varlistentry>
1038             <term><constant>PRIVIL_VIEW_INFO</constant></term>
1039             <listitem><para>The user can list messages and read data about
1040                 a message post and delivery.</para></listitem>
1041           </varlistentry>
1042
1043           <varlistentry>
1044             <term><constant>PRIVIL_SEARCH_DB</constant></term>
1045             <listitem><para>The user can can search for
1046                 boxes.</para></listitem>
1047           </varlistentry>
1048
1049           <varlistentry>
1050             <term><constant>PRIVIL_OWNER_ADM</constant></term>
1051             <listitem><para>The user can administer his box (to add and remove
1052                 permitted users and to modify theirs
1053                 permissions.)</para></listitem>
1054           </varlistentry>
1055
1056           <varlistentry>
1057             <term><constant>PRIVIL_READ_VAULT</constant></term>
1058             <listitem>
1059               <para>The user can read messages stored in the long term storage.</para>
1060               <note><para>This permission is not used since 2012-05.</para></note>
1061             </listitem>
1062           </varlistentry>
1063
1064           <varlistentry>
1065             <term><constant>PRIVIL_ERASE_VAULT</constant></term>
1066             <listitem><para>The user can delete messages from the long term
1067                 storage.</para></listitem>
1068           </varlistentry>
1069         </variablelist>
1070       </refsection>
1071
1072       <refsection>
1073         <title><type>isds_message_status</type></title>
1074         <synopsis>typedef enum <type>isds_message_status</type>;</synopsis>
1075         <para>Message status. Known values are:</para>
1076         <variablelist>
1077           <varlistentry>
1078             <term><constant>MESSAGESTATE_SENT</constant></term>
1079             <listitem><para>The message has been put into
1080                 <abbrev>ISDS</abbrev>.</para></listitem>
1081           </varlistentry>
1082
1083           <varlistentry>
1084             <term><constant>MESSAGESTATE_STAMPED</constant></term>
1085             <listitem><para>Message was stamped by a time stamp
1086                 authority.</para></listitem>
1087           </varlistentry>
1088
1089           <varlistentry>
1090             <term><constant>MESSAGESTATE_INFECTED</constant></term>
1091             <listitem><para>The message included viruses. Infected documents
1092                 have been removed from the message.</para></listitem>
1093           </varlistentry>
1094
1095           <varlistentry>
1096             <term><constant>MESSAGESTATE_DELIVERED</constant></term>
1097             <listitem><para>The message was delivered.
1098                 (<structfield>dmDeliveryTime</structfield> is
1099                     populated.)</para></listitem>
1100           </varlistentry>
1101
1102           <varlistentry>
1103             <term><constant>MESSAGESTATE_SUBSTITUTED</constant></term>
1104             <listitem><para>The message was delivered through fiction,
1105                 <structfield>dmAcceptanceTime</structfield> is
1106                 populated.</para></listitem>
1107           </varlistentry>
1108
1109           <varlistentry>
1110             <term><constant>MESSAGESTATE_RECEIVED</constant></term>
1111             <listitem><para>The message was accepted (by user's log-in or
1112                 user's explicit request).
1113                 <structfield>dmAcceptanceTime</structfield> is
1114                 populated.</para></listitem>
1115           </varlistentry>
1116
1117           <varlistentry>
1118             <term><constant>MESSAGESTATE_READ</constant></term>
1119             <listitem><para>The message has been read by
1120                 a user.</para></listitem>
1121           </varlistentry>
1122
1123           <varlistentry>
1124             <term><constant>MESSAGESTATE_UNDELIVERABLE</constant></term>
1125             <listitem><para>The message could not been delivered.
1126                 (<abbrev>E.g.</abbrev>The recipient's box has been made
1127                 inaccessible meantime.)</para></listitem>
1128           </varlistentry>
1129
1130           <varlistentry>
1131             <term><constant>MESSAGESTATE_REMOVED</constant></term>
1132             <listitem><para>The message's content was
1133                 deleted.</para></listitem>
1134           </varlistentry>
1135
1136           <varlistentry>
1137             <term><constant>MESSAGESTATE_IN_SAFE</constant></term>
1138             <listitem><para>The message is stored in the long term
1139                 storage.</para></listitem>
1140           </varlistentry>
1141         </variablelist>
1142
1143         <para>The values can be combined into a bit mask for some functions.
1144           A special <constant>MESSAGESTATE_ANY</constant> macro denotes any of
1145           the states.</para>
1146       </refsection>
1147
1148       <refsection>
1149         <title><type>isds_hash_algorithm</type></title>
1150         <synopsis>typedef enum <type>isds_hash_algorithm</type>;</synopsis>
1151         <para>Hash algorithm types. Known values are:</para>
1152         <variablelist>
1153           <varlistentry>
1154             <term><constant>HASH_ALGORITHM_MD5</constant></term>
1155             <listitem><para><abbrev>MD5</abbrev>.</para></listitem>
1156           </varlistentry>
1157
1158           <varlistentry>
1159             <term><constant>HASH_ALGORITHM_SHA_1</constant></term>
1160             <listitem><para><abbrev>SHA-1</abbrev>.</para></listitem>
1161           </varlistentry>
1162
1163           <varlistentry>
1164             <term><constant>HASH_ALGORITHM_SHA_224</constant></term>
1165             <listitem><para><abbrev>SHA-224</abbrev>.</para></listitem>
1166           </varlistentry>
1167
1168           <varlistentry>
1169             <term><constant>HASH_ALGORITHM_SHA_256</constant></term>
1170             <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1171           </varlistentry>
1172
1173           <varlistentry>
1174             <term><constant>HASH_ALGORITHM_SHA_384</constant></term>
1175             <listitem><para><abbrev>SHA-384</abbrev>.</para></listitem>
1176           </varlistentry>
1177
1178           <varlistentry>
1179             <term><constant>HASH_ALGORITHM_SHA_512</constant></term>
1180             <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1181           </varlistentry>
1182         </variablelist>
1183       </refsection>
1184
1185       <refsection>
1186         <title><type>isds_buffer_strategy</type></title>
1187         <synopsis>typedef enum <type>isds_buffer_strategy</type>;</synopsis>
1188         <para>Buffer storage strategy. This type defines how a function should
1189           embed application provided buffer into
1190           <structfield>raw</structfield> element of output structure. Known
1191           values are:</para>
1192         <variablelist>
1193           <varlistentry>
1194             <term><constant>BUFFER_DONT_STORE</constant></term>
1195             <listitem><para>Don't fill <structfield>raw</structfield>
1196                 member.</para></listitem>
1197           </varlistentry>
1198
1199           <varlistentry>
1200             <term><constant>BUFFER_COPY</constant></term>
1201             <listitem><para>Copy buffer content into newly allocated
1202                 <structfield>raw</structfield> member.</para></listitem>
1203           </varlistentry>
1204
1205           <varlistentry>
1206             <term><constant>BUFFER_MOVE</constant></term>
1207             <listitem><para>Copy pointer. Leave deallocation to structure
1208                 destructor
1209                 (<function>isds_*_free</function>()).</para></listitem>
1210           </varlistentry>
1211         </variablelist>
1212       </refsection>
1213
1214       <refsection>
1215         <title>struct <structname>isds_hash</structname></title>
1216         <synopsis>struct <structname>isds_hash</structname>;</synopsis>
1217         <para>This is a hash value storage. Members are:</para>
1218         <variablelist>
1219           <varlistentry>
1220             <term><type>isds_hash_algorithm</type>
1221               <structfield>algorithm</structfield>;</term>
1222             <listitem><para>Hash algorithm.</para></listitem>
1223           </varlistentry>
1224
1225           <varlistentry>
1226             <term><type>size_t</type> <structfield>length</structfield>;</term>
1227             <listitem><para>Hash value length in bytes.</para></listitem>
1228           </varlistentry>
1229
1230           <varlistentry>
1231             <term><type>void *</type><structfield>value</structfield>;</term>
1232             <listitem><para>Hash value as a byte stream.</para></listitem>
1233           </varlistentry>
1234         </variablelist>
1235       </refsection>
1236
1237       <refsection>
1238         <title>struct <structname>isds_PersonName</structname></title>
1239         <synopsis>struct <structname>isds_PersonName</structname>;</synopsis>
1240         <para>Name of a person. Members are:</para>
1241         <variablelist>
1242           <varlistentry>
1243             <term><type>char *</type><structfield>pnFirstName</structfield>;</term>
1244             <listitem><para>First name.</para></listitem>
1245           </varlistentry>
1246
1247           <varlistentry>
1248             <term><type>char *</type><structfield>pnMiddleName</structfield>;</term>
1249             <listitem><para>Middle name.</para></listitem>
1250           </varlistentry>
1251
1252           <varlistentry>
1253             <term><type>char *</type><structfield>pnLastName</structfield>;</term>
1254             <listitem><para>Current last name.</para></listitem>
1255           </varlistentry>
1256
1257           <varlistentry>
1258             <term><type>char *</type><structfield>pnLastNameAtBirth</structfield>;</term>
1259             <listitem><para>Last name at birth.</para></listitem>
1260           </varlistentry>
1261         </variablelist>
1262       </refsection>
1263
1264       <refsection>
1265         <title>struct <structname>isds_BirthInfo</structname></title>
1266         <synopsis>struct <structname>isds_BirthInfo</structname>;</synopsis>
1267         <para>Date and place of a birth. Members are:</para>
1268         <variablelist>
1269           <varlistentry>
1270             <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1271             <listitem><para>Date of birth in local time at the birth place.
1272                 Only <structfield>tm_year</structfield>,
1273                 <structfield>tm_mon</structfield> and
1274                 <structfield>tm_mday</structfield> members of the <type>struct
1275                   tm</type> carry sane value. Others are
1276                 undefined.</para></listitem>
1277           </varlistentry>
1278
1279           <varlistentry>
1280             <term><type>char *</type><structfield>biCity</structfield>;</term>
1281             <listitem><para>City where a person was born.</para></listitem>
1282           </varlistentry>
1283
1284           <varlistentry>
1285             <term><type>char *</type><structfield>biCounty</structfield>;</term>
1286             <listitem><para>Region where a person was born. This is the kind
1287                 of region that is called <foreignphrase
1288                   lang="de">Bezirk</foreignphrase> in
1289                 German and <foreignphrase lang="cs">okres</foreignphrase> in
1290                 Czech.</para></listitem>
1291           </varlistentry>
1292
1293           <varlistentry>
1294             <term><type>char *</type><structfield>biState</structfield>;</term>
1295             <listitem><para>State wher a person was born.</para></listitem>
1296           </varlistentry>
1297         </variablelist>
1298       </refsection>
1299
1300       <refsection>
1301         <title>struct <structname>isds_Address</structname></title>
1302         <synopsis>struct <structname>isds_Address</structname>;</synopsis>
1303         <para>Postal address. Members are:</para>
1304         <variablelist>
1305           <varlistentry>
1306             <term><type>long int *</type><structfield>adCode</structfield>;</term>
1307             <listitem><para><abbrev>RUIN</abbrev> address code.</para></listitem>
1308           </varlistentry>
1309
1310           <varlistentry>
1311             <term><type>char *</type><structfield>adCity</structfield>;</term>
1312             <listitem><para>City.</para></listitem>
1313           </varlistentry>
1314
1315           <varlistentry>
1316             <term><type>char *</type><structfield>adDistrict</structfield>;</term>
1317             <listitem><para>Municipality part.</para></listitem>
1318           </varlistentry>
1319
1320           <varlistentry>
1321             <term><type>char *</type><structfield>adStreet</structfield>;</term>
1322             <listitem><para>Street.</para></listitem>
1323           </varlistentry>
1324
1325           <varlistentry>
1326             <term><type>char *</type><structfield>adNumberInStreet</structfield>;</term>
1327             <listitem><para>Identification of an entrance on the
1328                 street. <foreignphrase lang="cs">Číslo
1329                   orientační</foreignphrase> in Czech.</para></listitem>
1330           </varlistentry>
1331
1332           <varlistentry>
1333             <term><type>char *</type><structfield>adNumberInMunicipality</structfield>;</term>
1334             <listitem><para>Identification of a building in the municipality.
1335                 <foreignphrase lang="cs">Číslo popisné</foreignphrase> in
1336                 Czech.</para></listitem>
1337           </varlistentry>
1338
1339           <varlistentry>
1340             <term><type>char *</type><structfield>adZipCode</structfield>;</term>
1341             <listitem><para>Postal code for mail routing.</para></listitem>
1342           </varlistentry>
1343
1344           <varlistentry>
1345             <term><type>char *</type><structfield>adState</structfield>;</term>
1346             <listitem><para>State.</para></listitem>
1347           </varlistentry>
1348         </variablelist>
1349       </refsection>
1350
1351       <refsection>
1352         <title>struct <structname>isds_DbOwnerInfo</structname></title>
1353         <synopsis>struct <structname>isds_DbOwnerInfo</structname>;</synopsis>
1354         <para>Data about a box and his owner. NULL pointer values mean
1355           undefined values. Members are:</para>
1356         <variablelist>
1357           <varlistentry>
1358             <term><type>char *</type><structfield>dbID</structfield>;</term>
1359             <listitem><para>Box identifier. Specification limits the length to
1360                 7 characters.</para></listitem>
1361           </varlistentry>
1362
1363           <varlistentry>
1364             <term><type>isds_DbType *</type><structfield>dbType</structfield>;</term>
1365             <listitem><para>Box type.</para></listitem>
1366           </varlistentry>
1367
1368           <varlistentry>
1369             <term><type>char *</type><structfield>ic</structfield>;</term>
1370             <listitem><para>Identifier of the owner.</para></listitem>
1371           </varlistentry>
1372
1373           <varlistentry>
1374             <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1375             <listitem><para>Name of a person owning the box.</para></listitem>
1376           </varlistentry>
1377
1378           <varlistentry>
1379             <term><type>char *</type><structfield>firmName</structfield>;</term>
1380             <listitem><para>Name of a firm owning the box.</para></listitem>
1381           </varlistentry>
1382
1383           <varlistentry>
1384             <term><type>isds_BirthInfo *</type><structfield>birthInfo</structfield>;</term>
1385             <listitem><para>Birth details of the person.</para></listitem>
1386           </varlistentry>
1387
1388           <varlistentry>
1389             <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1390             <listitem><para>Postal address of the owner.</para></listitem>
1391           </varlistentry>
1392
1393           <varlistentry>
1394             <term><type>char *</type><structfield>nationality</structfield>;</term>
1395             <listitem><para>Nationality of the owner.</para></listitem>
1396           </varlistentry>
1397
1398           <varlistentry>
1399             <term><type>char *</type><structfield>email</structfield>;</term>
1400             <listitem><para>E-mail addres of the owner.</para></listitem>
1401           </varlistentry>
1402
1403           <varlistentry>
1404             <term><type>char *</type><structfield>telNumber</structfield>;</term>
1405             <listitem><para>Telephone number of the owner.</para></listitem>
1406           </varlistentry>
1407
1408           <varlistentry>
1409             <term><type>char *</type><structfield>identifier</structfield>;</term>
1410             <listitem><para>External box identifier for data provider
1411                 (<abbrev>OVM</abbrev>, <abbrev>PO</abbrev>, maybe
1412                 <abbrev>PFO</abbrev> box types.) Specification limits the
1413                 length to 20 characters.</para></listitem>
1414           </varlistentry>
1415
1416           <varlistentry>
1417             <term><type>_Bool *</type><structfield>aifoIsds</structfield>;</term>
1418             <listitem><para>Reference to citizen registry exists.</para></listitem>
1419           </varlistentry>
1420
1421           <varlistentry>
1422             <term><type>char *</type><structfield>registryCode</structfield>;</term>
1423             <listitem><para><abbrev>PFO</abbrev> external registry code.
1424                 Specification limits the length to
1425                 5 characters.</para></listitem>
1426           </varlistentry>
1427
1428           <varlistentry>
1429             <term><type>long int *</type><structfield>dbState</structfield>;</term>
1430             <listitem>
1431               <para>Box state. 1 means the box is active.</para>
1432               <note><para>The type is long int because specification declares it
1433                   as <type>xsd:integer</type>.</para></note>
1434               <note><para>TODO: enum?</para></note></listitem>
1435           </varlistentry>
1436
1437           <varlistentry>
1438             <term><type>_Bool *</type><structfield>dbEffectiveOVM</structfield>;</term>
1439             <listitem><para>The Box has <abbrev>OVM</abbrev> role (section 5a
1440                 of the act).</para></listitem>
1441           </varlistentry>
1442
1443           <varlistentry>
1444             <term><type>_Bool *</type><structfield>dbOpenAddressing</structfield>;</term>
1445             <listitem>This <para>non-<abbrev>OVM</abbrev> box is free to
1446                 receive messages from anybody.</para></listitem>
1447           </varlistentry>
1448         </variablelist>
1449       </refsection>
1450
1451       <refsection>
1452         <title><type>isds_UserType</type></title>
1453         <synopsis>typedef enum <type>isds_UserType</type>;</synopsis>
1454         <para>User type. Known values are:</para>
1455         <variablelist>
1456           <varlistentry>
1457             <term><constant>USERTYPE_PRIMARY</constant></term>
1458             <listitem><para>Owner of the box.</para></listitem>
1459           </varlistentry>
1460
1461           <varlistentry>
1462             <term><constant>USERTYPE_ENTRUSTED</constant></term>
1463             <listitem><para>User with limited access to the box.</para></listitem>
1464           </varlistentry>
1465
1466           <varlistentry>
1467             <term><constant>USERTYPE_ADMINISTRATOR</constant></term>
1468             <listitem><para>User who can manage
1469                 <constant>USERTYPE_ENTRUSTED</constant>
1470                 users.</para></listitem>
1471           </varlistentry>
1472
1473           <varlistentry>
1474             <term><constant>USERTYPE_OFFICIAL</constant></term>
1475             <listitem><para>???</para></listitem>
1476           </varlistentry>
1477
1478           <varlistentry>
1479             <term><constant>USERTYPE_OFFICIAL_CERT</constant></term>
1480             <listitem><para>???</para></listitem>
1481           </varlistentry>
1482
1483           <varlistentry>
1484             <term><constant>USERTYPE_LIQUIDATOR</constant></term>
1485             <listitem><para>Company liquidator.</para></listitem>
1486           </varlistentry>
1487
1488           <varlistentry>
1489             <term><constant>USERTYPE_RECEIVER</constant></term>
1490             <listitem><para>Company receiver.</para></listitem>
1491           </varlistentry>
1492
1493           <varlistentry>
1494             <term><constant>USERTYPE_GUARDIAN</constant></term>
1495             <listitem><para>Legal guardian.</para></listitem>
1496           </varlistentry>
1497         </variablelist>
1498       </refsection>
1499
1500       <refsection>
1501         <title>struct <structname>isds_DbUserInfo</structname></title>
1502         <synopsis>struct <structname>isds_DbUserInfo</structname>;</synopsis>
1503         <para>Data about a user. NULL pointer values mean
1504           undefined values. Members are:</para>
1505         <variablelist>
1506           <varlistentry>
1507             <term><type>char *</type><structfield>userID</structfield>;</term>
1508             <listitem><para>User identifier. Specification limits the length
1509                 from 6 to 12 characters.</para></listitem>
1510           </varlistentry>
1511
1512           <varlistentry>
1513             <term><type>isds_UserType *</type><structfield>userType</structfield>;</term>
1514             <listitem><para>User type.</para></listitem>
1515           </varlistentry>
1516
1517           <varlistentry>
1518             <term><type>long int *</type><structfield>userPrivils</structfield>;</term>
1519             <listitem><para>Set of user permissions.</para></listitem>
1520           </varlistentry>
1521
1522           <varlistentry>
1523             <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1524             <listitem><para>Name of the user.</para></listitem>
1525           </varlistentry>
1526
1527           <varlistentry>
1528             <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1529             <listitem><para>Postal address of the user.</para></listitem>
1530           </varlistentry>
1531
1532           <varlistentry>
1533             <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1534             <listitem><para>Date of birth in local time.
1535                 Only <structfield>tm_year</structfield>,
1536                 <structfield>tm_mon</structfield> and
1537                 <structfield>tm_mday</structfield> members of the <type>struct
1538                   tm</type> carry sane value. Others are
1539                 undefined.</para></listitem>
1540           </varlistentry>
1541
1542           <varlistentry>
1543             <term><type>char *</type><structfield>ic</structfield>;</term>
1544             <listitem><para>Identifier a supervising firm. Specification
1545                 limits the length to 8 characters.</para></listitem>
1546           </varlistentry>
1547
1548           <varlistentry>
1549             <term><type>char *</type><structfield>firmName</structfield>;</term>
1550             <listitem><para>Name of a supervising firm. Specification limits
1551                 the length to 100 characters.</para></listitem>
1552           </varlistentry>
1553
1554           <varlistentry>
1555             <term><type>char *</type><structfield>caStreet</structfield>;</term>
1556             <listitem><para>Contact address. Street and number.</para></listitem>
1557           </varlistentry>
1558
1559           <varlistentry>
1560             <term><type>char *</type><structfield>caCity</structfield>;</term>
1561             <listitem><para>Czech city of the contact address.</para></listitem>
1562           </varlistentry>
1563
1564           <varlistentry>
1565             <term><type>char *</type><structfield>caZipCode</structfield>;</term>
1566             <listitem><para>Postal code of the contact address.</para></listitem>
1567           </varlistentry>
1568
1569           <varlistentry>
1570             <term><type>char *</type><structfield>caState</structfield>;</term>
1571             <listitem><para>Abbreviated country of contact address. This value
1572                 is optional and implicit meaning is
1573                 <constant>CZ</constant>.</para></listitem>
1574           </varlistentry>
1575
1576           <varlistentry>
1577             <term><type>char *</type><structfield>aifo_ticket</structfield>;</term>
1578             <listitem><para>Reference to citizen registry. This value is
1579                 optional.</para></listitem>
1580           </varlistentry>
1581         </variablelist>
1582       </refsection>
1583
1584       <refsection>
1585         <title><type>isds_event_type</type></title>
1586         <synopsis>typedef enum <type>isds_event_type</type>;</synopsis>
1587         <para>Message event type. Known values are:</para>
1588         <variablelist>
1589           <varlistentry>
1590             <term><constant>EVENT_UKNOWN</constant></term>
1591             <listitem><para>Event uknown to this library.</para></listitem>
1592           </varlistentry>
1593
1594           <varlistentry>
1595             <term><constant>EVENT_ACCEPTED_BY_RECIPIENT</constant></term>
1596             <listitem><para>Message has been delivered and accepted by
1597                 recipient action.</para></listitem>
1598           </varlistentry>
1599
1600           <varlistentry>
1601             <term><constant>EVENT_ACCEPTED_BY_FICTION</constant></term>
1602             <listitem><para>Message has been delivered, acceptance period
1603                 timed out, the message is considered as
1604                 accepted.</para></listitem>
1605           </varlistentry>
1606
1607           <varlistentry>
1608             <term><constant>EVENT_UNDELIVERABLE</constant></term>
1609             <listitem><para>Recipient box was made inaccessible, thus the
1610                 message is undeliverable.</para></listitem>
1611           </varlistentry>
1612
1613           <varlistentry>
1614             <term><constant>EVENT_COMMERCIAL_ACCEPTED</constant></term>
1615             <listitem><para>Recipient confirmed acceptance of this commercial
1616                 message.</para></listitem>
1617           </varlistentry>
1618
1619           <varlistentry>
1620             <term><constant>EVENT_ENTERED_SYSTEM</constant></term>
1621             <listitem><para>The message entered the
1622                 <abbrev>ISDS</abbrev>system, <abbrev>i.e.</abbrev> it has been
1623                 just sent by a sender.</para></listitem>
1624           </varlistentry>
1625
1626           <varlistentry>
1627             <term><constant>EVENT_DELIVERED</constant></term>
1628             <listitem><para>The message has been delivered into recipient's
1629                 box.</para></listitem>
1630           </varlistentry>
1631
1632           <varlistentry>
1633             <term><constant>EVENT_PRIMARY_LOGIN</constant></term>
1634             <listitem><para>Primary user logged into recipent's
1635                 box.</para></listitem>
1636           </varlistentry>
1637
1638           <varlistentry>
1639             <term><constant>EVENT_ENTRUSTED_LOGIN</constant></term>
1640             <listitem><para>Entrusted user with capability to read logged
1641                 into recipient's box.</para></listitem>
1642           </varlistentry>
1643
1644           <varlistentry>
1645             <term><constant>EVENT_SYSCERT_LOGIN</constant></term>
1646             <listitem><para>An application authenticated by
1647                 <emphasis>system</emphasis> certificate logged into
1648                 recipient's box.</para></listitem>
1649           </varlistentry>
1650         </variablelist>
1651       </refsection>
1652
1653       <refsection>
1654         <title>struct <structname>isds_event</structname></title>
1655         <synopsis>struct <structname>isds_event</structname>;</synopsis>
1656         <para>An event that happened in a message life. All members are
1657           optional. Members are:</para>
1658         <variablelist>
1659           <varlistentry>
1660             <term><type>struct timeval *</type><structfield>time</structfield>;</term>
1661             <listitem><para>When the event occurred.</para></listitem>
1662           </varlistentry>
1663
1664           <varlistentry>
1665             <term><type>isds_event_type *</type><structfield>type</structfield>;</term>
1666             <listitem><para>Type of the envent.</para></listitem>
1667           </varlistentry>
1668
1669           <varlistentry>
1670             <term><type>charr *</type><structfield>description</structfield>;</term>
1671             <listitem><para>Human-readable event description generated by the
1672                 <abbrev>ISDS</abbrev> system. (Very probably in Czech
1673                 language).</para></listitem>
1674           </varlistentry>
1675         </variablelist>
1676       </refsection>
1677
1678       <refsection>
1679         <title>struct <structname>isds_envelope</structname></title>
1680         <synopsis>struct <structname>isds_envelope</structname>;</synopsis>
1681         <para>Message envelope. These are the metadata about a message. It
1682           does contain the message documents.</para>
1683         <para>Be ware that the string length constraints are forced only on
1684           output members transmitted to the <abbrev>ISDS</abbrev>. The other
1685           direction (downloading from the <abbrev>ISDS</abbrev>) can break
1686           these rules. It should not happen, but nobody knows how much
1687           incompatible new version of the <abbrev>ISDS</abbrev> protocol will
1688           be.  This is the gold Internet rule: be strict on what you send, be
1689           tolerant on what you receive.</para>
1690         <para>Following members apply to incoming messages only:</para>
1691         <variablelist>
1692           <varlistentry>
1693             <term><type>char *</type><structfield>dmID</structfield>;</term>
1694             <listitem><para>Message identifier. Maximal length is 20
1695                 characters.</para></listitem>
1696           </varlistentry>
1697
1698           <varlistentry>
1699             <term><type>char *</type><structfield>dbIDSender</structfield>;</term>
1700             <listitem><para>Box identifier of the sender. Special value
1701                 <literal>aaaaaaa</literal> means the message was sent by the
1702                 <abbrev>ISDS</abbrev> system. Not by another user. Maximal
1703                 length is 7 characters.</para></listitem>
1704           </varlistentry>
1705
1706           <varlistentry>
1707             <term><type>char *</type><structfield>dmSender</structfield>;</term>
1708             <listitem><para>Sender's name. Maximal length is 100
1709                 characters.</para></listitem>
1710           </varlistentry>
1711
1712           <varlistentry>
1713             <term><type>char *</type><structfield>dmSenderAddress</structfield>;</term>
1714             <listitem><para>Postal address of the sender. Maximal length is 100
1715                 characters.</para></listitem>
1716           </varlistentry>
1717
1718           <varlistentry>
1719             <term><type>long int *</type><structfield>dmSenderType</structfield>;</term>
1720             <listitem><para>Gross box type of the sender. You can use
1721                 <type>isds_DbType</type> to enumarate some known box types.
1722                 This is a generic integer because the protocol keeps the value
1723                 unconstrained and the library must support any syntactically
1724                 correct value.</para></listitem>
1725           </varlistentry>
1726
1727           <varlistentry>
1728             <term><type>char *</type><structfield>dmRecipient</structfield>;</term>
1729             <listitem><para>Recipient's name. Maximal length is 100
1730                 characters.</para></listitem>
1731           </varlistentry>
1732
1733           <varlistentry>
1734             <term><type>char *</type><structfield>dmRecipientAddress</structfield>;</term>
1735             <listitem><para>Postal address of the recipient. Maximal length is
1736                 100 characters.</para></listitem>
1737           </varlistentry>
1738
1739           <varlistentry>
1740             <term><type>_Bool *</type><structfield>dmAmbiguousRecipient</structfield>;</term>
1741             <listitem><para>The recipient has <abbrev>OVM</abbrev> role.</para></listitem>
1742           </varlistentry>
1743         </variablelist>
1744
1745         <para>Following members are assigned by the <abbrev>ISDS</abbrev> in
1746           different phases of message life cycle:</para>
1747         <variablelist>
1748           <varlistentry>
1749             <term><type>unsigned long int *</type><structfield>dmOrdinal</structfield>;</term>
1750             <listitem><para>Ordinal number in list of incoming/outgoing
1751                 messages.</para></listitem>
1752           </varlistentry>
1753
1754           <varlistentry>
1755             <term><type>isds_message_status *</type><structfield>dmMessageStatus</structfield>;</term>
1756             <listitem><para>Message state.</para></listitem>
1757           </varlistentry>
1758
1759           <varlistentry>
1760             <term><type>long int *</type><structfield>dmAttachmentSize</structfield>;</term>
1761             <listitem><para>Size of message documents in kilobytes. The value
1762                 is rounded.</para></listitem>
1763           </varlistentry>
1764
1765           <varlistentry>
1766             <term><type>struct timeval *</type><structfield>dmDeliveryTime</structfield>;</term>
1767             <listitem><para>The time of delivering the message into recipient's
1768                 box. It will be <constant>NULL</constant>, if the message has not
1769                 been delivered yet.</para></listitem>
1770           </varlistentry>
1771
1772           <varlistentry>
1773             <term><type>struct timeval *</type><structfield>dmAcceptanceTime</structfield>;</term>
1774             <listitem><para>The time of acceptancing the message by the
1775                 recipient. It will be <constant>NULL</constant>, if message
1776                 has not been accepted yet.</para></listitem>
1777           </varlistentry>
1778
1779           <varlistentry>
1780             <term><type>struct isds_hash *</type><structfield>hash</structfield>;</term>
1781             <listitem><para>The message digest. This is a hash of a substring representing
1782                 <literal>isds:dmDM</literal> <abbrev>XML</abbrev>
1783                 subtree. You can use
1784                 <function>isds_compute_message_hash</function> function to
1785                 compute a hash of the message and then compare it against this
1786                 structure member using <function>isds_hash_cmp</function>
1787                 function.</para></listitem>
1788           </varlistentry>
1789
1790           <varlistentry>
1791             <term><type>void *</type><structfield>timestamp</structfield>;</term>
1792             <listitem><para>This is a binary image of a qualified time stamp
1793                 of the <structfield>hash</structfield> value. The time stamp
1794                 is provided by the <abbrev>ISDS</abbrev> system. Messages that
1795                 have not yet been stamped will have this value
1796                 <constant>NULL</constant>.</para></listitem>
1797           </varlistentry>
1798
1799           <varlistentry>
1800             <term><type>size_t</type> <structfield>timestamp_length</structfield>;</term>
1801             <listitem><para>Length of the <structfield>timestamp</structfield>
1802                 value in bytes.</para></listitem>
1803           </varlistentry>
1804
1805           <varlistentry>
1806             <term><type>struct isds_list *</type><structfield>events</structfield>;</term>
1807             <listitem><para>Events the message passed trough. It's a list of
1808                 <type>isds_event</type> structures.</para></listitem>
1809           </varlistentry>
1810         </variablelist>
1811
1812         <para>Following members apply to both outgoing and incoming
1813           messages:</para>
1814
1815         <variablelist>
1816           <varlistentry>
1817             <term><type>char *</type><structfield>dmSenderOrgUnit</structfield>;</term>
1818             <listitem><para>Sender's organisation unit as a string. This is
1819                 optional.</para></listitem>
1820           </varlistentry>
1821
1822           <varlistentry>
1823             <term><type>long int *</type><structfield>dmSenderOrgUnitNum</structfield>;</term>
1824             <listitem><para>Sender's organisation unit as a number. This is
1825                 optional.</para></listitem>
1826           </varlistentry>
1827
1828           <varlistentry>
1829             <term><type>char *</type><structfield>dbIDRecipient</structfield>;</term>
1830             <listitem><para>Recipent's box identifier. This is mandatory.
1831                 Maximal length is 7 characters.</para></listitem>
1832           </varlistentry>
1833
1834           <varlistentry>
1835             <term><type>char *</type><structfield>dmRecipientOrgUnit</structfield>;</term>
1836             <listitem><para>Recipient's organisation unit as a string. This is
1837                 optional.</para></listitem>
1838           </varlistentry>
1839
1840           <varlistentry>
1841             <term><type>long int *</type><structfield>dmRecipientOrgUnitNum</structfield>;</term>
1842             <listitem><para>Recipent's organisation unit of as a number. This
1843                 is optional.</para></listitem>
1844           </varlistentry>
1845
1846           <varlistentry>
1847             <term><type>char *</type><structfield>dmToHands</structfield>;</term>
1848             <listitem><para>A person in recipient's organisation. This is
1849                 optional.</para></listitem>
1850           </varlistentry>
1851
1852           <varlistentry>
1853             <term><type>char *</type><structfield>dmAnnotation</structfield>;</term>
1854             <listitem><para>A subject (title) of the message. Maximal length
1855                 is 255 characters.</para></listitem>
1856           </varlistentry>
1857
1858           <varlistentry>
1859             <term><type>char *</type><structfield>dmRecipientRefNumber</structfield>;</term>
1860             <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1861                   příjemce</foreignphrase>. This is optional. Maximal length is 50
1862                 characters.</para></listitem>
1863           </varlistentry>
1864
1865           <varlistentry>
1866             <term><type>char *</type><structfield>dmSenderRefNumber</structfield>;</term>
1867             <listitem><para>Czech: <foreignphrase lang="cs">číslo jednací
1868                   odesílatele</foreignphrase>. This is optional. Maximal length is 50
1869                 chars.</para></listitem>
1870           </varlistentry>
1871
1872           <varlistentry>
1873             <term><type>char *</type><structfield>dmRecipientIdent</structfield>;</term>
1874             <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1875                   příjemce</foreignphrase>. This is optional. Maximal length is 50
1876                 characters.</para></listitem>
1877           </varlistentry>
1878
1879           <varlistentry>
1880             <term><type>char *</type><structfield>dmSenderIdent</structfield>;</term>
1881             <listitem><para>Czech: <foreignphrase lang="cs">spisová značka
1882                   odesílatele</foreignphrase> This is optional. Maximal length is 50
1883                 chars.</para></listitem>
1884           </varlistentry>
1885         </variablelist>
1886
1887         <para>Following five members constitue a reference to an item from the
1888           Czech Act Collection. The human-readable reference looks
1889           like <phrase><emphasis>Point</emphasis>
1890             (<emphasis>Paragraph</emphasis>)
1891             § <emphasis>Section</emphasis>
1892             <emphasis>Law</emphasis>/<emphasis>Year</emphasis>
1893             Coll.</phrase> The memebers apply to both incoming and outgoing
1894           messages:</para>
1895
1896         <variablelist>
1897           <varlistentry>
1898             <term><type>long int *</type><structfield>dmLegalTitleLaw</structfield>;</term>
1899             <listitem><para>A number of an act mandating the
1900                 authority.</para></listitem>
1901           </varlistentry>
1902
1903           <varlistentry>
1904             <term><type>long int *</type><structfield>dmLegalTitleYear</structfield>;</term>
1905             <listitem><para>A year of issuing the act mandating the
1906                 authority.</para></listitem>
1907           </varlistentry>
1908
1909           <varlistentry>
1910             <term><type>char *</type><structfield>dmLegalTitleSect</structfield>;</term>
1911             <listitem><para>A section of the act mandating the authority.
1912                 Czech: <foreignphrase
1913                   lang="cs">paragraf</foreignphrase>.</para></listitem>
1914           </varlistentry>
1915
1916           <varlistentry>
1917             <term><type>char *</type><structfield>dmLegalTitlePar</structfield>;</term>
1918             <listitem><para>A paragraph of the act mandating the authority.
1919                 Czech: <foreignphrase
1920                   lang="cs">odstavec</foreignphrase>.</para></listitem>
1921           </varlistentry>
1922
1923           <varlistentry>
1924             <term><type>char *</type><structfield>dmLegalTitlePoint</structfield>;</term>
1925             <listitem><para>A point of the act mandating the authority. Czech:
1926                 <foreignphrase lang="cs">písmeno</foreignphrase>.</para></listitem>
1927           </varlistentry>
1928         </variablelist>
1929
1930         <para>Other incoming/outgoing message members:</para>
1931
1932         <variablelist>
1933           <varlistentry>
1934             <term><type>_Bool *</type><structfield>dmPersonalDelivery</structfield>;</term>
1935             <listitem><para>If true, only person with higher privileges can
1936                 read this message.</para></listitem>
1937           </varlistentry>
1938
1939           <varlistentry>
1940             <term><type>_Bool *</type><structfield>dmAllowSubstDelivery</structfield>;</term>
1941             <listitem><para>Allow delivery through fiction.
1942                 <abbrev>I.e.</abbrev> Even if the recipient did not read this
1943                 message, the message is considered as delivered after
1944                 (currently) 10 days. This is called <phrase>delivery through
1945                   fiction</phrase>. Oonly OVM dbType sender can set
1946                 it.</para></listitem>
1947           </varlistentry>
1948
1949           <varlistentry>
1950             <term><type>char *</type><structfield>dmType</structfield>;</term>
1951             <listitem>
1952               <para>Message type (commercial subtypes or government message).</para>
1953
1954               <para>Input values (when sending the message):</para>
1955
1956               <variablelist>
1957                 <varlistentry>
1958                   <term><literal>"I"</literal></term>
1959                   <listitem><para>A commercial message offering paying the
1960                       response (<phrase>initiatory message</phrase>). It's
1961                       necessary to define
1962                       <structfield>dmSenderRefNumber</structfield>
1963                       member.</para></listitem>
1964                 </varlistentry>
1965
1966                 <varlistentry>
1967                   <term><literal>"K"</literal></term>
1968                   <listitem><para>A commercial message paid by the sender.</para></listitem>
1969                 </varlistentry>
1970
1971                 <varlistentry>
1972                   <term><literal>"O"</literal></term>
1973                   <listitem><para>A commercial response paid by the sender of
1974                       a initiatory message. It's necessary to copy a value
1975                       from the <structfield>dmSenderRefNumber</structfield> of
1976                       the initiatory message to the
1977                       <structfield>dmRecipientRefNumber</structfield> of this
1978                       message.</para></listitem>
1979                 </varlistentry>
1980
1981                 <varlistentry>
1982                   <term><literal>"V"</literal></term>
1983                   <listitem><para>A noncommercial government message. This is
1984                       the default meaning if the value is undefined while
1985                       sending a message.</para></listitem>
1986                 </varlistentry>
1987               </variablelist>
1988
1989               <para>Output values (when retrieving the message):</para>
1990
1991               <variablelist>
1992                 <varlistentry>
1993                   <term><literal>"A"</literal></term>
1994                   <listitem><para>This is a subsidized initiatory commercial
1995                       message which can pay a response.</para></listitem>
1996                 </varlistentry>
1997
1998                 <varlistentry>
1999                   <term><literal>"B"</literal></term>
2000                   <listitem><para>This is a subsidized initiatory commercial
2001                       message which has already paid the
2002                       response.</para></listitem>
2003                 </varlistentry>
2004
2005                 <varlistentry>
2006                   <term><literal>"C"</literal></term>
2007                   <listitem><para>This is a subsidized initiatory commercial
2008                       message where the response offer has
2009                       expired.</para></listitem>
2010                 </varlistentry>
2011
2012                 <varlistentry>
2013                   <term><literal>"D"</literal></term>
2014                   <listitem><para>This is an externally subsidized commercial
2015                       messsage.</para></listitem>
2016                 </varlistentry>
2017
2018                 <varlistentry>
2019                   <term><literal>"E"</literal></term>
2020                   <listitem><para>This is a commercial message prepaid by
2021                       a stamp.</para></listitem>
2022                 </varlistentry>
2023
2024                 <varlistentry>
2025                   <term><literal>"G"</literal></term>
2026                   <listitem><para>This is a commerical message paid by
2027                       a sponsor.</para></listitem>
2028                 </varlistentry>
2029
2030                 <varlistentry>
2031                   <term><literal>"I"</literal></term>
2032                   <listitem><para>See the input values.</para></listitem>
2033                 </varlistentry>
2034
2035                 <varlistentry>
2036                   <term><literal>"K"</literal></term>
2037                   <listitem><para>See the input values.</para></listitem>
2038                 </varlistentry>
2039
2040                 <varlistentry>
2041                   <term><literal>"O"</literal></term>
2042                   <listitem><para>See the input values.</para></listitem>
2043                 </varlistentry>
2044
2045                 <varlistentry>
2046                   <term><literal>"V"</literal></term>
2047                   <listitem><para>See the input values.</para></listitem>
2048                 </varlistentry>
2049
2050                 <varlistentry>
2051                   <term><literal>"X"</literal></term>
2052                   <listitem><para>This is an initiatory commercial message
2053                       where the response offer has expired.</para></listitem>
2054                 </varlistentry>
2055
2056                 <varlistentry>
2057                   <term><literal>"Y"</literal></term>
2058                   <listitem><para>This is an initiatory commercial message
2059                       which has already paid the response.</para></listitem>
2060                 </varlistentry>
2061
2062                 <varlistentry>
2063                   <term><literal>"Z"</literal></term>
2064                   <listitem><para>This is limitedly subsidized commercial message.</para></listitem>
2065                 </varlistentry>
2066               </variablelist>
2067
2068               <para>Length of the value is exactly 1 UTF-8 character if
2069                 defined. That means it's still zero-terminated character
2070                 string.</para></listitem>
2071           </varlistentry>
2072         </variablelist>
2073
2074         <para>Following members apply to outgoing messages only:</para>
2075
2076         <variablelist>
2077           <varlistentry>
2078             <term><type>_Bool *</type><structfield>dmOVM</structfield>;</term>
2079             <listitem><para>OVM sending mode. Non-OVM dbType boxes that have
2080                 dbEffectiveOVM equaled to true <emphasis>MUST</emphasis>
2081                 select between true (OVM mode) and false (non-OVM mode).
2082                 Otherwise the value is optional and the default value is
2083                 true.</para></listitem>
2084           </varlistentry>
2085
2086           <varlistentry>
2087             <term><type>_Bool *</type><structfield>dmPublishOwnID</structfield>;</term>
2088             <listitem><para>To allow to reveal sender's login name. The name
2089                 will be available to the recipient through
2090                 <function>isds_get_message_sender</function> function. The
2091                 sender's box type and identifier will be always available.
2092                 This feature exists because more users can have access to one
2093                 box and the recipient could not tell who was the sender. This
2094                 value is optional. Default value is false.</para></listitem>
2095           </varlistentry>
2096         </variablelist>
2097       </refsection>
2098
2099       <refsection>
2100         <title><type>isds_FileMetaType</type></title>
2101         <synopsis>typedef enum <type>isds_FileMetaType</type>;</synopsis>
2102         <para>Document type from point fo view of hierarchy of documents in
2103           a message. Known values are:</para>
2104         <variablelist>
2105           <varlistentry>
2106             <term><constant>FILEMETATYPE_MAIN</constant></term>
2107             <listitem><para>Main document. There should be exactly one
2108                 document of this type in a message.</para></listitem>
2109           </varlistentry>
2110
2111           <varlistentry>
2112             <term><constant>FILEMETATYPE_ENCLOSURE</constant></term>
2113             <listitem><para>An appendix. If a message has more documents,
2114                 generic-purpose documents other than the main one should have
2115                 this type.</para></listitem>
2116           </varlistentry>
2117
2118           <varlistentry>
2119             <term><constant>FILEMETATYPE_SIGNATURE</constant></term>
2120             <listitem><para>Digital signature. This document is a signature of
2121                 another document in the message.</para></listitem>
2122           </varlistentry>
2123
2124           <varlistentry>
2125             <term><constant>FILEMETATYPE_META</constant></term>
2126             <listitem><para><abbrev>XML</abbrev> document for
2127                 <phrase>electronic document information system</phrase>,
2128                 <foreignphrase lang="cs">elektronická spisová
2129                   služba</foreignphrase> (<abbrev lang="cs">ESS</abbrev>) in
2130                 Czech, purpose. </para></listitem>
2131           </varlistentry>
2132         </variablelist>
2133       </refsection>
2134
2135       <refsection>
2136         <title>struct <structname>isds_document</structname></title>
2137         <synopsis>struct <structname>isds_document</structname>;</synopsis>
2138         <para>A message document. Members are:</para>
2139         <variablelist>
2140           <varlistentry>
2141             <term><type>_Bool</type> <structfield>is_xml</structfield>;</term>
2142             <listitem><para>True if the document is an <abbrev>ISDS</abbrev>
2143                 <abbrev>XML</abbrev> document. False if the document is an
2144                 <abbrev>ISDS</abbrev> binary document.</para></listitem>
2145           </varlistentry>
2146
2147           <varlistentry>
2148             <term><type>xmlNodePtr</type> <structfield>xml_node_list</structfield>;</term>
2149             <listitem><para><abbrev>XML</abbrev> node-set presenting the
2150                 <abbrev>XML</abbrev> document content. This is a pointer to
2151                 first <abbrev>XML</abbrev> node of the <abbrev>XML</abbrev>
2152                 representation of the message as stored in
2153                 <structfield>xml</structfield> member of
2154                 <type>isds_message</type> structure. Use
2155                 <structfield>children</structfield> and
2156                 <structfield>next</structfield> members to walk through the
2157                 document. See <systemitem class="library">libxml2</systemitem>
2158                 library documentation for more details. The
2159                 <structfield>xml_node_list</structfield> will be
2160                 <constant>NULL</constant> if the document is empty. It's valid
2161                 only if the <structfield>is_xml</structfield> is
2162                 true.</para></listitem>
2163           </varlistentry>
2164
2165           <varlistentry>
2166             <term><type>void *</type><structfield>data</structfield>;</term>
2167             <listitem><para>A binary document content. The encoding and format
2168                 depends on <structfield>dmMimeType</structfield> member value.
2169                 This is valid only if the <structfield>is_xml</structfield> is
2170                 false.</para></listitem>
2171           </varlistentry>
2172
2173           <varlistentry>
2174             <term><type>size_t</type> <structfield>data_length</structfield>;</term>
2175             <listitem><para>Length of the <structfield>data</structfield>
2176                 buffer in bytes. It's valid only if the
2177                 <structfield>is_xml</structfield> is false.</para></listitem>
2178           </varlistentry>
2179
2180           <varlistentry>
2181             <term><type>char *</type><structfield>dmMimeType</structfield>;</term>
2182             <listitem><para><abbrev>MIME</abbrev> type of document. This
2183                 member is mandatory.</para></listitem>
2184           </varlistentry>
2185
2186           <varlistentry>
2187             <term><type>isds_FileMetaType</type> <structfield>dmFileMetaType</structfield>;</term>
2188             <listitem><para>Document type to create document hierarchy inside
2189                 a message.</para></listitem>
2190           </varlistentry>
2191
2192           <varlistentry>
2193             <term><type>char *</type><structfield>dmFileGuid</structfield>;</term>
2194             <listitem><para>Message-local document identifier. It can be used
2195                 as a key to refer to this document by
2196                 <structfield>dmUpFileGuid</structfield> member from a different
2197                 document. This is optional.</para></listitem>
2198           </varlistentry>
2199
2200           <varlistentry>
2201             <term><type>char *</type><structfield>dmUpFileGuid</structfield>;</term>
2202             <listitem><para>A reference to upper document identifier stored in
2203                 <structfield>dmFileGuid</structfield> member of different
2204                 document. You can use
2205                 <function>isds_find_document_by_id</function> function to
2206                 locate the upper document. This value is
2207                 optional.</para></listitem>
2208           </varlistentry>
2209
2210           <varlistentry>
2211             <term><type>char *</type><structfield>dmFileDescr</structfield>;</term>
2212             <listitem><para>Document name (title). <abbrev>E.g.</abbrev>
2213                 a file name. This value is mandatory.</para></listitem>
2214           </varlistentry>
2215
2216           <varlistentry>
2217             <term><type>char *</type><structfield>dmFormat</structfield>;</term>
2218             <listitem><para>A reference to <abbrev>XML</abbrev> format
2219                 definition that explains how to interpret the
2220                 <abbrev>XML</abbrev> document. <abbrev>E.g.</abbrev>
2221                 a <abbrev>URL</abbrev> to an <abbrev>XML</abbrev> schema. This
2222                 value is optional.</para></listitem>
2223           </varlistentry>
2224         </variablelist>
2225       </refsection>
2226
2227       <refsection>
2228         <title>struct <structname>isds_box_state_period</structname></title>
2229         <synopsis>struct <structname>isds_box_state_period</structname>;</synopsis>
2230         <para>A box state valid in the time range. Members are:</para>
2231         <variablelist>
2232           <varlistentry>
2233             <term><type>struct timeval *</type><structfield>from</structfield>;</term>
2234             <listitem><para>Time range beginning.</para></listitem>
2235           </varlistentry>
2236
2237           <varlistentry>
2238             <term><type>struct timeval *</type><structfield>to</structfield>;</term>
2239             <listitem><para>Time range end.</para></listitem>
2240           </varlistentry>
2241
2242           <varlistentry>
2243             <term><type>long int </type><structfield>dbState</structfield>;</term>
2244             <listitem><para>Box state. <constant>1</constant> means the box is
2245                 accessible. Other values mean the box is inaccessible. You can
2246                 use <type>isds_DbState</type> enum to identify some
2247                 states.</para></listitem>
2248           </varlistentry>
2249         </variablelist>
2250       </refsection>
2251
2252
2253     </refsection>
2254
2255     <refsection>
2256       <title>Functions</title>
2257
2258       <itemizedlist>
2259         <listitem><funcsynopsis><funcprototype>
2260               <funcdef>const char *<function>isds_strerror</function></funcdef>
2261               <paramdef>const isds_error <parameter>error</parameter></paramdef>
2262         </funcprototype></funcsynopsis></listitem>
2263
2264         <listitem><funcsynopsis><funcprototype>
2265           <funcdef>struct isds_ctx *<function>isds_ctx_create</function></funcdef>
2266           <void/>
2267         </funcprototype></funcsynopsis></listitem>
2268       </itemizedlist>
2269     </refsection>
2270
2271     <refsection>
2272       <title>See Also</title>
2273
2274       <para>
2275         <simplelist type="inline">
2276           <member><citerefentry>
2277               <refentrytitle>libcurl</refentrytitle>
2278               <manvolnum>3</manvolnum>
2279           </citerefentry></member>
2280           <member><citerefentry>
2281               <refentrytitle>libisds</refentrytitle>
2282               <manvolnum>3</manvolnum>
2283           </citerefentry></member>
2284           <member><citerefentry>
2285               <refentrytitle>time.h</refentrytitle>
2286               <manvolnum>0p</manvolnum>
2287           </citerefentry></member>
2288         </simplelist>
2289       </para>
2290     </refsection>
2291   </refentry>
2292 </reference>