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         <citerefentry>
 270           <refentrytitle>libcurl</refentrytitle>
 271           <manvolnum>3</manvolnum>
 272         </citerefentry>
 273       </para>
 274     </refsection>
 275
 276   </refentry>
 277
 278 </reference>