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> (<phrase lang="cs">Informační systém datových
  63           schránek</phrase> / Data Box Information System) as defined in
  64         <ulink url="http://portal.gov.cz/zakon/300/2008">Czech
  65           <abbrev>ISDS</abbrev> Act (300/2008 <abbrev>Coll.</abbrev>)</ulink>
  66         and implied documents. Current implementation details are described in
  67         <phrase lang="cs">Provozní řád</phrase> that can be downloaded from
  68         <ulink url="https://www.datoveschranky.info/ke-stazeni"><phrase
  69             lang="cs">Dokumenty ke stažení</phrase> section of
  70           <abbrev>ISDS</abbrev> Information Portal</ulink>.</para>
  71
  72       <para>The library provides a C language interface with synchronous
  73         non-reentrant blocking calls. Network communication progress reporting
  74         and operation logging and library debugging are implemented by calling
  75         back application-provided functions. Network operations can be
  76         canceled from network reporting call-back.</para>
  77     </refsection>
  78
  79     <refsection>
  80       <title>Library Initialization and Deinitialization</title>
  81
  82       <para>A libisds application must include <filename>isds.h</filename>
  83         header file. The application must call <function>isds_init</function>
  84         function to initialize the library before calling any other library
  85         functions.  After last libisds call, <function>isds_cleanup</function>
  86         function should be called to clean up some global resources and to
  87         deinitialize dependent libraries.</para>
  88     </refsection>
  89
  90     <refsection>
  91       <title>Contexts</title>
  92
  93       <para>Most of the functions operate on an established connection to the
  94         <abbrev>ISDS</abbrev> server. This is called a context and it's
  95         represented by a pointer to an opaque
  96         <structname>isds_ctx</structname> structure. The structure maintains
  97         state about network connection, authorization or error from last call
  98         on the context.</para>
  99
 100       <para>The context is allocated by <function>isds_ctx_create</function>
 101         function and deallocated by <function>isds_ctx_free</function>
 102         function.</para>
 103
 104       <para>There are more context subtypes. A specific subtype is assigned to
 105         the context when a fresh new context is passed to one of the few
 106         stratifying functions (<function>isds_login</function>,
 107         <function>czp_convert_document</function>,
 108         <function>isds_request_new_testing_box</function>). Once the context
 109         is specialized, you can use it only with functions understanding the
 110         subtype. This is not enforced by the library now, but it does not
 111         matter much because all the other functions assume the
 112         <function>isds_login</function> was called on the context. In other
 113         words, do not share the context among the three stratifying
 114         functions.</para>
 115
 116       <para>For example create a context with
 117         <function>isds_ctx_create</function>, then call
 118         <function>isds_login</function>, then work with box, then call
 119         <function>isds_logout</function>. Here you can reuse the context and
 120         log in as another user by calling <function>isds_login</function>
 121         again or destroy the context with <function>isds_ctx_free</function> if
 122         you don't need it anymore.</para>
 123
 124       <para>Or create a context with <function>isds_ctx_create</function>,
 125         send a document to authorized conversion using
 126         <function>czp_convert_document</function>, then you can send more
 127         documents to the authorized conversion by calling
 128         <function>czp_convert_document</function> again on the same context
 129         and finally destroy the context with
 130         <function>isds_ctx_free</function>.</para>
 131
 132     </refsection>
 133
 134     <refsection>
 135       <title>Errors</title>
 136
 137       <para>Most of the functions return an error code of
 138         <type>isds_error</type> type. <errorname>IE_SUCCESS</errorname> value
 139         denotes a successful call. Other values represent some kind of
 140         failure.</para>
 141
 142       <para>You can use <function>isds_strerror</function> function to obtain
 143         a human readable string representation of the error code.</para>
 144
 145       <para>If a function with context argument failed, you can use
 146         <function>isds_long_message</function> function to obtain a detailed
 147         error message. Please note that returned value lasts only to the next
 148         call on the context.</para>
 149     </refsection>
 150
 151     <refsection>
 152       <title>Character Encoding</title>
 153
 154       <para>All strings exchanged between the library and the application are
 155         encoded in <abbrev>UTF-8</abbrev>. Although there are a few
 156         exceptions:</para>
 157
 158       <itemizedlist>
 159         <listitem>
 160           <para><function>isds_strerror</function> and
 161             <function>isds_long_message</function> functions return
 162             locale encoded string.</para>
 163         </listitem>
 164
 165         <listitem>
 166           <para><function>isds_version</function> returns locale encoded
 167             string.</para>
 168         </listitem>
 169
 170         <listitem>
 171           <para>Log call-back function set by
 172             <function>isds_set_log_callback</function> function is called with
 173             raw byte stream.</para>
 174         </listitem>
 175
 176         <listitem>
 177           <para><structname>isds_pki_credentials</structname> structure string
 178             members have encoding specific to cryptographic library linked to
 179             cURL library.</para>
 180         </listitem>
 181
 182       </itemizedlist>
 183     </refsection>
 184
 185     <refsection>
 186       <title>Global Settings</title>
 187
 188       <para>Some functions influence library behavior globally. These are:</para>
 189
 190       <itemizedlist>
 191         <listitem>
 192           <para><function>isds_init</function> and
 193             <function>isds_cleanup</function> used to initialize and
 194             deinitialize the library.</para>
 195         </listitem>
 196
 197         <listitem>
 198           <para><function>isds_set_logging</function> and
 199             <function>isds_set_log_callback</function> to set logging.</para>
 200         </listitem>
 201       </itemizedlist>
 202     </refsection>
 203
 204     <refsection>
 205       <title>Logging and Debugging</title>
 206
 207       <para>Logging is global for all libisds calls. Log level and facility
 208         can be set with <function>isds_set_logging</function> function.</para>
 209
 210       <para>The log is printed on standard error output by default.
 211         Application can redirect the messages to a call-back function by
 212         registering the call-back function with
 213         <function>isds_set_log_callback</function>.</para>
 214     </refsection>
 215
 216     <refsection>
 217       <title>Network Input/Output</title>
 218
 219       <para>Some functions operating on a context create network sockets and
 220         do network input and output.</para>
 221
 222       <para>Network timeout can be set with
 223         <function>isds_set_timeout</function> function. Function calls aborted
 224         owing to the timeout will return
 225         <errorname>IE_TIMED_OUT</errorname>.</para>
 226
 227       <para>Network operation progress can be monitored by a call-back
 228         function. The call-back function can be registered using
 229         <function>isds_set_progress_callback</function> function. Registered
 230         call-back function will be called periodically with arguments
 231         declaring amount of transferred data. The call-back return value
 232         determines whether to continue in the network operation or to cancel
 233         the operation. Functions failed owing to canceling network operation
 234         will return <errorname>IE_ABORTED</errorname>.</para>
 235     </refsection>
 236
 237     <refsection>
 238       <title>Memory management</title>
 239
 240       <para>The library provides destructors for all libisds data structures.
 241         For example <function>isds_ctx_free</function> function accepts a pointer
 242         to a pointer to the <structname>isds_ctx</structname> structure, frees
 243         the double referenced structure (recursively), writes NULL to the
 244         pointed pointer (which invalidates the pointer effectively) and returns
 245         nothing.</para>
 246
 247       <para>Upon a function call, all output arguments are automatically
 248         reallocated to desired size. On a function failure, all output
 249         arguments are automatically deallocated and their pointers set to
 250         NULL. Exceptions are documented at respective functions.</para>
 251
 252       <para>Output strings are allocated using standard
 253         <function>malloc</function> call. Application is responsible for their
 254         deallocation (in case of no failure and if not specified otherwise.)
 255         Use standard <function>free</function> call for strings,
 256         use libisds destructors for libisds structures.</para>
 257     </refsection>
 258
 259     <refsection>
 260       <title>Available Functions, Types, and Constants</title>
 261
 262       <para>See <filename>isds.h</filename> header file.</para>
 263     </refsection>
 264
 265     <refsection>
 266       <title>See Also</title>
 267
 268       <para>
 269         <simplelist type="inline">
 270           <member><citerefentry>
 271               <refentrytitle>isds.h</refentrytitle>
 272               <manvolnum>3</manvolnum>
 273           </citerefentry></member>
 274           <member><citerefentry>
 275               <refentrytitle>libcurl</refentrytitle>
 276               <manvolnum>3</manvolnum>
 277           </citerefentry></member>
 278         </simplelist>
 279       </para>
 280     </refsection>
 281   </refentry>
 282
 283
 284   <refentry id="isds.h.3">
 285     <refmeta>
 286       <refentrytitle>isds.h</refentrytitle>
 287       <manvolnum>3</manvolnum>
 288     </refmeta>
 289
 290     <refnamediv>
 291       <refname>isds.h</refname>
 292       <refpurpose>API definition for libisds</refpurpose>
 293     </refnamediv>
 294
 295     <refsynopsisdiv>
 296       <synopsis><![CDATA[#include <isds.h>
 297 ]]></synopsis>
 298     </refsynopsisdiv>
 299
 300     <refsection>
 301       <title>Description</title>
 302
 303       <para>This header file declares inteface for libisds library.</para>
 304     </refsection>
 305
 306     <refsection>
 307       <title>Constants</title>
 308
 309       <refsection>
 310         <title>Service locators</title>
 311
 312         <para>Addresses of known <abbrev>ISDS</abbrev> servers.</para>
 313
 314         <refsection>
 315           <title>Base <abbrev>URL</abbrev>s of production <abbrev>ISDS</abbrev> instance</title>
 316
 317           <refsection>
 318             <title><varname>isds_locator</varname></title>
 319             <synopsis>extern const char <varname>isds_locator</varname>[];</synopsis>
 320             <para>Without client certificate authentication.</para>
 321           </refsection>
 322
 323           <refsection>
 324             <title><varname>isds_cert_locator</varname></title>
 325             <synopsis>extern const char <varname>isds_cert_locator</varname>[];</synopsis>
 326             <para>With client certificate authentication.</para>
 327           </refsection>
 328
 329           <refsection>
 330             <title><varname>isds_otp_locator</varname></title>
 331             <synopsis>extern const char <varname>isds_otp_locator</varname>[];</synopsis>
 332             <para>Without <abbrev>OTP</abbrev> authentication.</para>
 333           </refsection>
 334         </refsection>
 335
 336         <refsection>
 337           <title>Base <abbrev>URL</abbrev>s of testing <abbrev>ISDS</abbrev> instance</title>
 338
 339           <refsection>
 340             <title><varname>isds_testing_locator</varname></title>
 341             <synopsis>extern const char <varname>isds_testing_locator</varname>[];</synopsis>
 342             <para>Without client certificate authentication.</para>
 343           </refsection>
 344
 345           <refsection>
 346             <title><varname>isds_cert_testing_locator</varname></title>
 347             <synopsis>extern const char <varname>isds_cert_testing_locator</varname>[];</synopsis>
 348             <para>With client certificate authentication.</para>
 349           </refsection>
 350
 351           <refsection>
 352             <title><varname>isds_otp_testing_locator</varname></title>
 353             <synopsis>extern const char <varname>isds_otp_testing_locator</varname>[];</synopsis>
 354             <para>Without <abbrev>OTP</abbrev> authentication.</para>
 355           </refsection>
 356         </refsection>
 357
 358       </refsection>
 359     </refsection>
 360
 361     <refsection>
 362       <title>Data types</title>
 363
 364       <refsection>
 365         <title>struct <structname>isds_ctx</structname></title>
 366         <synopsis>struct <structname>isds_ctx</structname>;</synopsis>
 367         <para>Context for specific <abbrev>ISDS</abbrev> box.</para>
 368       </refsection>
 369
 370       <refsection>
 371         <title><type>isds_error</type></title>
 372         <synopsis>typedef enum <type>isds_error</type>;</synopsis>
 373         <para>Error code. Known values:</para>
 374         <variablelist>
 375           <varlistentry>
 376             <term><errorname>IE_SUCCESS</errorname></term>
 377             <listitem><para>No error. Numeric value 0.</para></listitem>
 378           </varlistentry>
 379
 380           <varlistentry>
 381             <term><errorname>IE_ERROR</errorname></term>
 382             <listitem><para>Unspecified error.</para></listitem>
 383           </varlistentry>
 384
 385           <varlistentry>
 386             <term><errorname>IE_NOTSUP</errorname></term>
 387             <listitem><para>Operation is not supported.</para></listitem>
 388           </varlistentry>
 389
 390           <varlistentry>
 391             <term><errorname>IE_INVAL</errorname></term>
 392             <listitem><para>Invalid value.</para></listitem>
 393           </varlistentry>
 394
 395           <varlistentry>
 396             <term><errorname>IE_INVALID_CONTEXT</errorname></term>
 397             <listitem><para>The context is not valid.</para></listitem>
 398           </varlistentry>
 399
 400           <varlistentry>
 401             <term><errorname>IE_NOT_LOGGED_IN</errorname></term>
 402             <listitem><para>The context has not been logged in.</para></listitem>
 403           </varlistentry>
 404
 405           <varlistentry>
 406             <term><errorname>IE_CONNECTION_CLOSED</errorname></term>
 407             <listitem><para>Network connection has been closed.</para></listitem>
 408           </varlistentry>
 409
 410           <varlistentry>
 411             <term><errorname>IE_TIMED_OUT</errorname></term>
 412             <listitem><para>Time limit for network operation exceeded.</para></listitem>
 413           </varlistentry>
 414
 415           <varlistentry>
 416             <term><errorname>IE_NOEXIST</errorname></term>
 417             <listitem><para>Requested entity does exist.</para></listitem>
 418           </varlistentry>
 419
 420           <varlistentry>
 421             <term><errorname>IE_NOMEM</errorname></term>
 422             <listitem><para>Not enough memory.</para></listitem>
 423           </varlistentry>
 424
 425           <varlistentry>
 426             <term><errorname>IE_NETWORK</errorname></term>
 427             <listitem><para>Network error.</para></listitem>
 428           </varlistentry>
 429
 430           <varlistentry>
 431             <term><errorname>IE_HTTP</errorname></term>
 432             <listitem><para>Error on <abbrev>HTTP</abbrev> level.</para></listitem>
 433           </varlistentry>
 434
 435           <varlistentry>
 436             <term><errorname>IE_SOAP</errorname></term>
 437             <listitem><para>Error on <abbrev>SOAP</abbrev> level.</para></listitem>
 438           </varlistentry>
 439
 440           <varlistentry>
 441             <term><errorname>IE_XML</errorname></term>
 442             <listitem><para>Error on XML level.</para></listitem>
 443           </varlistentry>
 444
 445           <varlistentry>
 446             <term><errorname>IE_ISDS</errorname></term>
 447             <listitem><para>Problem with <abbrev>ISDS</abbrev> server.</para></listitem>
 448           </varlistentry>
 449
 450           <varlistentry>
 451             <term><errorname>IE_ENUM</errorname></term>
 452             <listitem><para>Invalid enum value.</para></listitem>
 453           </varlistentry>
 454
 455           <varlistentry>
 456             <term><errorname>IE_DATE</errorname></term>
 457             <listitem><para>Invalid date value.</para></listitem>
 458           </varlistentry>
 459
 460           <varlistentry>
 461             <term><errorname>IE_2BIG</errorname></term>
 462             <listitem><para>Value is too big.</para></listitem>
 463           </varlistentry>
 464
 465           <varlistentry>
 466             <term><errorname>IE_2SMALL</errorname></term>
 467             <listitem><para>Value is too small.</para></listitem>
 468           </varlistentry>
 469
 470           <varlistentry>
 471             <term><errorname>IE_NOTUNIQ</errorname></term>
 472             <listitem><para>Value is not uniq.</para></listitem>
 473           </varlistentry>
 474
 475           <varlistentry>
 476             <term><errorname>IE_NOTEQUAL</errorname></term>
 477             <listitem><para>Compared values are not equal.</para></listitem>
 478           </varlistentry>
 479
 480           <varlistentry>
 481             <term><errorname>IE_PARTIAL_SUCCESS</errorname></term>
 482             <listitem><para>Operaration on a vector succeded for some values, but failed for others.</para></listitem>
 483           </varlistentry>
 484
 485           <varlistentry>
 486             <term><errorname>IE_ABORTED</errorname></term>
 487             <listitem><para>Operation was aborted by application request.</para></listitem>
 488           </varlistentry>
 489
 490           <varlistentry>
 491             <term><errorname>IE_SECURITY</errorname></term>
 492             <listitem><para>Security requirements were not satisfied.</para></listitem>
 493           </varlistentry>
 494         </variablelist>
 495       </refsection>
 496
 497       <refsection>
 498         <title><type>isds_log_level</type></title>
 499         <synopsis>typedef enum <type>isds_log_level</type>;</synopsis>
 500         <para>Log level. Know values:</para>
 501         <variablelist>
 502           <varlistentry>
 503             <term><constant>ILL_NONE</constant></term>
 504             <listitem><para>0</para></listitem>
 505           </varlistentry>
 506
 507           <varlistentry>
 508             <term><constant>ILL_CRIT</constant></term>
 509             <listitem><para>10</para></listitem>
 510           </varlistentry>
 511
 512           <varlistentry>
 513             <term><constant>ILL_ERR</constant></term>
 514             <listitem><para>20</para></listitem>
 515           </varlistentry>
 516
 517           <varlistentry>
 518             <term><constant>ILL_WARNING</constant></term>
 519             <listitem><para>30</para></listitem>
 520           </varlistentry>
 521
 522           <varlistentry>
 523             <term><constant>ILL_INFO</constant></term>
 524             <listitem><para>40</para></listitem>
 525           </varlistentry>
 526
 527           <varlistentry>
 528             <term><constant>ILL_DEBUG</constant></term>
 529             <listitem><para>50</para></listitem>
 530           </varlistentry>
 531
 532           <varlistentry>
 533             <term><constant>ILL_ALL</constant></term>
 534             <listitem><para>100</para></listitem>
 535           </varlistentry>
 536         </variablelist>
 537       </refsection>
 538
 539       <refsection>
 540         <title><type>isds_log_facility</type></title>
 541         <synopsis>typedef enum <type>isds_log_facility</type>;</synopsis>
 542         <para>Log facility. Know values:</para>
 543         <variablelist>
 544           <varlistentry>
 545             <term><constant>ILF_NONE</constant></term>
 546             <listitem><para>0x0</para></listitem>
 547           </varlistentry>
 548
 549           <varlistentry>
 550             <term><constant>ILF_HTTP</constant></term>
 551             <listitem><para>0x1</para></listitem>
 552           </varlistentry>
 553
 554           <varlistentry>
 555             <term><constant>ILF_SOAP</constant></term>
 556             <listitem><para>0x2</para></listitem>
 557           </varlistentry>
 558
 559           <varlistentry>
 560             <term><constant>ILF_ISDS</constant></term>
 561             <listitem><para>0x4</para></listitem>
 562           </varlistentry>
 563
 564           <varlistentry>
 565             <term><constant>ILF_FILE</constant></term>
 566             <listitem><para>0x8</para></listitem>
 567           </varlistentry>
 568
 569           <varlistentry>
 570             <term><constant>ILF_SEC</constant></term>
 571             <listitem><para>0x10</para></listitem>
 572           </varlistentry>
 573
 574           <varlistentry>
 575             <term><constant>ILF_XML</constant></term>
 576             <listitem><para>0x20</para></listitem>
 577           </varlistentry>
 578
 579           <varlistentry>
 580             <term><constant>ILF_ALL</constant></term>
 581             <listitem><para>0xFF</para></listitem>
 582           </varlistentry>
 583         </variablelist>
 584       </refsection>
 585
 586       <refsection>
 587         <title><type>isds_option</type></title>
 588         <synopsis>typedef enum <type>isds_option</type>;</synopsis>
 589         <para>libisds option identifiers. Known values:</para>
 590         <variablelist>
 591           <varlistentry>
 592             <term><constant>IOPT_TLS_VERIFY_SERVER</constant></term>
 593             <listitem><para>Option type is <type>_Bool</type>. Whether to
 594                 verify server identity. Default value is
 595                 true.</para></listitem>
 596           </varlistentry>
 597
 598           <varlistentry>
 599             <term><constant>IOPT_TLS_CA_FILE</constant></term>
 600             <listitem><para>Option type is <type>char *</type>. Option value
 601                 is a file name with certificate authority
 602                 certificates. Default value depends on used cryptographic
 603                 library.</para></listitem>
 604           </varlistentry>
 605
 606           <varlistentry>
 607             <term><constant>IOPT_TLS_CA_DIRECTORY</constant></term>
 608             <listitem><para>Option type is <type>char *</type>, Option value
 609                 is a directory with certificate authority certificates.
 610                 Default value depends on used cryptographic
 611                 library.</para></listitem>
 612           </varlistentry>
 613
 614           <varlistentry>
 615             <term><constant>IOPT_TLS_CRL_FILE</constant></term>
 616             <listitem><para>Option type is <type>char *</type>. Option value
 617                 is a file name with certificat revocation list in
 618                 <abbrev>PEM</abbrev> format. Default value depends on used
 619                 cryptographic library.</para></listitem>
 620           </varlistentry>
 621
 622           <varlistentry>
 623             <term><constant>IOPT_NORMALIZE_MIME_TYPE</constant></term>
 624             <listitem><para>Optiona type is <type>_Bool</type>. Whether to
 625                 normalize <abbrev>MIME</abbrev> type values. Default value is
 626                 false.</para></listitem>
 627           </varlistentry>
 628         </variablelist>
 629       </refsection>
 630
 631       <refsection>
 632         <title><type>isds_tls_option</type></title>
 633         <synopsis>typedef enum <type>isds_tls_option</type>;</synopsis>
 634         <warning><para>This type is deprecated.</para></warning>
 635         <para><abbrev>TLS</abbrev> libisds option identifiers. Known values:</para>
 636         <variablelist>
 637           <varlistentry>
 638             <term><constant>ITLS_VERIFY_SERVER</constant></term>
 639             <listitem><para>Option type is <type>_Bool</type>. Whether to
 640                 verify server identity.</para></listitem>
 641           </varlistentry>
 642
 643           <varlistentry>
 644             <term><constant>ITLS_CA_FILE</constant></term>
 645             <listitem><para>Option type is <type>char *</type>. Option value
 646                 is a file name with certificate authority
 647                 certificates.</para></listitem>
 648           </varlistentry>
 649
 650           <varlistentry>
 651             <term><constant>ITLS_CA_DIRECTORY</constant></term>
 652             <listitem><para>Option type is <type>char *</type>. Option value
 653                 is a directory name with certificate authority
 654                 certificates.</para></listitem>
 655           </varlistentry>
 656
 657           <varlistentry>
 658             <term><constant>ITLS_CRL_FILE</constant></term>
 659             <listitem><para>Option type is <type>char *</type>. Option value
 660                 is a file name with certificate revocation list in
 661                 <abbrev>PEM</abbrev> format.</para></listitem>
 662           </varlistentry>
 663         </variablelist>
 664       </refsection>
 665
 666       <refsection>
 667         <title><type>isds_pki_format</type></title>
 668         <synopsis>typedef enum <type>isds_pki_format</type>;</synopsis>
 669         <para>Cryptographic material encoding. Known values:</para>
 670         <variablelist>
 671           <varlistentry>
 672             <term><constant>PKI_FORMAT_PEM</constant></term>
 673             <listitem><para><abbrev>PEM</abbrev> format.</para></listitem>
 674           </varlistentry>
 675
 676           <varlistentry>
 677             <term><constant>PKI_FORMAT_DER</constant></term>
 678             <listitem><para><abbrev>DER format.</abbrev></para></listitem>
 679           </varlistentry>
 680
 681           <varlistentry>
 682             <term><constant>PKI_FORMAT_ENG</constant></term>
 683             <listitem><para>The material is stored in a cryptographic engine.</para></listitem>
 684           </varlistentry>
 685         </variablelist>
 686       </refsection>
 687
 688       <refsection>
 689         <title>struct <structname>isds_pki_credentials</structname></title>
 690         <synopsis>struct <structname>isds_pki_credentials</structname>;</synopsis>
 691         <para>This structure holds public key infrastructure cryptographic
 692           material to authenticate a client. Members are:</para>
 693         <variablelist>
 694           <varlistentry>
 695             <term><type>char *</type><structfield>engine</structfield>;</term>
 696             <listitem><para>String identifier of cryptographic engine to use
 697                 (where key is stored). Use NULL for no
 698                 engine.</para></listitem>
 699           </varlistentry>
 700
 701           <varlistentry>
 702             <term><type>isds_pki_format</type> <structfield>certificate_format</structfield>;</term>
 703             <listitem><para>Certificate format.</para></listitem>
 704           </varlistentry>
 705
 706           <varlistentry>
 707             <term><type>char *</type><structfield>certificate</structfield>;</term>
 708             <listitem><para>A path to client certificate, or a certificate
 709                 nickname in case of <abbrev>NSS</abbrev> as curl back-end, or
 710                 key slot identifier inside cryptographic engine. Some
 711                 cryptographinc engines can pair certificate with key
 712                 automatically (NULL value).</para></listitem>
 713           </varlistentry>
 714
 715           <varlistentry>
 716             <term><type>isds_pki_format</type> <structfield>key_format</structfield>;</term>
 717             <listitem><para>Private key format.</para></listitem>
 718           </varlistentry>
 719
 720           <varlistentry>
 721             <term><type>char *</type><structfield>key</structfield>;</term>
 722             <listitem><para>A path to client private key, or key identifier in
 723                 case an engine is used.</para></listitem>
 724           </varlistentry>
 725
 726           <varlistentry>
 727             <term><type>char *</type><structfield>passphrase</structfield>;</term>
 728             <listitem><para>Zero terminated string with password for
 729                 decrypting private key, or engine <abbrev>PIN</abbrev>. Use
 730                 NULL for no pass-phrase or to let the engine to ask for
 731                 it.</para></listitem>
 732           </varlistentry>
 733         </variablelist>
 734       </refsection>
 735
 736       <refsection>
 737         <title><type>isds_otp_method</type></title>
 738         <synopsis>typedef enum <type>isds_otp_method</type>;</synopsis>
 739         <para>One-time password authentication method. Known values:</para>
 740         <variablelist>
 741           <varlistentry>
 742             <term><constant>OTP_HMAC</constant></term>
 743             <listitem><para><abbrev>HMAC</abbrev>-based <abbrev>OTP</abbrev> method.</para></listitem>
 744           </varlistentry>
 745
 746           <varlistentry>
 747             <term><constant>OTP_TIME</constant></term>
 748             <listitem><para>Time-based <abbrev>OTP</abbrev> method.</para></listitem>
 749           </varlistentry>
 750         </variablelist>
 751       </refsection>
 752
 753       <refsection>
 754         <title><type>isds_otp_resolution</type></title>
 755         <synopsis>typedef enum <type>isds_otp_resolution</type>;</synopsis>
 756         <para>One-time password authentication resolution. Known values:</para>
 757         <variablelist>
 758           <varlistentry>
 759             <term><constant>OTP_RESOLUTION_SUCCESS</constant></term>
 760             <listitem><para>Authentication succeded.</para></listitem>
 761           </varlistentry>
 762
 763           <varlistentry>
 764             <term><constant>OTP_RESOLUTION_UNKNOWN</constant></term>
 765             <listitem><para>Status is unkown.</para></listitem>
 766           </varlistentry>
 767
 768           <varlistentry>
 769             <term><constant>OTP_RESOLUTION_BAD_AUTHENTICATION</constant></term>
 770             <listitem><para>Bad log-in. You can retry to log in.</para></listitem>
 771           </varlistentry>
 772
 773           <varlistentry>
 774             <term><constant>OTP_RESOLUTION_ACCESS_BLOCKED</constant></term>
 775             <listitem><para>Access blocked for 60 minutes. (Because a brute
 776                 force attack was detected.)</para></listitem>
 777           </varlistentry>
 778
 779           <varlistentry>
 780             <term><constant>OTP_RESOLUTION_PASSWORD_EXPIRED</constant></term>
 781             <listitem>
 782               <para>Password has expired.</para>
 783               <note>
 784                 <para>It's not clear which password expired:
 785                   <abbrev>OTP</abbrev> or regular password?</para>
 786               </note>
 787             </listitem>
 788           </varlistentry>
 789
 790           <varlistentry>
 791             <term><constant>OTP_RESOLUTION_TO_FAST</constant></term>
 792             <listitem><para><abbrev>OTP</abbrev> cannot be sent repeatedly at
 793                 this rate. (Minimal delay depends on <abbrev>TOTP</abbrev>
 794                 window setting.)</para></listitem>
 795           </varlistentry>
 796
 797           <varlistentry>
 798             <term><constant>OTP_RESOLUTION_UNAUTHORIZED</constant></term>
 799             <listitem><para>User name is not allowed to access requested
 800                 <abbrev>URI</abbrev>.</para></listitem>
 801           </varlistentry>
 802
 803           <varlistentry>
 804             <term><constant>OTP_RESOLUTION_TOTP_SENT</constant></term>
 805             <listitem><para><abbrev>OTP</abbrev> has been generated and sent
 806                 by the <abbrev>ISDS</abbrev> to the user.</para></listitem>
 807           </varlistentry>
 808
 809           <varlistentry>
 810             <term><constant>OTP_RESOLUTION_TOTP_NOT_SENT</constant></term>
 811             <listitem><para><abbrev>OTP</abbrev> could not been sent by the
 812                 <abbrev>ISDS</abbrev>. Retry later.</para></listitem>
 813           </varlistentry>
 814         </variablelist>
 815       </refsection>
 816
 817       <refsection>
 818         <title>struct <structname>isds_otp</structname></title>
 819         <synopsis>struct <structname>isds_otp</structname>;</synopsis>
 820         <para>This structure holds one-time password when authenticating
 821           a client and resolution of the authentication.</para>
 822
 823         <para>Input members are:</para>
 824         <variablelist>
 825           <varlistentry>
 826             <term><type>isds_otp_method</type> <structfield>method</structfield>;</term>
 827             <listitem><para>Select <abbrev>OTP</abbrev> method to use.</para></listitem>
 828           </varlistentry>
 829
 830           <varlistentry>
 831             <term><type>char *</type><structfield>otp_code</structfield>;</term>
 832             <listitem><para>One-time password to use. Pass NULL, if you do not
 833                 know it yet (<abbrev>e.g.</abbrev> in case of first phase of
 834                 time-based <abbrev>OTP</abbrev> authentication to request new
 835                 code from <abbrev>ISDS</abbrev>.)</para></listitem>
 836           </varlistentry>
 837         </variablelist>
 838
 839         <para>Output members are:</para>
 840         <variablelist>
 841           <varlistentry>
 842             <term><type>isds_otp_resolution</type> <structfield>resolution</structfield>;</term>
 843             <listitem><para>Fine-grade resolution of this <abbrev>OTP</abbrev>
 844                 authentication attempt.</para></listitem>
 845           </varlistentry>
 846         </variablelist>
 847       </refsection>
 848
 849       <refsection>
 850         <title><type>isds_DbType</type></title>
 851         <synopsis>typedef enum <type>isds_DbType</type>;</synopsis>
 852         <para>Box type. It classifies box owner by his legal status. Known
 853           values:</para>
 854         <variablelist>
 855           <varlistentry>
 856             <term><constant>DBTYPE_OVM_MAIN</constant></term>
 857             <listitem><para>This is a special value for
 858                 <function>isds_find_box_by_fulltext</function>.
 859                 It's not accepted by any other
 860                 <abbrev>services</abbrev>.</para></listitem>
 861           </varlistentry>
 862
 863           <varlistentry>
 864             <term><constant>DBTYPE_SYSTEM</constant></term>
 865             <listitem><para>This is a special value for sender of messages sent
 866                 by the <abbrev>ISDS</abbrev>. You can find it only in
 867                 incomming messages. It's not accepted by any other
 868                 <abbrev>services</abbrev>.</para></listitem>
 869           </varlistentry>
 870
 871           <varlistentry>
 872             <term><constant>DBTYPE_OVM</constant></term>
 873             <listitem><para>Standard government (state or municipality or
 874                 similar) office.</para></listitem>
 875           </varlistentry>
 876
 877           <varlistentry>
 878             <term><constant>DBTYPE_OVM_NOTAR</constant></term>
 879             <listitem><para>Notary.</para></listitem>
 880           </varlistentry>
 881
 882           <varlistentry>
 883             <term><constant>DBTYPE_OVM_EXEKUT</constant></term>
 884             <listitem><para>Executor.</para></listitem>
 885           </varlistentry>
 886
 887           <varlistentry>
 888             <term><constant>DBTYPE_OVM_REQ</constant></term>
 889             <listitem><para>Subsidiary office with <abbrev>OVM</abbrev>
 890                 (governing) status assigned on request (section 6 and 7 of the
 891                 act).</para></listitem>
 892           </varlistentry>
 893
 894           <varlistentry>
 895             <term><constant>DBTYPE_PO</constant></term>
 896             <listitem><para>Standard commercial organization (listed in trade
 897                 registry).</para></listitem>
 898           </varlistentry>
 899
 900           <varlistentry>
 901             <term><constant>DBTYPE_PO_ZAK</constant></term>
 902             <listitem><para>Other organization founded by an act.</para></listitem>
 903           </varlistentry>
 904
 905           <varlistentry>
 906             <term><constant>DBTYPE_PO_REQ</constant></term>
 907             <listitem><para>An organization with a box assigned on its
 908                 request.</para></listitem>
 909           </varlistentry>
 910
 911           <varlistentry>
 912             <term><constant>DBTYPE_PFO</constant></term>
 913             <listitem><para>Person in bussiness.</para></listitem>
 914           </varlistentry>
 915
 916           <varlistentry>
 917             <term><constant>DBTYPE_PFO_ADVOK</constant></term>
 918             <listitem><para>Lawyer.</para></listitem>
 919           </varlistentry>
 920
 921           <varlistentry>
 922             <term><constant>DBTYPE_PFO_DANPOR</constant></term>
 923             <listitem><para>Tax consultant.</para></listitem>
 924           </varlistentry>
 925
 926           <varlistentry>
 927             <term><constant>DBTYPE_PFO_INSSPR</constant></term>
 928             <listitem><para>Administrator of insolvency.</para></listitem>
 929           </varlistentry>
 930
 931           <varlistentry>
 932             <term><constant>DBTYPE_FO</constant></term>
 933             <listitem><para>Standard person.</para></listitem>
 934           </varlistentry>
 935         </variablelist>
 936       </refsection>
 937
 938       <refsection>
 939         <title><type>isds_DbState</type></title>
 940         <synopsis>typedef enum <type>isds_DbState</type>;</synopsis>
 941         <para>Box status from point of view of accessibility. Known
 942           values:</para>
 943         <variablelist>
 944           <varlistentry>
 945             <term><constant>DBSTATE_ACCESSIBLE</constant></term>
 946             <listitem><para>The box is accessible.</para></listitem>
 947           </varlistentry>
 948
 949           <varlistentry>
 950             <term><constant>DBSTATE_TEMP_UNACCESSIBLE</constant></term>
 951             <listitem><para>The box is temporarily inaccessible.</para></listitem>
 952           </varlistentry>
 953
 954           <varlistentry>
 955             <term><constant>DBSTATE_NOT_YET_ACCESSIBLE</constant></term>
 956             <listitem><para>The box has not yet been activated.</para></listitem>
 957           </varlistentry>
 958
 959           <varlistentry>
 960             <term><constant>DBSTATE_PERM_UNACCESSIBLE</constant></term>
 961             <listitem><para>The box is permanently inaccessible.</para></listitem>
 962           </varlistentry>
 963
 964           <varlistentry>
 965             <term><constant>DBSTATE_REMOVED</constant></term>
 966             <listitem><para>The box has been removed.</para></listitem>
 967           </varlistentry>
 968         </variablelist>
 969       </refsection>
 970
 971       <refsection>
 972         <title><type>isds_priviledges</type></title>
 973         <synopsis>typedef enum <type>isds_priviledges</type>;</synopsis>
 974         <para>Distinct user permissions from point of view of <abbrev>ISDS</abbrev>.
 975           Instances can be bitmaps of any of these distinct values. Distinct known
 976           values are:</para>
 977         <variablelist>
 978           <varlistentry>
 979             <term><constant>PRIVIL_READ_NON_PERSONAL</constant></term>
 980             <listitem><para>The user can download and read messages with
 981                 <structfield>dmPersonalDelivery</structfield> equaled to
 982                 false.</para></listitem>
 983           </varlistentry>
 984
 985           <varlistentry>
 986             <term><constant>PRIVIL_READ_ALL</constant></term>
 987             <listitem><para>The user can download and read messages with
 988                 <structfield>dmPersonalDelivery</structfield> equaled to
 989                 true.</para></listitem>
 990           </varlistentry>
 991
 992           <varlistentry>
 993             <term><constant>PRIVIL_CREATE_DM</constant></term>
 994             <listitem><para>The user can create and send messages, the user
 995                 can download outgoing (sent) messages.</para></listitem>
 996           </varlistentry>
 997
 998           <varlistentry>
 999             <term><constant>PRIVIL_VIEW_INFO</constant></term>
1000             <listitem><para>The user can list messages and read data about
1001                 a message post and delivery.</para></listitem>
1002           </varlistentry>
1003
1004           <varlistentry>
1005             <term><constant>PRIVIL_SEARCH_DB</constant></term>
1006             <listitem><para>The user can can search for
1007                 boxes.</para></listitem>
1008           </varlistentry>
1009
1010           <varlistentry>
1011             <term><constant>PRIVIL_OWNER_ADM</constant></term>
1012             <listitem><para>The user can administer his box (to add and remove
1013                 permitted users and to modify theirs
1014                 permissions.)</para></listitem>
1015           </varlistentry>
1016
1017           <varlistentry>
1018             <term><constant>PRIVIL_READ_VAULT</constant></term>
1019             <listitem>
1020               <para>The user can read messages stored in the long term storage.</para>
1021               <note><para>This permission is not used since 2012-05.</para></note>
1022             </listitem>
1023           </varlistentry>
1024
1025           <varlistentry>
1026             <term><constant>PRIVIL_ERASE_VAULT</constant></term>
1027             <listitem><para>The user can delete messages from the long term
1028                 storage.</para></listitem>
1029           </varlistentry>
1030         </variablelist>
1031       </refsection>
1032
1033       <refsection>
1034         <title><type>isds_message_status</type></title>
1035         <synopsis>typedef enum <type>isds_message_status</type>;</synopsis>
1036         <para>Message status. Known values are:</para>
1037         <variablelist>
1038           <varlistentry>
1039             <term><constant>MESSAGESTATE_SENT</constant></term>
1040             <listitem><para>The message has been put into
1041                 <abbrev>ISDS</abbrev>.</para></listitem>
1042           </varlistentry>
1043
1044           <varlistentry>
1045             <term><constant>MESSAGESTATE_STAMPED</constant></term>
1046             <listitem><para>Message was stamped by a time stamp
1047                 authority.</para></listitem>
1048           </varlistentry>
1049
1050           <varlistentry>
1051             <term><constant>MESSAGESTATE_INFECTED</constant></term>
1052             <listitem><para>The message included viruses. Infected documents
1053                 have been removed from the message.</para></listitem>
1054           </varlistentry>
1055
1056           <varlistentry>
1057             <term><constant>MESSAGESTATE_DELIVERED</constant></term>
1058             <listitem><para>The message was delivered.
1059                 (<structfield>dmDeliveryTime</structfield> is
1060                     populated.)</para></listitem>
1061           </varlistentry>
1062
1063           <varlistentry>
1064             <term><constant>MESSAGESTATE_SUBSTITUTED</constant></term>
1065             <listitem><para>The message was delivered through fiction,
1066                 <structfield>dmAcceptanceTime</structfield> is
1067                 populated.</para></listitem>
1068           </varlistentry>
1069
1070           <varlistentry>
1071             <term><constant>MESSAGESTATE_RECEIVED</constant></term>
1072             <listitem><para>The message was accepted (by user's log-in or
1073                 user's explicit request).
1074                 <structfield>dmAcceptanceTime</structfield> is
1075                 populated.</para></listitem>
1076           </varlistentry>
1077
1078           <varlistentry>
1079             <term><constant>MESSAGESTATE_READ</constant></term>
1080             <listitem><para>The message has been read by
1081                 a user.</para></listitem>
1082           </varlistentry>
1083
1084           <varlistentry>
1085             <term><constant>MESSAGESTATE_UNDELIVERABLE</constant></term>
1086             <listitem><para>The message could not been delivered.
1087                 (<abbrev>E.g.</abbrev>The recipient's box has been made
1088                 inaccessible meantime.)</para></listitem>
1089           </varlistentry>
1090
1091           <varlistentry>
1092             <term><constant>MESSAGESTATE_REMOVED</constant></term>
1093             <listitem><para>The message's content was
1094                 deleted.</para></listitem>
1095           </varlistentry>
1096
1097           <varlistentry>
1098             <term><constant>MESSAGESTATE_IN_SAFE</constant></term>
1099             <listitem><para>The message is stored in the long term
1100                 storage.</para></listitem>
1101           </varlistentry>
1102         </variablelist>
1103
1104         <para>The values can be combined into a bit mask for some functions.
1105           A special <constant>MESSAGESTATE_ANY</constant> macro denotes any of
1106           the states.</para>
1107       </refsection>
1108
1109       <refsection>
1110         <title><type>isds_hash_algorithm</type></title>
1111         <synopsis>typedef enum <type>isds_hash_algorithm</type>;</synopsis>
1112         <para>Hash algorithm types. Known values are:</para>
1113         <variablelist>
1114           <varlistentry>
1115             <term><constant>HASH_ALGORITHM_MD5</constant></term>
1116             <listitem><para><abbrev>MD5</abbrev>.</para></listitem>
1117           </varlistentry>
1118
1119           <varlistentry>
1120             <term><constant>HASH_ALGORITHM_SHA_1</constant></term>
1121             <listitem><para><abbrev>SHA-1</abbrev>.</para></listitem>
1122           </varlistentry>
1123
1124           <varlistentry>
1125             <term><constant>HASH_ALGORITHM_SHA_224</constant></term>
1126             <listitem><para><abbrev>SHA-224</abbrev>.</para></listitem>
1127           </varlistentry>
1128
1129           <varlistentry>
1130             <term><constant>HASH_ALGORITHM_SHA_256</constant></term>
1131             <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1132           </varlistentry>
1133
1134           <varlistentry>
1135             <term><constant>HASH_ALGORITHM_SHA_384</constant></term>
1136             <listitem><para><abbrev>SHA-384</abbrev>.</para></listitem>
1137           </varlistentry>
1138
1139           <varlistentry>
1140             <term><constant>HASH_ALGORITHM_SHA_512</constant></term>
1141             <listitem><para><abbrev>SHA-256</abbrev>.</para></listitem>
1142           </varlistentry>
1143         </variablelist>
1144       </refsection>
1145
1146       <refsection>
1147         <title><type>isds_buffer_strategy</type></title>
1148         <synopsis>typedef enum <type>isds_buffer_strategy</type>;</synopsis>
1149         <para>Buffer storage strategy. This type defines how a function should
1150           embed application provided buffer into
1151           <structfield>raw</structfield> element of output structure. Known
1152           values are:</para>
1153         <variablelist>
1154           <varlistentry>
1155             <term><constant>BUFFER_DONT_STORE</constant></term>
1156             <listitem><para>Don't fill <structfield>raw</structfield>
1157                 member.</para></listitem>
1158           </varlistentry>
1159
1160           <varlistentry>
1161             <term><constant>BUFFER_COPY</constant></term>
1162             <listitem><para>Copy buffer content into newly allocated
1163                 <structfield>raw</structfield> member.</para></listitem>
1164           </varlistentry>
1165
1166           <varlistentry>
1167             <term><constant>BUFFER_MOVE</constant></term>
1168             <listitem><para>Copy pointer. Leave deallocation to structure
1169                 destructor
1170                 (<function>isds_*_free</function>()).</para></listitem>
1171           </varlistentry>
1172         </variablelist>
1173       </refsection>
1174
1175       <refsection>
1176         <title>struct <structname>isds_hash</structname></title>
1177         <synopsis>struct <structname>isds_hash</structname>;</synopsis>
1178         <para>This is a hash value storage. Members are:</para>
1179         <variablelist>
1180           <varlistentry>
1181             <term><type>isds_hash_algorithm</type>
1182               <structfield>algorithm</structfield>;</term>
1183             <listitem><para>Hash algorithm.</para></listitem>
1184           </varlistentry>
1185
1186           <varlistentry>
1187             <term><type>size_t</type> <structfield>length</structfield>;</term>
1188             <listitem><para>Hash value length in bytes.</para></listitem>
1189           </varlistentry>
1190
1191           <varlistentry>
1192             <term><type>void *</type><structfield>value</structfield>;</term>
1193             <listitem><para>Hash value as a byte stream.</para></listitem>
1194           </varlistentry>
1195         </variablelist>
1196       </refsection>
1197
1198       <refsection>
1199         <title>struct <structname>isds_PersonName</structname></title>
1200         <synopsis>struct <structname>isds_PersonName</structname>;</synopsis>
1201         <para>Name of a person. Members are:</para>
1202         <variablelist>
1203           <varlistentry>
1204             <term><type>char *</type><structfield>pnFirstName</structfield>;</term>
1205             <listitem><para>First name.</para></listitem>
1206           </varlistentry>
1207
1208           <varlistentry>
1209             <term><type>char *</type><structfield>pnMiddleName</structfield>;</term>
1210             <listitem><para>Middle name.</para></listitem>
1211           </varlistentry>
1212
1213           <varlistentry>
1214             <term><type>char *</type><structfield>pnLastName</structfield>;</term>
1215             <listitem><para>Current last name.</para></listitem>
1216           </varlistentry>
1217
1218           <varlistentry>
1219             <term><type>char *</type><structfield>pnLastNameAtBirth</structfield>;</term>
1220             <listitem><para>Last name at birth.</para></listitem>
1221           </varlistentry>
1222         </variablelist>
1223       </refsection>
1224
1225       <refsection>
1226         <title>struct <structname>isds_BirthInfo</structname></title>
1227         <synopsis>struct <structname>isds_BirthInfo</structname>;</synopsis>
1228         <para>Date and place of a birth. Members are:</para>
1229         <variablelist>
1230           <varlistentry>
1231             <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1232             <listitem><para>Date of birth in local time at the birth place.
1233                 Only <structfield>tm_year</structfield>,
1234                 <structfield>tm_mon</structfield> and
1235                 <structfield>tm_mday</structfield> members of the <type>struct
1236                   tm</type> carry sane value. Others are
1237                 undefined.</para></listitem>
1238           </varlistentry>
1239
1240           <varlistentry>
1241             <term><type>char *</type><structfield>biCity</structfield>;</term>
1242             <listitem><para>City where a person was born.</para></listitem>
1243           </varlistentry>
1244
1245           <varlistentry>
1246             <term><type>char *</type><structfield>biCounty</structfield>;</term>
1247             <listitem><para>Region where a person was born. This is the kind
1248                 of region that is called <phrase lang="de">Bezirk</phrase> in
1249                 German and <phrase lang="cs">okres</phrase> in
1250                 Czech.</para></listitem>
1251           </varlistentry>
1252
1253           <varlistentry>
1254             <term><type>char *</type><structfield>biState</structfield>;</term>
1255             <listitem><para>State wher a person was born.</para></listitem>
1256           </varlistentry>
1257         </variablelist>
1258       </refsection>
1259
1260       <refsection>
1261         <title>struct <structname>isds_Address</structname></title>
1262         <synopsis>struct <structname>isds_Address</structname>;</synopsis>
1263         <para>Postal address. Members are:</para>
1264         <variablelist>
1265           <varlistentry>
1266             <term><type>long int *</type><structfield>adCode</structfield>;</term>
1267             <listitem><para><abbrev>RUIN</abbrev> address code.</para></listitem>
1268           </varlistentry>
1269
1270           <varlistentry>
1271             <term><type>char *</type><structfield>adCity</structfield>;</term>
1272             <listitem><para>City.</para></listitem>
1273           </varlistentry>
1274
1275           <varlistentry>
1276             <term><type>char *</type><structfield>adDistrict</structfield>;</term>
1277             <listitem><para>Municipality part.</para></listitem>
1278           </varlistentry>
1279
1280           <varlistentry>
1281             <term><type>char *</type><structfield>adStreet</structfield>;</term>
1282             <listitem><para>Street.</para></listitem>
1283           </varlistentry>
1284
1285           <varlistentry>
1286             <term><type>char *</type><structfield>adNumberInStreet</structfield>;</term>
1287             <listitem><para>Identification of an entrance on the
1288                 street. <phrase lang="cs">Číslo orientační</phrase> in
1289                 Czech.</para></listitem>
1290           </varlistentry>
1291
1292           <varlistentry>
1293             <term><type>char *</type><structfield>adNumberInMunicipality</structfield>;</term>
1294             <listitem><para>Identification of a building in the municipality.
1295                 <phrase lang="cs">Číslo popisné</phrase> in
1296                 Czech.</para></listitem>
1297           </varlistentry>
1298
1299           <varlistentry>
1300             <term><type>char *</type><structfield>adZipCode</structfield>;</term>
1301             <listitem><para>Postal code for mail routing.</para></listitem>
1302           </varlistentry>
1303
1304           <varlistentry>
1305             <term><type>char *</type><structfield>adState</structfield>;</term>
1306             <listitem><para>State.</para></listitem>
1307           </varlistentry>
1308         </variablelist>
1309       </refsection>
1310
1311       <refsection>
1312         <title>struct <structname>isds_DbOwnerInfo</structname></title>
1313         <synopsis>struct <structname>isds_DbOwnerInfo</structname>;</synopsis>
1314         <para>Data about a box and his owner. NULL pointer values mean
1315           undefined values. Members are:</para>
1316         <variablelist>
1317           <varlistentry>
1318             <term><type>char *</type><structfield>dbID</structfield>;</term>
1319             <listitem><para>Box identifier. Specification limits the length to
1320                 7 characters.</para></listitem>
1321           </varlistentry>
1322
1323           <varlistentry>
1324             <term><type>isds_DbType *</type><structfield>dbType</structfield>;</term>
1325             <listitem><para>Box type.</para></listitem>
1326           </varlistentry>
1327
1328           <varlistentry>
1329             <term><type>char *</type><structfield>ic</structfield>;</term>
1330             <listitem><para>Identifier of the owner.</para></listitem>
1331           </varlistentry>
1332
1333           <varlistentry>
1334             <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1335             <listitem><para>Name of a person owning the box.</para></listitem>
1336           </varlistentry>
1337
1338           <varlistentry>
1339             <term><type>char *</type><structfield>firmName</structfield>;</term>
1340             <listitem><para>Name of a firm owning the box.</para></listitem>
1341           </varlistentry>
1342
1343           <varlistentry>
1344             <term><type>isds_BirthInfo *</type><structfield>birthInfo</structfield>;</term>
1345             <listitem><para>Birth details of the person.</para></listitem>
1346           </varlistentry>
1347
1348           <varlistentry>
1349             <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1350             <listitem><para>Postal address of the owner.</para></listitem>
1351           </varlistentry>
1352
1353           <varlistentry>
1354             <term><type>char *</type><structfield>nationality</structfield>;</term>
1355             <listitem><para>Nationality of the owner.</para></listitem>
1356           </varlistentry>
1357
1358           <varlistentry>
1359             <term><type>char *</type><structfield>email</structfield>;</term>
1360             <listitem><para>E-mail addres of the owner.</para></listitem>
1361           </varlistentry>
1362
1363           <varlistentry>
1364             <term><type>char *</type><structfield>telNumber</structfield>;</term>
1365             <listitem><para>Telephone number of the owner.</para></listitem>
1366           </varlistentry>
1367
1368           <varlistentry>
1369             <term><type>char *</type><structfield>identifier</structfield>;</term>
1370             <listitem><para>External box identifier for data provider
1371                 (<abbrev>OVM</abbrev>, <abbrev>PO</abbrev>, maybe
1372                 <abbrev>PFO</abbrev> box types.) Specification limits the
1373                 length to 20 characters.</para></listitem>
1374           </varlistentry>
1375
1376           <varlistentry>
1377             <term><type>_Bool *</type><structfield>aifoIsds</structfield>;</term>
1378             <listitem><para>Reference to citizen registry exists.</para></listitem>
1379           </varlistentry>
1380
1381           <varlistentry>
1382             <term><type>char *</type><structfield>registryCode</structfield>;</term>
1383             <listitem><para><abbrev>PFO</abbrev> external registry code.
1384                 Specification limits the length to
1385                 5 characters.</para></listitem>
1386           </varlistentry>
1387
1388           <varlistentry>
1389             <term><type>long int *</type><structfield>dbState</structfield>;</term>
1390             <listitem>
1391               <para>Box state. 1 means the box is active.</para>
1392               <note><para>The type is long int because specification declares it
1393                   as <type>xsd:integer</type>.</para></note>
1394               <note><para>TODO: enum?</para></note></listitem>
1395           </varlistentry>
1396
1397           <varlistentry>
1398             <term><type>_Bool *</type><structfield>dbEffectiveOVM</structfield>;</term>
1399             <listitem><para>The Box has <abbrev>OVM</abbrev> role (section 5a
1400                 of the act).</para></listitem>
1401           </varlistentry>
1402
1403           <varlistentry>
1404             <term><type>_Bool *</type><structfield>dbOpenAddressing</structfield>;</term>
1405             <listitem>This <para>non-<abbrev>OVM</abbrev> box is free to
1406                 receive messages from anybody.</para></listitem>
1407           </varlistentry>
1408         </variablelist>
1409       </refsection>
1410
1411       <refsection>
1412         <title><type>isds_UserType</type></title>
1413         <synopsis>typedef enum <type>isds_UserType</type>;</synopsis>
1414         <para>User type. Known values are:</para>
1415         <variablelist>
1416           <varlistentry>
1417             <term><constant>USERTYPE_PRIMARY</constant></term>
1418             <listitem><para>Owner of the box.</para></listitem>
1419           </varlistentry>
1420
1421           <varlistentry>
1422             <term><constant>USERTYPE_ENTRUSTED</constant></term>
1423             <listitem><para>User with limited access to the box.</para></listitem>
1424           </varlistentry>
1425
1426           <varlistentry>
1427             <term><constant>USERTYPE_ADMINISTRATOR</constant></term>
1428             <listitem><para>User who can manage
1429                 <constant>USERTYPE_ENTRUSTED</constant>
1430                 users.</para></listitem>
1431           </varlistentry>
1432
1433           <varlistentry>
1434             <term><constant>USERTYPE_OFFICIAL</constant></term>
1435             <listitem><para>???</para></listitem>
1436           </varlistentry>
1437
1438           <varlistentry>
1439             <term><constant>USERTYPE_OFFICIAL_CERT</constant></term>
1440             <listitem><para>???</para></listitem>
1441           </varlistentry>
1442
1443           <varlistentry>
1444             <term><constant>USERTYPE_LIQUIDATOR</constant></term>
1445             <listitem><para>Company liquidator.</para></listitem>
1446           </varlistentry>
1447         </variablelist>
1448       </refsection>
1449
1450       <refsection>
1451         <title>struct <structname>isds_DbUserInfo</structname></title>
1452         <synopsis>struct <structname>isds_DbUserInfo</structname>;</synopsis>
1453         <para>Data about a user. NULL pointer values mean
1454           undefined values. Members are:</para>
1455         <variablelist>
1456           <varlistentry>
1457             <term><type>char *</type><structfield>userID</structfield>;</term>
1458             <listitem><para>User identifier. Specification limits the length
1459                 from 6 to 12 characters.</para></listitem>
1460           </varlistentry>
1461
1462           <varlistentry>
1463             <term><type>isds_UserType *</type><structfield>userType</structfield>;</term>
1464             <listitem><para>User type.</para></listitem>
1465           </varlistentry>
1466
1467           <varlistentry>
1468             <term><type>long int *</type><structfield>userPrivils</structfield>;</term>
1469             <listitem><para>Set of user permissions.</para></listitem>
1470           </varlistentry>
1471
1472           <varlistentry>
1473             <term><type>isds_PersonName *</type><structfield>personName</structfield>;</term>
1474             <listitem><para>Name of the user.</para></listitem>
1475           </varlistentry>
1476
1477           <varlistentry>
1478             <term><type>isds_Address *</type><structfield>address</structfield>;</term>
1479             <listitem><para>Postal address of the user.</para></listitem>
1480           </varlistentry>
1481
1482           <varlistentry>
1483             <term><type>struct tm *</type><structfield>biDate</structfield>;</term>
1484             <listitem><para>Date of birth in local time.
1485                 Only <structfield>tm_year</structfield>,
1486                 <structfield>tm_mon</structfield> and
1487                 <structfield>tm_mday</structfield> members of the <type>struct
1488                   tm</type> carry sane value. Others are
1489                 undefined.</para></listitem>
1490           </varlistentry>
1491
1492           <varlistentry>
1493             <term><type>char *</type><structfield>ic</structfield>;</term>
1494             <listitem><para>Identifier a supervising firm. Specification
1495                 limits the length to 8 characters.</para></listitem>
1496           </varlistentry>
1497
1498           <varlistentry>
1499             <term><type>char *</type><structfield>firmName</structfield>;</term>
1500             <listitem><para>Name of a supervising firm. Specification limits
1501                 the length to 100 characters.</para></listitem>
1502           </varlistentry>
1503
1504           <varlistentry>
1505             <term><type>char *</type><structfield>caStreet</structfield>;</term>
1506             <listitem><para>Contact address. Street and number.</para></listitem>
1507           </varlistentry>
1508
1509           <varlistentry>
1510             <term><type>char *</type><structfield>caCity</structfield>;</term>
1511             <listitem><para>Czech city of the contact address.</para></listitem>
1512           </varlistentry>
1513
1514           <varlistentry>
1515             <term><type>char *</type><structfield>caZipCode</structfield>;</term>
1516             <listitem><para>Postal code of the contact address.</para></listitem>
1517           </varlistentry>
1518
1519           <varlistentry>
1520             <term><type>char *</type><structfield>caState</structfield>;</term>
1521             <listitem><para>Abbreviated country of contact address. This value
1522                 is optional and implicit meaning is
1523                 <constant>CZ</constant>.</para></listitem>
1524           </varlistentry>
1525
1526           <varlistentry>
1527             <term><type>char *</type><structfield>aifo_ticket</structfield>;</term>
1528             <listitem><para>Reference to citizen registry. This value is
1529                 optional.</para></listitem>
1530           </varlistentry>
1531         </variablelist>
1532       </refsection>
1533
1534       <refsection>
1535         <title>struct <structname>isds_box_state_period</structname></title>
1536         <synopsis>struct <structname>isds_box_state_period</structname>;</synopsis>
1537         <para>A box state valid in the time range. Members are:</para>
1538         <variablelist>
1539           <varlistentry>
1540             <term><type>struct timeval *</type><structfield>from</structfield>;</term>
1541             <listitem><para>Time range beginning.</para></listitem>
1542           </varlistentry>
1543
1544           <varlistentry>
1545             <term><type>struct timeval *</type><structfield>to</structfield>;</term>
1546             <listitem><para>Time range end.</para></listitem>
1547           </varlistentry>
1548
1549           <varlistentry>
1550             <term><type>long int </type><structfield>dbState</structfield>;</term>
1551             <listitem><para>Box state. <constant>1</constant> means the box is
1552                 accessible. Other values mean the box is inaccessible. You can
1553                 use <type>isds_DbState</type> enum to identify some
1554                 states.</para></listitem>
1555           </varlistentry>
1556         </variablelist>
1557       </refsection>
1558
1559
1560     </refsection>
1561
1562     <refsection>
1563       <title>Functions</title>
1564
1565       <itemizedlist>
1566         <listitem><funcsynopsis><funcprototype>
1567               <funcdef>const char *<function>isds_strerror</function></funcdef>
1568               <paramdef>const isds_error <parameter>error</parameter></paramdef>
1569         </funcprototype></funcsynopsis></listitem>
1570
1571         <listitem><funcsynopsis><funcprototype>
1572           <funcdef>struct isds_ctx *<function>isds_ctx_create</function></funcdef>
1573           <void/>
1574         </funcprototype></funcsynopsis></listitem>
1575       </itemizedlist>
1576     </refsection>
1577
1578     <refsection>
1579       <title>See Also</title>
1580
1581       <para>
1582         <simplelist type="inline">
1583           <member><citerefentry>
1584               <refentrytitle>libcurl</refentrytitle>
1585               <manvolnum>3</manvolnum>
1586           </citerefentry></member>
1587           <member><citerefentry>
1588               <refentrytitle>libisds</refentrytitle>
1589               <manvolnum>3</manvolnum>
1590           </citerefentry></member>
1591           <member><citerefentry>
1592               <refentrytitle>time.h</refentrytitle>
1593               <manvolnum>0p</manvolnum>
1594           </citerefentry></member>
1595         </simplelist>
1596       </para>
1597     </refsection>
1598   </refentry>
1599 </reference>