1LIBDATOVKA(3)                Manual for Libdatovka               LIBDATOVKA(3)
2
3
4

NAME

6       libdatovka - ISDS client library
7

SYNOPSIS

9       #include <libdatovka/isds.h>
10       #include <stdio.h>
11
12       isds_error err;
13       struct isds_ctx *ctx;
14
15       err = isds_init();
16       ctx = isds_ctx_create();
17
18       err = isds_login(ctx, NULL, "username", "password", NULL, NULL);
19       if (err) {
20           printf("isds_login() failed: %s: %s\n",
21               isds_strerror(err), isds_long_message(ctx));
22       } else {
23           printf("Logged in.\n");
24       }
25
26       err = isds_ctx_free(&ctx);
27       err = isds_cleanup();
28

DESCRIPTION

30       This  is  a  client  library  for  accessing SOAP services of ISDS (In‐
31       formační systém datových schránek / Data Box Information System) as de‐
32       fined in Czech ISDS Act (300/2008 Coll.)[1] and implied documents. Cur‐
33       rent implementation details are described in Provozní řád that  can  be
34       downloaded  from  Dokumenty  ke  stažení  section  of  ISDS Information
35       Portal[2].
36
37       The library provides a C language interface with synchronous  non-reen‐
38       trant  blocking calls. Network communication progress reporting and op‐
39       eration logging and library debugging are implemented by  calling  back
40       application-provided  functions.  Network  operations  can be cancelled
41       from network reporting call-back.
42

LIBRARY INITIALIZATION AND DEINITIALIZATION

44       A libdatovka application  must  include  the  libdatovka/isds.h  header
45       file.  The  application  must call isds_init function to initialize the
46       library before calling any other library functions. After  last  libda‐
47       tovka  call,  isds_cleanup  function  should be called to clean up some
48       global resources and to deinitialize dependent libraries.
49

CONTEXTS

51       Most of the functions operate on an established connection to the  ISDS
52       server.  This  is called a context and it's represented by a pointer to
53       an opaque isds_ctx structure. The structure maintains state about  net‐
54       work connection, authorization or error from last call on the context.
55
56       The context is allocated by isds_ctx_create function and deallocated by
57       isds_ctx_free function.
58
59       There are more context subtypes. A specific subtype is assigned to  the
60       context  when a fresh new context is passed to one of the few stratify‐
61       ing        functions         (isds_login,         czp_convert_document,
62       isds_request_new_testing_box). Once the context is specialized, you can
63       use it only with functions understanding the subtype. This is  not  en‐
64       forced  by the library now, but it does not matter much because all the
65       other functions assume the isds_login was called  on  the  context.  In
66       other words, do not share the context among the three stratifying func‐
67       tions.
68
69       For  example  create  a  context  with   isds_ctx_create,   then   call
70       isds_login, then work with box, then call isds_logout. Here you can re‐
71       use the context and log in as another user by calling isds_login  again
72       or destroy the context with isds_ctx_free if you don't need it anymore.
73
74       Or create a context with isds_ctx_create, send a document to authorized
75       conversion using czp_convert_document, then you can send more documents
76       to  the  authorized conversion by calling czp_convert_document again on
77       the same context and finally destroy the context with isds_ctx_free.
78

ERRORS

80       Most of the functions return an error code of isds_error type.  IE_SUC‐
81       CESS  value denotes a successful call. Other values represent some kind
82       of failure.
83
84       You can use isds_strerror function to obtain a  human  readable  string
85       representation of the error code.
86
87       If   a   function   with   context   argument   failed,   you  can  use
88       isds_long_message function to obtain a detailed error  message.  Please
89       note that returned value lasts only to the next call on the context.
90

CHARACTER ENCODING

92       All  strings  exchanged between the library and the application are en‐
93       coded in UTF-8. Although there are a few exceptions:
94
95isds_strerror and isds_long_message functions return locale encoded
96           string.
97
98isds_version returns locale encoded string.
99
100       •   Log  call-back  function  set  by isds_set_log_callback function is
101           called with raw byte stream.
102
103       •   isds_pki_credentials structure string members  have  encoding  spe‐
104           cific to cryptographic library linked to cURL library.
105

GLOBAL SETTINGS

107       Some functions influence library behaviour globally. These are:
108
109isds_init  and isds_cleanup used to initialize and deinitialize the
110           library.
111
112isds_set_logging and isds_set_log_callback to set logging.
113

LOGGING AND DEBUGGING

115       Logging is global for all libdatovka calls. Log level and facility  can
116       be set with isds_set_logging function.
117
118       The log is printed on standard error output by default. Application can
119       redirect the messages  to  a  call-back  function  by  registering  the
120       call-back function with isds_set_log_callback.
121

NETWORK INPUT/OUTPUT

123       Some  functions  operating  on  a context create network sockets and do
124       network input and output.
125
126       Network timeout can be set  with  isds_set_timeout  function.  Function
127       calls aborted owing to the timeout will return IE_TIMED_OUT.
128
129       Network  operation  progress  can be monitored by a call-back function.
130       The     call-back     function     can     be     registered      using
131       isds_set_progress_callback function. Registered call-back function will
132       be called periodically with arguments declaring amount  of  transferred
133       data.  The call-back return value determines whether to continue in the
134       network operation or to cancel the operation. Functions failed owing to
135       cancelling network operation will return IE_ABORTED.
136

MEMORY MANAGEMENT

138       The  library  provides  destructors for all libdatovka data structures.
139       For example isds_ctx_free function accepts a pointer to  a  pointer  to
140       the  isds_ctx  structure, frees the double referenced structure (recur‐
141       sively), writes NULL to the  pointed  pointer  (which  invalidates  the
142       pointer effectively) and returns nothing.
143
144       Upon  a  function  call, all output arguments are automatically reallo‐
145       cated to desired size. On a function failure, all output arguments  are
146       automatically  deallocated  and  their pointers set to NULL. Exceptions
147       are documented at respective functions.
148
149       Output strings are allocated using standard malloc call. Application is
150       responsible  for  their  deallocation (in case of no failure and if not
151       specified otherwise.) Use standard free call for  strings,  use  libda‐
152       tovka destructors for libdatovka structures.
153

AVAILABLE FUNCTIONS, TYPES, AND CONSTANTS

155       See libdatovka/isds.h header file.
156

SEE ALSO

158       isds.h.libdatovka(3), libcurl(3)
159

AUTHORS

161       CZ.NIC, z. s. p. o.
162           Maintains libdatovka. Has been contributing to libisds.
163
164       Petr Písař
165           He has written libisds.
166

NOTES

168        1. Czech
169                     ISDS Act (300/2008 Coll.)
170           http://portal.gov.cz/zakon/300/2008
171
172        2. Dokumenty ke stažení section of
173                     ISDS Information Portal
174           https://www.datoveschranky.info/ke-stazeni
175
176
177
178[FIXME: source]                   11/09/2023                     LIBDATOVKA(3)
Impressum